coaction 2.0.0 → 2.1.0

package/README.md

@@ -1,21 +1,17 @@
 # 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)
 
 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
@@ -36,8 +32,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 +55,24 @@ const store = create((set, get) => ({
 }));
 ```
 
-Advanced integrations can import the native signal primitives and adapter helper
-directly from `coaction`:
+Advanced integrations can import the native signal primitives and adapter helper directly from `coaction`:
 
 ```ts
 import { computed, defineExternalStoreAdapter, effect, signal } from 'coaction';
 ```
 
-Store methods using `this` are rebound to the latest state when invoked from
-`getState()`, so destructuring remains safe:
+### 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:
+
+- 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.
+
+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 +95,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/dist/index.d.mts

@@ -393,9 +393,14 @@ declare const create: Creator;
 //#endregion
 //#region packages/core/src/internal.d.ts
 type MutationOperation = 'setState' | 'apply';
+type StoreOperation = MutationOperation | 'subscribe' | `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.
@@ -438,6 +443,10 @@ interface Internal<T extends CreateState = CreateState> {
    * 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.
    */
@@ -454,6 +463,10 @@ interface Internal<T extends CreateState = CreateState> {
    * 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.
    */
@@ -555,7 +568,45 @@ declare const replaceExternalStoreState: <T extends CreateState>(store: Middlewa
   syncImmutable
 }?: ReplaceExternalStoreStateOptions) => void;
 //#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>) => 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/utils.d.ts
+declare class UnsafePatchPathError extends Error {
+  name: string;
+}
+declare class StateSchemaError extends Error {
+  name: string;
+}
+declare const isStateSchemaError: (error: unknown) => error is StateSchemaError;
+declare const assertSafePatches: <T extends {
+  path: unknown;
+}>(patches: T[] | undefined, source?: string) => void;
+declare const sanitizePatches: <T extends {
+  path: unknown;
+  value?: unknown;
+}>(patches: T[] | undefined, options?: {
+  source?: string;
+  warnOnDropped?: boolean;
+}) => T[] | undefined;
+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;
@@ -572,4 +623,4 @@ declare const sanitizeInitialStateValue: <T>(source: T, seen?: WeakMap<object, u
  */
 declare const wrapStore: <T extends object>(store: Store<T>, getState?: (...args: unknown[]) => T) => StoreReturn<T>;
 //#endregion
-export { type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ExternalStoreAdapterOptions, type ISlices, type Middleware, type MiddlewareStore, type PatchTransform, type ReactiveTracker, type Slice, type SliceState, type Slices, type Store, type StoreOptions, type StoreTraceEvent, computed, create, createBinder, createReactiveTracker, defineExternalStoreAdapter, effect, effectScope, endBatch, isComputed, isEffect, isEffectScope, isSignal, onStoreReady, replaceExternalStoreState, replaceOwnEnumerable, sanitizeInitialStateValue, sanitizeReplacementState, signal, startBatch, trigger, wrapStore };
+export { type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ExternalStoreAdapterOptions, type ISlices, type Middleware, type MiddlewareStore, type PatchTransform, type ReactiveTracker, type Slice, type SliceState, type Slices, StateSchemaError, type Store, type StoreOptions, type StoreTraceEvent, UnsafePatchPathError, applyMutableAdapterPatches, applyRootReplacementWithPatches, assertSafePatches, computed, create, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, effect, effectScope, endBatch, getMutableAdapterOwnEnumerableKeys, isComputed, isEffect, isEffectScope, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isSignal, isStateSchemaError, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, sanitizeInitialStateValue, sanitizePatches, sanitizeReplacementState, signal, snapshotMutableAdapterPureState, startBatch, toMutableAdapterSnapshot, trigger, wrapStore };

package/dist/index.d.ts

@@ -393,9 +393,14 @@ declare const create: Creator;
 //#endregion
 //#region packages/core/src/internal.d.ts
 type MutationOperation = 'setState' | 'apply';
+type StoreOperation = MutationOperation | 'subscribe' | `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.
@@ -438,6 +443,10 @@ interface Internal<T extends CreateState = CreateState> {
    * 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.
    */
@@ -454,6 +463,10 @@ interface Internal<T extends CreateState = CreateState> {
    * 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.
    */
@@ -555,7 +568,45 @@ declare const replaceExternalStoreState: <T extends CreateState>(store: Middlewa
   syncImmutable
 }?: ReplaceExternalStoreStateOptions) => void;
 //#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>) => 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/utils.d.ts
+declare class UnsafePatchPathError extends Error {
+  name: string;
+}
+declare class StateSchemaError extends Error {
+  name: string;
+}
+declare const isStateSchemaError: (error: unknown) => error is StateSchemaError;
+declare const assertSafePatches: <T extends {
+  path: unknown;
+}>(patches: T[] | undefined, source?: string) => void;
+declare const sanitizePatches: <T extends {
+  path: unknown;
+  value?: unknown;
+}>(patches: T[] | undefined, options?: {
+  source?: string;
+  warnOnDropped?: boolean;
+}) => T[] | undefined;
+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;
@@ -572,4 +623,4 @@ declare const sanitizeInitialStateValue: <T>(source: T, seen?: WeakMap<object, u
  */
 declare const wrapStore: <T extends object>(store: Store<T>, getState?: (...args: unknown[]) => T) => StoreReturn<T>;
 //#endregion
-export { type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ExternalStoreAdapterOptions, type ISlices, type Middleware, type MiddlewareStore, type PatchTransform, type ReactiveTracker, type Slice, type SliceState, type Slices, type Store, type StoreOptions, type StoreTraceEvent, computed, create, createBinder, createReactiveTracker, defineExternalStoreAdapter, effect, effectScope, endBatch, isComputed, isEffect, isEffectScope, isSignal, onStoreReady, replaceExternalStoreState, replaceOwnEnumerable, sanitizeInitialStateValue, sanitizeReplacementState, signal, startBatch, trigger, wrapStore };
+export { type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ExternalStoreAdapterOptions, type ISlices, type Middleware, type MiddlewareStore, type PatchTransform, type ReactiveTracker, type Slice, type SliceState, type Slices, StateSchemaError, type Store, type StoreOptions, type StoreTraceEvent, UnsafePatchPathError, applyMutableAdapterPatches, applyRootReplacementWithPatches, assertSafePatches, computed, create, createBinder, createReactiveTracker, createRootReplacementPatches, defineExternalStoreAdapter, effect, effectScope, endBatch, getMutableAdapterOwnEnumerableKeys, isComputed, isEffect, isEffectScope, isEqualMutableAdapterSnapshot, isMutableAdapterUnsafeKey, isSignal, isStateSchemaError, onStoreReady, replaceExternalStoreState, replaceMutableAdapterState, replaceOwnEnumerable, sanitizeInitialStateValue, sanitizePatches, sanitizeReplacementState, signal, snapshotMutableAdapterPureState, startBatch, toMutableAdapterSnapshot, trigger, wrapStore };