coaction 2.0.0 → 3.0.0

package/README.md

@@ -1,27 +1,25 @@
 # coaction
 
-![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)
+![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 2.0 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.
+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.
 
 ## Installation
 
-You can install it via npm, yarn or pnpm.
+Install it with pnpm:
 
 ```sh
-npm install coaction
+pnpm add coaction
 ```
 
 ## Usage
 
 ```jsx
-import { create } from 'coaction';
+import { create } from 'coaction/local';
 
 const store = create((set) => ({
   count: 0,
@@ -36,8 +34,13 @@ const store = create((set) => ({
 }));
 ```
 
-Accessor getters are cached automatically through the built-in signal runtime.
-Use `get(deps, selector)` when you want to declare dependencies manually:
+Core stores are immutable by default. Getters and methods can read through `this`, but writes to Coaction-owned state must happen inside `set()` or `set((draft) => ...)`. Direct writes such as `this.count += 1` in a store method throw because they bypass the commit path that notifies subscribers, produces patches when enabled, and synchronizes worker/client mirrors in shared mode.
+
+Coaction fixes the public state schema after initialization. A single store cannot add new top-level state keys later, and a slices store cannot add new slice keys or new top-level fields inside a slice. Replacement-style APIs such as `apply()` may omit a known single-store root key; the public getter remains present and reads as `undefined`, but no unknown key is promoted into the public module. Slice root keys are stricter and cannot be removed or replaced with non-object values. Keep dynamic data inside an existing object or array field.
+
+Mutable adapters such as MobX, Pinia, and Valtio keep Coaction raw state, public state, and the external mutable runtime synchronized for known schema keys. Coaction still treats its raw/public schema as authoritative: out-of-band unknown properties written directly onto a third-party mutable runtime are not promoted into Coaction state, and adapter-specific docs define whether that external runtime property is pruned, restored, or left to the underlying library.
+
+Accessor getters are cached automatically through the built-in signal runtime. Use `get(deps, selector)` when you want to declare dependencies manually:
 
 ```ts
 const store = create((set, get) => ({
@@ -54,15 +57,46 @@ 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';
 ```
 
-Store methods using `this` are rebound to the latest state when invoked from
-`getState()`, so destructuring remains safe:
+### Adapter and Middleware Utilities
+
+`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`.
+- Patch safety helpers: `assertSafePatches`, `sanitizePatches`, `UnsafePatchPathError`.
+- State shape helpers: `StateSchemaError`, `isStateSchemaError`, `sanitizeReplacementState`, `sanitizeInitialStateValue`, `replaceOwnEnumerable`.
+
+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
 const store = create((set) => ({
@@ -85,11 +119,7 @@ increment();
 
 ### Store Shape Mode (`sliceMode`)
 
-`create()` uses `sliceMode: 'auto'` by default. For backward compatibility,
-`auto` still treats a non-empty object whose enumerable values are all
-functions as slices. That shape is ambiguous with a plain store that only
-contains methods, so development builds warn and you should set `sliceMode`
-explicitly.
+`create()` uses `sliceMode: 'auto'` by default. For backward compatibility, `auto` still treats a non-empty object whose enumerable values are all functions as slices. That shape is ambiguous with a plain store that only contains methods, so development builds warn and you should set `sliceMode` explicitly.
 
 You can force behavior explicitly:
 

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,468 @@
+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/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 StoreTraceEvent, applyMutableAdapterPatches, applyRootReplacementWithPatches, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, getMutableAdapterOwnEnumerableKeys, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isStateSchemaError, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, sanitizeInitialStateValue, sanitizeReplacementState, snapshotMutableAdapterPureState, toMutableAdapterSnapshot, wrapStore };