Skip to content

Commit 9f6422b

Browse files
DevHawkNovDevHawkNov
committed
Use the TypeScript v5.5+ JSDoc tag @import to import types in modules.
See: https://devblogs.microsoft.com/typescript/announcing-typescript-5-5/#the-jsdoc-import-tag Note that the JSDoc type imports have to be before the real module imports to workaround this TypeScript bug where sometimes the type imports are falsely considered unused: microsoft/TypeScript#58368 (comment) microsoft/TypeScript#58969
1 parent f237800 commit 9f6422b

40 files changed

+248
-170
lines changed

‎CacheContext.mjs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
// @ts-check
22

3-
import React from "react";
3+
/** @import Cache from "./Cache.mjs" */
44

5-
/** @typedef {import("./Cache.mjs").default} Cache */
5+
import React from "react";
66

77
/**
88
* [React context](https://reactjs.org/docs/context.html) for a

‎HYDRATION_TIME_MS.mjs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// @ts-check
22

3-
/** @typedef {import("./useAutoLoad.mjs").default} useAutoLoad */
3+
/** @import useAutoLoad from "./useAutoLoad.mjs" */
44

55
/**
66
* Number of milliseconds after the first client render that’s considered the

‎Loading.mjs

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
// @ts-check
22

3-
/** @typedef {import("./Cache.mjs").CacheKey} CacheKey */
4-
/** @typedef {import("./Cache.mjs").CacheValue} CacheValue */
5-
/** @typedef {import("./LoadingCacheValue.mjs").default} LoadingCacheValue */
3+
/**
4+
* @import { CacheKey, CacheValue } from "./Cache.mjs"
5+
* @import LoadingCacheValue from "./LoadingCacheValue.mjs"
6+
*/
67

78
/**
89
* Loading store.

‎LoadingCacheValue.mjs

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,14 @@
11
// @ts-check
22

3+
/**
4+
* @import { CacheEventMap, CacheKey, CacheValue } from "./Cache.mjs"
5+
* @import { LoadingEventMap } from "./Loading.mjs"
6+
*/
7+
38
import Cache from "./Cache.mjs";
49
import cacheEntrySet from "./cacheEntrySet.mjs";
510
import Loading from "./Loading.mjs";
611

7-
/** @typedef {import("./Cache.mjs").CacheValue} CacheValue */
8-
/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
9-
/** @typedef {import("./Loading.mjs").LoadingEventMap} LoadingEventMap */
10-
1112
/**
1213
* Controls loading a {@link CacheValue cache value}. It dispatches this
1314
* sequence of events:
@@ -20,7 +21,7 @@ export default class LoadingCacheValue {
2021
/**
2122
* @param {Loading} loading Loading to update.
2223
* @param {Cache} cache Cache to update.
23-
* @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
24+
* @param {CacheKey} cacheKey Cache key.
2425
* @param {Promise<CacheValue>} loadingResult Resolves the loading result
2526
* (including any loading errors) to be set as the
2627
* {@link CacheValue cache value} if loading isn’t aborted. Shouldn’t

‎LoadingContext.mjs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
// @ts-check
22

3-
import React from "react";
3+
/** @import Loading from "./Loading.mjs" */
44

5-
/** @typedef {import("./Loading.mjs").default} Loading */
5+
import React from "react";
66

77
/**
88
* [React context](https://reactjs.org/docs/context.html) for a

‎cacheDelete.mjs

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,19 @@
11
// @ts-check
22

3+
/**
4+
* @import { CacheEventMap, CacheKey } from "./Cache.mjs"
5+
* @import { CacheKeyMatcher } from "./types.mjs"
6+
*/
7+
38
import Cache from "./Cache.mjs";
49
import cacheEntryDelete from "./cacheEntryDelete.mjs";
510

