coaction 1.3.0 → 1.4.1

package/README.md

@@ -25,9 +25,37 @@ const useStore = create((set) => ({
 }));
 ```
 
+Store methods using `this` are rebound to the latest state when invoked from
+`getState()`, so destructuring remains safe:
+
+```ts
+const store = create((set) => ({
+  count: 0,
+  increment() {
+    set(() => {
+      this.count += 1;
+    });
+  }
+}));
+
+const { increment } = store.getState();
+increment();
+```
+
+## API Reference
+
+- [Generated core API index](https://github.com/unadlib/coaction/blob/main/docs/api/core/index.md)
+- [Core API notes](https://github.com/unadlib/coaction/blob/main/docs/api/core/documents/core-api-notes.md)
+
 ### Store Shape Mode (`sliceMode`)
 
-`create()` uses `sliceMode: 'auto'` by default. You can force behavior 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:
 
 - `sliceMode: 'single'`: treat object input as a single store.
 - `sliceMode: 'slices'`: require object-of-slice-functions input.

package/dist/index.d.mts

@@ -1,104 +1,177 @@
 import { Transport } from 'data-transport';
 import { Draft, Patches } from 'mutative';
 
+/**
+ * Generic object shape used by stores and slices.
+ */
 type ISlices<T = any> = Record<string, 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?: string;
+    /**
+     * 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;
     /**
-     * Set the next state.
+     * Mutate the current state.
+     *
+     * @remarks
+     * Pass a deep-partial object to merge fields, or pass an updater to edit a
+     * Mutative draft. Client-side shared stores intentionally reject direct
+     * `setState()` calls; trigger a store method instead.
      */
     setState: (
     /**
-     * The next state.
+     * The next partial state, or an updater that mutates a draft.
      */
     next: DeepPartial<T> | ((draft: Draft<T>) => any) | null, 
     /**
-     * The updater is used to update the state.
+     * Low-level updater hook used by transports and middleware integrations.
      */
     updater?: (next: DeepPartial<T> | ((draft: Draft<T>) => any) | null) => [] | [T, Patches, Patches]) => void;
     /**
-     * Get the current state.
+     * 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 the state changes, and return the unsubscribe function.
+     * Subscribe to state changes.
+     *
+     * @returns A function that removes the listener.
      */
     subscribe: (listener: Listener) => () => void;
     /**
-     * Unsubscribe all listeners and dispose the transport.
+     * Tear down the store.
+     *
+     * @remarks
+     * `destroy()` is idempotent. It clears subscriptions and disposes any
+     * attached transport.
      */
     destroy: () => void;
     /**
-     * The store is shared in the web worker, shared worker, or other process.
+     * Indicates whether the store is local, the main shared store, or a client
+     * mirror of a shared store.
      */
     share?: 'main' | 'client' | false;
     /**
-     * The transport is used to communicate between the main thread and the worker or shared worker.
+     * Transport used to synchronize a shared store between processes or threads.
      */
     transport?: Transport;
     /**
-     * The store is a slices.
+     * Whether `createState` was interpreted as a slices object.
      */
     isSliceStore: boolean;
     /**
-     * apply the patches to the state.
+     * 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()`.
      */
     apply: (state?: T, patches?: Patches) => void;
     /**
-     * the pure state is used to get the state without the methods and getters.
+     * Return the current state without methods or getters.
+     *
+     * @remarks
+     * Useful for serialization, inspection, or tests that only care about raw
+     * data.
      */
     getPureState: () => T;
     /**
-     * Get the initial state.
+     * Return the state produced during initialization before later mutations.
      */
     getInitialState: () => T;
     /**
-     * The patch is used to update the state.
+     * @deprecated Middleware compatibility hook. Prefer typing middleware stores
+     * with `MiddlewareStore`.
      */
-    patch?: (option: {
-        patches: Patches;
-        inversePatches: Patches;
-    }) => {
-        patches: Patches;
-        inversePatches: Patches;
-    };
+    patch?: (option: PatchTransform) => PatchTransform;
     /**
-     * The trace is used to trace the action
+     * @deprecated Middleware compatibility hook. Prefer typing middleware stores
+     * with `MiddlewareStore`.
      */
-    trace?: (options: {
-        /**
-         * The id of the method.
-         */
-        id: string;
-        /**
-         * The method name.
-         */
-        method: string;
-        /**
-         * The slice key.
-         */
-        sliceKey?: string;
-        /**
-         * The parameters of the method.
-         */
-        parameters?: any[];
-        /**
-         * The result of the method.
-         */
-        result?: any;
-    }) => void;
+    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.
@@ -112,6 +185,14 @@ get: Getter<T>,
  * The store is used to store the state.
  */
 store: Store<T>) => T;
