@khanacademy/wonder-blocks-data 10.1.0 → 10.1.2

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

@@ -0,0 +1,37 @@
+import type { Result, ValidCacheData } from "./types";
+type RequestCache = {
+    [id: string]: Promise<Result<any>>;
+};
+type FulfillOptions<TData extends ValidCacheData> = {
+    handler: () => Promise<TData>;
+    hydrate?: boolean;
+};
+/**
+ * This fulfills a request, making sure that in-flight requests are shared.
+ */
+export declare class RequestFulfillment {
+    static get Default(): RequestFulfillment;
+    _requests: RequestCache;
+    /**
+     * Get a promise of a request for a given handler and options.
+     *
+     * This will return an inflight request if one exists, otherwise it will
+     * make a new request. Inflight requests are deleted once they resolve.
+     */
+    fulfill: <TData extends ValidCacheData>(id: string, options: FulfillOptions<TData>) => Promise<Result<TData>>;
+    /**
+     * Abort an inflight request.
+     *
+     * NOTE: Currently, this does not perform an actual abort. It merely
+     * removes the request from being tracked.
+     */
+    abort: (id: string) => void;
+    /**
+     * Abort all inflight requests.
+     *
+     * NOTE: Currently, this does not perform actual aborts. It merely
+     * removes the requests from our tracking.
+     */
+    abortAll: () => void;
+}
+export {};

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

@@ -0,0 +1,50 @@
+/**
+ * Flowtype definitions for request-fulfillment
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { Result, ValidCacheData } from "./types";
+declare type RequestCache = {
+  [id: string]: Promise<Result<any>>,
+};
+declare type FulfillOptions<TData: ValidCacheData> = {
+  handler: () => Promise<TData>,
+  hydrate?: boolean,
+  ...
+};
+/**
+ * This fulfills a request, making sure that in-flight requests are shared.
+ */
+declare export class RequestFulfillment {
+  static Default: RequestFulfillment;
+  _requests: RequestCache;
+
+  /**
+   * Get a promise of a request for a given handler and options.
+   *
+   * This will return an inflight request if one exists, otherwise it will
+   * make a new request. Inflight requests are deleted once they resolve.
+   */
+  fulfill: <TData: ValidCacheData>(
+    id: string,
+    options: FulfillOptions<TData>
+  ) => Promise<Result<TData>>;
+
+  /**
+   * Abort an inflight request.
+   *
+   * NOTE: Currently, this does not perform an actual abort. It merely
+   * removes the request from being tracked.
+   */
+  abort: (id: string) => void;
+
+  /**
+   * Abort all inflight requests.
+   *
+   * NOTE: Currently, this does not perform actual aborts. It merely
+   * removes the requests from our tracking.
+   */
+  abortAll: () => void;
+}

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

@@ -0,0 +1,62 @@
+import * as React from "react";
+import { SsrCache } from "./ssr-cache";
+import { RequestFulfillment } from "./request-fulfillment";
+import type { ResponseCache, ValidCacheData } from "./types";
+type TrackerFn = <TData extends ValidCacheData>(id: string, handler: () => Promise<TData>, hydrate: boolean) => void;
+type RequestCache = {
+    [id: string]: {
+        hydrate: boolean;
+        handler: () => Promise<any>;
+    };
+};
+/**
+ * Used to inject our tracking function into the render framework.
+ *
+ * INTERNAL USE ONLY
+ */
+export declare const TrackerContext: React.Context<TrackerFn | null | undefined>;
+/**
+ * Implements request tracking and fulfillment.
+ *
+ * INTERNAL USE ONLY
+ */
+export declare class RequestTracker {
+    static get Default(): RequestTracker;
+    /**
+     * These are the caches for tracked requests, their handlers, and responses.
+     */
+    _trackedRequests: RequestCache;
+    _responseCache: SsrCache;
+    _requestFulfillment: RequestFulfillment;
+    constructor(responseCache?: SsrCache | null);
+    /**
+     * Track a request.
+     *
+     * This method caches a request and its handler for use during server-side
+     * rendering to allow us to fulfill requests before producing a final render.
+     */
+    trackDataRequest: <TData extends ValidCacheData>(id: string, handler: () => Promise<TData>, hydrate: boolean) => void;
+    /**
+     * Reset our tracking info.
+     */
+    reset: () => void;
+    /**
+     * Indicates if we have requests waiting to be fulfilled.
+     */
+    get hasUnfulfilledRequests(): boolean;
+    /**
+     * Initiate fulfillment of all tracked requests.
+     *
+     * This loops over the requests that were tracked using TrackData, and asks
+     * the respective handlers to fulfill those requests in the order they were
+     * tracked.
+     *
+     * Calling this method marks tracked requests as fulfilled; requests are
+     * removed from the list of tracked requests by calling this method.
+     *
+     * @returns {Promise<ResponseCache>} The promise of the data that was
+     * cached as a result of fulfilling the tracked requests.
+     */
+    fulfillTrackedRequests: () => Promise<ResponseCache>;
+}
+export {};

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

