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
jaydenseric · Jul 12, 2024 · 38a7abc · 38a7abc
1 parent 8365a1e
commit 38a7abc
Show file tree

Hide file tree

Showing 40 changed files with 248 additions and 170 deletions.
diff --git a/CacheContext.mjs b/CacheContext.mjs
@@ -1,8 +1,8 @@
 // @ts-check
 
-import React from "react";
+/** @import Cache from "./Cache.mjs" */
 
-/** @typedef {import("./Cache.mjs").default} Cache */
+import React from "react";
 
 /**
  * [React context](https://reactjs.org/docs/context.html) for a

diff --git a/HYDRATION_TIME_MS.mjs b/HYDRATION_TIME_MS.mjs
@@ -1,6 +1,6 @@
 // @ts-check
 
-/** @typedef {import("./useAutoLoad.mjs").default} useAutoLoad */
+/** @import useAutoLoad from "./useAutoLoad.mjs" */
 
 /**
  * Number of milliseconds after the first client render that’s considered the

diff --git a/Loading.mjs b/Loading.mjs
@@ -1,8 +1,9 @@
 // @ts-check
 
-/** @typedef {import("./Cache.mjs").CacheKey} CacheKey */
-/** @typedef {import("./Cache.mjs").CacheValue} CacheValue */
-/** @typedef {import("./LoadingCacheValue.mjs").default} LoadingCacheValue */
+/**
+ * @import { CacheKey, CacheValue } from "./Cache.mjs"
+ * @import LoadingCacheValue from "./LoadingCacheValue.mjs"
+ */
 
 /**
  * Loading store.

diff --git a/LoadingCacheValue.mjs b/LoadingCacheValue.mjs
@@ -1,13 +1,14 @@
 // @ts-check
 
+/**
+ * @import { CacheEventMap, CacheKey, CacheValue } from "./Cache.mjs"
+ * @import { LoadingEventMap } from "./Loading.mjs"
+ */
+
 import Cache from "./Cache.mjs";
 import cacheEntrySet from "./cacheEntrySet.mjs";
 import Loading from "./Loading.mjs";
 
-/** @typedef {import("./Cache.mjs").CacheValue} CacheValue */
-/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
-/** @typedef {import("./Loading.mjs").LoadingEventMap} LoadingEventMap */
-
 /**
  * Controls loading a {@link CacheValue cache value}. It dispatches this
  * sequence of events:
@@ -20,7 +21,7 @@ export default class LoadingCacheValue {
   /**
    * @param {Loading} loading Loading to update.
    * @param {Cache} cache Cache to update.
-   * @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
+   * @param {CacheKey} cacheKey Cache key.
    * @param {Promise<CacheValue>} loadingResult Resolves the loading result
    *   (including any loading errors) to be set as the
    *   {@link CacheValue cache value} if loading isn’t aborted. Shouldn’t

diff --git a/LoadingContext.mjs b/LoadingContext.mjs
@@ -1,8 +1,8 @@
 // @ts-check
 
-import React from "react";
+/** @import Loading from "./Loading.mjs" */
 
-/** @typedef {import("./Loading.mjs").default} Loading */
+import React from "react";
 
 /**
  * [React context](https://reactjs.org/docs/context.html) for a

diff --git a/cacheDelete.mjs b/cacheDelete.mjs
@@ -1,17 +1,19 @@
 // @ts-check
 
+/**
+ * @import { CacheEventMap, CacheKey } from "./Cache.mjs"
+ * @import { CacheKeyMatcher } from "./types.mjs"
+ */
+
 import Cache from "./Cache.mjs";
 import cacheEntryDelete from "./cacheEntryDelete.mjs";
 
