@khanacademy/wonder-blocks-data 5.0.1 → 7.0.0

package/src/util/request-tracking.js

@@ -7,14 +7,14 @@ import type {ResponseCache, ValidCacheData} from "./types.js";
 
 type TrackerFn = <TData: ValidCacheData>(
     id: string,
-    handler: () => Promise<?TData>,
+    handler: () => Promise<TData>,
     hydrate: boolean,
 ) => void;
 
 type RequestCache = {
     [id: string]: {|
-        hydrate?: boolean,
-        handler: () => Promise<?any>,
+        hydrate: boolean,
+        handler: () => Promise<any>,
     |},
     ...
 };
@@ -55,7 +55,7 @@ export class RequestTracker {
 
     constructor(responseCache: ?SsrCache = undefined) {
         this._responseCache = responseCache || SsrCache.Default;
-        this._requestFulfillment = new RequestFulfillment(responseCache);
+        this._requestFulfillment = new RequestFulfillment();
     }
 
     /**
@@ -66,11 +66,11 @@ export class RequestTracker {
      */
     trackDataRequest: <TData: ValidCacheData>(
         id: string,
-        handler: () => Promise<?TData>,
+        handler: () => Promise<TData>,
         hydrate: boolean,
     ) => void = <TData: ValidCacheData>(
         id: string,
-        handler: () => Promise<?TData>,
+        handler: () => Promise<TData>,
         hydrate: boolean,
     ): void => {
         /**
@@ -114,13 +114,68 @@ export class RequestTracker {
     fulfillTrackedRequests: () => Promise<ResponseCache> =
         (): Promise<ResponseCache> => {
             const promises = [];
+            const {cacheData, cacheError} = this._responseCache;
 
             for (const requestKey of Object.keys(this._trackedRequests)) {
-                const promise = this._requestFulfillment.fulfill(
-                    requestKey,
-                    this._trackedRequests[requestKey],
-                );
-                promises.push(promise);
+                const options = this._trackedRequests[requestKey];
+
+                try {
+                    promises.push(
+                        this._requestFulfillment
+                            .fulfill(requestKey, {...options})
+                            .then((result) => {
+                                switch (result.status) {
+                                    case "success":
+                                        /**
+                                         * Let's cache the data!
+                                         *
+                                         * NOTE: This only caches when we're
+                                         * server side.
+                                         */
+                                        cacheData(
+                                            requestKey,
+                                            result.data,
+                                            options.hydrate,
+                                        );
+                                        break;
+
+                                    case "error":
+                                        /**
+                                         * Let's cache the error!
+                                         *
+                                         * NOTE: This only caches when we're
+                                         * server side.
+                                         */
+                                        cacheError(
+                                            requestKey,
+                                            result.error,
+                                            options.hydrate,
+                                        );
+                                        break;
+                                }
+
+                                // For status === "loading":
+                                // Could never get here unless we wrote
+                                // the code wrong. Rather than bloat
+                                // code with useless error, just ignore.
+
+                                // For status === "aborted":
+                                // We won't cache this.
+                                // We don't hydrate aborted requests,
+                                // so the client would just see them
+                                // as unfulfilled data.
+                                return;
+                            }),
+                    );
+                } catch (e) {
+                    // This captures if there are problems in the code that
+                    // begins the requests.
+                    promises.push(
+                        Promise.resolve(
+                            cacheError(requestKey, e, options.hydrate),
+                        ),
+                    );
+                }
             }
 
             /**
@@ -129,16 +184,15 @@ export class RequestTracker {
              * We call this now for a simpler API.
              *
              * If we reset the tracked calls after all promises resolve, any
-             * requst tracking done while promises are in flight would be lost.
+             * request tracking done while promises are in flight would be lost.
              *
              * If we don't reset at all, then we have to expose the `reset` call
              * for consumers to use, or they'll only ever be able to accumulate
              * more and more tracked requests, having to fulfill them all every
              * time.
              *
-             * Calling it here means we can have multiple "track -> request" cycles
-             * in a row and in an easy to reason about manner.
-             *
+             * Calling it here means we can have multiple "track -> request"
+             * cycles in a row and in an easy to reason about manner.
              */
             this.reset();
 

package/src/util/result-from-cache-response.js

@@ -1,4 +1,6 @@
 // @flow