@@ -0,0 +1,81 @@
+/**
+ * Flowtype definitions for request-tracking
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import * as React from "react";
+import { SsrCache } from "./ssr-cache";
+import { RequestFulfillment } from "./request-fulfillment";
+import type { ResponseCache, ValidCacheData } from "./types";
+declare type TrackerFn = <TData: ValidCacheData>(
+  id: string,
+  handler: () => Promise<TData>,
+  hydrate: boolean
+) => void;
+declare type RequestCache = {
+  [id: string]: {
+    hydrate: boolean,
+    handler: () => Promise<any>,
+    ...
+  },
+};
+/**
+ * Used to inject our tracking function into the render framework.
+ *
+ * INTERNAL USE ONLY
+ */
+declare export var TrackerContext: React.Context<TrackerFn | null | void>;
+/**
+ * Implements request tracking and fulfillment.
+ *
+ * INTERNAL USE ONLY
+ */
+declare export class RequestTracker {
+  static Default: RequestTracker;
+
+  /**
+   * These are the caches for tracked requests, their handlers, and responses.
+   */
+  _trackedRequests: RequestCache;
+  _responseCache: SsrCache;
+  _requestFulfillment: RequestFulfillment;
+  constructor(responseCache?: SsrCache | null): this;
+
+  /**
+   * Track a request.
+   *
+   * This method caches a request and its handler for use during server-side
+   * rendering to allow us to fulfill requests before producing a final render.
+   */
+  trackDataRequest: <TData: ValidCacheData>(
+    id: string,
+    handler: () => Promise<TData>,
+    hydrate: boolean
+  ) => void;
+
+  /**
+   * Reset our tracking info.
+   */
+  reset: () => void;
+
+  /**
+   * Indicates if we have requests waiting to be fulfilled.
+   */
+  hasUnfulfilledRequests: boolean;
+
+  /**
+   * Initiate fulfillment of all tracked requests.
+   *
+   * This loops over the requests that were tracked using TrackData, and asks
+   * the respective handlers to fulfill those requests in the order they were
+   * tracked.
+   *
+   * Calling this method marks tracked requests as fulfilled; requests are
+   * removed from the list of tracked requests by calling this method.
+   * @returns {Promise<ResponseCache>} The promise of the data that was
+   * cached as a result of fulfilling the tracked requests.
+   */
+  fulfillTrackedRequests: () => Promise<ResponseCache>;
+}

package/dist/util/result-from-cache-response.d.ts

@@ -0,0 +1,5 @@
+import type { ValidCacheData, CachedResponse, Result } from "./types";
+/**
+ * Turns a cache entry into a stateful result.
+ */
+export declare const resultFromCachedResponse: <TData extends ValidCacheData>(cacheEntry?: CachedResponse<TData> | null | undefined) => Result<TData> | null | undefined;

package/dist/util/result-from-cache-response.js.flow

@@ -0,0 +1,15 @@
+/**
+ * Flowtype definitions for result-from-cache-response
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { ValidCacheData, CachedResponse, Result } from "./types";
+
+/**
+ * Turns a cache entry into a stateful result.
+ */
+declare export var resultFromCachedResponse: <TData: ValidCacheData>(
+  cacheEntry?: CachedResponse<TData> | null | void
+) => Result<TData> | null | void;

package/dist/util/scoped-in-memory-cache.d.ts

