@khanacademy/wonder-blocks-data 10.1.0 → 10.1.2

package/dist/hooks/use-cached-effect.d.ts

@@ -0,0 +1,70 @@
+import type { Result, ValidCacheData } from "../util/types";
+import { FetchPolicy } from "../util/types";
+type CachedEffectOptions<TData extends ValidCacheData> = {
+    /**
+     * The policy to use when determining how to retrieve the request data from
+     * cache and network.
+     *
+     * Defaults to `FetchPolicy.CacheBeforeNetwork`.
+     */
+    fetchPolicy?: typeof FetchPolicy[keyof typeof FetchPolicy];
+    /**
+     * When `true`, the effect will not be executed; otherwise, the effect will
+     * be executed.
+     *
+     * If this is set to `true` while the effect is still pending, the pending
+     * effect will be cancelled.
+     *
+     * Default is `false`.
+     */
+    skip?: boolean;
+    /**
+     * When `true`, the effect will not reset the result to the loading status
+     * while executing if the requestId changes, instead, returning
+     * the existing result from before the change; otherwise, the result will
+     * be set to loading status.
+     *
+     * If the status is loading when the changes are made, it will remain as
+     * loading; old pending effects are discarded on changes and as such this
+     * value has no effect in that case.
+     */
+    retainResultOnChange?: boolean;
+    /**
+     * Callback that is invoked if the result for the given hook has changed.
+     *
+     * When defined, the hook will invoke this callback whenever it has reason
+     * to change the result and will not otherwise affect component rendering
+     * directly.
+     *
+     * When not defined, the hook will ensure the component re-renders to pick
+     * up the latest result.
+     */
+    onResultChanged?: (result: Result<TData>) => void;
+    /**
+     * Scope to use with the shared cache.
+     *
+     * When specified, the given scope will be used to isolate this hook's
+     * cached results. Otherwise, a shared default scope will be used.
+     *
+     * Changing this value after the first call is not supported.
+     */
+    scope?: string;
+};
+/**
+ * Hook to execute and cache an async operation on the client.
+ *
+ * This hook executes the given handler on the client if there is no
+ * cached result to use.
+ *
+ * Results are cached so they can be shared between equivalent invocations.
+ * In-flight requests are also shared, so that concurrent calls will
+ * behave as one might exect. Cache updates invoked by one hook instance
+ * do not trigger renders in components that use the same requestID; however,
+ * that should not matter since concurrent requests will share the same
+ * in-flight request, and subsequent renders will grab from the cache.
+ *
+ * Once the request has been tried once and a non-loading response has been
+ * cached, the request will not executed made again.
+ */
+export declare const useCachedEffect: <TData extends ValidCacheData>(requestId: string, handler: () => Promise<TData>, options?: CachedEffectOptions<TData>) => [Result<TData>, () => void];
+export {};

package/dist/hooks/use-cached-effect.js.flow

