@khanacademy/wonder-blocks-data 3.1.1 → 4.0.0

package/src/util/ssr-cache.js

@@ -0,0 +1,206 @@
+// @flow
+import {Server} from "@khanacademy/wonder-blocks-core";
+import {ScopedInMemoryCache} from "./scoped-in-memory-cache.js";
+
+import type {ValidCacheData, CachedResponse, ResponseCache} from "./types.js";
+
+const DefaultScope = "default";
+
+/**
+ * The default instance is stored here.
+ * It's created below in the Default() static property.
+ */
+let _default: SsrCache;
+
+/**
+ * Implements the response cache.
+ *
+ * INTERNAL USE ONLY
+ */
+export class SsrCache {
+    static get Default(): SsrCache {
+        if (!_default) {
+            _default = new SsrCache();
+        }
+        return _default;
+    }
+
+    _hydrationCache: ScopedInMemoryCache;
+    _ssrOnlyCache: ?ScopedInMemoryCache;
+
+    constructor(
+        hydrationCache: ?ScopedInMemoryCache = null,
+        ssrOnlyCache: ?ScopedInMemoryCache = null,
+    ) {
+        this._ssrOnlyCache = Server.isServerSide()
+            ? ssrOnlyCache || new ScopedInMemoryCache()
+            : undefined;
+        this._hydrationCache = hydrationCache || new ScopedInMemoryCache();
+    }
+
+    _setCachedResponse<TData: ValidCacheData>(
+        id: string,
+        entry: CachedResponse<TData>,
+        hydrate: boolean,
+    ): CachedResponse<TData> {
+        const frozenEntry = Object.freeze(entry);
+        if (Server.isServerSide()) {
+            // We are server-side.
+            // We need to store this value.
+            if (hydrate) {
+                this._hydrationCache.set(DefaultScope, id, frozenEntry);
+            } else {
+                // Usually, when server-side, this cache will always be present.
+                // We do fake server-side in our doc example though, when it
+                // won't be.
+                this._ssrOnlyCache?.set(DefaultScope, id, frozenEntry);
+            }
+        }
+        return frozenEntry;
+    }
+
+    /**
+     * 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 = (source) => {
+        if (this._hydrationCache.inUse) {
+            throw new Error(
+                "Cannot initialize data response cache more than once",
+            );
+        }
+        this._hydrationCache = new ScopedInMemoryCache({
+            // $FlowIgnore[incompatible-call]
+            [DefaultScope]: source,
+        });
+    };
+
+    /**
+     * Cache data for a specific response.
+     *
+     * This is a noop when client-side.
+     */
+    cacheData: <TData: ValidCacheData>(
+        id: string,
+        data: TData,
+        hydrate: boolean,
+    ) => CachedResponse<TData> = <TData: ValidCacheData>(
+        id: string,
+        data: TData,
+        hydrate: boolean,
+    ): CachedResponse<TData> => this._setCachedResponse(id, {data}, hydrate);
+
+    /**
+     * 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> = <TData: ValidCacheData>(
+        id: string,
+        error: Error | string,
+        hydrate: boolean,
+    ): CachedResponse<TData> => {
+        const errorMessage = typeof error === "string" ? error : error.message;
+        return this._setCachedResponse(id, {error: errorMessage}, hydrate);
+    };
+
+    /**
+     * Retrieve data from our cache.
+     */
+    getEntry: <TData: ValidCacheData>(
+        id: string,
+    ) => ?$ReadOnly<CachedResponse<TData>> = <TData: ValidCacheData>(
+        id: string,
+    ): ?$ReadOnly<CachedResponse<TData>> => {
+        // Get the cached entry for this value.
+
+        // We first look in the ssr cache and then the hydration cache.
+        const internalEntry =
+            this._ssrOnlyCache?.get(DefaultScope, id) ??
+            this._hydrationCache.get(DefaultScope, id);
+
+        // 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 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.purge(DefaultScope, id);
+        }
+        // Getting the typing right between the in-memory cache and this
+        // is hard. Just telling flow it's OK.
+        // $FlowIgnore[incompatible-return]
+        return internalEntry;
+    };
+
+    /**
+     * Remove from cache, the entry matching the given handler and options.
+     *
+     * This will, if present therein, remove the value from the custom cache
+     * associated with the handler and the framework in-memory cache.
+     *
+     * Returns true if something was removed from any cache; otherwise, false.
+     */
+    remove: (id: string) => boolean = (id: string): boolean => {
+        // NOTE(somewhatabstract): We could invoke removeAll with a predicate
+        // 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.
+
+        // Delete the entry from the appropriate cache.
+        return (
+            this._hydrationCache.purge(DefaultScope, id) ||
+            (this._ssrOnlyCache?.purge(DefaultScope, id) ?? false)
+        );
+    };
+
+    /**
+     * 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.
+     */
+    removeAll: (
+        predicate?: (
+            key: string,
+            cachedEntry: $ReadOnly<CachedResponse<ValidCacheData>>,
+        ) => boolean,
+    ) => void = (predicate) => {
+        const realPredicate = predicate
+            ? // We know what we're putting into the cache so let's assume it
+              // conforms.
+              // $FlowIgnore[incompatible-call]
+              (_, key, cachedEntry) => predicate(key, cachedEntry)
+            : undefined;
+
+        // Apply the predicate to what we have in our caches.
+        this._hydrationCache.purgeAll(realPredicate);
+        this._ssrOnlyCache?.purgeAll(realPredicate);
+    };
+
+    /**
+     * Deep clone the hydration cache.
+     *
+     * By design, this only clones the data that is to be used for hydration.
+     */
+    cloneHydratableData: () => ResponseCache = (): ResponseCache => {
+        // We return our hydration cache only.
+        const cache = this._hydrationCache.clone();
+
+        // If we're empty, we still want to return an object, so we default
+        // to an empty object.
+        // We only need the default scope out of our scoped in-memory cache.
+        // We know that it conforms to our expectations.
+        // $FlowIgnore[incompatible-return]
+        return cache[DefaultScope] ?? {};
+    };
+}

