Added syncExternalStore plugin (#38)

Author: smikhalevski

README.md

@@ -77,7 +77,8 @@ npm install --save-prod react-executor
 - [`retryInvalidated`](#retryinvalidated)
 - [`retryRejected`](#retryrejected)
 - [`retryWhen`](#retrywhen)
-- [`syncStorage`](#syncstorage)
+- [`syncBrowserStorage`](#syncbrowserstorage)
+- [`syncExternalStore`](#syncsxternalstore)
 
 <span class="toc-icon">⚛️&ensp;</span>[**React integration**](#react-integration)
 
@@ -1411,17 +1412,14 @@ const executor = useExecutor('test', heavyTask, [
 ]);
 ```
 
-## `syncStorage`
+## `syncBrowserStorage`
 
-Persists the executor value in the synchronous storage.
+Synchronizes the executor state with `localStorage` or `sessionStorage` item. No-op in a non-browser environment.
 
-<!-- prettier-ignore -->
 ```ts
-import syncStorage from 'react-executor/plugin/syncStorage';
+import syncBrowserStorage from 'react-executor/plugin/syncBrowserStorage';
 
-const executor = useExecutor('test', 42, [
-  syncStorage(localStorage),
-]);
+const executor = useExecutor('test', 42, [syncBrowserStorage()]);
 ```
 
 With this plugin, you can synchronize the executor state
@@ -1442,7 +1440,7 @@ Here's how you can enable serialization of objects with circular references:
 import JSONMarshal from 'json-marshal';
 
 const executor = useExecutor('test', 42, [
-  syncStorage(localStorage, {
+  syncBrowserStorage({
     serializer: JSONMarshal,
   }),
 ]);
@@ -1452,22 +1450,53 @@ const executor = useExecutor('test', 42, [
 > With additional configuration, [json-marshal&#8239;<sup>↗</sup>](https://github.com/smikhalevski/json-marshal#readme)
 > can stringify and parse any data structure.
 
-By default, `syncStorage` plugin uses a [serialized executor key](#executor-keys) as a storage key. You can provide a
-custom key
-via [`storageKey`&#8239;<sup>↗</sup>](https://smikhalevski.github.io/react-executor/interfaces/plugin_syncStorage.SyncStorageOptions.html#storagekey)
+By default, `syncBrowserStorage` plugin uses a [serialized executor key](#executor-keys) as a storage key. You can
+provide a custom key
+via [`storageKey`&#8239;<sup>↗</sup>](https://smikhalevski.github.io/react-executor/interfaces/plugin_syncBrowserStorage.SyncBrowserStorageOptions.html#storagekey)
 option:
 
 ```ts
-useExecutor('test', 42, [syncStorage(localStorage, { storageKey: 'hello' })]);
+useExecutor('test', 42, [syncBrowserStorage({ storageKey: 'hello' })]);
 ```
 
-In the environment where storage is unavailable (for example, [during SSR](#server-side-rendering)), you can
-conditionally disable the plugin:
+## `syncExternalStore`
+
+Persists the executor state in the observable external store.
+
+Here's the minimal external store example:
 
 ```ts
-useExecutor('test', 42, [typeof localStorage !== 'undefined' ? syncStorage(localStorage) : null]);
+import { useExecutor, ExecutorState } from 'react-executor';
+import syncExternalStore, { ExternalStore } from 'react-executor/plugin/syncExternalStore';
+
+let myStoredState: ExecutorState | null = null;
+
+const myStore: ExternalStore<ExecutorState> = {
+  get() {
+    return myStoredState;
+  },
+
+  subscribe(listener) {
+    // Place subscription login here
+    return () => {};
+  },
+};
+
+const myExecutor = useExecutor('test', 42, [syncExternalStore(myStore)]);
 ```
 
+When executor is [settled](#settle-an-executor), [cleared](#clear-an-executor), [invalidated](#invalidate-results) or
+annotated then the plugin calls
+the [`ExternalStore.set`&#8239;<sup>↗</sup>](https://smikhalevski.github.io/react-executor/interfaces/plugin_syncExternalStore.ExternalStore.html#set)
+method on the store.
+
+When executor is [detached](#detach-an-executor) then the plugin calls
+the [`ExternalStore.delete`&#8239;<sup>↗</sup>](https://smikhalevski.github.io/react-executor/interfaces/plugin_syncExternalStore.ExternalStore.html#delete)
+method on the store.
+
+Prefer [`syncBrowserStorage`](#syncbrowserstorage) if you want to persist the executor state in a `localStorage`
+or `sessionStorage`.
+
 # React integration
 
 In the basic scenario, to use executors in your React app, you don't need any additional configuration, just use
@@ -2091,21 +2120,21 @@ const App = () => <ExecutorManagerProvider value={manager}>{/* Render you app he
 
 ## Storage state versioning
 
-You can store an executor state in a `localStorage` using the [`syncStorage`](#syncstorage) plugin:
+You can store an executor state in a `localStorage` using the [`syncBrowserStorage`](#syncbrowserstorage) plugin:
 
 ```ts
 import { useExecutor } from 'react-executor';
-import syncStorage from 'react-executor/plugin/syncStorage';
+import syncBrowserStorage from 'react-executor/plugin/syncBrowserStorage';
 
-const playerExecutor = useExecutor('player', { health: '50%' }, [syncStorage(localStorage)]);
+const playerExecutor = useExecutor('player', { health: '50%' }, [syncBrowserStorage()]);
 // ⮕ Executor<{ health: string }>
 ```
 
 But what if over time you'd like to change the structure of the value stored in the `playerExecutor`? For example,
 make `health` property a number:
 
 ```ts
-const playerExecutor = useExecutor('player', { health: 0.5 }, [syncStorage(localStorage)]);
+const playerExecutor = useExecutor('player', { health: 0.5 }, [syncBrowserStorage()]);
 ```
 
 After users have used the previous version of the app where `health` was a string, they would still receive a string
@@ -2139,10 +2168,10 @@ export function requireVersion(version: number): ExecutorPlugin {
 Add the plugin to the executor:
 
 ```ts
-const playerExecutor = useExecutor('player', { health: 0.5 }, [syncStorage(localStorage), requireVersion(1)]);
+const playerExecutor = useExecutor('player', { health: 0.5 }, [syncBrowserStorage(), requireVersion(1)]);
 ```
 
-After the `syncStorage` plugin reads the data from the `localStorage`, the `requireVersion` plugin ensures that
+After the `syncBrowserStorage` plugin reads the data from the `localStorage`, the `requireVersion` plugin ensures that
 the `version` annotation read from the `localStorage` matches the required version. On mismatch the executor is cleared
 and the initial value `{ health: 0.5 }` is written to the storage.
 
@@ -2176,7 +2205,7 @@ Now `requireVersion` would apply the migration on the state version mismatch:
 
 ```ts
 const playerExecutor = useExecutor('player', { health: 0.5 }, [
-  syncStorage(localStorage),
+  syncBrowserStorage(),
 
   requireVersion(1, executor => {
     executor.resolve({

package.json

@@ -30,7 +30,8 @@
     "./plugin/retryInvalidated": "./plugin/retryInvalidated.js",
     "./plugin/retryRejected": "./plugin/retryRejected.js",
     "./plugin/retryWhen": "./plugin/retryWhen.js",
-    "./plugin/syncStorage": "./plugin/syncStorage.js",
+    "./plugin/syncBrowserStorage": "./plugin/syncBrowserStorage.js",
+    "./plugin/syncExternalStore": "./plugin/syncExternalStore.js",
     "./package.json": "./package.json"
   },
   "sideEffects": false,

src/main/plugin/syncBrowserStorage.ts

@@ -0,0 +1,134 @@
+/**
+ * The plugin that synchronizes the executor state with a browser storage item.
+ *
+ * ```ts
+ * import syncBrowserStorage from 'react-executor/plugin/syncBrowserStorage';
+ *
+ * const executor = useExecutor('test', 42, [syncBrowserStorage()]);
+ * ```
+ *
+ * @module plugin/syncBrowserStorage
+ */
+
+import type { Executor, ExecutorPlugin, ExecutorState, Serializer } from '../types.js';
+import { emptyObject } from '../utils.js';
+import syncExternalStore, { ExternalStore } from './syncExternalStore.js';
+import { PubSub } from 'parallel-universe';
+
+/**
+ * Options of the {@link syncBrowserStorage} plugin.
+ */
+export interface SyncBrowserStorageOptions {
+  /**
+   * The storage where executor state is persisted.
+   *
+   * @default "local"
+   */
+  storageType?: 'local' | 'session';
+
+  /**
+   * A storage item key, or a callback that returns a storage item key.
+   *
+   * By default, an {@link react-executor!ExecutorManagerOptions.keyIdGenerator executor key ID} is used.
+   */
+  storageKey?: string | ((executor: Executor) => string);
+
+  /**
+   * The storage item value serializer.
+   *
+   * @default JSON
+   */
+  serializer?: Serializer;
+}
+
+/**
+ * Synchronizes the executor state with a browser storage item. No-op in a non-browser environment.
+ *
+ * If an executor is detached, then the corresponding item is removed from the storage.
+ *
+ * @param options Storage options.
+ */
+export default function syncBrowserStorage(options: SyncBrowserStorageOptions = emptyObject): ExecutorPlugin {
+  const { storageType = 'local', storageKey, serializer = JSON } = options;
+
+  return executor => {
+    const key =
+      storageKey === undefined
+        ? executor.manager.keyIdGenerator(executor.key)
+        : typeof storageKey === 'function'
+          ? storageKey(executor)
+          : storageKey;
+
+    if (typeof key !== 'string') {
+      throw new Error('Cannot guess a storage key for an executor, the "storageKey" option is required');
+    }
+
+    if (typeof window !== 'undefined') {
+      syncExternalStore(new BrowserStore(storageType, key, serializer))(executor);
+    }
+  };
+}
+
+const pubSub = new PubSub<StorageEvent>();
+
+function handleStorage(event: StorageEvent): void {
+  pubSub.publish(event);
+}
+
+class BrowserStore implements ExternalStore<ExecutorState> {
+  readonly storageArea;
+
+  constructor(
+    readonly storageType: 'local' | 'session',
+    readonly key: string,
+    readonly serializer: Serializer
+  ) {
+    this.storageArea = this.storageType === 'session' ? sessionStorage : localStorage;
+  }
+
+  get(): ExecutorState | null {
+    const storedValue = this.storageArea.getItem(this.key);
+
+    if (storedValue === null) {
+      return null;
+    }
+
+    try {
+      return this.serializer.parse(storedValue);
+    } catch (error) {
+      setTimeout(() => {
+        // Throw unhandled error
+        throw error;
+      }, 0);
+      return null;
+    }
+  }
+
+  set(state: ExecutorState): void {
+    this.storageArea.setItem(this.key, this.serializer.stringify(state));
+  }
+
+  delete(): void {
+    this.storageArea.removeItem(this.key);
+  }
+
+  subscribe(listener: (state: ExecutorState | null) => void): () => void {
+    if (pubSub.listenerCount === 0) {
+      window.addEventListener('storage', handleStorage);
+    }
+
+    const unsubscribe = pubSub.subscribe(event => {
+      if (event.storageArea === this.storageArea && event.key === this.key) {
+        listener(this.get());
+      }
+    });
+
+    return () => {
+      unsubscribe();
+
+      if (pubSub.listenerCount === 0) {
+        window.removeEventListener('storage', handleStorage);
+      }
+    };
+  }
+}