coaction 1.4.0 → 1.5.0

package/README.md

@@ -25,12 +25,35 @@ 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. 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 you should set `sliceMode` explicitly.
+contains methods, so development builds warn and you should set `sliceMode`
+explicitly.
 
 You can force behavior explicitly:
 

package/dist/index.d.mts

@@ -1,15 +1,31 @@
 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.
@@ -32,57 +48,90 @@ interface StoreTraceEvent {
      */
     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. Passing `null` is a no-op. 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;
     /**
@@ -98,13 +147,31 @@ interface Store<T extends ISlices = ISlices> {
 }
 /**
  * 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.
@@ -118,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.
@@ -131,10 +206,24 @@ get: Getter<T>,
  * The store is used to store the state.
  */
 store: Store<T>) => T[K];
+/**
+ * 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.
@@ -149,13 +238,22 @@ type StoreOptions<T extends CreateState> = {
      * 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.
+     * 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.
@@ -163,14 +261,26 @@ type StoreOptions<T extends CreateState> = {
      */
     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.
+     * 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.
@@ -178,6 +288,9 @@ type ClientStoreOptions<T extends CreateState> = {
      */
     sliceMode?: 'auto' | 'slices' | 'single';
 } & ClientTransportOptions;
+/**
+ * Transport-related options for client/shared-store mirrors.
+ */
 interface ClientTransportOptions {
     /**
      * @deprecated Internal worker-mode override retained for compatibility.
@@ -203,14 +316,46 @@ interface ClientTransportOptions {
      */
     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>;
@@ -219,7 +364,19 @@ 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.
+ * - New semantics should prefer explicit helpers or variants over adding more
+ *   ambiguous `create()` input forms.
  */
 declare const create: Creator;
 
@@ -271,54 +428,69 @@ 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>;