.editorconfig

@@ -1,11 +1,10 @@
-# http://editorconfig.org
-
 root = true
 
 [*]
 charset = utf-8
 end_of_line = lf
 indent_style = space
 indent_size = 2
+max_line_length = 80
 trim_trailing_whitespace = true
 insert_final_newline = true

.eslintrc.json

@@ -1,3 +1,31 @@
 {
-  "extends": ["env"]
+  "extends": ["eslint:recommended", "plugin:react-hooks/recommended"],
+  "env": {
+    "es2022": true,
+    "node": true,
+    "browser": true
+  },
+  "parserOptions": {
+    "ecmaVersion": "latest"
+  },
+  "plugins": ["simple-import-sort"],
+  "rules": {
+    "simple-import-sort/imports": "error",
+    "simple-import-sort/exports": "error"
+  },
+  "overrides": [
+    {
+      "files": ["*.mjs"],
+      "parserOptions": {
+        "sourceType": "module"
+      },
+      "globals": {
+        "__dirname": "off",
+        "__filename": "off",
+        "exports": "off",
+        "module": "off",
+        "require": "off"
+      }
+    }
+  ]
 }

.github/funding.yml

@@ -0,0 +1 @@
+github: jaydenseric

.github/workflows/ci.yml

@@ -1,22 +1,18 @@
 name: CI
-on: [push]
+on: [push, workflow_dispatch]
 jobs:
   test:
     name: Test with Node.js v${{ matrix.node }} and ${{ matrix.os }}
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
-        node: ['8', '10', '12', '13']
+        node: ["18", "20", "22"]
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v4
       - name: Setup Node.js v${{ matrix.node }}
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node }}
       - name: npm install and test
-        run: |
-          npm install
-          npm test
-        env:
-          CI: true
+        run: npm install-test

.gitignore

@@ -1,7 +1,2 @@
 node_modules
-npm-debug.log
 .DS_Store
-/universal
-/server
-/test
-.nyc_output

.prettierignore

@@ -1,3 +1 @@
 package.json
-.nyc_output
-tap-snapshots

.prettierrc.json

@@ -1,5 +1,3 @@
 {
-  "proseWrap": "never",
-  "singleQuote": true,
-  "semi": false
+  "proseWrap": "never"
 }

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "typescript.disableAutomaticTypeAcquisition": true,
+  "typescript.enablePromptUseWorkspaceTsdk": true,
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

Cache.mjs

@@ -0,0 +1,70 @@
+// @ts-check
+
+/**
+ * Cache store.
+ * @see {@link CacheEventMap `CacheEventMap`} for a map of possible events.
+ */
+export default class Cache extends EventTarget {
+  /**
+   * @param {CacheStore} [store] Initial {@link Cache.store cache store}.
+   *   Defaults to `{}`. Useful for hydrating cache data from a server side
+   *   render prior to the initial client side render.
+   */
+  constructor(store = {}) {
+    super();
+
+    if (typeof store !== "object" || !store || Array.isArray(store))
+      throw new TypeError("Constructor argument 1 `store` must be an object.");
+
+    /**
+     * Store of cache {@link CacheKey keys} and associated
+     * {@link CacheValue values}.
+     * @type {CacheStore}
+     */
+    this.store = store;
+  }
+}
+
+/**
+ * Map of possible {@linkcode Cache} events. Note that the keys don’t match the
+ * dispatched event names that dynamically contain the associated
+ * {@link CacheKey cache key}.
+ * @typedef {object} CacheEventMap
+ * @prop {CustomEvent<CacheEventSetDetail>} set Signals that a
+ *   {@link Cache.store cache store} entry was set. The event name starts with
+ *   the {@link CacheKey cache key} of the set entry, followed by `/set`.
+ * @prop {CustomEvent} stale Signals that a {@link Cache.store cache store}
+ *   entry is now stale (often due to a mutation) and should probably be
+ *   reloaded. The event name starts with the
+ *   {@link CacheKey cache key} of the stale entry, followed by `/stale`.
+ * @prop {CustomEvent} prune Signals that a {@link Cache.store cache store}
+ *   entry will be deleted unless the event is canceled via
+ *   `event.preventDefault()`. The event name starts with the
+ *   {@link CacheKey cache key} of the entry being pruned, followed by `/prune`.
+ * @prop {CustomEvent} delete Signals that a {@link Cache.store cache store}
+ *   entry was deleted. The event name starts with the
+ *   {@link CacheKey cache key} of the deleted entry, followed by `/delete`.
+ */
+
+/**
+ * @typedef {object} CacheEventSetDetail
+ * @prop {CacheValue} cacheValue The set {@link CacheValue cache value}.
+ */
+
+/**
+ * Unique key to access a {@link CacheValue cache value}.
+ * @typedef {string} CacheKey
+ */
+
+/**
+ * {@link Cache.store Cache store} value. If server side rendering, it should
+ * be JSON serializable for client hydration. It should contain information
+ * about any errors that occurred during loading so they can be rendered, and if
+ * server side rendering, be hydrated on the client.
+ * @typedef {unknown} CacheValue
+ */
+
+/**
+ * Cache store.
+ * @typedef {{ [cacheKey: CacheKey]: CacheValue }} CacheStore
+ */

Cache.test.mjs

