@khanacademy/wonder-blocks-data 13.0.11 → 14.0.0

package/src/util/data-error.ts

@@ -1,63 +0,0 @@
-import {KindError} from "@khanacademy/wonder-stuff-core";
-import type {ErrorOptions} from "./types";
-
-/**
- * Error kinds for DataError.
- */
-export const DataErrors = Object.freeze({
-    /**
-     * The kind of error is not known.
-     */
-    Unknown: "Unknown",
-
-    /**
-     * The error is internal to the executing code.
-     */
-    Internal: "Internal",
-
-    /**
-     * There was a problem with the provided input.
-     */
-    InvalidInput: "InvalidInput",
-
-    /**
-     * A network error occurred.
-     */
-    Network: "Network",
-
-    /**
-     * There was a problem due to the state of the system not matching the
-     * requested operation or input.
-     */
-    NotAllowed: "NotAllowed",
-
-    /**
-     * Response could not be parsed.
-     */
-    Parse: "Parse",
-
-    /**
-     * An error that occurred during SSR and was hydrated from cache
-     */
-    Hydrated: "Hydrated",
-});
-
-/**
- * An error from the Wonder Blocks Data API.
- *
- * Errors of this type will have names of the format:
- *     `${kind}DataError`
- */
-export class DataError extends KindError {
-    constructor(
-        message: string,
-        kind: typeof DataErrors[keyof typeof DataErrors],
-        {metadata, cause}: ErrorOptions = {} as Partial<ErrorOptions>,
-    ) {
-        super(message, kind, {
-            metadata,
-            cause,
-            name: "Data",
-        });
-    }
-}

package/src/util/get-gql-data-from-response.ts

@@ -1,65 +0,0 @@
-import {DataError, DataErrors} from "./data-error";
-import {GqlError, GqlErrors} from "./gql-error";
-
-/**
- * Validate a GQL operation response and extract the data.
- */
-export const getGqlDataFromResponse = async <TData>(
-    response: Response,
-): Promise<TData> => {
-    // Get the response as text, that way we can use the text in error
-    // messaging, should our parsing fail.
-    const bodyText = await response.text();
-    let result;
-    try {
-        result = JSON.parse(bodyText);
-    } catch (e: any) {
-        throw new DataError("Failed to parse response", DataErrors.Parse, {
-            metadata: {
-                statusCode: response.status,
-                bodyText,
-            },
-            cause: e,
-        });
-    }
-
-    // Check for a bad status code.
-    if (response.status >= 300) {
-        throw new DataError("Response unsuccessful", DataErrors.Network, {
-            metadata: {
-                statusCode: response.status,
-                result,
-            },
-        });
-    }
-
-    // Check that we have a valid result payload.
-    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 the response payload has errors, throw an error.
-    if (
-        result.errors != null &&
-        Array.isArray(result.errors) &&
-        result.errors.length > 0
-    ) {
-        throw new GqlError("GraphQL errors", GqlErrors.ErrorResult, {
-            metadata: {
-                statusCode: response.status,
-                result,
-            },
-        });
-    }
-
-    // We got here, so return the data.
-    return result.data;
-};

package/src/util/get-gql-request-id.ts