+import {Status} from "./status.js";
+import {DataError, DataErrors} from "./data-error.js";
 import type {ValidCacheData, CachedResponse, Result} from "./types.js";
 
 /**
@@ -6,30 +8,24 @@ import type {ValidCacheData, CachedResponse, Result} from "./types.js";
  */
 export const resultFromCachedResponse = <TData: ValidCacheData>(
     cacheEntry: ?CachedResponse<TData>,
-): Result<TData> => {
-    // No cache entry means we didn't load one yet.
+): ?Result<TData> => {
+    // No cache entry means no result to be hydrated.
     if (cacheEntry == null) {
-        return {
-            status: "loading",
-        };
+        return null;
     }
 
     const {data, error} = cacheEntry;
     if (error != null) {
-        return {
-            status: "error",
-            error,
-        };
+        // Let's hydrate the error. We don't persist everything about the
+        // original error on the server, hence why we only superficially
+        // hydrate it to a GqlHydratedError.
+        return Status.error(new DataError(error, DataErrors.Hydrated));
     }
 
     if (data != null) {
-        return {
-            status: "success",
-            data,
-        };
+        return Status.success(data);
     }
 
-    return {
-        status: "aborted",
-    };
+    // We shouldn't get here since we don't actually cache null data.
+    return Status.aborted();
 };

package/src/util/scoped-in-memory-cache.js

@@ -1,6 +1,6 @@
 // @flow
-import {KindError, Errors, clone} from "@khanacademy/wonder-stuff-core";
-import type {ValidCacheData, ScopedCache} from "./types.js";
+import {DataError, DataErrors} from "./data-error.js";
+import type {ScopedCache, ValidCacheData} from "./types.js";
 
 /**
  * Describe an in-memory cache.
@@ -8,15 +8,8 @@ import type {ValidCacheData, ScopedCache} from "./types.js";
 export class ScopedInMemoryCache {
     _cache: ScopedCache;
 
-    constructor(initialCache: ScopedCache = Object.freeze({})) {
-        try {
-            this._cache = clone(initialCache);
-        } catch (e) {
-            throw new KindError(
-                `An error occurred trying to initialize from a response cache snapshot: ${e}`,
-                Errors.InvalidInput,
-            );
-        }
+    constructor(initialCache: ScopedCache = {}) {
+        this._cache = initialCache;
     }
 
     /**
@@ -31,50 +24,47 @@ export class ScopedInMemoryCache {
     /**
      * Set a value in the cache.
      */