@@ -0,0 +1,70 @@
+// @ts-check
+
+import "./test/polyfillCustomEvent.mjs";
+
+import { deepStrictEqual, strictEqual, throws } from "node:assert";
+import { describe, it } from "node:test";
+
+import Cache from "./Cache.mjs";
+import assertBundleSize from "./test/assertBundleSize.mjs";
+import assertInstanceOf from "./test/assertInstanceOf.mjs";
+
+describe("Class `Cache`.", { concurrency: true }, () => {
+  it("Bundle size.", async () => {
+    await assertBundleSize(new URL("./Cache.mjs", import.meta.url), 200);
+  });
+
+  it("Constructor argument 1 `store` not an object.", () => {
+    throws(() => {
+      new Cache(
+        // @ts-expect-error Testing invalid.
+        null,
+      );
+    }, new TypeError("Constructor argument 1 `store` must be an object."));
+  });
+
+  it("Constructor argument 1 `store` missing", () => {
+    const cache = new Cache();
+
+    deepStrictEqual(cache.store, {});
+  });
+
+  it("Constructor argument 1 `store` an object.", () => {
+    const initialStore = {
+      a: 1,
+      b: 2,
+    };
+    const cache = new Cache({ ...initialStore });
+
+    deepStrictEqual(cache.store, initialStore);
+  });
+
+  it("Events.", () => {
+    const cache = new Cache();
+
+    assertInstanceOf(cache, EventTarget);
+
+    /** @type {Event | null} */
+    let listenedEvent = null;
+
+    /** @type {EventListener} */
+    const listener = (event) => {
+      listenedEvent = event;
+    };
+
+    const eventName = "a";
+    const event = new CustomEvent(eventName);
+
+    cache.addEventListener(eventName, listener);
+    cache.dispatchEvent(event);
+
+    strictEqual(listenedEvent, event);
+
+    listenedEvent = null;
+
+    cache.removeEventListener(eventName, listener);
+    cache.dispatchEvent(new CustomEvent(eventName));
+
+    strictEqual(listenedEvent, null);
+  });
+});

CacheContext.mjs

@@ -0,0 +1,18 @@
+// @ts-check
+
+/** @import Cache from "./Cache.mjs" */
+
+import React from "react";
+
+/**
+ * [React context](https://reactjs.org/docs/context.html) for a
+ * {@linkcode Cache} instance.
+ * @type {React.Context<Cache | undefined>}
+ */
+const CacheContext = React.createContext(
+  /** @type {Cache | undefined} */ (undefined),
+);
+
+CacheContext.displayName = "CacheContext";
+
+export default CacheContext;

CacheContext.test.mjs

@@ -0,0 +1,38 @@
+// @ts-check
+
+import { strictEqual } from "node:assert";
+import { describe, it } from "node:test";
+
+import React from "react";
+
+import Cache from "./Cache.mjs";
+import CacheContext from "./CacheContext.mjs";
+import assertBundleSize from "./test/assertBundleSize.mjs";
+import createReactTestRenderer from "./test/createReactTestRenderer.mjs";
+
+describe("React context `CacheContext`.", { concurrency: true }, () => {
+  it("Bundle size.", async () => {
+    await assertBundleSize(new URL("./CacheContext.mjs", import.meta.url), 120);
+  });
+
+  it("Used as a React context.", () => {
+    let contextValue;
+
+    function TestComponent() {
+      contextValue = React.useContext(CacheContext);
+      return null;
+    }
+
+    const value = new Cache();
+
+    createReactTestRenderer(
+      React.createElement(
+        CacheContext.Provider,
+        { value },
+        React.createElement(TestComponent),
+      ),
+    );
+
+    strictEqual(contextValue, value);
+  });
+});

HYDRATION_TIME_MS.mjs

@@ -0,0 +1,10 @@
+// @ts-check
+
+/** @import useAutoLoad from "./useAutoLoad.mjs" */
+
+/**
+ * Number of milliseconds after the first client render that’s considered the
+ * hydration time; during which the {@linkcode useAutoLoad} React hook won’t
+ * load if the cache entry is already populated.
+ */
+export default 1000;

HYDRATION_TIME_MS.test.mjs

@@ -0,0 +1,20 @@
+// @ts-check
+
+import { strictEqual } from "node:assert";
+import { describe, it } from "node:test";
+
+import HYDRATION_TIME_MS from "./HYDRATION_TIME_MS.mjs";
+import assertBundleSize from "./test/assertBundleSize.mjs";
+
+describe("Constant `HYDRATION_TIME_MS`.", { concurrency: true }, () => {
+  it("Bundle size.", async () => {
+    await assertBundleSize(
+      new URL("./HYDRATION_TIME_MS.mjs", import.meta.url),
+      65,
+    );
+  });
+
+  it("Value.", () => {
+    strictEqual(HYDRATION_TIME_MS, 1000);
+  });
+});

HydrationTimeStampContext.mjs

@@ -0,0 +1,16 @@
+// @ts-check
+
+import React from "react";
+
+/**
+ * [React context](https://reactjs.org/docs/context.html) for the client side
+ * hydration {@link DOMHighResTimeStamp time stamp}.
+ * @type {React.Context<DOMHighResTimeStamp | undefined>}
+ */
+const HydrationTimeStampContext = React.createContext(
+  /** @type {DOMHighResTimeStamp | undefined} */ (undefined),
+);
+
+HydrationTimeStampContext.displayName = "HydrationTimeStampContext";
+
+export default HydrationTimeStampContext;