coaction 2.1.0 → 3.1.0

package/dist/local.d.mts

@@ -0,0 +1,344 @@
+import { Transport } from "data-transport";
+import { Draft, Patches } from "mutative";
+import { computed, effect, effectScope, endBatch, isComputed, isEffect, isEffectScope, isSignal, signal, startBatch, trigger } from "alien-signals";
+
+//#region packages/core/src/jsonTypes.d.ts
+type JsonPrimitive = null | boolean | number | string;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+//#endregion
+//#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> {}
+type TransportPolicyRequest = {
+  action: readonly string[];
+  args: readonly JsonValue[];
+  type: 'execute';
+} | {
+  type: 'fullSync';
+};
+type TransportPolicy = {
+  /** Further restrict action paths declared by the authoritative store. */allowedActions?: readonly (readonly string[])[]; /** Authorize a decoded JSON request before serving it. */
+  authorize?: (request: TransportPolicyRequest) => boolean | Promise<boolean>;
+  /**
+   * Map a caught execute error to an explicitly client-visible message.
+   * Returning `undefined` keeps the generic redacted message.
+   */
+  mapError?: (error: unknown, request: TransportPolicyRequest) => string | undefined | Promise<string | undefined>;
+};
+/**
+ * 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;
+/**
+ * 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.
+ */
+
+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[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<PropertyKey, 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;
+  /**
+   * @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; /** Restrict requests accepted by a shared-main store. */
+  transportPolicy?: TransportPolicy;
+  /**
+   * Middleware chain applied before the initial state is finalized.
+   */
+  middlewares?: Middleware<T>[];
+  /**
+   * 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.
+   *
+   * @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 accepted by the statically isolated local-store entry point. */
+type LocalStoreOptions<T extends CreateState> = Omit<StoreOptions<T>, 'transport' | 'transportPolicy' | 'workerType'>;
+/**
+ * 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>>;
+type SingleLocalStoreOptions<T extends CreateState> = LocalStoreOptions<T> & {
+  sliceMode: 'single';
+};
+/** Overload set for the transport-free `coaction/local` create function. */
+type LocalCreator = {
+  <T extends ISlices>(createState: T, options: SingleLocalStoreOptions<T>): StoreReturn<T>;
+  <T extends Record<PropertyKey, Slice<any>>>(createState: T, options?: LocalStoreOptions<T>): StoreReturn<SliceState<T>>;
+  <T extends ISlices>(createState: Slice<T> | T, options?: LocalStoreOptions<T>): StoreReturn<T>;
+};
+//#endregion
+//#region packages/core/src/createLocal.d.ts
+/**
+ * Create a store without linking the shared transport runtime.
+ *
+ * @remarks
+ * The public `coaction/local` entry exports this implementation as `create`.
+ * `createLocal` is only its internal and documentation name; it is not
+ * exported by the root `coaction` entry.
+ */
+declare const createLocal: LocalCreator;
+//#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/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 DeepPartial, type Getter, type ISlices, type Listener, type LocalCreator, type LocalStoreOptions, type Middleware, type MiddlewareStore, type PatchTransform, type Slice, type SliceState, type Slices, type Store, type StoreReturn, type StoreTraceEvent, computed, createLocal as create, effect, effectScope, endBatch, isComputed, isEffect, isEffectScope, isSignal, onStoreReady, signal, startBatch, trigger, wrapStore };

package/dist/local.d.ts

@@ -0,0 +1,344 @@
+import { Transport } from "data-transport";
+import { Draft, Patches } from "mutative";
+import { computed, effect, effectScope, endBatch, isComputed, isEffect, isEffectScope, isSignal, signal, startBatch, trigger } from "alien-signals";
+
+//#region packages/core/src/jsonTypes.d.ts
+type JsonPrimitive = null | boolean | number | string;
+type JsonValue = JsonPrimitive | JsonValue[] | {
+  [key: string]: JsonValue;
+};
+//#endregion
+//#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> {}
+type TransportPolicyRequest = {
+  action: readonly string[];
+  args: readonly JsonValue[];
+  type: 'execute';
+} | {
+  type: 'fullSync';
+};
+type TransportPolicy = {
+  /** Further restrict action paths declared by the authoritative store. */allowedActions?: readonly (readonly string[])[]; /** Authorize a decoded JSON request before serving it. */
+  authorize?: (request: TransportPolicyRequest) => boolean | Promise<boolean>;
+  /**
+   * Map a caught execute error to an explicitly client-visible message.
+   * Returning `undefined` keeps the generic redacted message.
+   */
+  mapError?: (error: unknown, request: TransportPolicyRequest) => string | undefined | Promise<string | undefined>;
+};
+/**
+ * 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;
+/**
+ * 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.
+ */
+
+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[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<PropertyKey, 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;
+  /**
+   * @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; /** Restrict requests accepted by a shared-main store. */
+  transportPolicy?: TransportPolicy;
+  /**
+   * Middleware chain applied before the initial state is finalized.
+   */
+  middlewares?: Middleware<T>[];
+  /**
+   * 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.
+   *
+   * @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 accepted by the statically isolated local-store entry point. */
+type LocalStoreOptions<T extends CreateState> = Omit<StoreOptions<T>, 'transport' | 'transportPolicy' | 'workerType'>;
+/**
+ * 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>>;
+type SingleLocalStoreOptions<T extends CreateState> = LocalStoreOptions<T> & {
+  sliceMode: 'single';
+};
+/** Overload set for the transport-free `coaction/local` create function. */
+type LocalCreator = {
+  <T extends ISlices>(createState: T, options: SingleLocalStoreOptions<T>): StoreReturn<T>;
+  <T extends Record<PropertyKey, Slice<any>>>(createState: T, options?: LocalStoreOptions<T>): StoreReturn<SliceState<T>>;
+  <T extends ISlices>(createState: Slice<T> | T, options?: LocalStoreOptions<T>): StoreReturn<T>;
+};
+//#endregion
+//#region packages/core/src/createLocal.d.ts
+/**
+ * Create a store without linking the shared transport runtime.
+ *
+ * @remarks
+ * The public `coaction/local` entry exports this implementation as `create`.
+ * `createLocal` is only its internal and documentation name; it is not
+ * exported by the root `coaction` entry.
+ */
+declare const createLocal: LocalCreator;
+//#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/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 DeepPartial, type Getter, type ISlices, type Listener, type LocalCreator, type LocalStoreOptions, type Middleware, type MiddlewareStore, type PatchTransform, type Slice, type SliceState, type Slices, type Store, type StoreReturn, type StoreTraceEvent, computed, createLocal as create, effect, effectScope, endBatch, isComputed, isEffect, isEffectScope, isSignal, onStoreReady, signal, startBatch, trigger, wrapStore };