@khanacademy/wonder-blocks-data 15.0.3 → 15.1.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @khanacademy/wonder-blocks-data
 
+## 15.1.0
+
+### Minor Changes
+
+- 6c55a12: Add `ErrorResultGqlError`, a typed `GqlError` thrown when a GraphQL response reports errors, exposing `statusCode` and the parsed `result` payload (partial `data` plus `errors`) so consumers can use partial results without type suppression. Also adds the `isErrorResultGqlError` type guard and the `GqlPartialData`, `GqlResponseError`, and `GqlErrorResultPayload` types.
+
+### Patch Changes
+
+- @khanacademy/wonder-blocks-core@12.5.0
+
+## 15.0.4
+
+### Patch Changes
+
+- Updated dependencies [63dcc94]
+    - @khanacademy/wonder-blocks-core@12.5.0
+
 ## 15.0.3
 
 ### Patch Changes

package/dist/es/index.js

@@ -50,7 +50,9 @@ const toString=value=>{if(typeof value==="string"){return value}if(typeof value=
 
 const GqlErrors=Object.freeze({Internal:"Internal",BadResponse:"BadResponse",ErrorResult:"ErrorResult"});class GqlError extends KindError{constructor(message,kind,{metadata,cause}={}){super(message,kind,{metadata,cause,name:"Gql"});}}
 
-const getGqlDataFromResponse=async response=>{const bodyText=await response.text();let result;try{result=JSON.parse(bodyText);}catch(e){throw new DataError("Failed to parse response",DataErrors.Parse,{metadata:{statusCode:response.status,bodyText},cause:e})}if(response.status>=300){throw new DataError("Response unsuccessful",DataErrors.Network,{metadata:{statusCode:response.status,result}})}if(!Object.prototype.hasOwnProperty.call(result,"data")&&!Object.prototype.hasOwnProperty.call(result,"errors")){throw new GqlError("Server response missing",GqlErrors.BadResponse,{metadata:{statusCode:response.status,result}})}if(result.errors!=null&&Array.isArray(result.errors)&&result.errors.length>0){throw new GqlError("GraphQL errors",GqlErrors.ErrorResult,{metadata:{statusCode:response.status,result}})}return result.data};
+class ErrorResultGqlError extends GqlError{constructor(statusCode,result){super("GraphQL errors",GqlErrors.ErrorResult,{metadata:{statusCode,result:result}});this.statusCode=statusCode;this.result=result;}}
+
+const getGqlDataFromResponse=async response=>{const bodyText=await response.text();let result;try{result=JSON.parse(bodyText);}catch(e){throw new DataError("Failed to parse response",DataErrors.Parse,{metadata:{statusCode:response.status,bodyText},cause:e})}if(response.status>=300){throw new DataError("Response unsuccessful",DataErrors.Network,{metadata:{statusCode:response.status,result}})}if(!Object.prototype.hasOwnProperty.call(result,"data")&&!Object.prototype.hasOwnProperty.call(result,"errors")){throw new GqlError("Server response missing",GqlErrors.BadResponse,{metadata:{statusCode:response.status,result}})}if(result.errors!=null&&Array.isArray(result.errors)&&result.errors.length>0){throw new ErrorResultGqlError(response.status,result)}return result.data};
 
 const DocumentTypes=Object.freeze({query:"query",mutation:"mutation"});const cache=new Map;function graphQLDocumentNodeParser(document){const cached=cache.get(document);if(cached){return cached}if(!document?.kind){if(process.env.NODE_ENV==="production"){throw new DataError("Bad DocumentNode",DataErrors.InvalidInput)}else {throw new DataError(`Argument of ${JSON.stringify(document)} passed to parser was not a valid GraphQL `+`DocumentNode. You may need to use 'graphql-tag' or another method `+`to convert your operation into a document`,DataErrors.InvalidInput)}}const fragments=document.definitions.filter(x=>x.kind==="FragmentDefinition");const queries=document.definitions.filter(x=>x.kind==="OperationDefinition"&&x.operation==="query");const mutations=document.definitions.filter(x=>x.kind==="OperationDefinition"&&x.operation==="mutation");const subscriptions=document.definitions.filter(x=>x.kind==="OperationDefinition"&&x.operation==="subscription");if(fragments.length&&!queries.length&&!mutations.length){if(process.env.NODE_ENV==="production"){throw new DataError("Fragment only",DataErrors.InvalidInput)}else {throw new DataError(`Passing only a fragment to 'graphql' is not supported. `+`You must include a query or mutation as well`,DataErrors.InvalidInput)}}if(subscriptions.length){if(process.env.NODE_ENV==="production"){throw new DataError("No subscriptions",DataErrors.InvalidInput)}else {throw new DataError(`We do not support subscriptions. `+`${JSON.stringify(document)} had ${subscriptions.length} subscriptions`,DataErrors.InvalidInput)}}if(queries.length+mutations.length>1){if(process.env.NODE_ENV==="production"){throw new DataError("Too many ops",DataErrors.InvalidInput)}else {throw new DataError(`We only support one query or mutation per component. `+`${JSON.stringify(document)} had ${queries.length} queries and `+`${mutations.length} mutations. `,DataErrors.InvalidInput)}}const type=queries.length?DocumentTypes.query:DocumentTypes.mutation;const definitions=queries.length?queries:mutations;const definition=definitions[0];const variables=definition.variableDefinitions||[];const name=definition.name?.kind==="Name"?definition.name.value:"data";const payload={name,type,variables};cache.set(document,payload);return payload}
 
@@ -66,4 +68,6 @@ const useGqlRouterContext=(contextOverrides={})=>{const gqlRouterContext=useCont
 
 const useGql=(context={})=>{const gqlRouterContext=useGqlRouterContext(context);const gqlFetch=useCallback((operation,options=Object.freeze({}))=>{const{fetch,defaultContext}=gqlRouterContext;const{variables,context={}}=options;const finalContext=mergeGqlContext(defaultContext,context);return fetch(operation,variables,finalContext).then(response=>getGqlDataFromResponse(response))},[gqlRouterContext]);return gqlFetch};
 
-export { Data, DataError, DataErrors, FetchPolicy, GqlError, GqlErrors, GqlRouter, InterceptRequests, ScopedInMemoryCache, SerializableInMemoryCache, SharedCache, Status, TrackData, WhenClientSide, abortInflightRequests, fetchTrackedRequests, getGqlDataFromResponse, getGqlRequestId, graphQLDocumentNodeParser, hasTrackedRequestsToBeFetched, initializeHydrationCache, purgeCaches, purgeHydrationCache, toGqlOperation, useCachedEffect, useGql, useHydratableEffect, useServerEffect, useSharedCache };
+const isErrorResultGqlError=error=>error instanceof ErrorResultGqlError;
+
+export { Data, DataError, DataErrors, ErrorResultGqlError, FetchPolicy, GqlError, GqlErrors, GqlRouter, InterceptRequests, ScopedInMemoryCache, SerializableInMemoryCache, SharedCache, Status, TrackData, WhenClientSide, abortInflightRequests, fetchTrackedRequests, getGqlDataFromResponse, getGqlRequestId, graphQLDocumentNodeParser, hasTrackedRequestsToBeFetched, initializeHydrationCache, isErrorResultGqlError, purgeCaches, purgeHydrationCache, toGqlOperation, useCachedEffect, useGql, useHydratableEffect, useServerEffect, useSharedCache };

package/dist/index.d.ts

@@ -21,4 +21,6 @@ export { toGqlOperation } from "./util/to-gql-operation";
 export { GqlRouter } from "./components/gql-router";
 export { useGql } from "./hooks/use-gql";
 export { GqlError, GqlErrors } from "./util/gql-error";
-export type { GqlContext, GqlOperation, GqlOperationType, GqlFetchOptions, GqlFetchFn, } from "./util/gql-types";
+export { ErrorResultGqlError } from "./util/error-result-gql-error";
+export { isErrorResultGqlError } from "./util/is-error-result-gql-error";
+export type { GqlContext, GqlOperation, GqlOperationType, GqlFetchOptions, GqlFetchFn, GqlPartialData, GqlResponseError, GqlErrorResultPayload, } from "./util/gql-types";

package/dist/index.js

@@ -73,7 +73,9 @@ const toString=value=>{if(typeof value==="string"){return value}if(typeof value=
 
 const GqlErrors=Object.freeze({Internal:"Internal",BadResponse:"BadResponse",ErrorResult:"ErrorResult"});class GqlError extends wonderStuffCore.KindError{constructor(message,kind,{metadata,cause}={}){super(message,kind,{metadata,cause,name:"Gql"});}}
 
-const getGqlDataFromResponse=async response=>{const bodyText=await response.text();let result;try{result=JSON.parse(bodyText);}catch(e){throw new DataError("Failed to parse response",DataErrors.Parse,{metadata:{statusCode:response.status,bodyText},cause:e})}if(response.status>=300){throw new DataError("Response unsuccessful",DataErrors.Network,{metadata:{statusCode:response.status,result}})}if(!Object.prototype.hasOwnProperty.call(result,"data")&&!Object.prototype.hasOwnProperty.call(result,"errors")){throw new GqlError("Server response missing",GqlErrors.BadResponse,{metadata:{statusCode:response.status,result}})}if(result.errors!=null&&Array.isArray(result.errors)&&result.errors.length>0){throw new GqlError("GraphQL errors",GqlErrors.ErrorResult,{metadata:{statusCode:response.status,result}})}return result.data};
+class ErrorResultGqlError extends GqlError{constructor(statusCode,result){super("GraphQL errors",GqlErrors.ErrorResult,{metadata:{statusCode,result:result}});this.statusCode=statusCode;this.result=result;}}
+
+const getGqlDataFromResponse=async response=>{const bodyText=await response.text();let result;try{result=JSON.parse(bodyText);}catch(e){throw new DataError("Failed to parse response",DataErrors.Parse,{metadata:{statusCode:response.status,bodyText},cause:e})}if(response.status>=300){throw new DataError("Response unsuccessful",DataErrors.Network,{metadata:{statusCode:response.status,result}})}if(!Object.prototype.hasOwnProperty.call(result,"data")&&!Object.prototype.hasOwnProperty.call(result,"errors")){throw new GqlError("Server response missing",GqlErrors.BadResponse,{metadata:{statusCode:response.status,result}})}if(result.errors!=null&&Array.isArray(result.errors)&&result.errors.length>0){throw new ErrorResultGqlError(response.status,result)}return result.data};
 
 const DocumentTypes=Object.freeze({query:"query",mutation:"mutation"});const cache=new Map;function graphQLDocumentNodeParser(document){const cached=cache.get(document);if(cached){return cached}if(!document?.kind){if(process.env.NODE_ENV==="production"){throw new DataError("Bad DocumentNode",DataErrors.InvalidInput)}else {throw new DataError(`Argument of ${JSON.stringify(document)} passed to parser was not a valid GraphQL `+`DocumentNode. You may need to use 'graphql-tag' or another method `+`to convert your operation into a document`,DataErrors.InvalidInput)}}const fragments=document.definitions.filter(x=>x.kind==="FragmentDefinition");const queries=document.definitions.filter(x=>x.kind==="OperationDefinition"&&x.operation==="query");const mutations=document.definitions.filter(x=>x.kind==="OperationDefinition"&&x.operation==="mutation");const subscriptions=document.definitions.filter(x=>x.kind==="OperationDefinition"&&x.operation==="subscription");if(fragments.length&&!queries.length&&!mutations.length){if(process.env.NODE_ENV==="production"){throw new DataError("Fragment only",DataErrors.InvalidInput)}else {throw new DataError(`Passing only a fragment to 'graphql' is not supported. `+`You must include a query or mutation as well`,DataErrors.InvalidInput)}}if(subscriptions.length){if(process.env.NODE_ENV==="production"){throw new DataError("No subscriptions",DataErrors.InvalidInput)}else {throw new DataError(`We do not support subscriptions. `+`${JSON.stringify(document)} had ${subscriptions.length} subscriptions`,DataErrors.InvalidInput)}}if(queries.length+mutations.length>1){if(process.env.NODE_ENV==="production"){throw new DataError("Too many ops",DataErrors.InvalidInput)}else {throw new DataError(`We only support one query or mutation per component. `+`${JSON.stringify(document)} had ${queries.length} queries and `+`${mutations.length} mutations. `,DataErrors.InvalidInput)}}const type=queries.length?DocumentTypes.query:DocumentTypes.mutation;const definitions=queries.length?queries:mutations;const definition=definitions[0];const variables=definition.variableDefinitions||[];const name=definition.name?.kind==="Name"?definition.name.value:"data";const payload={name,type,variables};cache.set(document,payload);return payload}
 
@@ -89,9 +91,12 @@ const useGqlRouterContext=(contextOverrides={})=>{const gqlRouterContext=React.u
 
 const useGql=(context={})=>{const gqlRouterContext=useGqlRouterContext(context);const gqlFetch=React.useCallback((operation,options=Object.freeze({}))=>{const{fetch,defaultContext}=gqlRouterContext;const{variables,context={}}=options;const finalContext=mergeGqlContext(defaultContext,context);return fetch(operation,variables,finalContext).then(response=>getGqlDataFromResponse(response))},[gqlRouterContext]);return gqlFetch};
 
+const isErrorResultGqlError=error=>error instanceof ErrorResultGqlError;
+
 exports.Data = Data;
 exports.DataError = DataError;
 exports.DataErrors = DataErrors;
+exports.ErrorResultGqlError = ErrorResultGqlError;
 exports.FetchPolicy = FetchPolicy;
 exports.GqlError = GqlError;
 exports.GqlErrors = GqlErrors;
@@ -110,6 +115,7 @@ exports.getGqlRequestId = getGqlRequestId;
 exports.graphQLDocumentNodeParser = graphQLDocumentNodeParser;
 exports.hasTrackedRequestsToBeFetched = hasTrackedRequestsToBeFetched;
 exports.initializeHydrationCache = initializeHydrationCache;
+exports.isErrorResultGqlError = isErrorResultGqlError;
 exports.purgeCaches = purgeCaches;
 exports.purgeHydrationCache = purgeHydrationCache;
 exports.toGqlOperation = toGqlOperation;

package/dist/util/error-result-gql-error.d.ts

@@ -0,0 +1,26 @@
+import { GqlError } from "./gql-error";
+import type { GqlErrorResultPayload } from "./gql-types";
+/**
+ * A GraphQL response that completed but reported errors.
+ *
+ * GraphQL servers can return a valid response payload that carries both an
+ * `errors` array and a `data` object. Fields that failed are nulled, with the
+ * null propagating up to the nearest nullable ancestor, so the `data` that
+ * comes back is a partial version of the requested `TData`, or null if the
+ * whole result failed. This error exposes that payload with types so callers
+ * can make use of the partial data without guessing at the shape.
+ *
+ * The payload is also attached as `metadata` so that logging sees the same
+ * details it always did.
+ */
+export declare class ErrorResultGqlError<TData> extends GqlError {
+    /**
+     * The HTTP status code of the response.
+     */
+    readonly statusCode: number;
+    /**
+     * The parsed response payload, including the partial data and errors.
+     */
+    readonly result: GqlErrorResultPayload<TData>;
+    constructor(statusCode: number, result: GqlErrorResultPayload<TData>);
+}

package/dist/util/gql-types.d.ts

@@ -32,3 +32,36 @@ export type GqlFetchOptions<TVariables extends Record<any, any>, TContext extend
     variables?: TVariables;
     context?: Partial<TContext>;
 };
+/**
+ * The data of a GraphQL response that reported errors.
+ *
+ * Each top-level field is either the requested value or null. A field that
+ * errored is nulled, and that null propagates to the nearest nullable
+ * ancestor, so the top level of the result is the only level whose shape we
+ * can state with certainty.
+ */
+export type GqlPartialData<TData> = {
+    [K in keyof TData]: TData[K] | null;
+};
+/**
+ * An error entry from the `errors` array of a GraphQL response.
+ */
+export type GqlResponseError = {
+    message: string;
+    locations?: ReadonlyArray<{
+        line: number;
+        column: number;
+    }>;
+    path?: ReadonlyArray<string | number>;
+    extensions?: Record<string, unknown>;
+};
+/**
+ * The payload of a GraphQL response that reported errors.
+ *
+ * `data` is absent or null when the whole operation failed; otherwise it is
+ * the partial data the server was able to resolve.
+ */
+export type GqlErrorResultPayload<TData> = {
+    data?: GqlPartialData<TData> | null;
+    errors: ReadonlyArray<GqlResponseError>;
+};

package/dist/util/is-error-result-gql-error.d.ts

@@ -0,0 +1,12 @@
+import { ErrorResultGqlError } from "./error-result-gql-error";
+/**
+ * Determine if an error is an `ErrorResultGqlError`.
+ *
+ * The runtime check cannot verify the shape of the partial data, so `TData`
+ * is asserted rather than proven. Callers should only supply a `TData` that
+ * matches the operation whose response produced the error.
+ *
+ * @param error The value to check.
+ * @returns True if the error is an `ErrorResultGqlError`; otherwise, false.
+ */
+export declare const isErrorResultGqlError: <TData>(error: unknown) => error is ErrorResultGqlError<TData>;

package/package.json

@@ -3,7 +3,7 @@
   "description": "",
   "author": "Khan Academy",
   "license": "MIT",
-  "version": "15.0.3",
+  "version": "15.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -20,7 +20,7 @@
   "module": "dist/es/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@khanacademy/wonder-blocks-core": "12.4.4"
+    "@khanacademy/wonder-blocks-core": "12.5.0"
   },
   "peerDependencies": {
     "@khanacademy/wonder-stuff-core": "^3.0.0",
@@ -29,7 +29,7 @@
   "devDependencies": {
     "@khanacademy/wonder-stuff-testing": "^4.0.3",
     "@khanacademy/wb-dev-build-settings": "3.3.0",
-    "@khanacademy/wonder-blocks-testing-core": "5.1.1"
+    "@khanacademy/wonder-blocks-testing-core": "5.3.0"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"