coaction 2.0.0 → 3.0.0

package/dist/index.d.mts

@@ -2,6 +2,12 @@ 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.
@@ -156,6 +162,22 @@ interface Store<T extends ISlices = ISlices> {
  * `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.
  *
@@ -243,7 +265,8 @@ type StoreOptions<T extends CreateState> = {
   /**
    * Inject a pre-built transport for advanced shared-store setups.
    */
-  transport?: Transport;
+  transport?: Transport; /** Restrict requests accepted by a shared-main store. */
+  transportPolicy?: TransportPolicy;
   /**
    * Middleware chain applied before the initial state is finalized.
    */
@@ -379,197 +402,45 @@ type Creator = {
  * 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.
+ * Prefer the static `coaction/local` entry when transport support is not
+ * required. It excludes the JSON protocol and reconnect runtime from the
+ * consumer dependency graph.
  */
 declare const create: Creator;
 //#endregion
-//#region packages/core/src/internal.d.ts
-type MutationOperation = 'setState' | 'apply';
-type SignalSlot = {
-  refresh: () => void;
-};
-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;
-  /**
-   * Whether the batch is running.
-   */
-  isBatching: boolean;
-  /**
-   * The listeners.
-   */
-  listeners: Set<Listener>;
-  /**
-   * 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>;
-  /**
-   * 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;
-  /**
-   * Authorized client-mirror state application used by transports.
-   */
-  applyClientState?: (state?: T, patches?: Patches) => void;
-}
-//#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;
-};
+//#region packages/core/src/getRawStateClientAction.d.ts
 /**
- * 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.
+ * The authority changed while a remote action was in flight, so its side-effect
+ * outcome cannot be determined safely from the current client mirror.
  */
-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
- * This is the stable 2.x name for adapter authors. `createBinder()` remains as
- * a compatibility alias for existing official and community integrations.
- */
-declare function defineExternalStoreAdapter<F = (...args: any[]) => any>(options: ExternalStoreAdapterOptions<F>): F;
+declare class ActionAuthorityChangedError extends Error {
+  readonly code = "COACTION_ACTION_AUTHORITY_CHANGED";
+  readonly outcome = "unknown";
+  constructor(action: string);
+}
 //#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/reactiveTracker.d.ts
-type ReactiveTracker = {
-  getSnapshot: () => number;
-  subscribe: (listener: () => void) => () => void;
-  track: <T>(fn: () => T) => T;
-  dispose: () => void;
-};
-declare const createReactiveTracker: () => ReactiveTracker;
-//#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 const replaceOwnEnumerable: (target: Record<PropertyKey, unknown>, source: Record<PropertyKey, unknown>) => void;
+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;
 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 call {@link create} instead of using `wrapStore()`
- * directly.
- */
-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 { ActionAuthorityChangedError, type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ISlices, type JsonPrimitive, type JsonValue, type Middleware, type MiddlewareStore, type PatchTransform, type Slice, type SliceState, type Slices, StateSchemaError, type Store, type StoreOptions, type StoreTraceEvent, type TransportPolicy, type TransportPolicyRequest, UnsafePatchPathError, assertSafePatches, computed, create, effect, effectScope, endBatch, isComputed, isEffect, isEffectScope, isSignal, isStateSchemaError, onStoreReady, sanitizeInitialStateValue, sanitizePatches, sanitizeReplacementState, signal, startBatch, trigger };

package/dist/index.d.ts

@@ -2,6 +2,12 @@ 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.
@@ -156,6 +162,22 @@ interface Store<T extends ISlices = ISlices> {
  * `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.
  *
@@ -243,7 +265,8 @@ type StoreOptions<T extends CreateState> = {
   /**
    * Inject a pre-built transport for advanced shared-store setups.
    */
-  transport?: Transport;
+  transport?: Transport; /** Restrict requests accepted by a shared-main store. */
+  transportPolicy?: TransportPolicy;
   /**
    * Middleware chain applied before the initial state is finalized.
    */
@@ -379,197 +402,45 @@ type Creator = {
  * 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.
+ * Prefer the static `coaction/local` entry when transport support is not
+ * required. It excludes the JSON protocol and reconnect runtime from the
+ * consumer dependency graph.
  */
 declare const create: Creator;
 //#endregion
-//#region packages/core/src/internal.d.ts
-type MutationOperation = 'setState' | 'apply';
-type SignalSlot = {
-  refresh: () => void;
-};
-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;
-  /**
-   * Whether the batch is running.
-   */
-  isBatching: boolean;
-  /**
-   * The listeners.
-   */
-  listeners: Set<Listener>;
-  /**
-   * 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>;
-  /**
-   * 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;
-  /**
-   * Authorized client-mirror state application used by transports.
-   */
-  applyClientState?: (state?: T, patches?: Patches) => void;
-}
-//#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;
-};
+//#region packages/core/src/getRawStateClientAction.d.ts
 /**
- * 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.
+ * The authority changed while a remote action was in flight, so its side-effect
+ * outcome cannot be determined safely from the current client mirror.
  */
-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
- * This is the stable 2.x name for adapter authors. `createBinder()` remains as
- * a compatibility alias for existing official and community integrations.
- */
-declare function defineExternalStoreAdapter<F = (...args: any[]) => any>(options: ExternalStoreAdapterOptions<F>): F;
+declare class ActionAuthorityChangedError extends Error {
+  readonly code = "COACTION_ACTION_AUTHORITY_CHANGED";
+  readonly outcome = "unknown";
+  constructor(action: string);
+}
 //#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/reactiveTracker.d.ts
-type ReactiveTracker = {
-  getSnapshot: () => number;
-  subscribe: (listener: () => void) => () => void;
-  track: <T>(fn: () => T) => T;
-  dispose: () => void;
-};
-declare const createReactiveTracker: () => ReactiveTracker;
-//#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 const replaceOwnEnumerable: (target: Record<PropertyKey, unknown>, source: Record<PropertyKey, unknown>) => void;
+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;
 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 call {@link create} instead of using `wrapStore()`
- * directly.
- */
-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 { ActionAuthorityChangedError, type StoreWithAsyncFunction as AsyncStore, type Asyncify, type ClientStoreOptions, type ISlices, type JsonPrimitive, type JsonValue, type Middleware, type MiddlewareStore, type PatchTransform, type Slice, type SliceState, type Slices, StateSchemaError, type Store, type StoreOptions, type StoreTraceEvent, type TransportPolicy, type TransportPolicyRequest, UnsafePatchPathError, assertSafePatches, computed, create, effect, effectScope, endBatch, isComputed, isEffect, isEffectScope, isSignal, isStateSchemaError, onStoreReady, sanitizeInitialStateValue, sanitizePatches, sanitizeReplacementState, signal, startBatch, trigger };