@@ -0,0 +1,85 @@
+/**
+ * Flowtype definitions for use-cached-effect
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { Result, ValidCacheData } from "../util/types";
+import { FetchPolicy } from "../util/types";
+declare type CachedEffectOptions<TData: ValidCacheData> = {
+  /**
+   * The policy to use when determining how to retrieve the request data from
+   * cache and network.
+   *
+   * Defaults to `FetchPolicy.CacheBeforeNetwork`.
+   */
+  fetchPolicy?: $ElementType<typeof FetchPolicy, $Keys<typeof FetchPolicy>>,
+
+  /**
+   * When `true`, the effect will not be executed; otherwise, the effect will
+   * be executed.
+   *
+   * If this is set to `true` while the effect is still pending, the pending
+   * effect will be cancelled.
+   *
+   * Default is `false`.
+   */
+  skip?: boolean,
+
+  /**
+   * When `true`, the effect will not reset the result to the loading status
+   * while executing if the requestId changes, instead, returning
+   * the existing result from before the change; otherwise, the result will
+   * be set to loading status.
+   *
+   * If the status is loading when the changes are made, it will remain as
+   * loading; old pending effects are discarded on changes and as such this
+   * value has no effect in that case.
+   */
+  retainResultOnChange?: boolean,
+
+  /**
+   * Callback that is invoked if the result for the given hook has changed.
+   *
+   * When defined, the hook will invoke this callback whenever it has reason
+   * to change the result and will not otherwise affect component rendering
+   * directly.
+   *
+   * When not defined, the hook will ensure the component re-renders to pick
+   * up the latest result.
+   */
+  onResultChanged?: (result: Result<TData>) => void,
+
+  /**
+   * Scope to use with the shared cache.
+   *
+   * When specified, the given scope will be used to isolate this hook's
+   * cached results. Otherwise, a shared default scope will be used.
+   *
+   * Changing this value after the first call is not supported.
+   */
+  scope?: string,
+  ...
+};
+/**
+ * Hook to execute and cache an async operation on the client.
+ *
+ * This hook executes the given handler on the client if there is no
+ * cached result to use.
+ *
+ * Results are cached so they can be shared between equivalent invocations.
+ * In-flight requests are also shared, so that concurrent calls will
+ * behave as one might exect. Cache updates invoked by one hook instance
+ * do not trigger renders in components that use the same requestID; however,
+ * that should not matter since concurrent requests will share the same
+ * in-flight request, and subsequent renders will grab from the cache.
+ *
+ * Once the request has been tried once and a non-loading response has been
+ * cached, the request will not executed made again.
+ */
+declare export var useCachedEffect: <TData: ValidCacheData>(
+  requestId: string,
+  handler: () => Promise<TData>,
+  options?: CachedEffectOptions<TData>
+) => [Result<TData>, () => void];

package/dist/hooks/use-gql-router-context.d.ts

@@ -0,0 +1,5 @@
+import type { GqlRouterConfiguration, GqlContext } from "../util/gql-types";
+/**
+ * Construct a GqlRouterContext from the current one and partial context.
+ */
+export declare const useGqlRouterContext: <TContext extends GqlContext>(contextOverrides?: Partial<TContext>) => GqlRouterConfiguration<TContext>;

package/dist/hooks/use-gql-router-context.js.flow

@@ -0,0 +1,15 @@
+/**
+ * Flowtype definitions for use-gql-router-context
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { GqlRouterConfiguration, GqlContext } from "../util/gql-types";
+
+/**
+ * Construct a GqlRouterContext from the current one and partial context.
+ */
+declare export var useGqlRouterContext: <TContext: GqlContext>(
+  contextOverrides?: $Rest<TContext, { ... }>
+) => GqlRouterConfiguration<TContext>;

package/dist/hooks/use-gql.d.ts

@@ -0,0 +1,12 @@
+import type { GqlContext, GqlOperation, GqlFetchOptions } from "../util/gql-types";
+/**
+ * Hook to obtain a gqlFetch function for performing GraphQL requests.
+ *
+ * The fetch function will resolve null if the request was aborted, otherwise
+ * it will resolve the data returned by the GraphQL server.
+ *
+ * Context is merged with the default context provided to the GqlRouter.
+ * Values in the partial context given to the returned fetch function will
+ * only be included if they have a value other than undefined.
+ */
+export declare const useGql: <TContext extends GqlContext>(context?: Partial<TContext>) => <TData, TVariables extends Record<any, any>>(operation: GqlOperation<TData, TVariables>, options?: GqlFetchOptions<TVariables, TContext> | undefined) => Promise<TData>;

package/dist/hooks/use-gql.js.flow

@@ -0,0 +1,29 @@
+/**
+ * Flowtype definitions for use-gql
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type {
+  GqlContext,
+  GqlOperation,
+  GqlFetchOptions,
+} from "../util/gql-types";
+
+/**
+ * Hook to obtain a gqlFetch function for performing GraphQL requests.
+ *
+ * The fetch function will resolve null if the request was aborted, otherwise
+ * it will resolve the data returned by the GraphQL server.
+ *
+ * Context is merged with the default context provided to the GqlRouter.
+ * Values in the partial context given to the returned fetch function will
+ * only be included if they have a value other than undefined.
+ */
+declare export var useGql: <TContext: GqlContext>(
+  context?: $Rest<TContext, { ... }>
+) => <TData, TVariables: { [key: any]: any, ... }>(
+  operation: GqlOperation<TData, TVariables>,
+  options?: GqlFetchOptions<TVariables, TContext> | void
+) => Promise<TData>;

