@khanacademy/wonder-blocks-data 2.3.1 → 3.0.0

package/src/util/__tests__/result-from-cache-entry.test.js

@@ -0,0 +1,68 @@
+// @flow
+import {resultFromCacheEntry} from "../result-from-cache-entry.js";
+
+describe("#resultFromCacheEntry", () => {
+    it("should return loading status if cache entry is null", () => {
+        // Arrange
+        const cacheEntry = null;
+
+        // Act
+        const result = resultFromCacheEntry(cacheEntry);
+
+        // Assert
+        expect(result).toStrictEqual({
+            status: "loading",
+        });
+    });
+
+    it("should return success status if cache entry has data", () => {
+        // Arrange
+        const cacheEntry = {
+            data: "DATA",
+            error: null,
+        };
+
+        // Act
+        const result = resultFromCacheEntry(cacheEntry);
+
+        // Assert
+        expect(result).toStrictEqual({
+            status: "success",
+            data: "DATA",
+        });
+    });
+
+    it("should return error status if cache entry has no data and no error", () => {
+        // Arrange
+        const cacheEntry: any = {
+            data: null,
+            error: null,
+        };
+
+        // Act
+        const result = resultFromCacheEntry(cacheEntry);
+
+        // Assert
+        expect(result).toStrictEqual({
+            status: "error",
+            error: "Loaded result has invalid state where data and error are missing",
+        });
+    });
+
+    it("should return error status if cache entry has error", () => {
+        // Arrange
+        const cacheEntry: any = {
+            data: null,
+            error: "ERROR",
+        };
+
+        // Act
+        const result = resultFromCacheEntry(cacheEntry);
+
+        // Assert
+        expect(result).toStrictEqual({
+            status: "error",
+            error: "ERROR",
+        });
+    });
+});

package/src/util/memory-cache.js

@@ -25,12 +25,11 @@ function deepClone<T: {...}>(source: T | $ReadOnly<T>): $ReadOnly<T> {
  *
  * Special case cache implementation for the memory cache.
  *
- * This is only used within our framework. Handlers don't need to
- * provide this as a custom cache as the framework will default to this in the
- * absence of a custom cache. We use this for SSR too (see ./response-cache.js).
+ * This is only used within our framework for SSR (see ./response-cache.js).
  */
 export default class MemoryCache<TOptions, TData: ValidData>
-    implements ICache<TOptions, TData> {
+    implements ICache<TOptions, TData>
+{
     _cache: Cache;
 
     constructor(source: ?$ReadOnly<Cache> = null) {
@@ -52,6 +51,11 @@ export default class MemoryCache<TOptions, TData: ValidData>
         }
     }
 
+    /**
+     * Indicate if this cache is being used or now.
+     *
+     * When the cache has entries, returns `true`; otherwise, returns `false`.
+     */
     get inUse(): boolean {
         return Object.keys(this._cache).length > 0;
     }
@@ -67,9 +71,7 @@ export default class MemoryCache<TOptions, TData: ValidData>
     ): void => {
         const requestType = handler.type;
 
-        const frozenEntry = Object.isFrozen(entry)
-            ? entry
-            : Object.freeze(entry);
+        const frozenEntry = Object.freeze(entry);
 
         // Ensure we have a cache location for this handler type.
         this._cache[requestType] = this._cache[requestType] || {};
@@ -156,16 +158,19 @@ export default class MemoryCache<TOptions, TData: ValidData>
             return 0;
         }
 
-        // Apply the predicate to what we have cached.
         let removedCount = 0;
-        for (const [key, entry] of Object.entries(handlerCache)) {
-            if (
-                typeof predicate !== "function" ||
-                predicate(key, (entry: any))
-            ) {
-                removedCount++;
-                delete handlerCache[key];
+        if (typeof predicate === "function") {
+            // Apply the predicate to what we have cached.
+            for (const [key, entry] of Object.entries(handlerCache)) {
+                if (predicate(key, (entry: any))) {
+                    removedCount++;
+                    delete handlerCache[key];
+                }
             }
+        } else {
+            // We're removing everything so delete the entire subcache.
+            removedCount = Object.keys(handlerCache).length;
+            delete this._cache[requestType];
         }
         return removedCount;
     };

package/src/util/request-fulfillment.js

@@ -76,6 +76,8 @@ export class RequestFulfillment {
                     delete handlerRequests[key];
                     /**
                      * Let's cache the data!
+                     *
+                     * NOTE: This only caches when we're server side.
                      */
                     return cacheData<TOptions, TData>(handler, options, data);
                 })
@@ -83,6 +85,8 @@ export class RequestFulfillment {
                     delete handlerRequests[key];
                     /**
                      * Let's cache the error!
+                     *
+                     * NOTE: This only caches when we're server side.
                      */
                     return cacheError<TOptions, TData>(handler, options, error);
                 });