package/src/util/types.js

@@ -1,135 +1,70 @@
 // @flow
-export type ValidData = string | boolean | number | {...};
-
-export type Status = "loading" | "success" | "error";
+/**
+ * Define what can be cached.
+ *
+ * We disallow functions and undefined as undefined represents a cache miss
+ * and functions are not allowed.
+ */
+export type ValidCacheData =
+    | string
+    | boolean
+    | number
+    | {...}
+    | Array<?ValidCacheData>;
 
-export type Result<TData: ValidData> =
+/**
+ * The normalized result of a request.
+ */
+export type Result<TData: ValidCacheData> =
     | {|
           status: "loading",
       |}
     | {|
           status: "success",
-          data?: TData,
+          data: TData,
       |}
     | {|
           status: "error",
           error: string,
+      |}
+    | {|
+          status: "aborted",
       |};
 
-export type CacheEntry<TData: ValidData> =
+/**
+ * A cache entry for a fulfilled request response.
+ */
+export type CachedResponse<TData: ValidCacheData> =
     | {|
           +error: string,
-          +data?: ?void,
+          +data?: void,
       |}
     | {|
           +data: TData,
-          +error?: ?void,
+          +error?: void,
       |};
 
-type HandlerSubcache = {
-    [key: string]: CacheEntry<any>,
-    ...
-};
-
-export type InterceptFulfillRequestFn<TOptions, TData: ValidData> = (
-    options: TOptions,
-) => ?Promise<TData>;
-
-export type Interceptor = {|
-    fulfillRequest: InterceptFulfillRequestFn<any, any>,
-|};
-
-export type InterceptContextData = {
-    [key: string]: Interceptor,
-    ...
-};
-
-export type Cache = {
-    [key: string]: HandlerSubcache,
+/**
+ * A cache of fulfilled request responses.
+ */
+export type ResponseCache = {
+    [key: string]: CachedResponse<any>,
     ...
 };
 
-export interface ICache<TOptions, TData: ValidData> {
-    /**
-     * Stores a value in the cache for the given handler and options.
-     */
-    store(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        entry: CacheEntry<TData>,
-    ): void;
-
-    /**
-     * Retrieves a value from the cache for the given handler and options.
-     */
-    retrieve(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): ?$ReadOnly<CacheEntry<TData>>;
-
-    /**
-     * Remove the cached entry for the given handler and options.
-     *
-     * If the item exists in the cache, the cached entry is deleted and true
-     * is returned. Otherwise, this returns false.
-     */
-    remove(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): boolean;
-
-    /**
-     * Remove all cached entries for the given handler that, optionally, match
-     * a given predicate.
-     *
-     * Returns the number of entries that were cleared from the cache.
-     */
-    removeAll(
-        handler: IRequestHandler<TOptions, TData>,
-        predicate?: (
-            key: string,
-            cachedEntry: $ReadOnly<CacheEntry<TData>>,
-        ) => boolean,
-    ): number;
-}
-
 /**
- * A handler for data requests.
+ * A cache with scoped sections.
  */
-export interface IRequestHandler<TOptions, TData: ValidData> {
+export type ScopedCache = {
     /**
-     * Fulfill a given request.
-     *
-     * @param {TOptions} options Options tha the request may need.
-     * @return {Promise<TData>} A promise of the requested data.
+     * The cache is scoped to allow easier clearing of different types of usage.
      */
-    fulfillRequest(options: TOptions): Promise<TData>;
-
-    /**
-     * The handler type; this is used to uniquely identify this handler from
-     * any other handler.
-     */
-    get type(): string;
-
-    /**
-     * 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.
-     *
-     * 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.
-     */
-    get hydrate(): 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.
-     */
-    getKey(options: TOptions): string;
-}
-
-export type ResponseCache = $ReadOnly<Cache>;
+    [scope: string]: {
+        /**
+         * Each value in the cache is then identified within a given scope.
+         */
+        [id: string]: ValidCacheData,
+        ...
+    },
+    ...
+};