-/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
-/** @typedef {import("./Cache.mjs").CacheKey} CacheKey */
-
 /**
  * Deletes {@link Cache.store cache store} entries, dispatching the
  * {@linkcode Cache} event {@link CacheEventMap.delete `delete`}. Useful after a
  * user logs out.
  * @param {Cache} cache Cache to update.
- * @param {import("./types.mjs").CacheKeyMatcher} [cacheKeyMatcher] Matches
+ * @param {CacheKeyMatcher} [cacheKeyMatcher] Matches
  *   {@link CacheKey cache keys} to delete. By default all are matched.
  */
 export default function cacheDelete(cache, cacheKeyMatcher) {

diff --git a/cacheEntryDelete.mjs b/cacheEntryDelete.mjs
@@ -1,14 +1,14 @@
 // @ts-check
 
-import Cache from "./Cache.mjs";
+/** @import { CacheEventMap, CacheKey } from "./Cache.mjs" */
 
-/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
+import Cache from "./Cache.mjs";
 
 /**
  * Deletes a {@link Cache.store cache store} entry, dispatching the
  * {@linkcode Cache} event {@link CacheEventMap.delete `delete`}.
  * @param {Cache} cache Cache to update.
- * @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
+ * @param {CacheKey} cacheKey Cache key.
  */
 export default function cacheEntryDelete(cache, cacheKey) {
   if (!(cache instanceof Cache))

diff --git a/cacheEntryPrune.mjs b/cacheEntryPrune.mjs
@@ -1,17 +1,17 @@
 // @ts-check
 
+/** @import { CacheEventMap, CacheKey } from "./Cache.mjs" */
+
 import Cache from "./Cache.mjs";
 import cacheEntryDelete from "./cacheEntryDelete.mjs";
 
-/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
-
 /**
  * Prunes a {@link Cache.store cache store} entry (if present) by dispatching
  * the {@linkcode Cache} event {@link CacheEventMap.prune `prune`} and if no
  * listener cancels it via `event.preventDefault()`, using
  * {@linkcode cacheEntryDelete}.
  * @param {Cache} cache Cache to update.
- * @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
+ * @param {CacheKey} cacheKey Cache key.
  */
 export default function cacheEntryPrune(cache, cacheKey) {
   if (!(cache instanceof Cache))

diff --git a/cacheEntrySet.mjs b/cacheEntrySet.mjs
@@ -1,15 +1,15 @@
 // @ts-check
 
-import Cache from "./Cache.mjs";
+/** @import { CacheEventMap, CacheKey, CacheValue } from "./Cache.mjs" */
 
-/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
+import Cache from "./Cache.mjs";
 
 /**
  * Sets a {@link Cache.store cache store} entry, dispatching the
  * {@linkcode Cache} event {@link CacheEventMap.set `set`}.
  * @param {Cache} cache Cache to update.
- * @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
- * @param {import("./Cache.mjs").CacheValue} cacheValue Cache value.
+ * @param {CacheKey} cacheKey Cache key.
+ * @param {CacheValue} cacheValue Cache value.
  */
 export default function cacheEntrySet(cache, cacheKey, cacheValue) {
   if (!(cache instanceof Cache))

diff --git a/cacheEntryStale.mjs b/cacheEntryStale.mjs
@@ -1,15 +1,15 @@
 // @ts-check
 
-import Cache from "./Cache.mjs";
+/** @import { CacheEventMap, CacheKey } from "./Cache.mjs" */
 
-/** @typedef {import("./Cache.mjs").CacheEventMap} CacheEventMap */
+import Cache from "./Cache.mjs";
 
 /**
  * Stales a {@link Cache.store cache store} entry (throwing an error if missing)
  * by dispatching the {@linkcode Cache} event
  * {@link CacheEventMap.stale `stale`} to signal it should probably be reloaded.
  * @param {Cache} cache Cache to update.
- * @param {import("./Cache.mjs").CacheKey} cacheKey Cache key.
+ * @param {CacheKey} cacheKey Cache key.
  */
 export default function cacheEntryStale(cache, cacheKey) {
   if (!(cache instanceof Cache))

diff --git a/cachePrune.mjs b/cachePrune.mjs
@@ -1,15 +1,18 @@
 // @ts-check
 
+/**
+ * @import { CacheKey } from "./Cache.mjs"
+ * @import { CacheKeyMatcher } from "./types.mjs"
+ */
+
 import Cache from "./Cache.mjs";
 import cacheEntryPrune from "./cacheEntryPrune.mjs";
 
-/** @typedef {import("./Cache.mjs").CacheKey} CacheKey */
-
 /**
  * Prunes {@link Cache.store cache store} entries by using
  * {@linkcode cacheEntryPrune} for each entry. Useful after a mutation.
  * @param {Cache} cache Cache to update.
- * @param {import("./types.mjs").CacheKeyMatcher} [cacheKeyMatcher] Matches
+ * @param {CacheKeyMatcher} [cacheKeyMatcher] Matches
  *   {@link CacheKey cache keys} to prune. By default all are matched.
  */
 export default function cachePrune(cache, cacheKeyMatcher) {

diff --git a/cacheStale.mjs b/cacheStale.mjs
@@ -1,15 +1,18 @@
 // @ts-check
 
+/**
+ * @import { CacheKey } from "./Cache.mjs"
+ * @import { CacheKeyMatcher } from "./types.mjs"
+ */
+
 import Cache from "./Cache.mjs";
 import cacheEntryStale from "./cacheEntryStale.mjs";
 
-/** @typedef {import("./Cache.mjs").CacheKey} CacheKey */
-
 /**
  * Stales {@link Cache.store cache store} entries by using
  * {@linkcode cacheEntryStale} for each entry. Useful after a mutation.
  * @param {Cache} cache Cache to update.
- * @param {import("./types.mjs").CacheKeyMatcher} [cacheKeyMatcher] Matches
+ * @param {CacheKeyMatcher} [cacheKeyMatcher] Matches
  *   {@link CacheKey cache keys} to stale. By default all are matched.
  */
 export default function cacheStale(cache, cacheKeyMatcher) {

diff --git a/changelog.md b/changelog.md
@@ -7,6 +7,7 @@
 - Updated Node.js support to `^18.18.0 || ^20.9.0 || >=22.0.0`.
 - Use the Node.js test runner API and remove the dev dependency [`test-director`](https://npm.im/test-director).
 - 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).
+- Use the TypeScript v5.5+ JSDoc tag `@import` to import types in modules.
 
 ### Patch
 

diff --git a/fetchGraphQL.mjs b/fetchGraphQL.mjs
@@ -1,13 +1,22 @@
 // @ts-check
 
+/**
+ * @import { CacheValue } from "./Cache.mjs"
+ * @import {
+ *   GraphQLResult,
+ *   GraphQLResultError,
+ *   GraphQLResultErrorLoadingFetch,
+ *   GraphQLResultErrorResponseHttpStatus,
+ *   GraphQLResultErrorResponseJsonParse,
+ *   GraphQLResultErrorResponseMalformed,
+ * } from "./types.mjs"
+ */
+
 const ERROR_CODE_FETCH_ERROR = "FETCH_ERROR";
 const ERROR_CODE_RESPONSE_HTTP_STATUS = "RESPONSE_HTTP_STATUS";
 const ERROR_CODE_RESPONSE_JSON_PARSE_ERROR = "RESPONSE_JSON_PARSE_ERROR";
 const ERROR_CODE_RESPONSE_MALFORMED = "RESPONSE_MALFORMED";
 
-/** @typedef {import("./Cache.mjs").CacheValue} CacheValue */
-/** @typedef {import("./types.mjs").GraphQLResult} GraphQLResult */
-
 /**
  * Fetches a GraphQL operation, always resolving a
  * {@link GraphQLResult GraphQL result} suitable for use as a
@@ -45,7 +54,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
 
         if (!response.ok)
           resultErrors.push(
-            /** @type {import("./types.mjs").GraphQLResultErrorResponseHttpStatus} */ ({
+            /** @type {GraphQLResultErrorResponseHttpStatus} */ ({
               message: `HTTP ${response.status} status.`,
               extensions: {
                 client: true,
@@ -65,7 +74,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
 
             if (typeof json !== "object" || !json || Array.isArray(json))
               resultErrors.push(
-                /** @type {import("./types.mjs").GraphQLResultErrorResponseMalformed}*/ ({
+                /** @type {GraphQLResultErrorResponseMalformed}*/ ({
                   message: "Response JSON isn’t an object.",
                   extensions: {
                     client: true,
@@ -79,7 +88,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
 
               if (!hasErrors && !hasData)
                 resultErrors.push(
-                  /** @type {import("./types.mjs").GraphQLResultErrorResponseMalformed}*/ ({
+                  /** @type {GraphQLResultErrorResponseMalformed}*/ ({
                     message:
                       "Response JSON is missing an `errors` or `data` property.",
                     extensions: {
@@ -94,7 +103,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
                 if (hasErrors)
                   if (!Array.isArray(json.errors))
                     resultErrors.push(
-                      /** @type {import("./types.mjs").GraphQLResultErrorResponseMalformed}*/ ({
+                      /** @type {GraphQLResultErrorResponseMalformed}*/ ({
                         message:
                           "Response JSON `errors` property isn’t an array.",
                         extensions: {
@@ -114,7 +123,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
                     Array.isArray(json.data)
                   )
                     resultErrors.push(
-                      /** @type {import("./types.mjs").GraphQLResultErrorResponseMalformed}*/ ({
+                      /** @type {GraphQLResultErrorResponseMalformed}*/ ({
                         message:
                           "Response JSON `data` property isn’t an object or null.",
                         extensions: {
@@ -131,7 +140,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
           // Response JSON parse error.
           ({ message }) => {
             resultErrors.push(
-              /** @type {import("./types.mjs").GraphQLResultErrorResponseJsonParse} */ ({
+              /** @type {GraphQLResultErrorResponseJsonParse} */ ({
                 message: "Response JSON parse error.",
                 extensions: {
                   client: true,
@@ -147,7 +156,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
       // Fetch error.
       ({ message }) => {
         resultErrors.push(
-          /** @type {import("./types.mjs").GraphQLResultErrorLoadingFetch} */ ({
+          /** @type {GraphQLResultErrorLoadingFetch} */ ({
             message: "Fetch error.",
             extensions: {
               client: true,
@@ -166,24 +175,21 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
 
 /**
  * {@linkcode fetchGraphQL} {@link GraphQLResult GraphQL result}.
- * @typedef {import("./types.mjs").GraphQLResult<
- *   FetchGraphQLResultError
- * >} FetchGraphQLResult
+ * @typedef {GraphQLResult<FetchGraphQLResultError>} FetchGraphQLResult
  */
 
 /**
  * {@linkcode fetchGraphQL} {@link GraphQLResult.errors GraphQL result error}.
  * @typedef {FetchGraphQLResultErrorLoading
- *   | import("./types.mjs").GraphQLResultError
- * } FetchGraphQLResultError
+ *   | GraphQLResultError} FetchGraphQLResultError
  */
 
 /**
  * {@linkcode fetchGraphQL} {@link GraphQLResult.errors GraphQL result error}
  * that’s generated on the client, not the GraphQL server.
- * @typedef {import("./types.mjs").GraphQLResultErrorLoadingFetch
- *   | import("./types.mjs").GraphQLResultErrorResponseHttpStatus
- *   | import("./types.mjs").GraphQLResultErrorResponseJsonParse
- *   | import("./types.mjs").GraphQLResultErrorResponseMalformed
+ * @typedef {GraphQLResultErrorLoadingFetch
+ *   | GraphQLResultErrorResponseHttpStatus
+ *   | GraphQLResultErrorResponseJsonParse
+ *   | GraphQLResultErrorResponseMalformed
  * } FetchGraphQLResultErrorLoading
  */
diff --git a/fetchOptionsGraphQL.mjs b/fetchOptionsGraphQL.mjs
@@ -1,10 +1,10 @@
 // @ts-check
 
+/** @import { GraphQLOperation } from "./types.mjs" */
+
 import extractFiles from "extract-files/extractFiles.mjs";
 import isExtractableFile from "extract-files/isExtractableFile.mjs";
 
-/** @typedef {import("./types.mjs").GraphQLOperation} GraphQLOperation */
-
 /**
  * Creates default {@link RequestInit `fetch` options} for a
  * {@link GraphQLOperation GraphQL operation}. If the operation contains files

diff --git a/test/createReactTestRenderer.mjs b/test/createReactTestRenderer.mjs
@@ -1,13 +1,18 @@
 // @ts-check
 
+/**
+ * @import { ReactNode } from "react"
+ * @import { ReactTestRenderer as TestRenderer } from "react-test-renderer"
+ */
+
 import ReactTestRenderer from "react-test-renderer";
 
 /**
  * Creates a React test renderer.
- * @param {import("react").ReactNode} reactRoot Root React node to render.
+ * @param {ReactNode} reactRoot Root React node to render.
  */
 export default function createReactTestRenderer(reactRoot) {
-  /** @type {import("react-test-renderer").ReactTestRenderer | undefined} */
+  /** @type {TestRenderer | undefined} */
   let testRenderer;
 
   ReactTestRenderer.act(() => {
@@ -17,7 +22,5 @@ export default function createReactTestRenderer(reactRoot) {
     );
   });
 
-  return /** @type {import("react-test-renderer").ReactTestRenderer} */ (
-    testRenderer
-  );
+  return /** @type {TestRenderer} */ (testRenderer);
 }