package/src/util/request-handler.js

@@ -1,5 +1,5 @@
 // @flow
-import type {ValidData, CacheEntry, IRequestHandler, ICache} from "./types.js";
+import type {ValidData, IRequestHandler} from "./types.js";
 
 /**
  * Base implementation for creating a request handler.
@@ -8,18 +8,13 @@ import type {ValidData, CacheEntry, IRequestHandler, ICache} from "./types.js";
  * use with the Wonder Blocks Data framework.
  */
 export default class RequestHandler<TOptions, TData: ValidData>
-    implements IRequestHandler<TOptions, TData> {
+    implements IRequestHandler<TOptions, TData>
+{
     _type: string;
-    _cache: ?ICache<TOptions, TData>;
     _hydrate: boolean;
 
-    constructor(
-        type: string,
-        cache?: ICache<TOptions, TData>,
-        hydrate?: boolean = true,
-    ) {
+    constructor(type: string, hydrate?: boolean = true) {
         this._type = type;
-        this._cache = cache || null;
         this._hydrate = !!hydrate;
     }
 
@@ -27,29 +22,10 @@ export default class RequestHandler<TOptions, TData: ValidData>
         return this._type;
     }
 
-    get cache(): ?ICache<TOptions, TData> {
-        return this._cache;
-    }
-
     get hydrate(): boolean {
         return this._hydrate;
     }
 
-    shouldRefreshCache(
-        options: TOptions,
-        cachedEntry: ?$ReadOnly<CacheEntry<TData>>,
-    ): boolean {
-        /**
-         * By default, the cache needs a refresh if the current entry is an
-         * error.
-         *
-         * This means that an error will cause a re-request on render.
-         * Useful if the server rendered an error, as it means the client
-         * will update after rehydration.
-         */
-        return cachedEntry == null || cachedEntry.error != null;
-    }
-
     getKey(options: TOptions): string {
         try {
             return options === undefined

package/src/util/request-handler.md

@@ -14,12 +14,6 @@ interface IRequestHandler<TOptions, TData> {
      */
     get type(): string;
 
-    /**
-     * A custom cache to use with data that this handler requests.
-     * This only affects client-side caching of data.
-     */
-    get cache(): ?ICache<TOptions, TData>;
-
     /**
      * When true, server-side results are cached and hydrated in the client.
      * When false, the server-side cache is not used and results are not
@@ -29,17 +23,6 @@ interface IRequestHandler<TOptions, TData> {
      */
     get hydrate(): boolean;
 
-    /**
-     * Determine if the cached data should be refreshed.
-     *
-     * If this returns true, the framework will use the currently cached value
-     * but also request a new value.
-     */
-    shouldRefreshCache(
-        options: TOptions,
-        cachedEntry: ?$ReadOnly<CacheEntry<TData>>,
-    ): boolean;
-
     /**
      * Get the key to use for a given request. This should be idempotent for a
      * given options set if you want caching to work across requests.
@@ -52,13 +35,6 @@ The constructor requires a `type` to identify your handler. This should be uniqu
 among the handlers that are used across your application, otherwise, requests
 may be fulfilled by the wrong handler.
 
-There is also an optional constructor argument, `cache`, which can be used to
-provide a custom cache for use with data the handler fulfills. Custom caches
-must implement the `ICache<TOptions, TData>` interface. If this is omitted, the
-core Wonder Blocks Data in-memory cache will be used. If you want to avoid
-caching in memory, see `NoCache`, which is a caching strategy that eliminates
-the use of caching entirely.
-
 The `fulfillRequest` method of this class is not implemented and will throw if
 called. Subclasses will need to implement this method.
 
@@ -73,11 +49,3 @@ SSR process is tracking the data for hydration. An example of setting this to
 false might be when you are using Apollo Client. In that scenario, you may use
 Apollo Cache to store and hydrate the data, while using Wonder Blocks Data to
 track and fulfill any query requests made via Apollo Client.
-
-Finally, the `shouldRefreshCache` method is provided for cases where a handler
-may want control over cache freshness. By default, this will return `true` for
-error results or a missing value. However, in some cases, handlers may want to
-make sure cached entries are not stale, and so may return `true` from the
-`shouldRefreshCache` method to instruct the framework to make a new request.
-The existing cached value will still be used, but an updated value will be
-requested.

package/src/util/request-tracking.js

@@ -25,9 +25,8 @@ type RequestCache = {
  *
  * INTERNAL USE ONLY
  */
-export const TrackerContext: React.Context<?TrackerFn> = new React.createContext<?TrackerFn>(
-    null,
-);
+export const TrackerContext: React.Context<?TrackerFn> =
+    new React.createContext<?TrackerFn>(null);
 
 /**
  * The default instance is stored here.

package/src/util/response-cache.js

@@ -1,13 +1,11 @@
 // @flow
 import {Server} from "@khanacademy/wonder-blocks-core";
 import MemoryCache from "./memory-cache.js";
-import NoCache from "./no-cache.js";
 
 import type {
     ValidData,
     CacheEntry,
     Cache,
-    ICache,
     IRequestHandler,
     ResponseCache as ResCache,
 } from "./types.js";
@@ -31,32 +29,17 @@ export class ResponseCache {
         return _default;
     }
 
-    _hydrationAndDefaultCache: MemoryCache<any, any>;
+    _hydrationCache: MemoryCache<any, any>;
     _ssrOnlyCache: ?MemoryCache<any, any>;
 
     constructor(
-        memoryCache: ?MemoryCache<any, any> = null,
+        hydrationCache: ?MemoryCache<any, any> = null,
         ssrOnlyCache: ?MemoryCache<any, any> = null,
     ) {
         this._ssrOnlyCache = Server.isServerSide()
             ? ssrOnlyCache || new MemoryCache()
             : undefined;
-        this._hydrationAndDefaultCache = memoryCache || new MemoryCache();
-    }
-
-    /**
-     * Returns the default cache to use for the given handler.
-     */
-    _defaultCache<TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-    ): ICache<TOptions, TData> {
-        if (handler.hydrate) {
-            return this._hydrationAndDefaultCache;
-        }
-
-        // If the handler doesn't want to hydrate, we return the SSR-only cache.
-        // If we are client-side, we return our non-caching implementation.
-        return this._ssrOnlyCache || NoCache.Default;
+        this._hydrationCache = hydrationCache || new MemoryCache();
     }
 
     _setCacheEntry<TOptions, TData: ValidData>(
@@ -65,15 +48,14 @@ export class ResponseCache {
         entry: CacheEntry<TData>,
     ): CacheEntry<TData> {
         const frozenEntry = Object.freeze(entry);
-
-        if (this._ssrOnlyCache == null && handler.cache != null) {
-            // We are not server-side, and our handler has its own cache,
-            // so we use that to store values.
-            handler.cache.store(handler, options, frozenEntry);
-        } else {
-            // We are either server-side, or our handler doesn't provide
-            // a caching override.
-            this._defaultCache(handler).store(handler, options, frozenEntry);
+        if (this._ssrOnlyCache != null) {
+            // We are server-side.
+            // We need to store this value.
+            if (handler.hydrate) {
+                this._hydrationCache.store(handler, options, frozenEntry);
+            } else {
+                this._ssrOnlyCache.store(handler, options, frozenEntry);
+            }
         }
         return frozenEntry;
     }
@@ -84,14 +66,14 @@ export class ResponseCache {
      * This can only be called if the cache is not already in use.
      */
     initialize: (source: ResCache) => void = (source) => {
-        if (this._hydrationAndDefaultCache.inUse) {
+        if (this._hydrationCache.inUse) {
             throw new Error(
                 "Cannot initialize data response cache more than once",
             );
         }
 
         try {
-            this._hydrationAndDefaultCache = new MemoryCache(source);
+            this._hydrationCache = new MemoryCache(source);
         } catch (e) {
             throw new Error(
                 `An error occurred trying to initialize the data response cache: ${e}`,
@@ -101,6 +83,8 @@ export class ResponseCache {
 
     /**
      * Cache data for a specific response.
+     *
+     * This is a noop when client-side.
      */
     cacheData: <TOptions, TData: ValidData>(
         handler: IRequestHandler<TOptions, TData>,
@@ -110,12 +94,12 @@ export class ResponseCache {
         handler: IRequestHandler<TOptions, TData>,
         options: TOptions,
         data: TData,
-    ): CacheEntry<TData> => {
-        return this._setCacheEntry(handler, options, {data});
-    };
+    ): CacheEntry<TData> => this._setCacheEntry(handler, options, {data});
 
     /**
      * Cache an error for a specific response.
+     *
+     * This is a noop when client-side.
      */
     cacheError: <TOptions, TData: ValidData>(
         handler: IRequestHandler<TOptions, TData>,
@@ -140,42 +124,27 @@ export class ResponseCache {
         handler: IRequestHandler<TOptions, TData>,
         options: TOptions,
     ): ?$ReadOnly<CacheEntry<TData>> => {
-        // If we're not server-side, and the handler has a custom cache
-        // let's try to use it.
-        if (this._ssrOnlyCache == null && handler.cache != null) {
-            const entry = handler.cache.retrieve(handler, options);
-            if (entry != null) {
-                // Custom cache has an entry, so use it.
-                return entry;
-            }
-        }
-
-        // Get the internal entry for the handler.
-        // This allows us to use our hydrated cache during hydration.
-        // If we just returned null when the custom cache didn't have it,
-        // we would never hydrate properly.
-        const internalEntry = this._defaultCache<TOptions, TData>(
-            handler,
-        ).retrieve(handler, options);
-
-        // If we are not server-side and we hydrated something that the custom
-        // cache didn't have, we need to make sure the custom cache contains
-        // that value.
-        if (
-            this._ssrOnlyCache == null &&
-            handler.cache != null &&
-            internalEntry != null
-        ) {
-            // Yes, if this throws, we will have a problem. We want that.
-            // Bad cache implementations should be overt.
-            handler.cache.store(handler, options, internalEntry);
+        // Get the cached entry for this value.
+        // If the handler wants WB Data to hydrate (i.e. handler.hydrate is
+        // true), we use our hydration cache. Otherwise, if we're server-side
+        // we use our SSR-only cache. Otherwise, there's no entry to return.
+        const cache = handler.hydrate
+            ? this._hydrationCache
+            : Server.isServerSide()
+            ? this._ssrOnlyCache
+            : undefined;
+        const internalEntry = cache?.retrieve(handler, options);
 
-            // We now delete this from our in-memory cache as we don't need it.
+        // If we are not server-side and we hydrated something, let's clear
+        // that from the hydration cache to save memory.
+        if (this._ssrOnlyCache == null && internalEntry != null) {
+            // We now delete this from our hydration cache as we don't need it.
             // This does mean that if another handler of the same type but
-            // without a custom cache won't get the value, but that's not an
-            // expected valid usage of this framework - two handlers with
-            // different caching options shouldn't be using the same type name.
-            this._hydrationAndDefaultCache.remove(handler, options);
+            // without some sort of linked cache won't get the value, but
+            // that's not an expected use-case. If two different places use the
+            // same handler and options (i.e. the same request), then the
+            // handler should cater to that to ensure they share the result.
+            this._hydrationCache.remove(handler, options);
         }
         return internalEntry;
     };
@@ -199,31 +168,19 @@ export class ResponseCache {
         // to match the key of the entry we're removing, but that's an
         // inefficient way to remove a single item, so let's not do that.
 
-        // If we're not server-side, and the handler has a custom cache
-        // let's try to use it.
-        const customCache = this._ssrOnlyCache == null ? handler.cache : null;
-        const removedCustom: boolean = !!customCache?.remove(handler, options);
-
-        // Delete the entry from our internal cache.
-        // Even if we have a custom cache, we want to make sure we still
-        // removed the same value from internal cache since this could be
-        // getting called before hydration for some complex advanced usage
-        // reason.
-        return (
-            this._defaultCache(handler).remove(handler, options) ||
-            removedCustom
-        );
+        // Delete the entry from the appropriate cache.
+        return handler.hydrate
+            ? this._hydrationCache.remove(handler, options)
+            : this._ssrOnlyCache?.remove(handler, options) ?? false;
     };
 
     /**
      * Remove from cache, any entries matching the given handler and predicate.
      *
-     * This will, if present therein, remove matching values from the custom
-     * cache associated with the handler and the framework in-memory cache.
+     * This will, if present therein, remove matching values from the framework
+     * in-memory cache.
      *
-     * It returns a count of all records removed. This is not a count of unique
-     * keys, but of unique entries. So if the same key is removed from both the
-     * framework and custom caches, that will be 2 records removed.
+     * It returns a count of all records removed.
      */
     removeAll: <TOptions, TData: ValidData>(
         handler: IRequestHandler<TOptions, TData>,
@@ -238,36 +195,19 @@ export class ResponseCache {
             cachedEntry: $ReadOnly<CacheEntry<TData>>,
         ) => boolean,
     ): number => {
-        // If we're not server-side, and the handler has a custom cache
-        // let's try to use it.
-        const customCache = this._ssrOnlyCache == null ? handler.cache : null;
-        const removedCountCustom: number =
-            customCache?.removeAll(handler, predicate) || 0;
-
-        // Apply the predicate to what we have in our internal cached.
-        // Even if we have a custom cache, we want to make sure we still
-        // removed the same value from internal cache since this could be
-        // getting called before hydration for some complex advanced usage
-        // reason.
-        const removedCount = this._defaultCache(handler).removeAll(
-            handler,
-            predicate,
-        );
-
-        // We have no idea which keys were removed from which caches,
-        // so we can't dedupe the remove counts based on keys.
-        // That's why we return the total records deleted rather than the
-        // total keys deleted.
-        return removedCount + removedCountCustom;
+        // Apply the predicate to what we have in the appropriate cache.
+        return handler.hydrate
+            ? this._hydrationCache.removeAll(handler, predicate)
+            : this._ssrOnlyCache?.removeAll(handler, predicate) ?? 0;
     };
 
     /**
      * Deep clone the hydration cache.
      *
-     * By design, this does not clone anything held in custom caches.
+     * By design, this only clones the data that is to be used for hydration.
      */
     cloneHydratableData: () => $ReadOnly<Cache> = (): $ReadOnly<Cache> => {
         // We return our hydration cache only.
-        return this._hydrationAndDefaultCache.cloneData();
+        return this._hydrationCache.cloneData();
     };
 }

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

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

package/src/util/types.js

@@ -1,16 +1,19 @@
 // @flow
 export type ValidData = string | boolean | number | {...};
 
+export type Status = "loading" | "success" | "error";
+
 export type Result<TData: ValidData> =
     | {|
-          loading: true,
-          data?: void,
-          error?: void,
+          status: "loading",
       |}
     | {|
-          loading: false,
+          status: "success",
           data?: TData,
-          error?: string,
+      |}
+    | {|
+          status: "error",
+          error: string,
       |};
 
 export type CacheEntry<TData: ValidData> =
@@ -28,24 +31,12 @@ type HandlerSubcache = {
     ...
 };
 
-export type InterceptCacheFn<TOptions, TData: ValidData> = (
-    options: TOptions,
-    cacheEntry: ?$ReadOnly<CacheEntry<TData>>,
-) => ?$ReadOnly<CacheEntry<TData>>;
-
 export type InterceptFulfillRequestFn<TOptions, TData: ValidData> = (
     options: TOptions,
 ) => ?Promise<TData>;
 
-export type InterceptShouldRefreshCacheFn<TOptions, TData: ValidData> = (
-    options: TOptions,
-    cachedEntry: ?$ReadOnly<CacheEntry<TData>>,
-) => ?boolean;
-
 export type Interceptor = {|
-    getEntry?: ?InterceptCacheFn<any, any>,
-    fulfillRequest?: ?InterceptFulfillRequestFn<any, any>,
-    shouldRefreshCache?: ?InterceptShouldRefreshCacheFn<any, any>,
+    fulfillRequest: InterceptFulfillRequestFn<any, any>,
 |};
 
 export type InterceptContextData = {
@@ -120,31 +111,19 @@ export interface IRequestHandler<TOptions, TData: ValidData> {
      */
     get type(): string;
 
-    /**
-     * A custom cache to use with data that this handler requests.
-     * This only affects client-side caching of data.
-     */
-    get cache(): ?ICache<TOptions, TData>;
-
     /**
      * When true, server-side results are cached and hydrated in the client.
      * When false, the server-side cache is not used and results are not
      * hydrated.
      * This should only be set to false if something is ensuring that the
      * hydrated client result will match the server result.
-     */
-    get hydrate(): boolean;
-
-    /**
-     * Determine if the cached data should be refreshed.
      *
-     * If this returns true, the framework will fulfill a new request by
-     * calling `fulfillRequest`.
+     * For example, if Apollo is used to handle GraphQL requests in SSR mode,
+     * it has its own cache that is used to hydrate the client. Setting this
+     * to false makes sure we don't store the data twice, which would
+     * unnecessarily bloat the data sent back to the client.
      */
-    shouldRefreshCache(
-        options: TOptions,
-        cachedEntry: ?$ReadOnly<CacheEntry<TData>>,
-    ): boolean;
+    get hydrate(): boolean;
 
     /**
      * Get the key to use for a given request. This should be idempotent for a