Added syncExternalStore

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,132 @@
+/**
+ * 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 json = this.storageArea.getItem(this.key);
+
+    if (json === null) {
+      return null;
+    }
+    try {
+      return this.serializer.parse(json);
+    } 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);
+      }
+    };
+  }
+}

src/main/plugin/syncExternalStore.ts

@@ -0,0 +1,110 @@
+import type { ExecutorPlugin, ExecutorState, Observable, PluginConfiguredPayload } from '../types.js';
+import { isObjectLike, isShallowEqual } from '../utils.js';
+import type { ExecutorImpl } from '../ExecutorImpl.js';
+
+export interface ExternalStore<Value> extends Observable<Value | null> {
+  get(): Value | null;
+
+  set?(value: Value): void;
+
+  delete?(): void;
+}
+
+export default function syncExternalStore<Value>(store: ExternalStore<ExecutorState<Value>>): ExecutorPlugin<Value> {
+  return executor => {
+    const setExternalState = () => store.set?.(executor.getStateSnapshot());
+
+    const setExecutorState = (nextState: ExecutorState | null) => {
+      if (executor.isPending) {
+        // The executor would overwrite external state when settled
+        return;
+      }
+
+      const prevState = executor.getStateSnapshot();
+
+      if (
+        // No external state
+        nextState === null ||
+        // Invalid external state
+        !isExecutorState(nextState) ||
+        // External state is outdated
+        (nextState.settledAt !== 0 && nextState.settledAt < prevState.settledAt)
+      ) {
+        setExternalState();
+        return;
+      }
+
+      publishChanges(executor as ExecutorImpl, prevState, nextState);
+    };
+
+    const unsubscribe = store.subscribe(setExecutorState);
+
+    setExecutorState(store.get());
+
+    executor.subscribe(event => {
+      switch (event.type) {
+        case 'cleared':
+        case 'fulfilled':
+        case 'rejected':
+        case 'invalidated':
+        case 'annotated':
+          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,
+    });
+  };
+}
+
+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 resolved, rejected or cleared
+  if (nextState.isFulfilled) {
+    executor.publish({ type: 'fulfilled' });
+  } else if (nextState.settledAt !== 0) {
+    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' });
+  }
+}
+
+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'
+  );
+}