@@ -1,106 +0,0 @@
-import {entries} from "@khanacademy/wonder-stuff-core";
-import type {GqlOperation, GqlContext} from "./gql-types";
-
-const toString = (value: unknown): string => {
-    if (typeof value === "string") {
-        return value;
-    }
-
-    if (typeof value === "object" && value != null) {
-        if (value instanceof Date) {
-            return value.toISOString();
-        } else if (typeof value.toString === "function") {
-            return value.toString();
-        }
-    }
-    return JSON.stringify(value) ?? "";
-};
-
-const toStringifiedVariables = (acc: any, key: string, value: unknown): any => {
-    if (typeof value === "object" && value !== null) {
-        // If we have an object or array, we build sub-variables so that
-        // the ID is easily human-readable rather than having lots of
-        // extra %-encodings. This means that an object or array variable
-        // turns into x variables, where x is the field or element count of
-        // variable. See below for example.
-        const subValues = entries(value);
-
-        // If we don't get any entries, it's possible this is a Date, Error,
-        // or some other non-standard value. While these generally should be
-        // avoided as variables, we should handle them gracefully.
-        if (subValues.length !== 0) {
-            return subValues.reduce((innerAcc, [i, v]: [any, any]) => {
-                const subKey = `${key}.${i}`;
-                return toStringifiedVariables(innerAcc, subKey, v);
-            }, acc);
-        }
-    }
-
-    acc[key] = toString(value);
-    return acc;
-};
-
-/**
- * Get an identifier for a given request.
- */
-export const getGqlRequestId = <TData, TVariables extends Record<any, any>>(
-    operation: GqlOperation<TData, TVariables>,
-    variables: TVariables | null | undefined,
-    context: GqlContext,
-): string => {
-    // We add all the bits for this into an array and then join them with
-    // a chosen separator.
-    const parts: Array<string> = [];
-
-    // First, we push the context values.
-    const sortableContext = new URLSearchParams(context);
-    sortableContext.sort();
-    parts.push(sortableContext.toString());
-
-    // Now we add the operation identifier.
-    parts.push(operation.id);
-
-    // Finally, if we have variables, we add those too.
-    if (variables != null) {
-        // We need to turn each variable into a string.
-        // We also need to ensure we sort any sub-object keys.
-        // `toStringifiedVariables` helps us with this by hoisting nested
-        // data to individual variables for the purposes of ID generation.
-        //
-        // For example, consider variables:
-        //    {x: [1,2,3], y: {a: 1, b: 2, c: 3}, z: 123}
-        //
-        // Each variable, x, y and z, would be stringified into
-        // stringifiedVariables as follows:
-        //  x becomes {"x.0": "1", "x.1": "2", "x.2": "3"}
-        //  y becomes {"y.a": "1", "y.b": "2", "y.c": "3"}
-        //  z becomes {"z": "123"}
-        //
-        // This then leads to stringifiedVariables being:
-        //  {
-        //    "x.0": "1",
-        //    "x.1": "2",
-        //    "x.2": "3",
-        //    "y.a": "1",
-        //    "y.b": "2",
-        //    "y.c": "3",
-        //    "z": "123",
-        //  }
-        //
-        // Thus allowing our use of URLSearchParams to both sort and easily
-        // encode the variables into an idempotent identifier for those
-        // variable values that is also human-readable.
-        const stringifiedVariables = Object.keys(variables).reduce<
-            Record<string, any>
-        >((acc, key) => {
-            const value = variables[key];
-            return toStringifiedVariables(acc, key, value);
-        }, {});
-        // We use the same mechanism as context to sort and arrange the
-        // variables.
-        const sortableVariables = new URLSearchParams(stringifiedVariables);
-        sortableVariables.sort();
-        parts.push(sortableVariables.toString());
-    }
-    return parts.join("|");
-};

package/src/util/gql-error.ts

@@ -1,43 +0,0 @@
-import {KindError} from "@khanacademy/wonder-stuff-core";
-
-import type {ErrorOptions} from "./types";
-
-/**
- * Error kinds for GqlError.
- */
-export const GqlErrors = Object.freeze({
-    /**
-     * An internal framework error.
-     */
-    Internal: "Internal",
-
-    /**
-     * Response does not have the correct structure for a GraphQL response.
-     */
-    BadResponse: "BadResponse",
-
-    /**
-     * A valid GraphQL result with errors field in the payload.
-     */
-    ErrorResult: "ErrorResult",
-});
-
-/**
- * An error from the GQL API.
- *
- * Errors of this type will have names of the format:
- *     `${kind}GqlError`
- */
-export class GqlError extends KindError {
-    constructor(
-        message: string,
-        kind: typeof GqlErrors[keyof typeof GqlErrors],
-        {metadata, cause}: ErrorOptions = {} as Partial<ErrorOptions>,
-    ) {
-        super(message, kind, {
-            metadata,
-            cause,
-            name: "Gql",
-        });
-    }
-}

package/src/util/gql-router-context.ts

@@ -1,9 +0,0 @@
-import * as React from "react";
-import type {GqlRouterConfiguration} from "./gql-types";
-
-const GqlRouterContext: React.Context<
-    GqlRouterConfiguration<any> | null | undefined
-> = React.createContext<GqlRouterConfiguration<any> | null | undefined>(null);
-GqlRouterContext.displayName = "GqlRouterContext";
-
-export {GqlRouterContext};

package/src/util/gql-types.ts