+/**
+ * Factory for a named slice inside a slices store.
+ *
+ * @remarks
+ * The returned object becomes the value stored under the slice key. When an
+ * object input only contains functions, prefer explicit `sliceMode` to avoid
+ * ambiguity between slices and a plain method-only store.
+ */
 type Slices<T extends ISlices, K extends keyof T> = (
 /**
  * The setState is used to update the state.
@@ -125,57 +206,156 @@ get: Getter<T>,
  * The store is used to store the state.
  */
 store: Store<T>) => T[K];
-type Middleware<T extends CreateState> = (store: Store<T>) => Store<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>;
+/**
+ * Derived state object produced by mapping slice factories to their return
+ * types.
+ */
 type SliceState<T extends Record<string, Slice<any>>> = {
     [K in keyof T]: ReturnType<T[K]>;
 };
+/**
+ * Options for creating a local store or the main side of a shared store.
+ */
 type StoreOptions<T extends CreateState> = {
     /**
      * The name of the store.
      */
     name?: string;
-    transport?: Transport;
+    /**
+     * @deprecated Internal worker-mode override retained for compatibility.
+     * Prefer passing `transport` or letting the runtime infer the environment.
+     */
     workerType?: 'SharedWorkerInternal' | 'WebWorkerInternal';
+    /**
+     * Inject a pre-built transport for advanced shared-store setups.
+     */
+    transport?: Transport;
+    /**
+     * Middleware chain applied before the initial state is finalized.
+     */
     middlewares?: Middleware<T>[];
     /**
-     * enable patches
+     * Enable patch generation.
+     *
+     * @remarks
+     * Required for async client stores and useful for middleware or mutable
+     * integrations that depend on patch streams.
      */
     enablePatches?: boolean;
     /**
-     * control how createState should be interpreted.
-     * - auto: infer from createState shape.
+     * Control how `createState` should be interpreted.
+     *
+     * @remarks
+     * - auto: infer from createState shape. Object maps whose values are all
+     *   functions are ambiguous, so prefer setting `sliceMode` explicitly.
      * - slices: force slices mode.
      * - single: force single-store mode.
      */
     sliceMode?: 'auto' | 'slices' | 'single';
 };
+/**
+ * Options for creating a client mirror of a shared store.
+ *
+ * @remarks
+ * Methods on the returned store become promise-returning methods because
+ * execution happens on the main/shared store.
+ */
 type ClientStoreOptions<T extends CreateState> = {
     /**
-     * The name of the store.
+     * The name of the shared store to connect to.
      */
     name?: string;
+    /**
+     * Middleware chain applied to the client-side store wrapper.
+     */
     middlewares?: Middleware<T>[];
     /**
-     * control how createState should be interpreted.
-     * - auto: infer from createState shape.
+     * Control how `createState` should be interpreted.
+     *
+     * @remarks
+     * - auto: infer from createState shape. Object maps whose values are all
+     *   functions are ambiguous, so prefer setting `sliceMode` explicitly.
      * - slices: force slices mode.
      * - single: force single-store mode.
      */
     sliceMode?: 'auto' | 'slices' | 'single';
 } & ClientTransportOptions;
+/**
+ * Transport-related options for client/shared-store mirrors.
+ */
 interface ClientTransportOptions {
+    /**
+     * @deprecated Internal worker-mode override retained for compatibility.
+     * Prefer passing `clientTransport` or `worker`.
+     */
     workerType?: 'WebWorkerClient' | 'SharedWorkerClient';
+    /**
+     * How long the client should wait for sequence catch-up before falling back
+     * to `fullSync`.
+     *
+     * Increase this when worker-side execution can complete before the matching
+     * incremental `update` message arrives under heavy load.
+     *
+     * @default 1500
+     */
+    executeSyncTimeoutMs?: number;
+    /**
+     * Inject a pre-built client transport.
+     */
     clientTransport?: Transport<any>;
+    /**
+     * Build a client transport from a Worker or SharedWorker instance.
+     */
     worker?: SharedWorker | Worker;
 }
