Fix and improve types.

Author: jaydenseric

changelog.md

@@ -2,10 +2,20 @@
 
 ## Next
 
+### Major
+
+- Renamed the type `FetchGraphQLResultErrors` to `FetchGraphQLResultError` in `fetchGraphQL.mjs`.
+
+### Minor
+
+- Added a new `FetchGraphQLResultErrorLoading` to `fetchGraphQL.mjs` containing the GraphQL result error types related to loading that are generated on the client, not the GraphQL server.
+
 ### Patch
 
 - Updated dev dependencies.
 - Simplified dev dependencies and config for ESLint.
+- Fixed issues with GraphQL result related types from `types.mjs`.
+- Improved various JSDoc descriptions.
 
 ## 17.0.0
 

fetchGraphQL.mjs

@@ -11,7 +11,8 @@ const ERROR_CODE_RESPONSE_MALFORMED = "RESPONSE_MALFORMED";
 /**
  * Fetches a GraphQL operation, always resolving a
  * {@link GraphQLResult GraphQL result} suitable for use as a
- * {@link CacheValue cache value}, even if there are errors.
+ * {@link CacheValue cache value}, even if there are
+ * {@link FetchGraphQLResultError errors}.
  * @param {string} fetchUri Fetch URI for the GraphQL API.
  * @param {RequestInit} [fetchOptions] Fetch options.
  * @returns {Promise<FetchGraphQLResult>} Resolves a result suitable for use as
@@ -25,7 +26,7 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
   /** @type {FetchGraphQLResult} */
   const result = {};
 
-  /** @type {Array<FetchGraphQLResultErrors>} */
+  /** @type {Array<FetchGraphQLResultError>} */
   const resultErrors = [];
 
   const fetcher =
@@ -164,19 +165,25 @@ export default function fetchGraphQL(fetchUri, fetchOptions) {
 }
 
 /**
- * {@link GraphQLResult GraphQL result} when using {@linkcode fetchGraphQL}.
+ * {@linkcode fetchGraphQL} {@link GraphQLResult GraphQL result}.
  * @typedef {import("./types.mjs").GraphQLResult<
- *   FetchGraphQLResultErrors
+ *   FetchGraphQLResultError
  * >} FetchGraphQLResult
  */
 
 /**
- * {@link GraphQLResult.errors GraphQL result errors} that are possible when
- * using {@linkcode fetchGraphQL}.
- * @typedef {import("./types.mjs").GraphQLResultError
- *   | import("./types.mjs").GraphQLResultErrorLoadingFetch
+ * {@linkcode fetchGraphQL} {@link GraphQLResult.errors GraphQL result error}.
+ * @typedef {FetchGraphQLResultErrorLoading
+ *   | import("./types.mjs").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
- * } FetchGraphQLResultErrors
+ * } FetchGraphQLResultErrorLoading
  */

types.mjs