@@ -1,64 +0,0 @@
-/**
- * Operation types.
- */
-export type GqlOperationType = "mutation" | "query";
-
-/**
- * A GraphQL operation.
- */
-export type GqlOperation<
-    // TData is not used to define a field on this type, but it is used
-    // to ensure that calls using this operation will properly return the
-    // correct data type.
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    TData, // TVariables is not used to define a field on this type, but it is used
-    // to ensure that calls using this operation will properly consume the
-    // correct variables type.
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    TVariables extends object = Empty,
-> = {
-    type: GqlOperationType;
-    id: string;
-    // We allow other things here to be passed along to the fetch function.
-    // For example, we might want to pass the full query/mutation definition
-    // as a string here to allow that to be sent to an Apollo server that
-    // expects it. This is a courtesy to calling code; these additional
-    // values are ignored by WB Data, and passed through as-is.
-    [key: string]: unknown;
-};
-
-export type GqlContext = {
-    [key: string]: string;
-};
-
-/**
- * Functions that make fetches of GQL operations.
- */
-export type GqlFetchFn<
-    TData,
-    TVariables extends Record<any, any>,
-    TContext extends GqlContext,
-> = (
-    operation: GqlOperation<TData, TVariables>,
-    variables: TVariables | null | undefined,
-    context: TContext,
-) => Promise<Response>;
-
-/**
- * The configuration stored in the GqlRouterContext context.
- */
-export type GqlRouterConfiguration<TContext extends GqlContext> = {
-    fetch: GqlFetchFn<any, any, any>;
-    defaultContext: TContext;
-};
-
-/**
- * Options for configuring a GQL fetch.
- */
-export type GqlFetchOptions<
-    TVariables extends Record<any, any>,
-    TContext extends GqlContext,
-> = {
-    variables?: TVariables;
-    context?: Partial<TContext>;
-};

package/src/util/graphql-document-node-parser.ts

@@ -1,132 +0,0 @@
-import type {
-    DocumentNode,
-    DefinitionNode,
-    VariableDefinitionNode,
-    OperationDefinitionNode,
-} from "./graphql-types";
-import {DataError, DataErrors} from "./data-error";
-
-export const DocumentTypes = Object.freeze({
-    query: "query",
-    mutation: "mutation",
-});
-
-export type DocumentType = typeof DocumentTypes[keyof typeof DocumentTypes];
-
-export interface IDocumentDefinition {
-    type: DocumentType;
-    name: string;
-    variables: ReadonlyArray<VariableDefinitionNode>;
-}
-
-const cache = new Map<DocumentNode, IDocumentDefinition>();
-
-/**
- * Parse a GraphQL document node to determine some info about it.
- *
- * This is based on:
- * https://github.com/apollographql/react-apollo/blob/3bc993b2ea91704bd6a2667f42d1940656c071ff/src/parser.ts
- */
-export function graphQLDocumentNodeParser(
-    document: DocumentNode,
-): IDocumentDefinition {
-    const cached = cache.get(document);
-    if (cached) {
-        return cached;
-    }
-
-    /**
-     * Saftey check for proper usage.
-     */
-    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: DefinitionNode) => x.kind === "FragmentDefinition",
-    );
-
-    const queries = document.definitions.filter(
-        (x: DefinitionNode) =>
-            x.kind === "OperationDefinition" &&
-            (x as OperationDefinitionNode).operation === "query",
-    );
-
-    const mutations = document.definitions.filter(
-        (x: DefinitionNode) =>
-            x.kind === "OperationDefinition" &&
-            (x as OperationDefinitionNode).operation === "mutation",
-    );
-
-    const subscriptions = document.definitions.filter(
-        (x: DefinitionNode) =>
-            x.kind === "OperationDefinition" &&
-            (x as OperationDefinitionNode).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: OperationDefinitionNode = definitions[0] as any;
-    const variables = definition.variableDefinitions || [];
-
-    // fallback to using data if no name
-    const name =
-        definition.name?.kind === "Name" ? definition.name.value : "data";
-
-    const payload: IDocumentDefinition = {name, type, variables};
-    cache.set(document, payload);
-    return payload;
-}

package/src/util/graphql-types.ts

@@ -1,28 +0,0 @@
-// WARNING: If you modify this file you must update graphql-types.js.flow.
-// NOTE(somewhatabstract):
-// These types are bare minimum to support document parsing. They're derived
-// from graphql@14.5.8, the last version that provided TypeScript types.
-// Doing this avoids us having to take a dependency on that library just for
-// these types.
-export interface DefinitionNode {
-    readonly kind: string;
-}
-
-export type VariableDefinitionNode = {
-    readonly kind: "VariableDefinition";
-};
-
-export interface OperationDefinitionNode extends DefinitionNode {
-    readonly kind: "OperationDefinition";
-    readonly operation: string;
-    readonly variableDefinitions: ReadonlyArray<VariableDefinitionNode>;
-    readonly name?: {
-        readonly kind: unknown;
-        readonly value: string;
-    };
-}
-
-export type DocumentNode = {
-    readonly kind: "Document";
-    readonly definitions: ReadonlyArray<DefinitionNode>;
-};

package/src/util/hydration-cache-api.ts