-    set: <TValue: ValidCacheData>(
+    set<TValue: ValidCacheData>(
         scope: string,
         id: string,
         value: TValue,
-    ) => void = <TValue: ValidCacheData>(scope, id, value: TValue): void => {
+    ): void {
         if (!id || typeof id !== "string") {
-            throw new KindError(
+            throw new DataError(
                 "id must be non-empty string",
-                Errors.InvalidInput,
+                DataErrors.InvalidInput,
             );
         }
 
         if (!scope || typeof scope !== "string") {
-            throw new KindError(
+            throw new DataError(
                 "scope must be non-empty string",
-                Errors.InvalidInput,
+                DataErrors.InvalidInput,
             );
         }
 
         if (typeof value === "function") {
-            throw new KindError(
+            throw new DataError(
                 "value must be a non-function value",
-                Errors.InvalidInput,
+                DataErrors.InvalidInput,
             );
         }
 
         this._cache[scope] = this._cache[scope] ?? {};
-        this._cache[scope][id] = Object.freeze(clone(value));
-    };
+        this._cache[scope][id] = value;
+    }
 
     /**
      * Retrieve a value from the cache.
      */
-    get: (scope: string, id: string) => ?ValidCacheData = (
-        scope,
-        id,
-    ): ?ValidCacheData => {
+    get(scope: string, id: string): ?ValidCacheData {
         return this._cache[scope]?.[id] ?? null;
-    };
+    }
 
     /**
      * Purge an item from the cache.
      */
-    purge: (scope: string, id: string) => void = (scope, id) => {
+    purge(scope: string, id: string): void {
         if (!this._cache[scope]?.[id]) {
             return;
         }
@@ -82,17 +72,17 @@ export class ScopedInMemoryCache {
         if (Object.keys(this._cache[scope]).length === 0) {
             delete this._cache[scope];
         }
-    };
+    }
 
     /**
      * Purge a scope of items that match the given predicate.
      *
      * If the predicate is omitted, then all items in the scope are purged.
      */
-    purgeScope: (
+    purgeScope(
         scope: string,
         predicate?: (id: string, value: ValidCacheData) => boolean,
-    ) => void = (scope, predicate) => {
+    ): void {
         if (!this._cache[scope]) {
             return;
         }
@@ -110,20 +100,20 @@ export class ScopedInMemoryCache {
         if (Object.keys(this._cache[scope]).length === 0) {
             delete this._cache[scope];
         }
-    };
+    }
 
     /**
      * 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: (
+    purgeAll(
         predicate?: (
             scope: string,
             id: string,
             value: ValidCacheData,
         ) => boolean,
-    ) => void = (predicate) => {
+    ): void {
         if (predicate == null) {
             this._cache = {};
             return;
@@ -132,18 +122,5 @@ export class ScopedInMemoryCache {
         for (const scope of Object.keys(this._cache)) {
             this.purgeScope(scope, (id, value) => predicate(scope, id, value));
         }
-    };
-
-    /**
-     * Clone the cache.
-     */
-    clone: () => ScopedCache = () => {
-        try {
-            return clone(this._cache);
-        } catch (e) {
-            throw new Error(
-                `An error occurred while trying to clone the cache: ${e}`,
-            );
-        }
-    };
+    }
 }

package/src/util/serializable-in-memory-cache.js

@@ -0,0 +1,49 @@
+// @flow
+import {clone} from "@khanacademy/wonder-stuff-core";
+import {DataError, DataErrors} from "./data-error.js";
+import {ScopedInMemoryCache} from "./scoped-in-memory-cache.js";
+import type {ValidCacheData, ScopedCache} from "./types.js";
+
+/**
+ * Describe a serializable in-memory cache.
+ */
+export class SerializableInMemoryCache extends ScopedInMemoryCache {
+    constructor(initialCache: ScopedCache = {}) {
+        try {
+            super(clone(initialCache));
+        } catch (e) {
+            throw new DataError(
+                `An error occurred trying to initialize from a response cache snapshot: ${e}`,
+                DataErrors.InvalidInput,
+            );
+        }
+    }
+
+    /**
+     * Set a value in the cache.
+     */
+    set<TValue: ValidCacheData>(
+        scope: string,
+        id: string,
+        value: TValue,
+    ): void {
+        super.set(scope, id, Object.freeze(clone(value)));
+    }
+
+    /**
+     * Clone the cache.
+     */
+    clone(): ScopedCache {
+        try {
+            return clone(this._cache);
+        } catch (e) {
+            throw new DataError(
+                "An error occurred while trying to clone the cache",
+                DataErrors.Internal,
+                {
+                    cause: e,
+                },
+            );
+        }
+    }
+}

package/src/util/ssr-cache.js

@@ -1,6 +1,6 @@
 // @flow
 import {Server} from "@khanacademy/wonder-blocks-core";
-import {ScopedInMemoryCache} from "./scoped-in-memory-cache.js";
+import {SerializableInMemoryCache} from "./serializable-in-memory-cache.js";
 
 import type {ValidCacheData, CachedResponse, ResponseCache} from "./types.js";
 
@@ -25,17 +25,18 @@ export class SsrCache {
         return _default;
     }
 
-    _hydrationCache: ScopedInMemoryCache;
-    _ssrOnlyCache: ?ScopedInMemoryCache;
+    _hydrationCache: SerializableInMemoryCache;
+    _ssrOnlyCache: ?SerializableInMemoryCache;
 
     constructor(
-        hydrationCache: ?ScopedInMemoryCache = null,
-        ssrOnlyCache: ?ScopedInMemoryCache = null,
+        hydrationCache: ?SerializableInMemoryCache = null,
+        ssrOnlyCache: ?SerializableInMemoryCache = null,
     ) {
         this._ssrOnlyCache = Server.isServerSide()
-            ? ssrOnlyCache || new ScopedInMemoryCache()
+            ? ssrOnlyCache || new SerializableInMemoryCache()
             : undefined;
-        this._hydrationCache = hydrationCache || new ScopedInMemoryCache();
+        this._hydrationCache =
+            hydrationCache || new SerializableInMemoryCache();
     }
 
     _setCachedResponse<TData: ValidCacheData>(
@@ -70,7 +71,7 @@ export class SsrCache {
                 "Cannot initialize data response cache more than once",
             );
         }
-        this._hydrationCache = new ScopedInMemoryCache({
+        this._hydrationCache = new SerializableInMemoryCache({
             // $FlowIgnore[incompatible-call]
             [DefaultScope]: source,
         });

package/src/util/status.js

@@ -0,0 +1,30 @@
+// @flow
+import type {Result, ValidCacheData} from "./types.js";
+
+const loadingStatus = Object.freeze({
+    status: "loading",
+});
+
+const abortedStatus = Object.freeze({
+    status: "aborted",
+});
+
+/**
+ * Create Result<TData> instances with specific statuses.
+ */
+export const Status = Object.freeze({
+    loading: <TData: ValidCacheData = ValidCacheData>(): Result<TData> =>
+        loadingStatus,
+    aborted: <TData: ValidCacheData = ValidCacheData>(): Result<TData> =>
+        abortedStatus,
+    success: <TData: ValidCacheData>(data: TData): Result<TData> => ({
+        status: "success",
+        data,
+    }),
+    error: <TData: ValidCacheData = ValidCacheData>(
+        error: Error,
+    ): Result<TData> => ({
+        status: "error",
+        error,
+    }),
+});

package/src/util/types.js

@@ -1,4 +1,6 @@
 // @flow
+import type {Metadata} from "@khanacademy/wonder-stuff-core";
+
 /**
  * Define what can be cached.
  *
@@ -25,7 +27,7 @@ export type Result<TData: ValidCacheData> =
       |}
     | {|
           status: "error",
-          error: string,
+          error: Error,
       |}
     | {|
           status: "aborted",
@@ -68,3 +70,18 @@ export type ScopedCache = {
     },
     ...
 };
+
+/**
+ * Options to pass to error construction.
+ */
+export type ErrorOptions = {|
+    /**
+     * Metadata to attach to the error.
+     */
+    metadata?: ?Metadata,
+
+    /**
+     * The error that caused the error being constructed.
+     */
+    cause?: ?Error,
+|};

package/docs.md

@@ -1,122 +0,0 @@
-## fulfillAllDataRequests
-
-When performing server-side rendering (SSR), the data requests that are being
-made via the `Data` component can be tracked by rendering the React tree
-inside the `TrackData` component. After this has occurred, the tracked requests
-can be fulfilled using `fulfillAllDataRequests`.
-
-This method returns a promise that resolves to a copy of the data that was
-cached by fulfilling the tracked requests. In the process, it clears the
-record of tracked requests so that new requests can be tracked and fulfilled
-if so required.
-
-The returned copy of the data cache can be used with the `initializeCache`
-method to prepare the data cache before a subsequent render. This is useful on
-the server to then SSR a more complete result, and again on the client, to
-rehydrate that result.
-
-### Usage
-
-```js static
-fulfillAllDataRequests(): Promise<ResponseCache>;
-```
-
-## initializeCache
-
-Wonder Blocks Data caches data in its response cache for hydration. This cache
-can be initialized with data using the `initializeCache` method.
-The `initializeCache` method can only be called when the hydration cache is
-empty.
-
-Usually, the data to be passed to `initializeCache` will be obtained by
-calling `fulfillAllDataRequests` after tracking data requests
-(see [TrackData](#trackdata)) during server-side rendering.
-
-Combine with `removeFromCache` or `removeAllFromCache` to support your testing
-needs.
-
-### Usage
-
-```js static
-initializeCache(sourceCache: ResponseCache): void;
-```
-
-#### Function arguments
-
-| Argument | Flow&nbsp;Type | Default | Description |
-| --- | --- | --- | --- |
-| `sourceData` | `ResponseCache` | _Required_ | The source cache that will be used to initialize the response cache. |
-
-## removeFromCache
-
-Removes an entry from the cache. The given handler and options identify the entry to be removed.
-
-If an item is removed, this returns `true`; otherwise, `false`.
-
-This can be used after `initializeCache` to manipulate the cache prior to hydration.
-This can be useful during testing.
-
-### Usage
-
-```js static
-removeFromCache(id: string): boolean;
-```
-
-#### Function arguments
-
-| Argument | Flow&nbsp;Type | Default | Description |
-| --- | --- | --- | --- |
-| `id` | `string` | _Required_ | The id of the item to be removed. |
-
-## removeAllFromCache
-
-Removes all entries that match a given predicate from the cache. If no predicate is given, all cached entries for the given handler are removed.
-
-This returns the count of entries removed.
-
-This can be used after `initializeCache` to manipulate the cache prior to hydration.
-This can be useful during testing (especially to clear the cache so that it can be initialized again).
-If the predicate is not given, all items are removed.
-
-### Usage
-
-```js static
-removeAllFromCache(predicate?: (key: string, entry: $ReadOnly<CachedResponse<TData>>) => boolean): number;
-```
-
-#### Function arguments
-
-| Argument | Flow&nbsp;Type | Default | Description |
-| --- | --- | --- | --- |
-| `predicate` | `(key: string, entry: $ReadOnly<CachedResponse<TData>>) => boolean)` | _Optional_ | A predicate to identify which entries to remove. If absent, all data is removed; if present, any entries for which the predicate returns `true` will be returned. |
-
-## Types
-
-### ResponseCache
-
-```js static
-type CachedResponse =
-    | {|
-        data: any,
-      |}
-    | {|
-        error: string,
-      |};
-
-type ResponseCache = {
-    [id: string]: CachedResponse,
-    ...,
-};
-```
-
-An example is of the response cache is shown below.
-
-```js static
-const responseCache = {
-    DATA_ID_1: {error: "It go 💥boom 😢"},
-    DATA_ID_2: {data: ["array", "of", "data"]},
-    DATA_ID_3: {data: {some: "data"}},
-};
-```
-
-In this example, the cache contains data retrieved for three different requests.