package/dist/hooks/use-hydratable-effect.d.ts

@@ -0,0 +1,102 @@
+import type { Result, ValidCacheData } from "../util/types";
+/**
+ * Policies to define how a hydratable effect should behave client-side.
+ */
+export declare const WhenClientSide: {
+    /**
+     * The result from executing the effect server-side will not be hydrated.
+     * The effect will always be executed client-side.
+     *
+     * This should only be used if there is something else that is responsible
+     * for properly hydrating this component (for example, the action invokes
+     * Apollo which manages its own cache to ensure things render properly).
+     */
+    readonly DoNotHydrate: "DoNotHydrate";
+    /**
+     * The result from executing the effect server-side will be hydrated.
+     * The effect will only execute client-side if there was no result to
+     * be hydrated (i.e. both error and success hydration results prevent the
+     * effect running client-side).
+     */
+    readonly ExecuteWhenNoResult: "ExecuteWhenNoResult";
+    /**
+     * The result from executing the effect server-side will be hydrated.
+     * If the hydrated result is a success result, the effect will not be
+     * executed client-side.
+     * If the hydrated result was not a success result, or there was no
+     * hydrated result, the effect will not be executed.
+     */
+    readonly ExecuteWhenNoSuccessResult: "ExecuteWhenNoSuccessResult";
+    /**
+     * The result from executing the effect server-side will be hydrated.
+     * The effect will always be executed client-side, regardless of the
+     * hydrated result status.
+     */
+    readonly AlwaysExecute: "AlwaysExecute";
+};
+type HydratableEffectOptions<TData extends ValidCacheData> = {
+    /**
+     * How the hook should behave when rendering client-side for the first time.
+     *
+     * This controls how the hook hydrates and executes when client-side.
+     *
+     * Default is `WhenClientSide.ExecuteWhenNoSuccessResult`.
+     *
+     * Changing this value after the first call is irrelevant as it only
+     * affects the initial render behavior.
+     */
+    clientBehavior?: typeof WhenClientSide[keyof typeof WhenClientSide];
+    /**
+     * When `true`, the effect will not be executed; otherwise, the effect will
+     * be executed.
+     *
+     * If this is set to `true` while the effect is still pending, the pending
+     * effect will be cancelled.
+     *
+     * Default is `false`.
+     */
+    skip?: boolean;
+    /**
+     * When `true`, the effect will not reset the result to the loading status
+     * while executing if the requestId changes, instead, returning
+     * the existing result from before the change; otherwise, the result will
+     * be set to loading status.
+     *
+     * If the status is loading when the changes are made, it will remain as
+     * loading; old pending effects are discarded on changes and as such this
+     * value has no effect in that case.
+     */
+    retainResultOnChange?: boolean;
+    /**
+     * Callback that is invoked if the result for the given hook has changed.
+     *
+     * When defined, the hook will invoke this callback whenever it has reason
+     * to change the result and will not otherwise affect component rendering
+     * directly.
+     *
+     * When not defined, the hook will ensure the component re-renders to pick
+     * up the latest result.
+     */
+    onResultChanged?: (result: Result<TData>) => void;
+    /**
+     * Scope to use with the shared cache.
+     *
+     * When specified, the given scope will be used to isolate this hook's
+     * cached results. Otherwise, a shared default scope will be used.
+     *
+     * Changing this value after the first call is not supported.
+     */
+    scope?: string;
+};
+/**
+ * Hook to execute an async operation on server and client.
+ *
+ * This hook executes the given handler on the server and on the client,
+ * and, depending on the given options, can hydrate the server-side result.
+ *
+ * Results are cached on the client so they can be shared between equivalent
+ * invocations. Cache changes from one hook instance do not trigger renders
+ * in components that use the same requestID.
+ */
+export declare const useHydratableEffect: <TData extends ValidCacheData>(requestId: string, handler: () => Promise<TData>, options?: HydratableEffectOptions<TData>) => Result<TData>;
+export {};

