@khanacademy/wonder-blocks-data 3.2.0 → 4.0.0

package/src/util/memory-cache.js

@@ -1,187 +0,0 @@
-// @flow
-import type {
-    ValidData,
-    ICache,
-    CacheEntry,
-    Cache,
-    IRequestHandler,
-} from "./types.js";
-
-function deepClone<T: {...}>(source: T | $ReadOnly<T>): $ReadOnly<T> {
-    /**
-     * We want to deep clone the source cache to dodge mutations by external
-     * references. So we serialize the source cache to JSON and parse it
-     * back into a new object.
-     *
-     * NOTE: This doesn't work for get/set property accessors.
-     */
-    const serializedInitCache = JSON.stringify(source);
-    const cloneInitCache = JSON.parse(serializedInitCache);
-    return Object.freeze(cloneInitCache);
-}
-
-/**
- * INTERNAL USE ONLY
- *
- * Special case cache implementation for the memory cache.
- *
- * This is only used within our framework for SSR (see ./response-cache.js).
- */
-export default class MemoryCache<TOptions, TData: ValidData>
-    implements ICache<TOptions, TData>
-{
-    _cache: Cache;
-
-    constructor(source: ?$ReadOnly<Cache> = null) {
-        this._cache = {};
-        if (source != null) {
-            try {
-                /**
-                 * Object.assign only performs a shallow clone.
-                 * So we deep clone it and then assign the clone values to our
-                 * internal cache.
-                 */
-                const cloneInitCache = deepClone(source);
-                Object.assign(this._cache, cloneInitCache);
-            } catch (e) {
-                throw new Error(
-                    `An error occurred trying to initialize from a response cache snapshot: ${e}`,
-                );
-            }
-        }
-    }
-
-    /**
-     * 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;
-    }
-
-    store: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        entry: CacheEntry<TData>,
-    ) => void = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        entry: CacheEntry<TData>,
-    ): void => {
-        const requestType = handler.type;
-
-        const frozenEntry = Object.freeze(entry);
-
-        // Ensure we have a cache location for this handler type.
-        this._cache[requestType] = this._cache[requestType] || {};
-
-        // Cache the data.
-        const key = handler.getKey(options);
-        this._cache[requestType][key] = frozenEntry;
-    };
-
-    retrieve: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ) => ?CacheEntry<TData> = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): ?CacheEntry<TData> => {
-        const requestType = handler.type;
-
-        // Get the internal subcache for the handler.
-        const handlerCache = this._cache[requestType];
-        if (!handlerCache) {
-            return null;
-        }
-
-        // Get the response.
-        const key = handler.getKey(options);
-        const internalEntry = handlerCache[key];
-        if (internalEntry == null) {
-            return null;
-        }
-
-        return internalEntry;
-    };
-
-    remove: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ) => boolean = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): boolean => {
-        const requestType = handler.type;
-
-        // 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.
-
-        // Get the internal subcache for the handler.
-        const handlerCache = this._cache[requestType];
-        if (!handlerCache) {
-            return false;
-        }
-
-        // Get the entry.
-        const key = handler.getKey(options);
-        const internalEntry = handlerCache[key];
-        if (internalEntry == null) {
-            return false;
-        }
-
-        // Delete the entry.
-        delete handlerCache[key];
-        return true;
-    };
-
-    removeAll: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        predicate?: (
-            key: string,
-            cachedEntry: $ReadOnly<CacheEntry<TData>>,
-        ) => boolean,
-    ) => number = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        predicate?: (
-            key: string,
-            cachedEntry: $ReadOnly<CacheEntry<TData>>,
-        ) => boolean,
-    ): number => {
-        const requestType = handler.type;
-
-        // Get the internal subcache for the handler.
-        const handlerCache = this._cache[requestType];
-        if (!handlerCache) {
-            return 0;
-        }
-
-        let removedCount = 0;
-        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;
-    };
-
-    cloneData: () => $ReadOnly<Cache> = (): $ReadOnly<Cache> => {
-        try {
-            return deepClone(this._cache);
-        } catch (e) {
-            throw new Error(
-                `An error occurred while trying to clone the cache: ${e}`,
-            );
-        }
-    };
-}

package/src/util/request-handler.js

@@ -1,42 +0,0 @@
-// @flow
-import type {ValidData, IRequestHandler} from "./types.js";
-
-/**
- * Base implementation for creating a request handler.
- *
- * Provides a base implementation of the `IRequestHandler` base class for
- * use with the Wonder Blocks Data framework.
- */
-export default class RequestHandler<TOptions, TData: ValidData>
-    implements IRequestHandler<TOptions, TData>
-{
-    _type: string;
-    _hydrate: boolean;
-
-    constructor(type: string, hydrate?: boolean = true) {
-        this._type = type;
-        this._hydrate = !!hydrate;
-    }
-
-    get type(): string {
-        return this._type;
-    }
-
-    get hydrate(): boolean {
-        return this._hydrate;
-    }
-
-    getKey(options: TOptions): string {
-        try {
-            return options === undefined
-                ? "undefined"
-                : (JSON.stringify(options): any);
-        } catch (e) {
-            throw new Error(`Failed to auto-generate key: ${e}`);
-        }
-    }
-
-    fulfillRequest(options: TOptions): Promise<TData> {
-        throw new Error("Not implemented");
-    }
-}

package/src/util/request-handler.md

@@ -1,51 +0,0 @@
-This class implements the `IRequestHandler` interface. It is to be used as a
-base class to implement your own request handler.
-
-```js static
-interface IRequestHandler<TOptions, TData> {
-    /**
-     * Fulfill a given request.
-     */
-    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.
-     */
-    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;
-}
-```
-
-The constructor requires a `type` to identify your handler. This should be unique
-among the handlers that are used across your application, otherwise, requests
-may be fulfilled by the wrong handler.
-
-The `fulfillRequest` method of this class is not implemented and will throw if
-called. Subclasses will need to implement this method.
-
-A default implementation of `getKey` is provided that serializes the options of
-a request to a string and uses that as the cache key. You may want to override
-this behavior to simplify the key or to omit some values from the key.
-
-The `hydrate` property indicates if the data that is fulfilled for the handler
-during SSR should be provided for hydration. This should be `true` in most
-cases. When `false`, React hydration will fail unless some other aspect of your
-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.

package/src/util/response-cache.js

@@ -1,213 +0,0 @@
-// @flow
-import {Server} from "@khanacademy/wonder-blocks-core";
-import MemoryCache from "./memory-cache.js";
-
-import type {
-    ValidData,
-    CacheEntry,
-    Cache,
-    IRequestHandler,
-    ResponseCache as ResCache,
-} from "./types.js";
-
-/**
- * The default instance is stored here.
- * It's created below in the Default() static property.
- */
-let _default: ResponseCache;
-
-/**
- * Implements the response cache.
- *
- * INTERNAL USE ONLY
- */
-export class ResponseCache {
-    static get Default(): ResponseCache {
-        if (!_default) {
-            _default = new ResponseCache();
-        }
-        return _default;
-    }
-
-    _hydrationCache: MemoryCache<any, any>;
-    _ssrOnlyCache: ?MemoryCache<any, any>;
-
-    constructor(
-        hydrationCache: ?MemoryCache<any, any> = null,
-        ssrOnlyCache: ?MemoryCache<any, any> = null,
-    ) {
-        this._ssrOnlyCache = Server.isServerSide()
-            ? ssrOnlyCache || new MemoryCache()
-            : undefined;
-        this._hydrationCache = hydrationCache || new MemoryCache();
-    }
-
-    _setCacheEntry<TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        entry: CacheEntry<TData>,
-    ): CacheEntry<TData> {
-        const frozenEntry = Object.freeze(entry);
-        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;
-    }
-
-    /**
-     * Initialize the cache from a given cache state.
-     *
-     * This can only be called if the cache is not already in use.
-     */
-    initialize: (source: ResCache) => void = (source) => {
-        if (this._hydrationCache.inUse) {
-            throw new Error(
-                "Cannot initialize data response cache more than once",
-            );
-        }
-
-        try {
-            this._hydrationCache = new MemoryCache(source);
-        } catch (e) {
-            throw new Error(
-                `An error occurred trying to initialize the data response cache: ${e}`,
-            );
-        }
-    };
-
-    /**
-     * Cache data for a specific response.
-     *
-     * This is a noop when client-side.
-     */
-    cacheData: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        data: TData,
-    ) => CacheEntry<TData> = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        data: TData,
-    ): 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>,
-        options: TOptions,
-        error: Error | string,
-    ) => CacheEntry<TData> = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        error: Error | string,
-    ): CacheEntry<TData> => {
-        const errorMessage = typeof error === "string" ? error : error.message;
-        return this._setCacheEntry(handler, options, {error: errorMessage});
-    };
-
-    /**
-     * Retrieve data from our cache.
-     */
-    getEntry: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ) => ?$ReadOnly<CacheEntry<TData>> = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): ?$ReadOnly<CacheEntry<TData>> => {
-        // 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);
-
-        // 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.remove(handler, options);
-        }
-        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: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ) => boolean = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): 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 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 framework
-     * in-memory cache.
-     *
-     * It returns a count of all records removed.
-     */
-    removeAll: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        predicate?: (
-            key: string,
-            cachedEntry: $ReadOnly<CacheEntry<TData>>,
-        ) => boolean,
-    ) => number = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        predicate?: (
-            key: string,
-            cachedEntry: $ReadOnly<CacheEntry<TData>>,
-        ) => boolean,
-    ): number => {
-        // 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 only clones the data that is to be used for hydration.
-     */
-    cloneHydratableData: () => $ReadOnly<Cache> = (): $ReadOnly<Cache> => {
-        // We return our hydration cache only.
-        return this._hydrationCache.cloneData();
-    };
-}