@@ -0,0 +1,38 @@
+import type { ScopedCache, RawScopedCache, ValidCacheData } from "./types";
+/**
+ * Describe an in-memory cache.
+ */
+export declare class ScopedInMemoryCache implements ScopedCache {
+    _cache: RawScopedCache;
+    constructor(initialCache?: RawScopedCache);
+    /**
+     * Indicate if this cache is being used or not.
+     *
+     * When the cache has entries, returns `true`; otherwise, returns `false`.
+     */
+    get inUse(): boolean;
+    /**
+     * Set a value in the cache.
+     */
+    set(scope: string, id: string, value: ValidCacheData): void;
+    /**
+     * Retrieve a value from the cache.
+     */
+    get(scope: string, id: string): ValidCacheData | null | undefined;
+    /**
+     * Purge an item from the cache.
+     */
+    purge(scope: string, id: string): void;
+    /**
+     * Purge a scope of items that match the given predicate.
+     *
+     * If the predicate is omitted, then all items in the scope are purged.
+     */
+    purgeScope(scope: string, predicate?: (id: string, value: ValidCacheData) => boolean): void;
+    /**
+     * Purge all items from the cache that match the given predicate.
+     *
+     * If the predicate is omitted, then all items in the cache are purged.
+     */
+    purgeAll(predicate?: (scope: string, id: string, value: ValidCacheData) => boolean): void;
+}

package/dist/util/scoped-in-memory-cache.js.flow

@@ -0,0 +1,57 @@
+/**
+ * Flowtype definitions for scoped-in-memory-cache
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { ScopedCache, RawScopedCache, ValidCacheData } from "./types";
+
+/**
+ * Describe an in-memory cache.
+ */
+declare export class ScopedInMemoryCache extends ScopedCache {
+  _cache: RawScopedCache;
+  constructor(initialCache?: RawScopedCache): this;
+
+  /**
+   * Indicate if this cache is being used or not.
+   *
+   * When the cache has entries, returns `true`; otherwise, returns `false`.
+   */
+  inUse: boolean;
+
+  /**
+   * Set a value in the cache.
+   */
+  set(scope: string, id: string, value: ValidCacheData): void;
+
+  /**
+   * Retrieve a value from the cache.
+   */
+  get(scope: string, id: string): ValidCacheData | null | void;
+
+  /**
+   * Purge an item from the cache.
+   */
+  purge(scope: string, id: string): void;
+
+  /**
+   * Purge a scope of items that match the given predicate.
+   *
+   * If the predicate is omitted, then all items in the scope are purged.
+   */
+  purgeScope(
+    scope: string,
+    predicate?: (id: string, value: ValidCacheData) => boolean
+  ): void;
+
+  /**
+   * Purge all items from the cache that match the given predicate.
+   *
+   * If the predicate is omitted, then all items in the cache are purged.
+   */
+  purgeAll(
+    predicate?: (scope: string, id: string, value: ValidCacheData) => boolean
+  ): void;
+}

package/dist/util/serializable-in-memory-cache.d.ts

@@ -0,0 +1,16 @@
+import { ScopedInMemoryCache } from "./scoped-in-memory-cache";
+import type { ValidCacheData, RawScopedCache } from "./types";
+/**
+ * Describe a serializable in-memory cache.
+ */
+export declare class SerializableInMemoryCache extends ScopedInMemoryCache {
+    constructor(initialCache?: RawScopedCache);
+    /**
+     * Set a value in the cache.
+     */
+    set(scope: string, id: string, value: ValidCacheData): void;
+    /**
+     * Clone the cache.
+     */
+    clone(): RawScopedCache;
+}

package/dist/util/serializable-in-memory-cache.js.flow

@@ -0,0 +1,26 @@
+/**
+ * Flowtype definitions for serializable-in-memory-cache
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import { ScopedInMemoryCache } from "./scoped-in-memory-cache";
+import type { ValidCacheData, RawScopedCache } from "./types";
+
+/**
+ * Describe a serializable in-memory cache.
+ */
+declare export class SerializableInMemoryCache extends ScopedInMemoryCache {
+  constructor(initialCache?: RawScopedCache): this;
+
+  /**
+   * Set a value in the cache.
+   */
+  set(scope: string, id: string, value: ValidCacheData): void;
+
+  /**
+   * Clone the cache.
+   */
+  clone(): RawScopedCache;
+}

package/dist/util/ssr-cache.d.ts