6-
/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
7-
/** @typedef {import("./Cache.mjs").CacheKey} CacheKey */
8-
911
/**
1012
* Deletes {@link Cache.store cache store} entries, dispatching the
1113
* {@linkcode Cache} event {@link CacheEventMap.delete `delete`}. Useful after a
1214
* user logs out.
1315
* @param {Cache} cache Cache to update.
14-
* @param {import("./types.mjs").CacheKeyMatcher} [cacheKeyMatcher] Matches
16+
* @param {CacheKeyMatcher} [cacheKeyMatcher] Matches
1517
* {@link CacheKey cache keys} to delete. By default all are matched.
1618
*/
1719
export default function cacheDelete(cache, cacheKeyMatcher) {

‎cacheEntryDelete.mjs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
// @ts-check
22

3-
import Cache from "./Cache.mjs";
3+
/** @import { CacheEventMap, CacheKey } from "./Cache.mjs" */
44

5-
/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
5+
import Cache from "./Cache.mjs";
66

77
/**
88
* Deletes a {@link Cache.store cache store} entry, dispatching the
99
* {@linkcode Cache} event {@link CacheEventMap.delete `delete`}.
1010
* @param {Cache} cache Cache to update.
11-
* @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
11+
* @param {CacheKey} cacheKey Cache key.
1212
*/
1313
export default function cacheEntryDelete(cache, cacheKey) {
1414
if (!(cache instanceof Cache))

‎cacheEntryPrune.mjs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,17 @@
11
// @ts-check
22

3+
/** @import { CacheEventMap, CacheKey } from "./Cache.mjs" */
4+
35
import Cache from "./Cache.mjs";
46
import cacheEntryDelete from "./cacheEntryDelete.mjs";
57

6-
/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
7-
88
/**
99
* Prunes a {@link Cache.store cache store} entry (if present) by dispatching
1010
* the {@linkcode Cache} event {@link CacheEventMap.prune `prune`} and if no
1111
* listener cancels it via `event.preventDefault()`, using
1212
* {@linkcode cacheEntryDelete}.
1313
* @param {Cache} cache Cache to update.
14-
* @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
14+
* @param {CacheKey} cacheKey Cache key.
1515
*/
1616
export default function cacheEntryPrune(cache, cacheKey) {
1717
if (!(cache instanceof Cache))

‎cacheEntrySet.mjs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
// @ts-check
22

3-
import Cache from "./Cache.mjs";
3+
/** @import { CacheEventMap, CacheKey, CacheValue } from "./Cache.mjs" */
44

5-
/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
5+
import Cache from "./Cache.mjs";
66

77
/**
88
* Sets a {@link Cache.store cache store} entry, dispatching the
99
* {@linkcode Cache} event {@link CacheEventMap.set `set`}.
1010
* @param {Cache} cache Cache to update.
11-
* @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
12-
* @param {import("./Cache.mjs").CacheValue} cacheValue Cache value.
11+
* @param {CacheKey} cacheKey Cache key.
12+
* @param {CacheValue} cacheValue Cache value.
1313
*/
1414
export default function cacheEntrySet(cache, cacheKey, cacheValue) {
1515
if (!(cache instanceof Cache))

‎cacheEntryStale.mjs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,15 @@
11
// @ts-check
22

3-
import Cache from "./Cache.mjs";
3+
/** @import { CacheEventMap, CacheKey } from "./Cache.mjs" */
44

5-
/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
5+
import Cache from "./Cache.mjs";
66

77
/**
88
* Stales a {@link Cache.store cache store} entry (throwing an error if missing)
99
* by dispatching the {@linkcode Cache} event
1010
* {@link CacheEventMap.stale `stale`} to signal it should probably be reloaded.
1111
* @param {Cache} cache Cache to update.
12-
* @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
12+
* @param {CacheKey} cacheKey Cache key.
1313
*/
1414
export default function cacheEntryStale(cache, cacheKey) {
1515
if (!(cache instanceof Cache))

‎cachePrune.mjs

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,18 @@
11
// @ts-check
22

3+
/**
4+
* @import { CacheKey } from "./Cache.mjs"
5+
* @import { CacheKeyMatcher } from "./types.mjs"
6+
*/
7+
38
import Cache from "./Cache.mjs";
49
import cacheEntryPrune from "./cacheEntryPrune.mjs";
510

6-
/** @typedef {import("./Cache.mjs").CacheKey} CacheKey */
7-
811
/**
912
* Prunes {@link Cache.store cache store} entries by using
1013
* {@linkcode cacheEntryPrune} for each entry. Useful after a mutation.
1114
* @param {Cache} cache Cache to update.
12-
* @param {import("./types.mjs").CacheKeyMatcher} [cacheKeyMatcher] Matches
15+
* @param {CacheKeyMatcher} [cacheKeyMatcher] Matches
1316
* {@link CacheKey cache keys} to prune. By default all are matched.
1417
*/
1518
export default function cachePrune(cache, cacheKeyMatcher) {

‎cacheStale.mjs

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,18 @@
11
// @ts-check
22

3+
/**
4+
* @import { CacheKey } from "./Cache.mjs"
5+
* @import { CacheKeyMatcher } from "./types.mjs"
6+
*/
7+
38
import Cache from "./Cache.mjs";
49
import cacheEntryStale from "./cacheEntryStale.mjs";
510

6-
/** @typedef {import("./Cache.mjs").CacheKey} CacheKey */
7-
811
/**
912
* Stales {@link Cache.store cache store} entries by using
1013
* {@linkcode cacheEntryStale} for each entry. Useful after a mutation.
1114
* @param {Cache} cache Cache to update.
12-
* @param {import("./types.mjs").CacheKeyMatcher} [cacheKeyMatcher] Matches
15+
* @param {CacheKeyMatcher} [cacheKeyMatcher] Matches
1316
* {@link CacheKey cache keys} to stale. By default all are matched.
1417
*/
1518
export default function cacheStale(cache, cacheKeyMatcher) {

‎changelog.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
- Updated Node.js support to `^18.18.0 || ^20.9.0 || >=22.0.0`.
88
- Use the Node.js test runner API and remove the dev dependency [`test-director`](https://npm.im/test-director).
99
- Refactored tests to use the standard `AbortController`, `AbortSignal`, `Event`, `EventTarget`, `File`, `FormData`, and `Response` APIs available in modern Node.js and removed the dev dependencies [`abort-controller`](https://npm.im/abort-controller), [`event-target-shim`](https://npm.im/event-target-shim), and [`node-fetch`](https://npm.im/node-fetch).
10+
- Use the TypeScript v5.5+ JSDoc tag `@import` to import types in modules.
1011

1112
### Patch
1213

‎fetchGraphQL.mjs

Lines changed: 25 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,22 @@
11
// @ts-check
22

3+
/**
4+
* @import { CacheValue } from "./Cache.mjs"
5+
* @import {
6+
* GraphQLResult,
7+
* GraphQLResultError,
8+
* GraphQLResultErrorLoadingFetch,
9+
* GraphQLResultErrorResponseHttpStatus,
10+
* GraphQLResultErrorResponseJsonParse,
11+
* GraphQLResultErrorResponseMalformed,
12+
* } from "./types.mjs"
13+
*/
14+
315
const ERROR_CODE_FETCH_ERROR = "FETCH_ERROR";
416
const ERROR_CODE_RESPONSE_HTTP_STATUS = "RESPONSE_HTTP_STATUS";
517
const ERROR_CODE_RESPONSE_JSON_PARSE_ERROR = "RESPONSE_JSON_PARSE_ERROR";
618
const ERROR_CODE_RESPONSE_MALFORMED = "RESPONSE_MALFORMED";
719

8-
/** @typedef {import("./Cache.mjs").CacheValue} CacheValue */
9-
/** @typedef {import("./types.mjs").GraphQLResult} GraphQLResult */
10-
1120
/**
1221
* Fetches a GraphQL operation, always resolving a
1322
* {@link GraphQLResult GraphQL result} suitable for use as a
@@ -45,7 +54,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
4554

4655
if (!response.ok)
4756
resultErrors.push(
48-
/** @type {import("./types.mjs").GraphQLResultErrorResponseHttpStatus} */ ({
57+
/** @type {GraphQLResultErrorResponseHttpStatus} */ ({
4958
message: `HTTP ${response.status} status.`,
5059
extensions: {
5160
client: true,
@@ -65,7 +74,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
6574

6675
if (typeof json !== "object" || !json || Array.isArray(json))
6776
resultErrors.push(
68-
/** @type {import("./types.mjs").GraphQLResultErrorResponseMalformed}*/ ({
77+
/** @type {GraphQLResultErrorResponseMalformed}*/ ({
6978
message: "Response JSON isn’t an object.",
7079
extensions: {
7180
client: true,
@@ -79,7 +88,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
7988

8089
if (!hasErrors && !hasData)
8190
resultErrors.push(
82-
/** @type {import("./types.mjs").GraphQLResultErrorResponseMalformed}*/ ({
91+
/** @type {GraphQLResultErrorResponseMalformed}*/ ({
8392
message:
8493
"Response JSON is missing an `errors` or `data` property.",
8594
extensions: {
@@ -94,7 +103,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
94103
if (hasErrors)
95104
if (!Array.isArray(json.errors))
96105
resultErrors.push(
97-
/** @type {import("./types.mjs").GraphQLResultErrorResponseMalformed}*/ ({
106+
/** @type {GraphQLResultErrorResponseMalformed}*/ ({
98107
message:
99108
"Response JSON `errors` property isn’t an array.",
100109
extensions: {
@@ -114,7 +123,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
114123
Array.isArray(json.data)
115124
)
116125
resultErrors.push(
117-
/** @type {import("./types.mjs").GraphQLResultErrorResponseMalformed}*/ ({
126+
/** @type {GraphQLResultErrorResponseMalformed}*/ ({
118127
message:
119128
"Response JSON `data` property isn’t an object or null.",
120129
extensions: {
@@ -131,7 +140,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
131140
// Response JSON parse error.
132141
({ message }) => {
133142
resultErrors.push(
134-
/** @type {import("./types.mjs").GraphQLResultErrorResponseJsonParse} */ ({
143+
/** @type {GraphQLResultErrorResponseJsonParse} */ ({
135144
message: "Response JSON parse error.",
136145
extensions: {
137146
client: true,
@@ -147,7 +156,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
147156
// Fetch error.
148157
({ message }) => {
149158
resultErrors.push(
150-
/** @type {import("./types.mjs").GraphQLResultErrorLoadingFetch} */ ({
159+
/** @type {GraphQLResultErrorLoadingFetch} */ ({
151160
message: "Fetch error.",
152161
extensions: {
153162
client: true,
@@ -166,24 +175,21 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
166175

167176
/**
168177
* {@linkcode fetchGraphQL} {@link GraphQLResult GraphQL result}.
169-
* @typedef {import("./types.mjs").GraphQLResult<
170-
* FetchGraphQLResultError
171-
* >} FetchGraphQLResult
178+
* @typedef {GraphQLResult<FetchGraphQLResultError>} FetchGraphQLResult
172179
*/
173180

174181
/**
175182
* {@linkcode fetchGraphQL} {@link GraphQLResult.errors GraphQL result error}.
176183
* @typedef {FetchGraphQLResultErrorLoading
177-
* | import("./types.mjs").GraphQLResultError
178-
* } FetchGraphQLResultError
184+
* | GraphQLResultError} FetchGraphQLResultError
179185
*/
180186

181187
/**
182188
* {@linkcode fetchGraphQL} {@link GraphQLResult.errors GraphQL result error}
183189
* that’s generated on the client, not the GraphQL server.
184-
* @typedef {import("./types.mjs").GraphQLResultErrorLoadingFetch
185-
* | import("./types.mjs").GraphQLResultErrorResponseHttpStatus
186-
* | import("./types.mjs").GraphQLResultErrorResponseJsonParse
187-
* | import("./types.mjs").GraphQLResultErrorResponseMalformed
190+
* @typedef {GraphQLResultErrorLoadingFetch
191+
* | GraphQLResultErrorResponseHttpStatus
192+
* | GraphQLResultErrorResponseJsonParse
193+
* | GraphQLResultErrorResponseMalformed
188194
* } FetchGraphQLResultErrorLoading
189195
*/

‎fetchOptionsGraphQL.mjs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
// @ts-check
22

3+
/** @import { GraphQLOperation } from "./types.mjs" */
4+
35
import extractFiles from "extract-files/extractFiles.mjs";
46
import isExtractableFile from "extract-files/isExtractableFile.mjs";
57

6-
/** @typedef {import("./types.mjs").GraphQLOperation} GraphQLOperation */
7-
88
/**
99
* Creates default {@link RequestInit `fetch` options} for a
1010
* {@link GraphQLOperation GraphQL operation}. If the operation contains files

‎test/createReactTestRenderer.mjs

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,18 @@
11
// @ts-check
22

3+
/**
4+
* @import { ReactNode } from "react"
5+
* @import { ReactTestRenderer as TestRenderer } from "react-test-renderer"
6+
*/
7+
38
import ReactTestRenderer from "react-test-renderer";
49

510
/**
611
* Creates a React test renderer.
7-
* @param {import("react").ReactNode} reactRoot Root React node to render.
12+
* @param {ReactNode} reactRoot Root React node to render.
813
*/
914
export default function createReactTestRenderer(reactRoot) {
10-
/** @type {import("react-test-renderer").ReactTestRenderer | undefined} */
15+
/** @type {TestRenderer | undefined} */
1116
let testRenderer;
1217

1318
ReactTestRenderer.act(() => {
@@ -17,7 +22,5 @@ export default function createReactTestRenderer(reactRoot) {
1722
);
1823
});
1924

20-
return /** @type {import("react-test-renderer").ReactTestRenderer} */ (
21-
testRenderer
22-
);
25+
return /** @type {TestRenderer} */ (testRenderer);
2326
}

0 commit comments

Comments
 (0)