@@ -1,30 +0,0 @@
-import {SsrCache} from "./ssr-cache";
-
-import type {ValidCacheData, CachedResponse, ResponseCache} from "./types";
-
-/**
- * Initialize the hydration cache.
- *
- * @param {ResponseCache} source The cache content to use for initializing the
- * cache.
- * @throws {Error} If the cache is already initialized.
- */
-export const initializeHydrationCache = (source: ResponseCache): void =>
-    SsrCache.Default.initialize(source);
-
-/**
- * Purge cached hydration responses that match the given predicate.
- *
- * @param {(id: string) => boolean} [predicate] The predicate to match against
- * the cached hydration responses. If no predicate is provided, all cached
- * hydration responses will be purged.
- */
-export const purgeHydrationCache = (
-    predicate?: (
-        key: string,
-        cacheEntry?:
-            | Readonly<CachedResponse<ValidCacheData>>
-            | null
-            | undefined,
-    ) => boolean,
-): void => SsrCache.Default.purgeData(predicate);

package/src/util/merge-gql-context.ts

@@ -1,35 +0,0 @@
-import type {GqlContext} from "./gql-types";
-
-/**
- * Construct a complete GqlContext from current defaults and a partial context.
- *
- * Values in the partial context that are `undefined` will be ignored.
- * Values in the partial context that are `null` will be deleted.
- */
-export const mergeGqlContext = <TContext extends GqlContext>(
-    defaultContext: TContext,
-    overrides: Partial<TContext>,
-): TContext => {
-    // Let's merge the partial context default context. We deliberately
-    // don't spread because spreading would overwrite default context
-    // values with undefined or null if the partial context includes a value
-    // explicitly set to undefined or null.
-    return Object.keys(overrides).reduce(
-        (acc, key) => {
-            // Undefined values are ignored.
-            if (overrides[key] !== undefined) {
-                if (overrides[key] === null) {
-                    // Null indicates we delete this context value.
-                    delete acc[key];
-                } else {
-                    // Otherwise, we set it.
-                    // @ts-expect-error TypeScript doesn't seem to see that
-                    // TContext can have string keys.
-                    acc[key] = overrides[key];
-                }
-            }
-            return acc;
-        },
-        {...defaultContext},
-    );
-};

package/src/util/purge-caches.ts

@@ -1,14 +0,0 @@
-import {SharedCache} from "../hooks/use-shared-cache";
-import {purgeHydrationCache} from "./hydration-cache-api";
-
-/**
- * Purge all caches managed by Wonder Blocks Data.
- *
- * This is a convenience method that purges the shared cache and the hydration
- * cache. It is useful for testing purposes to avoid having to reason about
- * which caches may have been used during a given test run.
- */
-export const purgeCaches = () => {
-    SharedCache.purgeAll();
-    purgeHydrationCache();
-};

package/src/util/request-api.ts

@@ -1,65 +0,0 @@
-import {Server} from "@khanacademy/wonder-blocks-core";
-import {RequestTracker} from "./request-tracking";
-import {RequestFulfillment} from "./request-fulfillment";
-import {DataError, DataErrors} from "./data-error";
-
-import type {ResponseCache} from "./types";
-
-const SSRCheck = () => {
-    if (Server.isServerSide()) {
-        return null;
-    }
-
-    if (process.env.NODE_ENV === "production") {
-        return new DataError("No CSR tracking", DataErrors.NotAllowed);
-    } else {
-        return new DataError(
-            "Data requests are not tracked for fulfillment when when client-side",
-            DataErrors.NotAllowed,
-        );
-    }
-};
-
-/**
- * Fetches all tracked data requests.
- *
- * This is for use with the `TrackData` component during server-side rendering.
- *
- * @throws {Error} If executed outside of server-side rendering.
- * @returns {Promise<void>} A promise that resolves when all tracked requests
- * have been fetched.
- */
-export const fetchTrackedRequests = (): Promise<ResponseCache> => {
-    const ssrCheck = SSRCheck();
-    if (ssrCheck != null) {
-        return Promise.reject(ssrCheck);
-    }
-    return RequestTracker.Default.fulfillTrackedRequests();
-};
-
-/**
- * Indicate if there are tracked requests waiting to be fetched.
- *
- * This is used in conjunction with `TrackData`.
- *
- * @throws {Error} If executed outside of server-side rendering.
- * @returns {boolean} `true` if there are unfetched tracked requests;
- * otherwise, `false`.
- */
-export const hasTrackedRequestsToBeFetched = (): boolean => {
-    const ssrCheck = SSRCheck();
-    if (ssrCheck != null) {
-        throw ssrCheck;
-    }
-    return RequestTracker.Default.hasUnfulfilledRequests;
-};
-
-/**
- * Abort all in-flight requests.
- *
- * This aborts all requests currently inflight via our default request
- * fulfillment.
- */
-export const abortInflightRequests = (): void => {
-    RequestFulfillment.Default.abortAll();
-};