@@ -0,0 +1,51 @@
+import { SerializableInMemoryCache } from "./serializable-in-memory-cache";
+import type { ValidCacheData, CachedResponse, ResponseCache } from "./types";
+/**
+ * Implements the response cache.
+ *
+ * INTERNAL USE ONLY
+ */
+export declare class SsrCache {
+    static get Default(): SsrCache;
+    _hydrationCache: SerializableInMemoryCache;
+    _ssrOnlyCache: SerializableInMemoryCache;
+    constructor(hydrationCache?: SerializableInMemoryCache | null, ssrOnlyCache?: SerializableInMemoryCache | null);
+    _setCachedResponse<TData extends ValidCacheData>(id: string, entry: CachedResponse<TData>, hydrate: boolean): CachedResponse<TData>;
+    /**
+     * Initialize the cache from a given cache state.
+     *
+     * This can only be called if the cache is not already in use.
+     */
+    initialize: (source: ResponseCache) => void;
+    /**
+     * Cache data for a specific response.
+     *
+     * This is a noop when client-side.
+     */
+    cacheData: <TData extends ValidCacheData>(id: string, data: TData, hydrate: boolean) => CachedResponse<TData>;
+    /**
+     * Cache an error for a specific response.
+     *
+     * This is a noop when client-side.
+     */
+    cacheError: <TData extends ValidCacheData>(id: string, error: Error | string, hydrate: boolean) => CachedResponse<TData>;
+    /**
+     * Retrieve data from our cache.
+     */
+    getEntry: <TData extends ValidCacheData>(id: string) => Readonly<CachedResponse<TData>> | null | undefined;
+    /**
+     * Remove from cache, any entries matching the given handler and predicate.
+     *
+     * This will, if present therein, remove matching values from the framework
+     * in-memory cache.
+     *
+     * It returns a count of all records removed.
+     */
+    purgeData: (predicate?: (key: string, cachedEntry: Readonly<CachedResponse<ValidCacheData>>) => boolean) => void;
+    /**
+     * Deep clone the hydration cache.
+     *
+     * By design, this only clones the data that is to be used for hydration.
+     */
+    cloneHydratableData: () => ResponseCache;
+}

package/dist/util/ssr-cache.js.flow

@@ -0,0 +1,87 @@
+/**
+ * Flowtype definitions for ssr-cache
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import { SerializableInMemoryCache } from "./serializable-in-memory-cache";
+import type { ValidCacheData, CachedResponse, ResponseCache } from "./types";
+
+/**
+ * Implements the response cache.
+ *
+ * INTERNAL USE ONLY
+ */
+declare export class SsrCache {
+  static Default: SsrCache;
+  _hydrationCache: SerializableInMemoryCache;
+  _ssrOnlyCache: SerializableInMemoryCache;
+  constructor(
+    hydrationCache?: SerializableInMemoryCache | null,
+    ssrOnlyCache?: SerializableInMemoryCache | null
+  ): this;
+  _setCachedResponse<TData: ValidCacheData>(
+    id: string,
+    entry: CachedResponse<TData>,
+    hydrate: boolean
+  ): CachedResponse<TData>;
+
+  /**
+   * Initialize the cache from a given cache state.
+   *
+   * This can only be called if the cache is not already in use.
+   */
+  initialize: (source: ResponseCache) => void;
+
+  /**
+   * Cache data for a specific response.
+   *
+   * This is a noop when client-side.
+   */
+  cacheData: <TData: ValidCacheData>(
+    id: string,
+    data: TData,
+    hydrate: boolean
+  ) => CachedResponse<TData>;
+
+  /**
+   * Cache an error for a specific response.
+   *
+   * This is a noop when client-side.
+   */
+  cacheError: <TData: ValidCacheData>(
+    id: string,
+    error: Error | string,
+    hydrate: boolean
+  ) => CachedResponse<TData>;
+
+  /**
+   * Retrieve data from our cache.
+   */
+  getEntry: <TData: ValidCacheData>(
+    id: string
+  ) => $ReadOnly<CachedResponse<TData>> | null | void;
+
+  /**
+   * Remove from cache, any entries matching the given handler and predicate.
+   *
+   * This will, if present therein, remove matching values from the framework
+   * in-memory cache.
+   *
+   * It returns a count of all records removed.
+   */
+  purgeData: (
+    predicate?: (
+      key: string,
+      cachedEntry: $ReadOnly<CachedResponse<ValidCacheData>>
+    ) => boolean
+  ) => void;
+
+  /**
+   * Deep clone the hydration cache.
+   *
+   * By design, this only clones the data that is to be used for hydration.
+   */
+  cloneHydratableData: () => ResponseCache;
+}