@@ -28,7 +28,7 @@ export {};
 /**
  * A GraphQL result.
  * @see [GraphQL spec for a response](https://spec.graphql.org/October2021/#sec-Response).
- * @template [ErrorTypes=GraphQLResultError]
+ * @template [ErrorTypes=GraphQLResultError] Possible error types.
  * @typedef {object} GraphQLResult
  * @prop {Response} [response] The GraphQL server response. Non-enumerable to
  *   prevent it from serializing to JSON when sending SSR cache to the client
@@ -39,45 +39,41 @@ export {};
  */
 
 /**
- * A {@link GraphQLResult.errors GraphQL result error}; either created by the
- * GraphQL server, or by whatever loaded the GraphQL on the client (e.g.
- * {@linkcode fetchGraphQL}).
+ * A {@link GraphQLResult.errors GraphQL result error}.
  * @see [GraphQL spec for response errors](https://spec.graphql.org/October2021/#sec-Errors).
- * @template [Extensions=Record<string, unknown>] Custom error data.
+ * @template {Record<string, unknown>} [Extensions=Record<string, unknown>]
+ *   Extensions to a standard GraphQL error.
  * @typedef {object} GraphQLResultError
  * @prop {string} message Error message.
  * @prop {Array<{ line: number; column: number }>} [locations] GraphQL query
  *   locations related to the error.
  * @prop {Array<string | number>} [path] GraphQL result
  *   {@link GraphQLResult.data `data`} property path related to the error.
- * @prop {Extensions} [extensions] Custom error data. If the error was created
- *   on the client and not the GraphQL server, this property should be present
- *   and contain at least `client: true`, although `code` and error specific
- *   properties may be present.
+ * @prop {Extensions} [extensions] Extensions to a standard GraphQL error.
  */
 
 /**
- * A {@link GraphQLResult GraphQL result} loading error generated by the client,
+ * A {@link GraphQLResult GraphQL result} loading error generated on the client,
  * not the GraphQL server.
- * @template {string} Code
- * @template [Extensions={}]
- * @typedef {Pick<
- *   GraphQLResultError<GraphQLResultErrorLoadingMeta & Extensions>,
- *   "message" | "extensions"
- * >} GraphQLResultErrorLoading
- *
+ * @template {string} Code Error code.
+ * @template {Record<string, unknown>} [Extensions={}] Error specific details.
+ * @typedef {object} GraphQLResultErrorLoading
+ * @prop {string} message Error message.
+ * @prop {GraphQLResultErrorLoadingMeta<Code> & Extensions} extensions Error
+ *   specific details.
  */
 
 /**
+ * @template {string} Code Error code.
  * @typedef {object} GraphQLResultErrorLoadingMeta
- * @prop {true} client Indicates that this error was generated by the client and
- *   wasn’t present in the GraphQL response.
- * @prop {string} code Error code.
+ * @prop {true} client Error was generated on the client, not the GraphQL
+ *   server.
+ * @prop {Code} code Error code.
  */
 
 /**
- * The GraphQL request had a fetch error, e.g. the `fetch` global isn’t defined,
- * or the network is offline.
+ * {@link GraphQLResultError GraphQL error} that the GraphQL request had a fetch
+ * error, e.g. the `fetch` global isn’t defined, or the network is offline.
  * @typedef {GraphQLResultErrorLoading<
  *   "FETCH_ERROR",
  *   GraphQLResultErrorLoadingFetchDetails
@@ -90,8 +86,8 @@ export {};
  */
 
 /**
- * The GraphQL request had a fetch error, e.g. the `fetch` global isn’t defined,
- * or the network is offline.
+ * {@link GraphQLResultError GraphQL error} that the GraphQL response had an
+ * error HTTP status.
  * @typedef {GraphQLResultErrorLoading<
  *   "RESPONSE_HTTP_STATUS",
  *   GraphQLResultErrorResponseHttpStatusDetails
@@ -105,7 +101,8 @@ export {};
  */
 
 /**
- * The GraphQL response JSON had a parse error.
+ * {@link GraphQLResultError GraphQL error} that the GraphQL response JSON had a
+ * parse error.
  * @typedef {GraphQLResultErrorLoading<
  *   "RESPONSE_JSON_PARSE_ERROR",
  *   GraphQLResultErrorResponseJsonParseDetails
@@ -118,9 +115,10 @@ export {};
  */
 
 /**
- * The GraphQL response JSON was malformed because it wasn’t an object, was
- * missing an `errors` or `data` property, the `errors` property wasn’t an
- * array, or the `data` property wasn’t an object or `null`.
+ * {@link GraphQLResultError GraphQL error} that the GraphQL response JSON was
+ * malformed because it wasn’t an object, was missing an `errors` or `data`
+ * property, the `errors` property wasn’t an array, or the `data` property
+ * wasn’t an object or `null`.
  * @typedef {GraphQLResultErrorLoading<
  *   "RESPONSE_MALFORMED"
  * >} GraphQLResultErrorResponseMalformed