coaction 2.1.0 → 3.1.0

package/README.md

@@ -2,6 +2,8 @@
 
 ![Node CI](https://github.com/coactionjs/coaction/workflows/Node%20CI/badge.svg) [![npm](https://img.shields.io/npm/v/coaction.svg)](https://www.npmjs.com/package/coaction) ![license](https://img.shields.io/npm/l/coaction)
 
+[English documentation](https://coactionjs.github.io/coaction/en/docs/) · [中文文档](https://coactionjs.github.io/coaction/zh/docs/)
+
 An efficient and flexible state management library for building high-performance, multithreading web applications.
 
 Coaction uses `alien-signals` internally for cached getter/computed state, React selector reactivity, and adapter-facing subscriptions. The core package also re-exports the signal primitives for advanced integrations.
@@ -17,7 +19,7 @@ pnpm add coaction
 ## Usage
 
 ```jsx
-import { create } from 'coaction';
+import { create } from 'coaction/local';
 
 const store = create((set) => ({
   count: 0,
@@ -55,15 +57,17 @@ const store = create((set, get) => ({
 }));
 ```
 
-Advanced integrations can import the native signal primitives and adapter helper directly from `coaction`:
+Local stores can import signal primitives from `coaction/local`. Adapter
+authors use the statically separate `coaction/adapter` entry:
 
 ```ts
-import { computed, defineExternalStoreAdapter, effect, signal } from 'coaction';
+import { computed, effect, signal } from 'coaction/local';
+import { defineExternalStoreAdapter } from 'coaction/adapter';
 ```
 
 ### Adapter and Middleware Utilities
 
-`coaction` also exports utilities for adapter and middleware authors. These are not needed for normal application state updates, but they are part of the supported integration surface used by the official packages:
+`coaction/adapter` exports utilities for adapter and middleware authors. These are not needed for normal application state updates, but they are part of the supported integration surface used by the official packages:
 
 - Mutable adapter helpers: `applyMutableAdapterPatches`, `replaceMutableAdapterState`, `toMutableAdapterSnapshot`, `snapshotMutableAdapterPureState`, `isEqualMutableAdapterSnapshot`, `getMutableAdapterOwnEnumerableKeys`, `isMutableAdapterUnsafeKey`.
 - Root replacement helpers: `createRootReplacementPatches`, `applyRootReplacementWithPatches`.
@@ -72,6 +76,26 @@ import { computed, defineExternalStoreAdapter, effect, signal } from 'coaction';
 
 Runtime mutation paths reject unsafe patch paths before applying state changes. If a `store.patch()` hook returns a path containing `__proto__`, `prototype`, or `constructor`, Coaction throws `UnsafePatchPathError` instead of silently dropping that patch and applying the rest.
 
+### Shared JSON contract
+
+Import `create` from `coaction/shared` when state crosses a Worker,
+SharedWorker, or injected transport boundary:
+
+```ts
+import { create } from 'coaction/shared';
+```
+
+Shared state, action arguments, action results, patch values, and full-sync
+snapshots must be JSON trees: finite numbers, strings, booleans, null, dense
+arrays, and plain records. Coaction rejects values that JSON would normalize or
+cannot represent losslessly, including `undefined`, `BigInt`, `NaN`, infinity,
+negative zero, functions in data, symbols, accessors, platform objects, sparse
+arrays, circular references, and repeated object references. Local stores do
+not inherit this restriction.
+
+An authority and every connected client must use the same Coaction major and
+wire protocol. Mixed-major shared deployments are unsupported.
+
 Store methods using `this` are rebound to the latest state when invoked from `getState()`, so destructuring remains safe:
 
 ```ts

package/adapter.d.ts

@@ -0,0 +1 @@
+export * from './dist/adapter';

package/adapter.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./dist/adapter.js');

package/dist/adapter.d.mts

@@ -0,0 +1,512 @@
+import { Transport } from "data-transport";
+import { Draft, Patches } from "mutative";
+
+//#region packages/core/src/interface.d.ts
+/**
+ * Generic object shape used by stores and slices.
+ */
+type ISlices<T = any> = Record<PropertyKey, T>;
+/**
+ * Recursive partial object accepted by {@link Store.setState} when merging a
+ * plain object payload into the current state tree.
+ */
+type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K] };
+/**
+ * Subscription callback invoked after the store publishes a state change.
+ */
+type Listener = () => void;
+/**
+ * Patch pair exposed to middleware compatibility hooks.
+ */
+interface PatchTransform {
+  patches: Patches;
+  inversePatches: Patches;
+}
+/**
+ * Trace envelope emitted before and after a store method executes.
+ */
+interface StoreTraceEvent {
+  /**
+   * The id of the method.
+   */
+  id: string;
+  /**
+   * The method name.
+   */
+  method: string;
+  /**
+   * The slice key.
+   */
+  sliceKey?: PropertyKey;
+  /**
+   * The parameters of the method.
+   */
+  parameters?: any[];
+  /**
+   * The result of the method.
+   */
+  result?: any;
+}
+/**
+ * Runtime store contract returned by {@link create} before framework-specific
+ * wrappers add selectors or reactivity helpers.
+ *
+ * @remarks
+ * `getState()` returns methods and getters alongside plain data. Methods
+ * extracted from the returned object keep the correct `this` binding when they
+ * are later invoked.
+ */
+interface Store<T extends ISlices = ISlices> {
+  /**
+   * The name of the store.
+   */
+  name: string;
+  /**
+   * Mutate the current state.
+   *
+   * @remarks
+   * Pass a deep-partial object to merge fields, or pass an updater to edit a
+   * Mutative draft. Passing `null` is a no-op. Client-side shared stores intentionally reject direct
+   * `setState()` calls; trigger a store method instead.
+   */
+  setState: (
+  /**
+   * The next partial state, or an updater that mutates a draft.
+   */
+
+  next: DeepPartial<T> | ((draft: Draft<T>) => any) | null,
+  /**
+   * Low-level updater hook used by transports and middleware integrations.
+   */
+
+  updater?: (next: DeepPartial<T> | ((draft: Draft<T>) => any) | null) => [] | [T, Patches, Patches]) => void;
+  /**
+   * Read the current state object.
+   *
+   * @remarks
+   * The returned object includes methods and getters. Methods destructured from
+   * this object continue to execute against the latest store state.
+   */
+  getState: () => T;
+  /**
+   * Subscribe to state changes.
+   *
+   * @returns A function that removes the listener.
+   */
+  subscribe: (listener: Listener) => () => void;
+  /**
+   * Tear down the store.
+   *
+   * @remarks
+   * `destroy()` is idempotent. It clears subscriptions and disposes any
+   * attached transport.
+   */
+  destroy: () => void;
+  /**
+   * Indicates whether the store is local, the main shared store, or a client
+   * mirror of a shared store.
+   */
+  share?: 'main' | 'client' | false;
+  /**
+   * Transport used to synchronize a shared store between processes or threads.
+   */
+  transport?: Transport;
+  /**
+   * Whether `createState` was interpreted as a slices object.
+   */
+  isSliceStore: boolean;
+  /**
+   * Apply patches to the current state.
+   *
+   * @remarks
+   * This is a low-level hook used by transports and middleware. Application
+   * code should generally prefer store methods or `setState()`. Client-side
+   * shared-store mirrors reject direct `apply()` calls.
+   */
+  apply: (state?: T, patches?: Patches) => void;
+  /**
+   * Return the current state without methods or getters.
+   *
+   * @remarks
+   * Useful for serialization, inspection, or tests that only care about raw
+   * data.
+   */
+  getPureState: () => T;
+  /**
+   * Return the state produced during initialization before later mutations.
+   */
+  getInitialState: () => T;
+  /**
+   * @deprecated Middleware compatibility hook. Prefer typing middleware stores
+   * with `MiddlewareStore`.
+   */
+  patch?: (option: PatchTransform) => PatchTransform;
+  /**
+   * @deprecated Middleware compatibility hook. Prefer typing middleware stores
+   * with `MiddlewareStore`.
+   */
+  trace?: (options: StoreTraceEvent) => void;
+}
+/**
+ * Semantic alias for middleware-facing stores.
+ *
+ * @remarks
+ * Middleware implementations should type their `store` parameter as
+ * `MiddlewareStore` instead of relying on deprecated `patch` or `trace` hooks.
+ */
+interface MiddlewareStore<T extends ISlices = ISlices> extends Store<T> {}
+/**
+ * Helper passed into {@link Slice} and {@link Slices} factories.
+ *
+ * @remarks
+ * Call it with no arguments to read the current store state. Call it with a
+ * dependency selector pair to define a computed value.
+ */
+interface Getter<T extends ISlices> {
+  <P extends any[], R>(getDeps: (store: T) => readonly [...P] | [...P], selector: (...args: P) => R): R;
+  (): T;
+}
+/**
+ * Factory for a single store object.
+ *
+ * @remarks
+ * Return a plain object containing state, getters, and methods. Methods and
+ * getters may use `this` to access the live store state.
+ */
+type Slice<T extends ISlices> = (
+/**
+ * The setState is used to update the state.
+ */
+set: Store<T>['setState'],
+/**
+ * The getState is used to get the state.
+ */
+get: Getter<T>,
+/**
+ * The store is used to store the state.
+ */
+store: Store<T>) => T;
+/**
+ * Store enhancer invoked during store creation.
+ *
+ * @remarks
+ * Middleware may mutate the received store in place or return a replacement
+ * store object, but it must preserve the {@link Store} contract.
+ */
+type Middleware<T extends CreateState> = (store: MiddlewareStore<T>) => MiddlewareStore<T>;
+/**
+ * Callable store returned by {@link create} in local or main/shared mode.
+ */
+type StoreReturn<T extends object> = Store<T> & ((...args: any[]) => T);
+/**
+ * Accepted `create()` input shape.
+ *
+ * @remarks
+ * This can be either a single store factory/object or a map of slice
+ * factories.
+ */
+type CreateState = ISlices | Record<PropertyKey, Slice<any>>;
+//#endregion
+//#region packages/core/src/internal.d.ts
+type MutationOperation = 'setState' | 'apply';
+type StoreOperation = MutationOperation | 'subscribe' | 'store initialization' | `action ${string}`;
+type SignalSlot = {
+  refresh: () => void;
+};
+type StateSchema = {
+  rootKeys: Set<PropertyKey>;
+  sliceKeys?: Map<PropertyKey, Set<PropertyKey>>;
+};
+interface Internal<T extends CreateState = CreateState> {
+  /**
+   * The store module.
+   */
+  module: T;
+  /**
+   * The root state.
+   */
+  rootState: T | Draft<T>;
+  /**
+   * The backup state.
+   */
+  backupState: T | Draft<T>;
+  /**
+   * Finalize the draft.
+   */
+  finalizeDraft: () => [T, Patches, Patches];
+  /**
+   * The mutable instance.
+   */
+  mutableInstance: any;
+  /**
+   * The sequence number.
+   */
+  sequence: number;
+  /** Identifies the lifetime of the current shared authority. */
+  transportEpoch?: string;
+  /** Action paths declared when the authoritative store was initialized. */
+  sharedActionPaths?: Set<string>;
+  /**
+   * Whether the batch is running.
+   */
+  isBatching: boolean;
+  /** Depth of a cached getter/computed evaluation over immutable state. */
+  computedReadDepth?: number;
+  /** Frozen snapshots keyed by immutable state object identity. */
+  computedSnapshotCache?: WeakMap<object, unknown>;
+  /** Immutable state sources keyed by frozen computed snapshot identity. */
+  computedSnapshotSources?: WeakMap<object, object>;
+  /** Whether a computed getter has returned a state snapshot object. */
+  computedIdentityRequired?: boolean;
+  /**
+   * The listeners.
+   */
+  listeners: Set<Listener>;
+  /** Cleanup callbacks owned by transport and integration layers. */
+  destroyCallbacks?: Set<() => void>;
+  /**
+   * Publish an externally-owned immutable state change to signal slots and
+   * store subscribers.
+   */
+  notifyStateChange: () => void;
+  /**
+   * Reactive state slots used by computed getters/selectors.
+   */
+  signalSlots?: Set<SignalSlot>;
+  /**
+   * State keys that are allowed after initialization.
+   */
+  stateSchema?: StateSchema;
+  /**
+   * The act is used to run the function in the action for mutable state.
+   */
+  actMutable?: <T extends () => any>(fn: T) => ReturnType<T>;
+  /**
+   * Get the mutable raw instance via the initial state.
+   */
+  toMutableRaw?: (key: any) => any;
+  /**
+   * The update immutable function.
+   */
+  updateImmutable?: (state: T) => void;
+  /**
+   * Adapter-level authority check for low-level mutations.
+   */
+  assertMutationAllowed?: (operation: MutationOperation) => void;
+  /**
+   * Store lifecycle guard.
+   */
+  assertAlive?: (operation: StoreOperation) => void;
+  /**
+   * Authorized client-mirror state application used by transports.
+   */
+  applyClientState?: (state?: T, patches?: Patches) => void;
+  /** Request an authoritative full sync for a client mirror. */
+  syncClientState?: (expectedEpoch?: string, minimumSequence?: number) => Promise<void>;
+  /** Cancel a transport promise when the client mirror is destroyed. */
+  awaitClientTransport?: <R>(value: PromiseLike<R> | R) => Promise<R>;
+  /** Validate committed state when a runtime capability requires it. */
+  validateState?: (state: unknown) => void;
+  /** Validate outbound patches before normalization or commit. */
+  validatePatches?: (patches: Patches) => void;
+  /** Validate an adapter replacement source before reading its values. */
+  validateReplacementSource?: (state: unknown) => void;
+  /** Commit patches already checked by the native updater. */
+  applyValidatedPatches?: (state: T, patches: Patches, skipFinalValidation: boolean) => boolean;
+  /** Publish patches when a shared authority transport is attached. */
+  emitPatches?: (patches: Patches) => void;
+  /** Return the plain state exposed at the JSON transport boundary. */
+  getTransportState?: () => unknown;
+}
+//#endregion
+//#region packages/core/src/binder.d.ts
+type ExternalStoreAdapterOptions<F = (...args: any[]) => any> = {
+  /**
+   * Normalize a third-party store instance into a raw state object plus the
+   * binding hook used during initialization.
+   */
+  handleState: <T extends object = object>(state: T) => {
+    /**
+     * Copy of the incoming state object that Coaction should consume.
+     */
+    copyState: T;
+    /**
+     * Optional nested key when the adapter exposes a single child object from
+     * the third-party store.
+     */
+    key?: keyof T;
+    /**
+     * Convert the external state object into the raw state shape used by
+     * Coaction.
+     */
+    bind: (state: T) => T;
+  };
+  /**
+   * Wire Coaction's store lifecycle to the external store implementation.
+   */
+  handleStore: (
+  /**
+   * Coaction store wrapper.
+   */
+
+  store: Store<object>,
+  /**
+   * Raw state object returned from `bind`.
+   */
+
+  rawState: object,
+  /**
+   * Original external store state object.
+   */
+
+  state: object,
+  /**
+   * Low-level Coaction adapter hooks used by official bindings.
+   */
+
+  internal: Internal<object>,
+  /**
+   * Optional nested key returned by `handleState`.
+   */
+
+  key?: PropertyKey) => void;
+};
+/**
+ * Build an adapter helper for bridging an external store implementation into
+ * Coaction.
+ *
+ * @remarks
+ * Import this compatibility helper from `coaction/adapter`.
+ *
+ * Official bindings use this to integrate stores such as Redux, Jotai, Pinia,
+ * Zustand, MobX, and Valtio. Binder-backed integrations are whole-store
+ * adapters; they are not compatible with Coaction slices mode.
+ */
+declare function createBinder<F = (...args: any[]) => any>({
+  handleState,
+  handleStore
+}: ExternalStoreAdapterOptions<F>): F;
+/**
+ * Define a whole-store adapter for integrating an external state runtime with
+ * Coaction.
+ *
+ * @remarks
+ * Import this helper from `coaction/adapter`. `createBinder()` remains as a
+ * compatibility alias for existing official and community integrations.
+ */
+declare function defineExternalStoreAdapter<F = (...args: any[]) => any>(options: ExternalStoreAdapterOptions<F>): F;
+//#endregion
+//#region packages/core/src/externalMutableAdapterUtils.d.ts
+declare const getMutableAdapterOwnEnumerableKeys: (value: object) => (string | symbol)[];
+declare const isMutableAdapterUnsafeKey: (key: PropertyKey) => key is "__proto__" | "prototype" | "constructor";
+declare const replaceMutableAdapterState: (rawState: Record<PropertyKey, unknown>, mutableState: Record<PropertyKey, unknown>, publicState: Record<PropertyKey, unknown>, source: Record<PropertyKey, unknown>) => void;
+declare const applyMutableAdapterPatches: (baseState: unknown, patches: Patches, rawState: Record<PropertyKey, unknown>, mutableState: Record<PropertyKey, unknown>, publicState: Record<PropertyKey, unknown>, validateState?: (state: unknown) => void) => void;
+declare const toMutableAdapterSnapshot: (value: unknown, visited?: WeakMap<object, unknown>) => unknown;
+declare const snapshotMutableAdapterPureState: (store: Store<object>) => Record<PropertyKey, unknown>;
+declare const isEqualMutableAdapterSnapshot: (left: unknown, right: unknown, visited?: WeakMap<object, WeakSet<object>>) => boolean;
+//#endregion
+//#region packages/core/src/reactiveTracker.d.ts
+type ReactiveTracker = {
+  getSnapshot: () => number;
+  subscribe: (listener: () => void) => () => void;
+  track: <T>(fn: () => T) => T;
+  dispose: () => void;
+};
+/**
+ * Create a low-level signal dependency tracker for framework adapters.
+ *
+ * @remarks
+ * Adapter and framework authors import this helper from `coaction/adapter`.
+ */
+declare const createReactiveTracker: () => ReactiveTracker;
+//#endregion
+//#region packages/core/src/lifecycle.d.ts
+declare const onStoreReady: <T extends CreateState>(store: Store<T>, callback: () => void) => () => void;
+//#endregion
+//#region packages/core/src/replaceExternalStoreState.d.ts
+type ReplaceExternalStoreStateOptions = {
+  syncImmutable?: boolean;
+};
+declare const replaceExternalStoreState: <T extends CreateState>(store: MiddlewareStore<T>, internal: Internal<T>, source: Record<PropertyKey, unknown>, {
+  syncImmutable
+}?: ReplaceExternalStoreStateOptions) => void;
+//#endregion
+//#region packages/core/src/storeCommit.d.ts
+type StoreCommitSource = 'setState' | 'mutableAction' | 'external' | 'replay';
+/**
+ * A patch pair emitted after Coaction has committed an authoritative state
+ * transition.
+ */
+type StoreCommit<T extends CreateState = CreateState> = {
+  readonly state: T;
+  readonly patches: Patches;
+  readonly inversePatches: Patches;
+  readonly source: StoreCommitSource;
+};
+/** Patch pair to replay through Coaction's authoritative mutation pipeline. */
+type StorePatchTransition = {
+  readonly patches: Patches;
+  readonly inversePatches: Patches;
+};
+type StorePatchReplayOptions<T extends CreateState = CreateState> = {
+  /** Middleware-scoped setState entry that should observe the replay. */setState?: Store<T>['setState'];
+};
+type StoreCommitListener<T extends CreateState> = (commit: StoreCommit<T>) => void;
+type StoreCommitPrepareListener<T extends CreateState> = (commit: StoreCommit<T>) => boolean | void;
+/**
+ * Observe patch pairs after successful Coaction commits.
+ *
+ * @remarks
+ * Registering a listener enables patch generation only while it is needed,
+ * even when the store was created without `enablePatches: true`.
+ */
+declare const onStoreCommit: <T extends CreateState>(store: Store<T>, listener: StoreCommitListener<T>) => () => void;
+/**
+ * Inspect a pending object-valued commit before its patch pair is applied.
+ *
+ * @remarks
+ * Return `true` to request an exact state replacement for transitions whose
+ * object graph cannot be represented safely by the patch pair.
+ */
+declare const onStoreCommitPrepare: <T extends CreateState>(store: Store<T>, listener: StoreCommitPrepareListener<T>) => () => void;
+/**
+ * Replay a patch pair through Coaction validation, patch middleware, adapters,
+ * subscriptions, and transports.
+ */
+declare const replayStorePatches: <T extends CreateState>(store: Store<T>, transition: StorePatchTransition, options?: StorePatchReplayOptions<T>) => T;
+//#endregion
+//#region packages/core/src/utils.d.ts
+declare class StateSchemaError extends Error {
+  name: string;
+}
+declare const isStateSchemaError: (error: unknown) => error is StateSchemaError;
+type RootReplacementPatch = {
+  op: 'add' | 'remove' | 'replace';
+  path: PropertyKey[];
+  value?: unknown;
+};
+declare const createRootReplacementPatches: (currentState: Record<PropertyKey, unknown>, nextState: Record<PropertyKey, unknown>) => {
+  patches: RootReplacementPatch[];
+  inversePatches: RootReplacementPatch[];
+};
+declare const applyRootReplacementWithPatches: <T extends object>(store: MiddlewareStore<T>, nextState: Record<PropertyKey, unknown>, options?: {
+  applyExactReplacement?: (state: T) => void;
+}) => [T, Patches, Patches];
+declare const replaceOwnEnumerable: (target: Record<PropertyKey, unknown>, source: Record<PropertyKey, unknown>) => void;
+declare const sanitizeReplacementState: <T>(source: T, seen?: WeakMap<object, unknown>) => T;
+declare const sanitizeInitialStateValue: <T>(source: T, seen?: WeakMap<object, unknown>) => T;
+//#endregion
+//#region packages/core/src/wrapStore.d.ts
+/**
+ * Convert a store object into Coaction's callable store shape.
+ *
+ * @remarks
+ * Framework bindings use this to attach selector-aware readers while
+ * preserving the underlying store API on the returned function object. Most
+ * applications should use a public `create` entry instead of calling
+ * `wrapStore()` directly. Framework authors import this helper from
+ * `coaction/local` or `coaction/adapter`.
+ */
+declare const wrapStore: <T extends object>(store: Store<T>, getState?: (...args: unknown[]) => T) => StoreReturn<T>;
+//#endregion
+export { type CreateState, type ExternalStoreAdapterOptions, type Middleware, type MiddlewareStore, type PatchTransform, type ReactiveTracker, StateSchemaError, type Store, type StoreCommit, type StoreCommitSource, type StorePatchReplayOptions, type StorePatchTransition, type StoreTraceEvent, applyMutableAdapterPatches, applyRootReplacementWithPatches, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, getMutableAdapterOwnEnumerableKeys, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isStateSchemaError, onStoreCommit, onStoreCommitPrepare, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, replayStorePatches, sanitizeInitialStateValue, sanitizeReplacementState, snapshotMutableAdapterPureState, toMutableAdapterSnapshot, wrapStore };