package/dist/util/status.d.ts

@@ -0,0 +1,10 @@
+import type { Result, ValidCacheData } from "./types";
+/**
+ * Create Result<TData> instances with specific statuses.
+ */
+export declare const Status: Readonly<{
+    loading: <TData extends ValidCacheData = ValidCacheData>() => Result<TData>;
+    aborted: <TData_1 extends ValidCacheData = ValidCacheData>() => Result<TData_1>;
+    success: <TData_2 extends ValidCacheData>(data: TData_2) => Result<TData_2>;
+    error: <TData_3 extends ValidCacheData = ValidCacheData>(error: Error) => Result<TData_3>;
+}>;

package/dist/util/status.js.flow

@@ -0,0 +1,19 @@
+/**
+ * Flowtype definitions for status
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { Result, ValidCacheData } from "./types";
+
+/**
+ * Create Result<TData> instances with specific statuses.
+ */
+declare export var Status: $ReadOnly<{
+  loading: <TData: ValidCacheData>() => Result<TData>,
+  aborted: <TData_1: ValidCacheData>() => Result<TData_1>,
+  success: <TData_2: ValidCacheData>(data: TData_2) => Result<TData_2>,
+  error: <TData_3: ValidCacheData>(error: Error) => Result<TData_3>,
+  ...
+}>;

package/dist/util/to-gql-operation.d.ts

@@ -0,0 +1,32 @@
+import type { GqlOperation } from "./gql-types";
+import type { DocumentNode } from "./graphql-types";
+/**
+ * Convert a GraphQL DocumentNode to a base Wonder Blocks Data GqlOperation.
+ *
+ * If you want to include the query/mutation body, extend the result of this
+ * method and use the `graphql/language/printer` like:
+ *
+ * ```js
+ * import {print} from "graphql/language/printer";
+ *
+ * const gqlOpWithBody = {
+ *     ...toGqlOperation(documentNode),
+ *     query: print(documentNode),
+ * };
+ * ```
+ *
+ * If you want to enforce inclusion of __typename properties, then you can use
+ * `apollo-utilities` first to modify the document:
+ *
+ * ```js
+ * import {print} from "graphql/language/printer";
+ * import {addTypenameToDocument} from "apollo-utilities";
+ *
+ * const documentWithTypenames = addTypenameToDocument(documentNode);
+ * const gqlOpWithBody = {
+ *     ...toGqlOperation(documentWithTypenames),
+ *     query: print(documentWithTypenames),
+ * };
+ * ```
+ */
+export declare const toGqlOperation: <TData, TVariables extends Record<any, any>>(documentNode: DocumentNode) => GqlOperation<TData, TVariables>;

package/dist/util/to-gql-operation.js.flow

@@ -0,0 +1,45 @@
+/**
+ * Flowtype definitions for to-gql-operation
+ * Generated by Flowgen from a Typescript Definition
+ * Flowgen v1.21.0
+ * @flow
+ */
+
+import type { GqlOperation } from "./gql-types";
+import type { DocumentNode } from "./graphql-types";
+
+/**
+ * Convert a GraphQL DocumentNode to a base Wonder Blocks Data GqlOperation.
+ *
+ * If you want to include the query/mutation body, extend the result of this
+ * method and use the `graphql/language/printer` like:
+ *
+ * ```js
+ * import {print} from "graphql/language/printer";
+ *
+ * const gqlOpWithBody = {
+ *     ...toGqlOperation(documentNode),
+ *     query: print(documentNode),
+ * };
+ * ```
+ *
+ * If you want to enforce inclusion of __typename properties, then you can use
+ * `apollo-utilities` first to modify the document:
+ *
+ * ```js
+ * import {print} from "graphql/language/printer";
+ * import {addTypenameToDocument} from "apollo-utilities";
+ *
+ * const documentWithTypenames = addTypenameToDocument(documentNode);
+ * const gqlOpWithBody = {
+ *     ...toGqlOperation(documentWithTypenames),
+ *     query: print(documentWithTypenames),
+ * };
+ * ```
+ */
+declare export var toGqlOperation: <
+  TData,
+  TVariables: { [key: any]: any, ... }
+>(
+  documentNode: DocumentNode
+) => GqlOperation<TData, TVariables>;