@khanacademy/wonder-blocks-data 3.2.0 → 4.0.0

package/src/util/request-fulfillment.js

@@ -1,15 +1,10 @@
 // @flow
-import {ResponseCache} from "./response-cache.js";
+import {SsrCache} from "./ssr-cache.js";
 
-import type {ValidData, CacheEntry, IRequestHandler} from "./types.js";
-
-type Subcache = {
-    [key: string]: Promise<any>,
-    ...
-};
+import type {ValidCacheData, CachedResponse} from "./types.js";
 
 type RequestCache = {
-    [handlerType: string]: Subcache,
+    [id: string]: Promise<any>,
     ...
 };
 
@@ -23,44 +18,39 @@ export class RequestFulfillment {
         return _default;
     }
 
-    _responseCache: ResponseCache;
+    _responseCache: SsrCache;
     _requests: RequestCache = {};
 
-    constructor(responseCache: ?ResponseCache = undefined) {
-        this._responseCache = responseCache || ResponseCache.Default;
+    constructor(responseCache: ?SsrCache = undefined) {
+        this._responseCache = responseCache || SsrCache.Default;
     }
 
-    _getHandlerSubcache: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-    ) => Subcache = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-    ): Subcache => {
-        if (!this._requests[handler.type]) {
-            this._requests[handler.type] = {};
-        }
-        return this._requests[handler.type];
-    };
-
     /**
      * 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: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ) => Promise<CacheEntry<TData>> = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): Promise<CacheEntry<TData>> => {
-        const handlerRequests = this._getHandlerSubcache(handler);
-        const key = handler.getKey(options);
-
+    fulfill: <TData: ValidCacheData>(
+        id: string,
+        options: {|
+            handler: () => Promise<?TData>,
+            hydrate?: boolean,
+        |},
+    ) => Promise<?CachedResponse<TData>> = <TData: ValidCacheData>(
+        id: string,
+        {
+            handler,
+            hydrate = true,
+        }: {|
+            handler: () => Promise<?TData>,
+            hydrate?: boolean,
+        |},
+    ): Promise<?CachedResponse<TData>> => {
         /**
          * If we have an inflight request, we'll provide that.
          */
-        const inflight = handlerRequests[key];
+        const inflight = this._requests[id];
         if (inflight) {
             return inflight;
         }
@@ -70,36 +60,38 @@ export class RequestFulfillment {
          */
         const {cacheData, cacheError} = this._responseCache;
         try {
-            const request = handler
-                .fulfillRequest(options)
-                .then((data: TData) => {
-                    delete handlerRequests[key];
+            const request = handler()
+                .then((data: ?TData) => {
+                    delete this._requests[id];
+                    if (data == null) {
+                        // Request aborted. We won't cache this.
+                        return null;
+                    }
+
                     /**
                      * Let's cache the data!
                      *
                      * NOTE: This only caches when we're server side.
                      */
-                    return cacheData<TOptions, TData>(handler, options, data);
+                    return cacheData<TData>(id, data, hydrate);
                 })
                 .catch((error: string | Error) => {
-                    delete handlerRequests[key];
+                    delete this._requests[id];
                     /**
                      * Let's cache the error!
                      *
                      * NOTE: This only caches when we're server side.
                      */
-                    return cacheError<TOptions, TData>(handler, options, error);
+                    return cacheError<TData>(id, error, hydrate);
                 });
-            handlerRequests[key] = request;
+            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<TOptions, TData>(handler, options, e),
-            );
+            return Promise.resolve(cacheError<TData>(id, e, hydrate));
         }
     };
 }

package/src/util/request-tracking.js

@@ -1,22 +1,21 @@
 // @flow
 import * as React from "react";
-import {ResponseCache} from "./response-cache.js";
+import {SsrCache} from "./ssr-cache.js";
 import {RequestFulfillment} from "./request-fulfillment.js";
 
-import type {Cache, IRequestHandler} from "./types.js";
+import type {ResponseCache, ValidCacheData} from "./types.js";
 