package/dist/hooks/use-hydratable-effect.js.flow

@@ -0,0 +1,125 @@
+/**
+ * Flowtype definitions for use-hydratable-effect
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { Result, ValidCacheData } from "../util/types";
+
+/**
+ * Policies to define how a hydratable effect should behave client-side.
+ */
+declare export var WhenClientSide: {
+  /**
+   * The result from executing the effect server-side will not be hydrated.
+   * The effect will always be executed client-side.
+   *
+   * This should only be used if there is something else that is responsible
+   * for properly hydrating this component (for example, the action invokes
+   * Apollo which manages its own cache to ensure things render properly).
+   */
+  +DoNotHydrate: "DoNotHydrate",
+
+  /**
+   * The result from executing the effect server-side will be hydrated.
+   * The effect will only execute client-side if there was no result to
+   * be hydrated (i.e. both error and success hydration results prevent the
+   * effect running client-side).
+   */
+  +ExecuteWhenNoResult: "ExecuteWhenNoResult",
+
+  /**
+   * The result from executing the effect server-side will be hydrated.
+   * If the hydrated result is a success result, the effect will not be
+   * executed client-side.
+   * If the hydrated result was not a success result, or there was no
+   * hydrated result, the effect will not be executed.
+   */
+  +ExecuteWhenNoSuccessResult: "ExecuteWhenNoSuccessResult",
+
+  /**
+   * The result from executing the effect server-side will be hydrated.
+   * The effect will always be executed client-side, regardless of the
+   * hydrated result status.
+   */
+  +AlwaysExecute: "AlwaysExecute",
+  ...
+};
+declare type HydratableEffectOptions<TData: ValidCacheData> = {
+  /**
+   * How the hook should behave when rendering client-side for the first time.
+   *
+   * This controls how the hook hydrates and executes when client-side.
+   *
+   * Default is `WhenClientSide.ExecuteWhenNoSuccessResult`.
+   *
+   * Changing this value after the first call is irrelevant as it only
+   * affects the initial render behavior.
+   */
+  clientBehavior?: $ElementType<
+    typeof WhenClientSide,
+    $Keys<typeof WhenClientSide>
+  >,
+
+  /**
+   * When `true`, the effect will not be executed; otherwise, the effect will
+   * be executed.
+   *
+   * If this is set to `true` while the effect is still pending, the pending
+   * effect will be cancelled.
+   *
+   * Default is `false`.
+   */
+  skip?: boolean,
+
+  /**
+   * When `true`, the effect will not reset the result to the loading status
+   * while executing if the requestId changes, instead, returning
+   * the existing result from before the change; otherwise, the result will
+   * be set to loading status.
+   *
+   * If the status is loading when the changes are made, it will remain as
+   * loading; old pending effects are discarded on changes and as such this
+   * value has no effect in that case.
+   */
+  retainResultOnChange?: boolean,
+
+  /**
+   * Callback that is invoked if the result for the given hook has changed.
+   *
+   * When defined, the hook will invoke this callback whenever it has reason
+   * to change the result and will not otherwise affect component rendering
+   * directly.
+   *
+   * When not defined, the hook will ensure the component re-renders to pick
+   * up the latest result.
+   */
+  onResultChanged?: (result: Result<TData>) => void,
+
+  /**
+   * Scope to use with the shared cache.
+   *
+   * When specified, the given scope will be used to isolate this hook's
+   * cached results. Otherwise, a shared default scope will be used.
+   *
+   * Changing this value after the first call is not supported.
+   */
+  scope?: string,
+  ...
+};
+/**
+ * Hook to execute an async operation on server and client.
+ *
+ * This hook executes the given handler on the server and on the client,
+ * and, depending on the given options, can hydrate the server-side result.
+ *
+ * Results are cached on the client so they can be shared between equivalent
+ * invocations. Cache changes from one hook instance do not trigger renders
+ * in components that use the same requestID.
+ */
+declare export var useHydratableEffect: <TData: ValidCacheData>(
+  requestId: string,
+  handler: () => Promise<TData>,
+  options?: HydratableEffectOptions<TData>
+) => Result<TData>;

