@khanacademy/wonder-blocks-data 13.0.11 → 14.0.0

package/src/hooks/use-hydratable-effect.ts

@@ -1,201 +0,0 @@
-import * as React from "react";
-
-import {useServerEffect} from "./use-server-effect";
-import {useSharedCache} from "./use-shared-cache";
-import {useCachedEffect} from "./use-cached-effect";
-
-import {FetchPolicy} from "../util/types";
-import type {Result, ValidCacheData} from "../util/types";
-
-/**
- * Policies to define how a hydratable effect should behave client-side.
- */
-export enum 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",
-}
-
-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;
-};
-
-const DefaultScope = "useHydratableEffect";
-
-/**
- * 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 const useHydratableEffect = <TData extends ValidCacheData>(
-    requestId: string,
-    handler: () => Promise<TData>,
-    options: HydratableEffectOptions<TData> = {} as Partial<
-        HydratableEffectOptions<TData>
-    >,
-): Result<TData> => {
-    const {
-        clientBehavior = WhenClientSide.ExecuteWhenNoSuccessResult,
-        skip = false,
-        retainResultOnChange = false,
-        onResultChanged,
-        scope = DefaultScope,
-    } = options;
-
-    // Now we instruct the server to perform the operation.
-    // When client-side, this will look up any response for hydration; it does
-    // not invoke the handler.
-    const serverResult = useServerEffect(requestId, handler, {
-        // Only hydrate if our behavior isn't telling us not to.
-        hydrate: clientBehavior !== WhenClientSide.DoNotHydrate,
-        skip,
-    });
-
-    const getDefaultCacheValue: () => Result<TData> | null | undefined =
-        React.useCallback(() => {
-            // If we don't have a requestId, it's our first render, the one
-            // where we hydrated. So defer to our clientBehavior value.
-            switch (clientBehavior) {
-                case WhenClientSide.DoNotHydrate:
-                case WhenClientSide.AlwaysExecute:
-                    // Either we weren't hydrating at all, or we don't care
-                    // if we hydrated something or not, either way, we're
-                    // doing a request.
-                    return null;
-
-                case WhenClientSide.ExecuteWhenNoResult:
-                    // We only execute if we didn't hydrate something.
-                    // So, returning the hydration result as default for our
-                    // cache, will then prevent the cached effect running.
-                    return serverResult;
-
-                case WhenClientSide.ExecuteWhenNoSuccessResult:
-                    // We only execute if we didn't hydrate a success result.
-                    if (serverResult?.status === "success") {
-                        // So, returning the hydration result as default for our
-                        // cache, will then prevent the cached effect running.
-                        return serverResult;
-                    }
-                    return null;
-            }
-            // There is no reason for this to change after the first render,
-            // you might think, but the function closes around serverResult and if
-            // the requestId changes, it still returns the hydrate result of the
-            // first render of the previous requestId. This then means that the
-            // hydrate result is still the same, and the effect is not re-executed
-            // because the cache gets incorrectly defaulted.
-            // However, we don't want to bother doing anything with this on
-            // client behavior changing since that truly is irrelevant.
-            // eslint-disable-next-line react-hooks/exhaustive-deps
-        }, [serverResult]);
-
-    // Instead of using state, which would be local to just this hook instance,
-    // we use a shared in-memory cache.
-    useSharedCache<Result<TData>>( // The key of the cached item
-        requestId, // The scope of the cached items
-        scope,
-        getDefaultCacheValue,
-    );
-
-    // When we're client-side, we ultimately want the result from this call.
-    const [clientResult] = useCachedEffect(requestId, handler, {
-        skip,
-        onResultChanged,
-        retainResultOnChange,
-        scope,
-        // Be explicit about our fetch policy for clarity.
-        fetchPolicy: FetchPolicy.CacheBeforeNetwork,
-    });
-
-    // OK, now which result do we return.
-    // Well, we return the serverResult on our very first call and then
-    // the clientResult thereafter. The great thing is that after the very
-    // first call, the serverResult is going to be `null` anyway.
-    return serverResult ?? clientResult;
-};

package/src/hooks/use-request-interception.ts

@@ -1,53 +0,0 @@
-import * as React from "react";
-
-import InterceptContext from "../components/intercept-context";
-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 const useRequestInterception = <TData extends ValidCacheData>(
-    requestId: string,
-    handler: () => Promise<TData>,
-): (() => Promise<TData>) => {
-    // Get the interceptors that have been registered.
-    const interceptors = React.useContext(InterceptContext);
-
-    // Now, we need to create a new handler that will check if the
-    // request is intercepted before ultimately calling the original handler
-    // if nothing intercepted it.
-    // We memoize this so that it only changes if something related to it
-    // changes.
-    const interceptedHandler = React.useCallback((): Promise<TData> => {
-        // Call the interceptors from closest to furthest.
-        // If one returns a non-null result, then we keep that.
-        const interceptResponse: Promise<TData> | null | undefined =
-            interceptors.reduceRight(
-                (prev: Promise<TData> | null | undefined, interceptor) => {
-                    if (prev != null) {
-                        return prev;
-                    }
-                    return interceptor(requestId) as
-                        | Promise<TData>
-                        | null
-                        | undefined;
-                },
-                null,
-            );
-        // If nothing intercepted this request, invoke the original handler.
-        // NOTE: We can't guarantee all interceptors return the same type
-        // as our handler, so how can TypeScript know? Let's just suppress that.
-        return interceptResponse ?? handler();
-    }, [handler, interceptors, requestId]);
-
-    return interceptedHandler;
-};

package/src/hooks/use-server-effect.ts

@@ -1,75 +0,0 @@
-import {Server} from "@khanacademy/wonder-blocks-core";
-import {useContext} from "react";
-import {TrackerContext} from "../util/request-tracking";
-import {SsrCache} from "../util/ssr-cache";
-import {resultFromCachedResponse} from "../util/result-from-cache-response";
-import {useRequestInterception} from "./use-request-interception";
-
-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 const useServerEffect = <TData extends ValidCacheData>(
-    requestId: string,
-    handler: () => Promise<TData>,
-    options: ServerEffectOptions = {} as Partial<ServerEffectOptions>,
-): Result<TData> | null | undefined => {
-    const {hydrate = true, skip = false} = options;
-
-    // Plug in to the request interception framework for code that wants
-    // to use that.
-    const interceptedHandler = useRequestInterception(requestId, handler);
-
-    // If we're server-side or hydrating, we'll have a cached entry to use.
-    // So we get that and use it to initialize our state.
-    // This works in both hydration and SSR because the very first call to
-    // this will have cached data in those cases as it will be present on the
-    // initial render - and subsequent renders on the client it will be null.
-    const cachedResult = SsrCache.Default.getEntry<TData>(requestId);
-
-    // We only track data requests when we are server-side, we are not skipping
-    // the request, and we don't already have a result, as given by the
-    // cachedData (which is also the initial value for the result state).
-    const maybeTrack = useContext(TrackerContext);
-    if (!skip && cachedResult == null && Server.isServerSide()) {
-        maybeTrack?.(requestId, interceptedHandler, hydrate);
-    }
-
-    // A null result means there was no result to hydrate.
-    return cachedResult == null ? null : resultFromCachedResponse(cachedResult);
-};

package/src/hooks/use-shared-cache.ts

@@ -1,107 +0,0 @@
-import * as React from "react";
-import {DataError, DataErrors} from "../util/data-error";
-import {ScopedInMemoryCache} from "../util/scoped-in-memory-cache";
-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;
-
-/**
- * This is the cache.
- * It's incredibly complex.
- * Very in-memory. So cache. Such complex. Wow.
- */
-const cache = new ScopedInMemoryCache();
-
-/**
- * Access to the shared in-memory cache.
- *
- * This is the cache used by `useSharedCache` and related hooks and
- * components.
- */
-export const SharedCache: ScopedCache = cache;
-
-/**
- * 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 const useSharedCache = <TValue extends ValidCacheData>(
-    id: string,
-    scope: string,
-    initialValue?:
-        | TValue
-        | null
-        | undefined
-        | (() => TValue | null | undefined),
-): [TValue | null | undefined, CacheValueFn<TValue>] => {
-    // Verify arguments.
-    if (!id || typeof id !== "string") {
-        throw new DataError(
-            "id must be a non-empty string",
-            DataErrors.InvalidInput,
-        );
-    }
-
-    if (!scope || typeof scope !== "string") {
-        throw new DataError(
-            "scope must be a non-empty string",
-            DataErrors.InvalidInput,
-        );
-    }
-
-    // Memoize our APIs.
-    // This one allows callers to set or replace the cached value.
-    const cacheValue = React.useCallback(
-        (value?: TValue | null) =>
-            value == null
-                ? cache.purge(scope, id)
-                : cache.set(scope, id, value),
-        [id, scope],
-    );
-
-    // We don't memo-ize the current value, just in case the cache was updated
-    // since our last run through. Also, our cache does not know what type it
-    // stores, so we have to cast it to the type we're exporting. This is a
-    // dev time courtesy, rather than a runtime thing.
-    let currentValue: TValue | null | undefined = cache.get(scope, id) as
-        | TValue
-        | null
-        | undefined;
-
-    // If we have an initial value, we need to add it to the cache
-    // and use it as our current value.
-    if (currentValue == null && initialValue !== undefined) {
-        // Get the initial value.
-        const value =
-            typeof initialValue === "function" ? initialValue() : initialValue;
-
-        if (value != null) {
-            // Update the cache.
-            cacheValue(value);
-
-            // Make sure we return this value as our current value.
-            currentValue = value;
-        }
-    }
-
-    // Now we have everything, let's return it.
-    return [currentValue, cacheValue];
-};

package/src/index.ts

@@ -1,46 +0,0 @@
-export {FetchPolicy} from "./util/types";
-export type {
-    ErrorOptions,
-    ResponseCache,
-    CachedResponse,
-    Result,
-    RawScopedCache,
-    ValidCacheData,
-    ScopedCache,
-} from "./util/types";
-
-export * from "./util/hydration-cache-api";
-export * from "./util/request-api";
-export {purgeCaches} from "./util/purge-caches";
-export {default as TrackData} from "./components/track-data";
-export {default as Data} from "./components/data";
-export {default as InterceptRequests} from "./components/intercept-requests";
-export {DataError, DataErrors} from "./util/data-error";
-export {useServerEffect} from "./hooks/use-server-effect";
-export {useCachedEffect} from "./hooks/use-cached-effect";
-export {useSharedCache, SharedCache} from "./hooks/use-shared-cache";
-export {
-    useHydratableEffect,
-    WhenClientSide,
-} from "./hooks/use-hydratable-effect";
-export {ScopedInMemoryCache} from "./util/scoped-in-memory-cache";
-export {SerializableInMemoryCache} from "./util/serializable-in-memory-cache";
-export {Status} from "./util/status";
-
-////////////////////////////////////////////////////////////////////////////////
-// GraphQL
-////////////////////////////////////////////////////////////////////////////////
-export {getGqlRequestId} from "./util/get-gql-request-id";
-export {getGqlDataFromResponse} from "./util/get-gql-data-from-response";
-export {graphQLDocumentNodeParser} from "./util/graphql-document-node-parser";
-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";

package/src/util/__tests__/__snapshots__/scoped-in-memory-cache.test.ts.snap

@@ -1,19 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`ScopedInMemoryCache #set should throw if the id is  1`] = `"id must be non-empty string"`;
-
-exports[`ScopedInMemoryCache #set should throw if the id is [Function anonymous] 1`] = `"id must be non-empty string"`;
-
-exports[`ScopedInMemoryCache #set should throw if the id is 5 1`] = `"id must be non-empty string"`;
-
-exports[`ScopedInMemoryCache #set should throw if the id is null 1`] = `"id must be non-empty string"`;
-
-exports[`ScopedInMemoryCache #set should throw if the scope is  1`] = `"scope must be non-empty string"`;
-
-exports[`ScopedInMemoryCache #set should throw if the scope is [Function anonymous] 1`] = `"scope must be non-empty string"`;
-
-exports[`ScopedInMemoryCache #set should throw if the scope is 5 1`] = `"scope must be non-empty string"`;
-
-exports[`ScopedInMemoryCache #set should throw if the scope is null 1`] = `"scope must be non-empty string"`;
-
-exports[`ScopedInMemoryCache #set should throw if the value is a function 1`] = `"value must be a non-function value"`;

package/src/util/__tests__/__snapshots__/serializable-in-memory-cache.test.ts.snap

@@ -1,19 +0,0 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
-
-exports[`SerializableInMemoryCache #set should throw if the id is  1`] = `"id must be non-empty string"`;
-
-exports[`SerializableInMemoryCache #set should throw if the id is [Function anonymous] 1`] = `"id must be non-empty string"`;
-
-exports[`SerializableInMemoryCache #set should throw if the id is 5 1`] = `"id must be non-empty string"`;
-
-exports[`SerializableInMemoryCache #set should throw if the id is null 1`] = `"id must be non-empty string"`;
-
-exports[`SerializableInMemoryCache #set should throw if the scope is  1`] = `"scope must be non-empty string"`;
-
-exports[`SerializableInMemoryCache #set should throw if the scope is [Function anonymous] 1`] = `"scope must be non-empty string"`;
-
-exports[`SerializableInMemoryCache #set should throw if the scope is 5 1`] = `"scope must be non-empty string"`;
-
-exports[`SerializableInMemoryCache #set should throw if the scope is null 1`] = `"scope must be non-empty string"`;
-
-exports[`SerializableInMemoryCache #set should throw if the value is a function 1`] = `"value must be a non-function value"`;