-type TrackerFn = (handler: IRequestHandler<any, any>, options: any) => void;
-
-type HandlerCache = {
-    [type: string]: IRequestHandler<any, any>,
-    ...
-};
+type TrackerFn = <TData: ValidCacheData>(
+    id: string,
+    handler: () => Promise<?TData>,
+    hydrate: boolean,
+) => void;
 
 type RequestCache = {
-    [handlerType: string]: {
-        [key: string]: any,
-        ...
-    },
+    [id: string]: {|
+        hydrate?: boolean,
+        handler: () => Promise<?any>,
+    |},
     ...
 };
 
@@ -50,13 +49,12 @@ export class RequestTracker {
     /**
      * These are the caches for tracked requests, their handlers, and responses.
      */
-    _trackedHandlers: HandlerCache = {};
     _trackedRequests: RequestCache = {};
-    _responseCache: ResponseCache;
+    _responseCache: SsrCache;
     _requestFulfillment: RequestFulfillment;
 
-    constructor(responseCache: ?ResponseCache = undefined) {
-        this._responseCache = responseCache || ResponseCache.Default;
+    constructor(responseCache: ?SsrCache = undefined) {
+        this._responseCache = responseCache || SsrCache.Default;
         this._requestFulfillment = new RequestFulfillment(responseCache);
     }
 
@@ -66,26 +64,23 @@ export class RequestTracker {
      * 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: (
-        handler: IRequestHandler<any, any>,
-        options: any,
-    ) => void = (handler: IRequestHandler<any, any>, options: any): void => {
-        const key = handler.getKey(options);
-        const type = handler.type;
-
-        /**
-         * Make sure we have stored the handler for use when fulfilling requests.
-         */
-        if (this._trackedHandlers[type] == null) {
-            this._trackedHandlers[type] = handler;
-            this._trackedRequests[type] = {};
-        }
-
+    trackDataRequest: <TData: ValidCacheData>(
+        id: string,
+        handler: () => Promise<?TData>,
+        hydrate: boolean,
+    ) => void = <TData: ValidCacheData>(
+        id: string,
+        handler: () => Promise<?TData>,
+        hydrate: boolean,
+    ): void => {
         /**
          * If we don't already have this tracked, then let's track it.
          */
-        if (this._trackedRequests[type][key] == null) {
-            this._trackedRequests[type][key] = options;
+        if (this._trackedRequests[id] == null) {
+            this._trackedRequests[id] = {
+                handler,
+                hydrate,
+            };
         }
     };
 
@@ -93,7 +88,6 @@ export class RequestTracker {
      * Reset our tracking info.
      */
     reset: () => void = () => {
-        this._trackedHandlers = {};
         this._trackedRequests = {};
     };
 
@@ -114,52 +108,45 @@ export class RequestTracker {
      * Calling this method marks tracked requests as fulfilled; requests are
      * removed from the list of tracked requests by calling this method.
      *
-     * @returns {Promise<Cache>} A frozen cache of the data that was cached
-     * as a result of fulfilling the tracked requests.
+     * @returns {Promise<ResponseCache>} The promise of the data that was
+     * cached as a result of fulfilling the tracked requests.
      */
-    fulfillTrackedRequests: () => Promise<$ReadOnly<Cache>> = (): Promise<
-        $ReadOnly<Cache>,
-    > => {
-        const promises = [];
+    fulfillTrackedRequests: () => Promise<ResponseCache> =
+        (): Promise<ResponseCache> => {
+            const promises = [];
 
-        for (const handlerType of Object.keys(this._trackedHandlers)) {
-            const handler = this._trackedHandlers[handlerType];
-
-            // For each handler, we will perform the request fulfillments!
-            const requests = this._trackedRequests[handlerType];
-            for (const requestKey of Object.keys(requests)) {
+            for (const requestKey of Object.keys(this._trackedRequests)) {
                 const promise = this._requestFulfillment.fulfill(
-                    handler,
-                    requests[requestKey],
+                    requestKey,
+                    this._trackedRequests[requestKey],
                 );
                 promises.push(promise);
             }
-        }
-
-        /**
-         * Clear out our tracked info.
-         *
-         * 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.
-         *
-         * 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.
-         *
-         */
-        this.reset();
 
-        /**
-         * Let's wait for everything to fulfill, and then clone the cached data.
-         */
-        return Promise.all(promises).then(() =>
-            this._responseCache.cloneHydratableData(),
-        );
-    };
+            /**
+             * Clear out our tracked info.
+             *
+             * 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.
+             *
+             * 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.
+             *
+             */
+            this.reset();
+
+            /**
+             * Let's wait for everything to fulfill, and then clone the cached data.
+             */
+            return Promise.all(promises).then(() =>
+                this._responseCache.cloneHydratableData(),
+            );
+        };
 }

package/src/util/{result-from-cache-entry.js → result-from-cache-response.js}

@@ -1,11 +1,11 @@
 // @flow
-import type {ValidData, CacheEntry, Result} from "./types.js";
+import type {ValidCacheData, CachedResponse, Result} from "./types.js";
 
 /**
  * Turns a cache entry into a stateful result.
  */
-export const resultFromCacheEntry = <TData: ValidData>(
-    cacheEntry: ?CacheEntry<TData>,
+export const resultFromCachedResponse = <TData: ValidCacheData>(
+    cacheEntry: ?CachedResponse<TData>,
 ): Result<TData> => {
     // No cache entry means we didn't load one yet.
     if (cacheEntry == null) {
@@ -15,24 +15,21 @@ export const resultFromCacheEntry = <TData: ValidData>(
     }
 
     const {data, error} = cacheEntry;
-
-    if (data != null) {
+    if (error != null) {
         return {
-            status: "success",
-            data,
+            status: "error",
+            error,
         };
     }
 
-    if (error == null) {
-        // We should never get here ever.
+    if (data != null) {
         return {
-            status: "error",
-            error: "Loaded result has invalid state where data and error are missing",
+            status: "success",
+            data,
         };
     }
 
     return {
-        status: "error",
-        error,
+        status: "aborted",
     };
 };

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

@@ -0,0 +1,149 @@
+// @flow
+import {KindError, Errors, clone} from "@khanacademy/wonder-stuff-core";
+import type {ValidCacheData, ScopedCache} from "./types.js";
+
+/**
+ * Describe an in-memory cache.
+ */
+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,
+            );
+        }
+    }
+
+    /**
+     * Indicate if this cache is being used or not.
+     *
+     * When the cache has entries, returns `true`; otherwise, returns `false`.
+     */
+    get inUse(): boolean {
+        return Object.keys(this._cache).length > 0;
+    }
+
+    /**
+     * Set a value in the cache.
+     */
+    set: <TValue: ValidCacheData>(
+        scope: string,
+        id: string,
+        value: TValue,
+    ) => void = <TValue: ValidCacheData>(scope, id, value: TValue): void => {
+        if (!id || typeof id !== "string") {
+            throw new KindError(
+                "id must be non-empty string",
+                Errors.InvalidInput,
+            );
+        }
+
+        if (!scope || typeof scope !== "string") {
+            throw new KindError(
+                "scope must be non-empty string",
+                Errors.InvalidInput,
+            );
+        }
+
+        if (typeof value === "function") {
+            throw new KindError(
+                "value must be a non-function value",
+                Errors.InvalidInput,
+            );
+        }
+
+        this._cache[scope] = this._cache[scope] ?? {};
+        this._cache[scope][id] = Object.freeze(clone(value));
+    };
+
+    /**
+     * Retrieve a value from the cache.
+     */
+    get: (scope: string, id: string) => ?ValidCacheData = (
+        scope,
+        id,
+    ): ?ValidCacheData => {
+        return this._cache[scope]?.[id] ?? null;
+    };
+
+    /**
+     * Purge an item from the cache.
+     */
+    purge: (scope: string, id: string) => void = (scope, id) => {
+        if (!this._cache[scope]?.[id]) {
+            return;
+        }
+        delete this._cache[scope][id];
+        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: (
+        scope: string,
+        predicate?: (id: string, value: ValidCacheData) => boolean,
+    ) => void = (scope, predicate) => {
+        if (!this._cache[scope]) {
+            return;
+        }
+
+        if (predicate == null) {
+            delete this._cache[scope];
+            return;
+        }
+
+        for (const key of Object.keys(this._cache[scope])) {
+            if (predicate(key, this._cache[scope][key])) {
+                delete this._cache[scope][key];
+            }
+        }
+        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: (
+        predicate?: (
+            scope: string,
+            id: string,
+            value: ValidCacheData,
+        ) => boolean,
+    ) => void = (predicate) => {
+        if (predicate == null) {
+            this._cache = {};
+            return;
+        }
+
+        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}`,
+            );
+        }
+    };
+}