@khanacademy/wonder-blocks-data 4.0.0 → 6.0.0

package/src/util/request-fulfillment.js

@@ -1,15 +1,18 @@
 // @flow
-import {SsrCache} from "./ssr-cache.js";
+import type {Result, ValidCacheData} from "./types.js";
 
-import type {ValidCacheData, CachedResponse} from "./types.js";
+import {DataError, DataErrors} from "./data-error.js";
 
 type RequestCache = {
-    [id: string]: Promise<any>,
+    [id: string]: Promise<Result<any>>,
     ...
 };
 
 let _default: RequestFulfillment;
 
+/**
+ * This fulfills a request, making sure that in-flight requests are shared.
+ */
 export class RequestFulfillment {
     static get Default(): RequestFulfillment {
         if (!_default) {
@@ -18,13 +21,8 @@ export class RequestFulfillment {
         return _default;
     }
 
-    _responseCache: SsrCache;
     _requests: RequestCache = {};
 
-    constructor(responseCache: ?SsrCache = undefined) {
-        this._responseCache = responseCache || SsrCache.Default;
-    }
-
     /**
      * Get a promise of a request for a given handler and options.
      *
@@ -34,19 +32,19 @@ export class RequestFulfillment {
     fulfill: <TData: ValidCacheData>(
         id: string,
         options: {|
-            handler: () => Promise<?TData>,
+            handler: () => Promise<TData>,
             hydrate?: boolean,
         |},
-    ) => Promise<?CachedResponse<TData>> = <TData: ValidCacheData>(
+    ) => Promise<Result<TData>> = <TData: ValidCacheData>(
         id: string,
         {
             handler,
             hydrate = true,
         }: {|
-            handler: () => Promise<?TData>,
+            handler: () => Promise<TData>,
             hydrate?: boolean,
         |},
-    ): Promise<?CachedResponse<TData>> => {
+    ): Promise<Result<TData>> => {
         /**
          * If we have an inflight request, we'll provide that.
          */
@@ -58,40 +56,45 @@ export class RequestFulfillment {
         /**
          * We don't have an inflight request, so let's set one up.
          */
-        const {cacheData, cacheError} = this._responseCache;
-        try {
-            const request = handler()
-                .then((data: ?TData) => {
-                    delete this._requests[id];
-                    if (data == null) {
-                        // Request aborted. We won't cache this.
-                        return null;
-                    }
+        const request = handler()
+            .then((data: TData): Result<TData> => ({
+                status: "success",
+                data,
+            }))
+            .catch((error: string | Error): Result<TData> => {
+                const actualError =
+                    typeof error === "string"
+                        ? new DataError("Request failed", DataErrors.Unknown, {
+                              metadata: {
+                                  unexpectedError: error,
+                              },
+                          })
+                        : error;
 
-                    /**
-                     * Let's cache the data!
-                     *
-                     * NOTE: This only caches when we're server side.
-                     */
-                    return cacheData<TData>(id, data, hydrate);
-                })
-                .catch((error: string | Error) => {
-                    delete this._requests[id];
-                    /**
-                     * Let's cache the error!
-                     *
-                     * NOTE: This only caches when we're server side.
-                     */
-                    return cacheError<TData>(id, error, hydrate);
-                });
-            this._requests[id] = request;
-            return request;
-        } catch (e) {
-            /**
-             * In this case, we don't cache an inflight request, because there
-             * really isn't one.
-             */
-            return Promise.resolve(cacheError<TData>(id, e, hydrate));
-        }
+                // Return aborted result if the request was aborted.
+                // The only way to detect this reliably, it seems, is to
+                // check the error name and see if it's "AbortError" (this
+                // is also what Apollo does).
+                // Even then, it's reliant on the handler supporting aborts.
+                // TODO(somewhatabstract, FEI-4276): Add first class abort
+                // support to the handler API.
+                if (actualError.name === "AbortError") {
+                    return {
+                        status: "aborted",
+                    };
+                }
+                return {
+                    status: "error",
+                    error: actualError,
+                };
+            })
+            .finally(() => {
+                delete this._requests[id];
+            });
+
+        // Store the request in our cache.
+        this._requests[id] = request;
+
+        return request;
     };
 }

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,
+|};