package/dist/hooks/use-request-interception.d.ts

@@ -0,0 +1,14 @@
+import type { ValidCacheData } from "../util/types";
+/**
+ * Allow request handling to be intercepted.
+ *
+ * Hook to take a uniquely identified request handler and return a
+ * method that will support request interception from the InterceptRequest
+ * component.
+ *
+ * If you want request interception to be supported with `useServerEffect` or
+ * any client-side effect that uses the handler, call this first to generate
+ * an intercepted handler, and then invoke `useServerEffect` (or other things)
+ * with that intercepted handler.
+ */
+export declare const useRequestInterception: <TData extends ValidCacheData>(requestId: string, handler: () => Promise<TData>) => () => Promise<TData>;

package/dist/hooks/use-request-interception.js.flow

@@ -0,0 +1,25 @@
+/**
+ * Flowtype definitions for use-request-interception
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { ValidCacheData } from "../util/types";
+
+/**
+ * Allow request handling to be intercepted.
+ *
+ * Hook to take a uniquely identified request handler and return a
+ * method that will support request interception from the InterceptRequest
+ * component.
+ *
+ * If you want request interception to be supported with `useServerEffect` or
+ * any client-side effect that uses the handler, call this first to generate
+ * an intercepted handler, and then invoke `useServerEffect` (or other things)
+ * with that intercepted handler.
+ */
+declare export var useRequestInterception: <TData: ValidCacheData>(
+  requestId: string,
+  handler: () => Promise<TData>
+) => () => Promise<TData>;

package/dist/hooks/use-server-effect.d.ts

@@ -0,0 +1,39 @@
+import type { Result, ValidCacheData } from "../util/types";
+type ServerEffectOptions = {
+    /**
+     * When `true`, the result of the effect when fulfilled using Wonder Blocks
+     * Data will be stored in the hydration cache for hydrating client-side;
+     * otherwise, the result will be stored in the server-side-only cache.
+     *
+     * This should only be set to `false` if something else will be responsible
+     * for hydration of the data on the client-side (for example, if Apollo's
+     * hydration support is used).
+     *
+     * Default is `true`.
+     */
+    hydrate?: boolean;
+    /**
+     * When `true`, the effect will not be tracked for fulfillment; otherwise,
+     * the effect will be tracked for fulfillment.
+     *
+     * Default is `false`.
+     */
+    skip?: boolean;
+};
+/**
+ * Hook to perform an asynchronous action during server-side rendering.
+ *
+ * This hook registers an asynchronous action to be performed during
+ * server-side rendering. The action is performed only once, and the result
+ * is cached against the given identifier so that subsequent calls return that
+ * cached result allowing components to render more of the component.
+ *
+ * This hook requires the Wonder Blocks Data functionality for resolving
+ * pending requests, as well as support for the hydration cache to be
+ * embedded into a page so that the result can by hydrated (if that is a
+ * requirement).
+ *
+ * The asynchronous action is never invoked on the client-side.
+ */
+export declare const useServerEffect: <TData extends ValidCacheData>(requestId: string, handler: () => Promise<TData>, options?: ServerEffectOptions) => Result<TData> | null | undefined;
+export {};

package/dist/hooks/use-server-effect.js.flow

@@ -0,0 +1,51 @@
+/**
+ * Flowtype definitions for use-server-effect
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { Result, ValidCacheData } from "../util/types";
+declare type ServerEffectOptions = {
+  /**
+   * When `true`, the result of the effect when fulfilled using Wonder Blocks
+   * Data will be stored in the hydration cache for hydrating client-side;
+   * otherwise, the result will be stored in the server-side-only cache.
+   *
+   * This should only be set to `false` if something else will be responsible
+   * for hydration of the data on the client-side (for example, if Apollo's
+   * hydration support is used).
+   *
+   * Default is `true`.
+   */
+  hydrate?: boolean,
+
+  /**
+   * When `true`, the effect will not be tracked for fulfillment; otherwise,
+   * the effect will be tracked for fulfillment.
+   *
+   * Default is `false`.
+   */
+  skip?: boolean,
+  ...
+};
+/**
+ * Hook to perform an asynchronous action during server-side rendering.
+ *
+ * This hook registers an asynchronous action to be performed during
+ * server-side rendering. The action is performed only once, and the result
+ * is cached against the given identifier so that subsequent calls return that
+ * cached result allowing components to render more of the component.
+ *
+ * This hook requires the Wonder Blocks Data functionality for resolving
+ * pending requests, as well as support for the hydration cache to be
+ * embedded into a page so that the result can by hydrated (if that is a
+ * requirement).
+ *
+ * The asynchronous action is never invoked on the client-side.
+ */
+declare export var useServerEffect: <TData: ValidCacheData>(
+  requestId: string,
+  handler: () => Promise<TData>,
+  options?: ServerEffectOptions
+) => Result<TData> | null | void;

