coaction 2.1.0 → 3.1.0

package/dist/shared.d.ts

@@ -0,0 +1,446 @@
+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 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 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.
+   *
+   * @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<Awaited<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<Awaited<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<PropertyKey, Slice<any>>;
+type SingleStoreOptions<T extends CreateState> = StoreOptions<T> & {
+  sliceMode: 'single';
+};
+type SingleClientStoreOptions<T extends CreateState> = ClientStoreOptions<T> & {
+  sliceMode: 'single';
+};
+/**
+ * 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 ISlices>(createState: T, options: SingleStoreOptions<T>): StoreReturn<T>;
+  <T extends Record<PropertyKey, Slice<any>>>(createState: T, options?: StoreOptions<T>): StoreReturn<SliceState<T>>;
+  <T extends ISlices>(createState: Slice<T> | T, options?: StoreOptions<T>): StoreReturn<T>;
+  <T extends ISlices>(createState: T, options: SingleClientStoreOptions<T>): StoreWithAsyncFunction<T>;
+  <T extends Record<PropertyKey, Slice<any>>>(createState: T, options?: ClientStoreOptions<T>): StoreWithAsyncFunction<SliceState<T>, true>;
+  <T extends ISlices>(createState: Slice<T> | T, options?: ClientStoreOptions<T>): StoreWithAsyncFunction<T>;
+};
+//#endregion
+//#region packages/core/src/create.d.ts
+/**
+ * Create a local store, the main side of a shared store, or a client mirror of
+ * a shared store.
+ *
+ * @remarks
+ * 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/getRawStateClientAction.d.ts
+/**
+ * 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 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/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;
+declare const sanitizeReplacementState: <T>(source: T, seen?: WeakMap<object, unknown>) => T;
+declare const sanitizeInitialStateValue: <T>(source: T, seen?: WeakMap<object, unknown>) => T;
+//#endregion
+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 };