coaction

English documentation · 中文文档

An efficient and flexible state management library for building high-performance, multithreading web applications.

Coaction uses alien-signals internally for cached getter/computed state, React selector reactivity, and adapter-facing subscriptions. The core package also re-exports the signal primitives for advanced integrations.

Installation

Install it with pnpm:

pnpm add coaction

Usage

import { create } from 'coaction/local';

const store = create((set) => ({
  count: 0,
  get doubleCount() {
    return this.count * 2;
  },
  increment() {
    set(() => {
      this.count += 1;
    });
  }
}));

Core stores are immutable by default. Getters and methods can read through this, but writes to Coaction-owned state must happen inside set() or set((draft) => ...). Direct writes such as this.count += 1 in a store method throw because they bypass the commit path that notifies subscribers, produces patches when enabled, and synchronizes worker/client mirrors in shared mode.

Coaction fixes the public state schema after initialization. A single store cannot add new top-level state keys later, and a slices store cannot add new slice keys or new top-level fields inside a slice. Replacement-style APIs such as apply() may omit a known single-store root key; the public getter remains present and reads as undefined, but no unknown key is promoted into the public module. Slice root keys are stricter and cannot be removed or replaced with non-object values. Keep dynamic data inside an existing object or array field.

Mutable adapters such as MobX, Pinia, and Valtio keep Coaction raw state, public state, and the external mutable runtime synchronized for known schema keys. Coaction still treats its raw/public schema as authoritative: out-of-band unknown properties written directly onto a third-party mutable runtime are not promoted into Coaction state, and adapter-specific docs define whether that external runtime property is pruned, restored, or left to the underlying library.

Accessor getters are cached automatically through the built-in signal runtime. Use get(deps, selector) when you want to declare dependencies manually:

const store = create((set, get) => ({
  count: 0,
  doubleCount: get(
    (state) => [state.count],
    (count) => count * 2
  ),
  increment() {
    set(() => {
      this.count += 1;
    });
  }
}));

Local stores can import signal primitives from coaction/local. Adapter authors use the statically separate coaction/adapter entry:

import { computed, effect, signal } from 'coaction/local';
import { defineExternalStoreAdapter } from 'coaction/adapter';

Adapter and Middleware Utilities

coaction/adapter exports utilities for adapter and middleware authors. These are not needed for normal application state updates, but they are part of the supported integration surface used by the official packages:

• Mutable adapter helpers: applyMutableAdapterPatches, replaceMutableAdapterState, toMutableAdapterSnapshot, snapshotMutableAdapterPureState, isEqualMutableAdapterSnapshot, getMutableAdapterOwnEnumerableKeys, isMutableAdapterUnsafeKey.
• Root replacement helpers: createRootReplacementPatches, applyRootReplacementWithPatches.
• Patch safety helpers: assertSafePatches, sanitizePatches, UnsafePatchPathError.
• State shape helpers: StateSchemaError, isStateSchemaError, sanitizeReplacementState, sanitizeInitialStateValue, replaceOwnEnumerable.

Runtime mutation paths reject unsafe patch paths before applying state changes. If a store.patch() hook returns a path containing __proto__, prototype, or constructor, Coaction throws UnsafePatchPathError instead of silently dropping that patch and applying the rest.

Shared JSON contract

Import create from coaction/shared when state crosses a Worker, SharedWorker, or injected transport boundary:

import { create } from 'coaction/shared';

Shared state, action arguments, action results, patch values, and full-sync snapshots must be JSON trees: finite numbers, strings, booleans, null, dense arrays, and plain records. Coaction rejects values that JSON would normalize or cannot represent losslessly, including undefined, BigInt, NaN, infinity, negative zero, functions in data, symbols, accessors, platform objects, sparse arrays, circular references, and repeated object references. Local stores do not inherit this restriction.

An authority and every connected client must use the same Coaction major and wire protocol. Mixed-major shared deployments are unsupported.

Store methods using this are rebound to the latest state when invoked from getState(), so destructuring remains safe:

const store = create((set) => ({
  count: 0,
  increment() {
    set(() => {
      this.count += 1;
    });
  }
}));

const { increment } = store.getState();
increment();

API Reference

• Generated core API index
• Core API notes

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 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.

create({ ping: () => 'pong' }, { sliceMode: 'single' });
create({ counter: (set) => ({ count: 0 }) }, { sliceMode: 'slices' });

Documentation

You can find the documentation here.