package/dist/hooks/use-shared-cache.d.ts

@@ -0,0 +1,32 @@
+import type { ValidCacheData, ScopedCache } from "../util/types";
+/**
+ * A function for inserting a value into the cache or clearing it.
+ */
+type CacheValueFn<TValue extends ValidCacheData> = (value?: TValue | null | undefined) => void;
+/**
+ * Access to the shared in-memory cache.
+ *
+ * This is the cache used by `useSharedCache` and related hooks and
+ * components.
+ */
+export declare const SharedCache: ScopedCache;
+/**
+ * Hook to retrieve data from and store data in an in-memory cache.
+ *
+ * @returns {[?ReadOnlyCacheValue, CacheValueFn]}
+ * Returns an array containing the current cache entry (or undefined), a
+ * function to set the cache entry (passing null or undefined to this function
+ * will delete the entry).
+ *
+ * NOTE: Unlike useState or useReducer, we don't automatically update folks
+ * if the value they reference changes. We might add it later (if we need to),
+ * but the likelihood here is that things won't be changing in this cache in a
+ * way where we would need that. If we do (and likely only in specific
+ * circumstances), we should consider adding a simple boolean useState that can
+ * be toggled to cause a rerender whenever the referenced cached data changes
+ * so that callers can re-render on cache changes. However, we should make
+ * sure this toggling is optional - or we could use a callback argument, to
+ * achieve this on an as-needed basis.
+ */
+export declare const useSharedCache: <TValue extends ValidCacheData>(id: string, scope: string, initialValue?: TValue | (() => TValue | null | undefined) | null | undefined) => [TValue | null | undefined, CacheValueFn<TValue>];
+export {};

package/dist/hooks/use-shared-cache.js.flow

@@ -0,0 +1,43 @@
+/**
+ * Flowtype definitions for use-shared-cache
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { ValidCacheData, ScopedCache } from "../util/types";
+
+/**
+ * A function for inserting a value into the cache or clearing it.
+ */
+declare type CacheValueFn<TValue: ValidCacheData> = (
+  value?: TValue | null | void
+) => void;
+/**
+ * Access to the shared in-memory cache.
+ *
+ * This is the cache used by `useSharedCache` and related hooks and
+ * components.
+ */
+declare export var SharedCache: ScopedCache;
+/**
+ * Hook to retrieve data from and store data in an in-memory cache.
+ * @returns {[?ReadOnlyCacheValue, CacheValueFn]} Returns an array containing the current cache entry (or undefined), a
+ * function to set the cache entry (passing null or undefined to this function
+ * will delete the entry).
+ *
+ * NOTE: Unlike useState or useReducer, we don't automatically update folks
+ * if the value they reference changes. We might add it later (if we need to),
+ * but the likelihood here is that things won't be changing in this cache in a
+ * way where we would need that. If we do (and likely only in specific
+ * circumstances), we should consider adding a simple boolean useState that can
+ * be toggled to cause a rerender whenever the referenced cached data changes
+ * so that callers can re-render on cache changes. However, we should make
+ * sure this toggling is optional - or we could use a callback argument, to
+ * achieve this on an as-needed basis.
+ */
+declare export var useSharedCache: <TValue: ValidCacheData>(
+  id: string,
+  scope: string,
+  initialValue?: TValue | (() => TValue | null | void) | null | void
+) => [TValue | null | void, CacheValueFn<TValue>];