Added syncExternalStore draft

Author: smikhalevski

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,145 @@
+/**
+ * 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, isObjectLike } 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 json = this.storageArea.getItem(this.key);
+
+    if (json === null) {
+      return null;
+    }
+    try {
+      const state = this.serializer.parse(json);
+
+      // Invalid external state
+      return isExecutorState(state) ? state : null;
+    } catch (e) {
+      setTimeout(() => {
+        throw e;
+      });
+      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);
+      }
+    };
+  }
+}
+
+function isExecutorState(state: ExecutorState | null): state is ExecutorState {
+  return (
+    isObjectLike(state) &&
+    isObjectLike(state.annotations) &&
+    typeof state.settledAt === 'number' &&
+    typeof state.invalidatedAt === 'number' &&
+    typeof state.isFulfilled === 'boolean'
+  );
+}

src/main/plugin/syncExternalStore.ts

@@ -0,0 +1,134 @@
+/**
+ * The plugin that persists the executor state in the observable external store.
+ *
+ * ```ts
+ * import syncExternalStore from 'react-executor/plugin/syncExternalStore';
+ *
+ * const executor = useExecutor('test', 42, [
+ *   syncExternalStore(myStore),
+ * ]);
+ * ```
+ *
+ * @module plugin/syncExternalStore
+ */
+
+import type { ExecutorPlugin, ExecutorState, Observable, PluginConfiguredPayload } from '../types.js';
+import { isShallowEqual } from '../utils.js';
+import type { ExecutorImpl } from '../ExecutorImpl.js';
+
+/**
+ * The observable external store.
+ *
+ * @template Value The value held by the external store.
+ */
+export interface ExternalStore<Value> extends Observable<Value | null | undefined | void> {
+  /**
+   * Returns the current stored value, or `null` if there's no value.
+   */
+  get(): Value | null;
+
+  /**
+   * Sets a new value to the store.
+   *
+   * @param value A value to set.
+   */
+  set?(value: Value): void;
+
+  /**
+   * Deletes a value from the store.
+   */
+  delete?(): void;
+}
+
+/**
+ * Persists the executor state in the observable external store.
+ *
+ * @param store The external store to persist executor state.
+ * @template Value The value stored by the executor.
+ */
+export default function syncExternalStore<Value>(store: ExternalStore<ExecutorState<Value>>): ExecutorPlugin<Value> {
+  return executor => {
+    const setExternalState = () => store.set?.(executor.getStateSnapshot());
+
+    const setExecutorState = (nextState: ExecutorState | null | undefined | void = store.get()) => {
+      if (executor.isPending) {
+        // The executor would overwrite external state when settled
+        return;
+      }
+
+      const prevState = executor.getStateSnapshot();
+
+      if (nextState === null || (nextState.settledAt !== 0 && nextState.settledAt < prevState.settledAt)) {
+        // No external state or it is outdated
+        setExternalState();
+        return;
+      }
+
+      publishChanges(executor as ExecutorImpl, prevState, nextState);
+    };
+
+    const unsubscribe = store.subscribe(setExecutorState);
+
+    executor.subscribe(event => {
+      switch (event.type) {
+        case 'annotated':
+        case 'fulfilled':
+        case 'rejected':
+        case 'cleared':
+        case 'invalidated':
+          setExternalState();
+          break;
+
+        case 'aborted':
+          setExecutorState(store.get());
+          break;
+
+        case 'detached':
+          store.delete?.();
+          unsubscribe();
+          break;
+      }
+    });
+
+    executor.publish({
+      type: 'plugin_configured',
+      payload: { type: 'syncExternalStore', options: { store } } satisfies PluginConfiguredPayload,
+    });
+
+    setExecutorState(store.get());
+  };
+}
+
+function publishChanges(executor: ExecutorImpl, prevState: ExecutorState, nextState: ExecutorState): void {
+  // Update the executor with the external state
+  executor.value = nextState.value;
+  executor.reason = nextState.reason;
+  executor.annotations = nextState.annotations;
+  executor.settledAt = nextState.settledAt;
+  executor.invalidatedAt = nextState.invalidatedAt;
+  executor.isFulfilled = nextState.isFulfilled;
+  executor.version++;
+
+  if (!isShallowEqual(nextState.annotations, prevState.annotations)) {
+    // Annotations have changed
+    executor.publish({ type: 'annotated' });
+  }
+
+  // The executor was fulfilled, rejected or cleared
+  if (nextState.isFulfilled) {
+    if (prevState.settledAt === 0 || !prevState.isFulfilled || !Object.is(prevState.value, nextState.value)) {
+      executor.publish({ type: 'fulfilled' });
+    }
+  } else if (nextState.settledAt !== 0) {
+    if (prevState.settledAt === 0 || prevState.isFulfilled || !Object.is(prevState.reason, nextState.reason)) {
+      executor.publish({ type: 'rejected' });
+    }
+  } else if (prevState.settledAt !== 0) {
+    executor.publish({ type: 'cleared' });
+  }
+
+  if (nextState.invalidatedAt !== 0 && prevState.invalidatedAt === 0) {
+    // The executor was invalidated
+    executor.publish({ type: 'invalidated' });
+  }
+}

src/main/utils.ts

@@ -42,12 +42,6 @@ export function isShallowEqual(a: any, b: any): boolean {
   return true;
 }
 
-export function throwUnhandled(error: unknown): void {
-  setTimeout(() => {
-    throw error;
-  }, 0);
-}
-
 /**
  * Returns the observable that inverses boolean values emitted by another observable.
  *

src/test/ExecutorImpl.test.ts

@@ -4,7 +4,8 @@ import { ExecutorImpl } from '../main/ExecutorImpl.js';
 import { AbortError, noop } from '../main/utils.js';
 import { ExecutorEvent, ExecutorState } from '../main/index.js';
 
-Date.now = () => 50;
+vi.useFakeTimers();
+vi.setSystemTime(50);
 
 const expectedReason = new Error('expected');
 

src/test/ExecutorManager.test.ts

@@ -2,7 +2,8 @@ import { beforeEach, describe, expect, Mock, test, vi } from 'vitest';
 import { ExecutorManager } from '../main/index.js';
 import { ExecutorImpl } from '../main/ExecutorImpl.js';
 
-Date.now = () => 50;
+vi.useFakeTimers();
+vi.setSystemTime(50);
 
 let listenerMock: Mock;
 let manager: ExecutorManager;