+/**
+ * Transform store methods into promise-returning methods for client stores.
+ */
 type Asyncify<T extends object, D extends true | false> = {
     [K in keyof T]: T[K] extends (...args: any[]) => any ? (...args: Parameters<T[K]>) => Promise<ReturnType<T[K]>> : D extends false ? T[K] : {
         [P in keyof T[K]]: T[K][P] extends (...args: any[]) => any ? (...args: Parameters<T[K][P]>) => Promise<ReturnType<T[K][P]>> : T[K][P];
     };
 };
+/**
+ * Store shape returned by {@link create} when acting as a client of a shared
+ * store.
+ *
+ * @remarks
+ * Methods return promises because they execute on the main/shared store.
+ */
 type StoreWithAsyncFunction<T extends object, D extends true | false = false> = Store<Asyncify<T, D>> & (() => Asyncify<T, D>);
+/**
+ * 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<string, Slice<any>>;
+/**
+ * Overload set for {@link create}.
+ *
+ * @remarks
+ * - `Slice` + `StoreOptions` returns a synchronous local or main/shared store.
+ * - slice map + `StoreOptions` returns a synchronous slices store.
+ * - `Slice` + `ClientStoreOptions` returns an async client store.
+ * - slice map + `ClientStoreOptions` returns an async client slices store.
+ *
+ * For object inputs whose enumerable values are all functions, prefer explicit
+ * `sliceMode` to avoid ambiguous inference.
+ */
 type Creator = {
     <T extends Record<string, Slice<any>>>(createState: T, options?: StoreOptions<T>): StoreReturn<SliceState<T>>;
     <T extends ISlices>(createState: Slice<T>, options?: StoreOptions<T>): StoreReturn<T>;
@@ -184,7 +364,17 @@ type Creator = {
 };
 
 /**
- * Create a simple store or a shared store. The shared store can be used in a worker or another thread.
+ * Create a local store, the main side of a shared store, or a client mirror of
+ * a shared store.
+ *
+ * @remarks
+ * - Pass a {@link Slice} function for a single store.
+ * - Pass an object of slice factories for a slices store.
+ * - When an object input only contains functions, prefer explicit `sliceMode`
+ *   to avoid ambiguous inference.
+ * - When `clientTransport` or `worker` is provided, returned store methods
+ *   become promise-returning methods because execution happens on the main
+ *   shared store.
  */
 declare const create: Creator;
 
@@ -236,55 +426,70 @@ interface Internal<T extends CreateState = CreateState> {
 }
 
 /**
- * createBinder is a function to create a binder for the 3rd party store.
+ * Build an adapter helper for bridging an external store implementation into
+ * Coaction.
+ *
+ * @remarks
+ * 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 }: {
     /**
-     * handleState is a function to handle the state object.
+     * 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) => {
         /**
-         * copyState is a copy of the state object.
+         * Copy of the incoming state object that Coaction should consume.
          */
         copyState: T;
         /**
-         * key is the key of the state object.
+         * Optional nested key when the adapter exposes a single child object from
+         * the third-party store.
          */
         key?: keyof T;
         /**
-         * bind is a function to bind the state object.
+         * Convert the external state object into the raw state shape used by
+         * Coaction.
          */
         bind: (state: T) => T;
     };
     /**
-     * handleStore is a function to handle the store object.
+     * Wire Coaction's store lifecycle to the external store implementation.
      */
     handleStore: (
     /**
-     * Coaction store
+     * Coaction store wrapper.
      */
     store: Store<object>, 
     /**
-     * The raw state object from 3rd party library.
+     * Raw state object returned from `bind`.
      */
     rawState: object, 
     /**
-     * 3rd party library state object to Coaction state object.
+     * Original external store state object.
      */
     state: object, 
     /**
-     * internal Coaction API.
+     * Low-level Coaction adapter hooks used by official bindings.
      */
     internal: Internal<object>, 
     /**
-     * the key of the slice state object.
+     * Optional nested key returned by `handleState`.
      */
     key?: string) => void;
 }): F;
 
 /**
- * wrapStore is a function to wrap the store and return function to get the state with store.
+ * 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 call {@link create} instead of using `wrapStore()`
+ * directly.
  */
 declare const wrapStore: <T extends object>(store: Store<T>, getState?: (...args: unknown[]) => T) => StoreReturn<T>;
 
-export { type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ISlices, type Middleware, type Slice, type SliceState, type Slices, type Store, type StoreOptions, create, createBinder, wrapStore };
+export { type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ISlices, type Middleware, type MiddlewareStore, type PatchTransform, type Slice, type SliceState, type Slices, type Store, type StoreOptions, type StoreTraceEvent, create, createBinder, wrapStore };