@khanacademy/wonder-blocks-data 10.1.0 → 10.1.2

package/dist/index.js.flow

@@ -1,2 +1,48 @@
-// @flow
-export * from "../src/index";
+/**
+ * Flowtype definitions for index
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+declare export { FetchPolicy } from "./util/types";
+export type {
+  ErrorOptions,
+  ResponseCache,
+  CachedResponse,
+  Result,
+  RawScopedCache,
+  ValidCacheData,
+  ScopedCache,
+} from "./util/types";
+declare export * from "./util/hydration-cache-api";
+declare export * from "./util/request-api";
+declare export { purgeCaches } from "./util/purge-caches";
+declare export { default as TrackData } from "./components/track-data";
+declare export { default as Data } from "./components/data";
+declare export { default as InterceptRequests } from "./components/intercept-requests";
+declare export { DataError, DataErrors } from "./util/data-error";
+declare export { useServerEffect } from "./hooks/use-server-effect";
+declare export { useCachedEffect } from "./hooks/use-cached-effect";
+declare export { useSharedCache, SharedCache } from "./hooks/use-shared-cache";
+declare export {
+  useHydratableEffect,
+  WhenClientSide,
+} from "./hooks/use-hydratable-effect";
+declare export { ScopedInMemoryCache } from "./util/scoped-in-memory-cache";
+declare export { SerializableInMemoryCache } from "./util/serializable-in-memory-cache";
+declare export { Status } from "./util/status";
+declare export { getGqlRequestId } from "./util/get-gql-request-id";
+declare export { getGqlDataFromResponse } from "./util/get-gql-data-from-response";
+declare export { graphQLDocumentNodeParser } from "./util/graphql-document-node-parser";
+declare export { toGqlOperation } from "./util/to-gql-operation";
+declare export { GqlRouter } from "./components/gql-router";
+declare export { useGql } from "./hooks/use-gql";
+declare export { GqlError, GqlErrors } from "./util/gql-error";
+export type {
+  GqlContext,
+  GqlOperation,
+  GqlOperationType,
+  GqlFetchOptions,
+  GqlFetchFn,
+} from "./util/gql-types";

package/dist/util/data-error.d.ts

@@ -0,0 +1,45 @@
+import { KindError } from "@khanacademy/wonder-stuff-core";
+import type { ErrorOptions } from "./types";
+/**
+ * Error kinds for DataError.
+ */
+export declare const DataErrors: Readonly<{
+    /**
+     * 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 declare class DataError extends KindError {
+    constructor(message: string, kind: typeof DataErrors[keyof typeof DataErrors], { metadata, cause }?: ErrorOptions);
+}

package/dist/util/data-error.js.flow

@@ -0,0 +1,64 @@
+/**
+ * Flowtype definitions for data-error
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import { KindError } from "@khanacademy/wonder-stuff-core";
+import type { ErrorOptions } from "./types";
+
+/**
+ * Error kinds for DataError.
+ */
+declare export var DataErrors: $ReadOnly<{
+  /**
+   * 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`
+ */
+declare export class DataError extends KindError {
+  constructor(
+    message: string,
+    kind: $ElementType<typeof DataErrors, $Keys<typeof DataErrors>>,
+    x?: ErrorOptions
+  ): this;
+}

package/dist/util/get-gql-data-from-response.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Validate a GQL operation response and extract the data.
+ */
+export declare const getGqlDataFromResponse: <TData>(response: Response) => Promise<TData>;

package/dist/util/get-gql-data-from-response.js.flow

@@ -0,0 +1,13 @@
+/**
+ * Flowtype definitions for get-gql-data-from-response
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+/**
+ * Validate a GQL operation response and extract the data.
+ */
+declare export var getGqlDataFromResponse: <TData>(
+  response: Response
+) => Promise<TData>;

package/dist/util/get-gql-request-id.d.ts

@@ -0,0 +1,5 @@
+import type { GqlOperation, GqlContext } from "./gql-types";
+/**
+ * Get an identifier for a given request.
+ */
+export declare const getGqlRequestId: <TData, TVariables extends Record<any, any>>(operation: GqlOperation<TData, TVariables>, variables: TVariables | null | undefined, context: GqlContext) => string;

package/dist/util/get-gql-request-id.js.flow

@@ -0,0 +1,20 @@
+/**
+ * Flowtype definitions for get-gql-request-id
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { GqlOperation, GqlContext } from "./gql-types";
+
+/**
+ * Get an identifier for a given request.
+ */
+declare export var getGqlRequestId: <
+  TData,
+  TVariables: { [key: any]: any, ... }
+>(
+  operation: GqlOperation<TData, TVariables>,
+  variables: TVariables | null | void,
+  context: GqlContext
+) => string;

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

@@ -0,0 +1,28 @@
+import { KindError } from "@khanacademy/wonder-stuff-core";
+import type { ErrorOptions } from "./types";
+/**
+ * Error kinds for GqlError.
+ */
+export declare const GqlErrors: Readonly<{
+    /**
+     * 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 declare class GqlError extends KindError {
+    constructor(message: string, kind: typeof GqlErrors[keyof typeof GqlErrors], { metadata, cause }?: ErrorOptions);
+}

package/dist/util/gql-error.js.flow

@@ -0,0 +1,43 @@
+/**
+ * Flowtype definitions for gql-error
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import { KindError } from "@khanacademy/wonder-stuff-core";
+import type { ErrorOptions } from "./types";
+
+/**
+ * Error kinds for GqlError.
+ */
+declare export var GqlErrors: $ReadOnly<{
+  /**
+   * 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`
+ */
+declare export class GqlError extends KindError {
+  constructor(
+    message: string,
+    kind: $ElementType<typeof GqlErrors, $Keys<typeof GqlErrors>>,
+    x?: ErrorOptions
+  ): this;
+}

package/dist/util/gql-router-context.d.ts

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

package/dist/util/gql-router-context.js.flow

@@ -0,0 +1,10 @@
+/**
+ * Flowtype definitions for gql-router-context
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import type { GqlRouterConfiguration } from "./gql-types";
+declare export var GqlRouterContext: React.Context<GqlRouterConfiguration<any> | null | void>;

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

@@ -0,0 +1,34 @@
+/**
+ * Operation types.
+ */
+export type GqlOperationType = "mutation" | "query";
+/**
+ * A GraphQL operation.
+ */
+export type GqlOperation<TData, // TVariables is not used to define a field on this type, but it is used
+TVariables extends object = Empty> = {
+    type: GqlOperationType;
+    id: string;
+    [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/dist/util/gql-types.js.flow

@@ -0,0 +1,53 @@
+/**
+ * Flowtype definitions for gql-types
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+/**
+ * Operation types.
+ */
+export type GqlOperationType = "mutation" | "query";
+/**
+ * A GraphQL operation.
+ */
+export type GqlOperation<TData, TVariables: { [key: string]: any } = Empty> = {
+  type: GqlOperationType,
+  id: string,
+  [key: string]: mixed,
+};
+export type GqlContext = {
+  [key: string]: string,
+};
+/**
+ * Functions that make fetches of GQL operations.
+ */
+export type GqlFetchFn<
+  TData,
+  TVariables: { [key: any]: any, ... },
+  TContext: GqlContext
+> = (
+  operation: GqlOperation<TData, TVariables>,
+  variables: TVariables | null | void,
+  context: TContext
+) => Promise<Response>;
+/**
+ * The configuration stored in the GqlRouterContext context.
+ */
+export type GqlRouterConfiguration<TContext: GqlContext> = {
+  fetch: GqlFetchFn<any, any, any>,
+  defaultContext: TContext,
+  ...
+};
+/**
+ * Options for configuring a GQL fetch.
+ */
+export type GqlFetchOptions<
+  TVariables: { [key: any]: any, ... },
+  TContext: GqlContext
+> = {
+  variables?: TVariables,
+  context?: $Rest<TContext, { ... }>,
+  ...
+};

package/dist/util/graphql-document-node-parser.d.ts

@@ -0,0 +1,18 @@
+import type { DocumentNode, VariableDefinitionNode } from "./graphql-types";
+export declare const DocumentTypes: Readonly<{
+    query: "query";
+    mutation: "mutation";
+}>;
+export type DocumentType = typeof DocumentTypes[keyof typeof DocumentTypes];
+export interface IDocumentDefinition {
+    type: DocumentType;
+    name: string;
+    variables: ReadonlyArray<VariableDefinitionNode>;
+}
+/**
+ * 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 declare function graphQLDocumentNodeParser(document: DocumentNode): IDocumentDefinition;

package/dist/util/graphql-document-node-parser.js.flow

@@ -0,0 +1,31 @@
+/**
+ * Flowtype definitions for graphql-document-node-parser
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { DocumentNode, VariableDefinitionNode } from "./graphql-types";
+declare export var DocumentTypes: $ReadOnly<{
+  query: "query",
+  mutation: "mutation",
+  ...
+}>;
+export type DocumentType = $ElementType<
+  typeof DocumentTypes,
+  $Keys<typeof DocumentTypes>
+>;
+export interface IDocumentDefinition {
+  type: DocumentType;
+  name: string;
+  variables: $ReadOnlyArray<VariableDefinitionNode>;
+}
+/**
+ * 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
+ */
+declare export function graphQLDocumentNodeParser(
+  document: DocumentNode
+): IDocumentDefinition;

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

@@ -0,0 +1,19 @@
+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/dist/util/graphql-types.js.flow

@@ -0,0 +1,30 @@
+/**
+ * Flowtype definitions for graphql-types
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+export interface DefinitionNode {
+  +kind: string;
+}
+export type VariableDefinitionNode = {
+  +kind: "VariableDefinition",
+  ...
+};
+export type OperationDefinitionNode = {
+  +kind: "OperationDefinition",
+  +operation: string,
+  +variableDefinitions: $ReadOnlyArray<VariableDefinitionNode>,
+  +name?: {
+    +kind: mixed,
+    +value: string,
+    ...
+  },
+  ...
+} & DefinitionNode;
+export type DocumentNode = {
+  +kind: "Document",
+  +definitions: $ReadOnlyArray<DefinitionNode>,
+  ...
+};

package/dist/util/hydration-cache-api.d.ts

@@ -0,0 +1,17 @@
+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 declare const initializeHydrationCache: (source: ResponseCache) => void;
+/**
+ * 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 declare const purgeHydrationCache: (predicate?: ((key: string, cacheEntry?: Readonly<CachedResponse<ValidCacheData>> | null | undefined) => boolean) | undefined) => void;

package/dist/util/hydration-cache-api.js.flow

@@ -0,0 +1,30 @@
+/**
+ * Flowtype definitions for hydration-cache-api
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+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.
+ */
+declare export var initializeHydrationCache: (source: ResponseCache) => void;
+/**
+ * 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.
+ */
+declare export var purgeHydrationCache: (
+  predicate?:
+    | ((
+        key: string,
+        cacheEntry?: $ReadOnly<CachedResponse<ValidCacheData>> | null | void
+      ) => boolean)
+    | void
+) => void;

package/dist/util/merge-gql-context.d.ts

@@ -0,0 +1,8 @@
+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 declare const mergeGqlContext: <TContext extends GqlContext>(defaultContext: TContext, overrides: Partial<TContext>) => TContext;

package/dist/util/merge-gql-context.js.flow

@@ -0,0 +1,19 @@
+/**
+ * Flowtype definitions for merge-gql-context
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+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.
+ */
+declare export var mergeGqlContext: <TContext: GqlContext>(
+  defaultContext: TContext,
+  overrides: $Rest<TContext, { ... }>
+) => TContext;

package/dist/util/purge-caches.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare const purgeCaches: () => void;

package/dist/util/purge-caches.js.flow

@@ -0,0 +1,15 @@
+/**
+ * Flowtype definitions for purge-caches
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+/**
+ * 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.
+ */
+declare export var purgeCaches: () => void;

package/dist/util/request-api.d.ts

@@ -0,0 +1,28 @@
+import type { ResponseCache } from "./types";
+/**
+ * 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 declare const fetchTrackedRequests: () => Promise<ResponseCache>;
+/**
+ * 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 declare const hasTrackedRequestsToBeFetched: () => boolean;
+/**
+ * Abort all in-flight requests.
+ *
+ * This aborts all requests currently inflight via our default request
+ * fulfillment.
+ */
+export declare const abortInflightRequests: () => void;

package/dist/util/request-api.js.flow

@@ -0,0 +1,34 @@
+/**
+ * Flowtype definitions for request-api
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { ResponseCache } from "./types";
+
+/**
+ * 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.
+ */
+declare export var fetchTrackedRequests: () => Promise<ResponseCache>;
+/**
+ * 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`.
+ */
+declare export var hasTrackedRequestsToBeFetched: () => boolean;
+/**
+ * Abort all in-flight requests.
+ *
+ * This aborts all requests currently inflight via our default request
+ * fulfillment.
+ */
+declare export var abortInflightRequests: () => void;