Motivation

Modern web applications are becoming increasingly complex, pushing the boundaries of what's possible in the browser. Single-threaded JavaScript often struggles to keep up with the demands of sophisticated UIs, real-time interactions, and data-intensive computations — leading to laggy interfaces and compromised user experiences.

While Web Workers (and SharedWorker) offer a path towards parallelism, they introduce challenges around state management, data synchronization, and maintaining coherent application logic across threads.

Coaction was created to bridge this gap — a state management solution that truly embraces the multithreading nature of modern web applications, without sacrificing developer experience.

• Performance first — Offload computationally intensive tasks and state management to worker threads, keeping your UI responsive and fluid.
• Scalable architecture — An intuitive API (inspired by Zustand) with Slices, namespaces, and computed properties promotes modularity and clean code organization.
• Flexible synchronization — Integration with data-transport enables generic transport protocols, supporting various communication patterns including remote synchronization for CRDTs applications.

Features

• Multithreading Sync — Share state between webpage and worker threads. With data-transport, avoid the complexities of message passing and serialization.
• Immutable State with Optional Mutability — Powered by Mutative, providing immutable state transitions with opt-in mutable instances for performance.
• Patch-Based Updates — Efficient incremental state changes through patch-based synchronization, ideal for CRDTs applications.
• Built-in Computed — Derived properties based on state dependencies with automatic caching.
• Slices Pattern — Combine multiple slices into a store with namespace support.
• Extensible Middleware — Enhance store behavior with logging, time-travel debugging, persistence, and more.
• Framework Agnostic — Works with React, Angular, Vue, Svelte, Solid, and state libraries like Redux, Zustand, and MobX.

Installation

For React applications:

npm install coaction @coaction/react

For the core library without any framework:

npm install coaction

Usage

Standard Mode Store

import { create } from '@coaction/react';

const useStore = create((set) => ({
  count: 0,
  increment: () => set((state) => state.count++)
}));

const CounterComponent = () => {
  const store = useStore();
  return (
    <div>
      <p>Count: {store.count}</p>
      <button onClick={store.increment}>Increment</button>
    </div>
  );
};

Shared Mode Store

counter.js

export const counter = (set) => ({
  count: 0,
  increment: () => set((state) => state.count++)
});

worker.js

import { create } from '@coaction/react';
import { counter } from './counter';

create(counter);

App.jsx

import { create } from '@coaction/react';
import { counter } from './counter';

const worker = new Worker(new URL('./worker.js', import.meta.url), {
  type: 'module'
});
const useStore = create(counter, { worker });

const CounterComponent = () => {
  const store = useStore();
  return (
    <div>
      <p>Count in Worker: {store.count}</p>
      <button onClick={() => store.increment()}>Increment</button>
    </div>
  );
};

Slices Pattern & Derived Data

import { create } from '@coaction/react';

const counter = (set, get) => ({
  count: 0,
  // derived data without cache
  get tripleCount() {
    return this.count * 3;
  },
  // derived data with cache
  doubleCount: get(
    (state) => [state.counter.count],
    (count) => count * 2
  ),
  increment() {
    set(() => {
      // you can use `this` to access the slice state
      this.count += 1;
    });
  }
});

const useStore = create(
  {
    counter
  },
  {
    sliceMode: 'slices'
  }
);

Methods that rely on this stay bound when you destructure them from getState():

const { increment } = useStore.getState().counter;
increment();

Operating Modes

Coaction operates in two primary modes:

Standard Mode

The store is managed entirely within the webpage thread. Patch updates are disabled by default for optimal performance.

Shared Mode

The worker thread serves as the primary source of shared state, utilizing transport for synchronization. Webpage threads act as clients, accessing and manipulating the state asynchronously.

In shared mode, the library automatically determines the execution context based on transport parameters, handling synchronization seamlessly. You can easily support multiple tabs, multithreading, or multiprocessing.

Examples

For a 3D scene shared across several tabs, you can effortlessly handle state management using Coaction:

https://github.com/user-attachments/assets/9eb9f4f8-8d47-433a-8eb2-85f044d6d8fa

sequenceDiagram
    participant Client as Webpage Thread (Client)
    participant Main as Worker Thread (Main)

    activate Client
    Note over Client: Start Worker Thread
    activate Main

    Client ->> Main: Trigger fullSync event after startup
    activate Main
    Main -->> Client: Synchronize data (full state)
    deactivate Main

    Note over Client: User triggers a UI event
    Client ->> Main: Send Store method and parameters
    activate Main
    Main ->> Main: Execute the corresponding method
    Main -->> Client: Synchronize state (patches)
    Note over Client: Render new state

    Main -->> Client: Asynchronously respond with method execution result
    deactivate Main
    deactivate Client

Performance

Benchmark measuring ops/sec to update 50K arrays and 1K objects — higher is better (source).

Coaction v0.1.5 vs Zustand v5.0.2

Coaction performs on par with Zustand in standard usage. The key difference emerges with immutable helpers: Coaction with Mutative is ~18.3x faster than Zustand with Immer (4,626 vs 253 ops/sec), thanks to Mutative's efficient state update mechanism.

Coaction vs Zustand

Coaction inherits Zustand's intuitive API design while adding built-in support for features Zustand doesn't offer out of the box:

Some features may have community solutions in Zustand; Coaction provides a more unified and streamlined API suited for modern web application development.

API Reference

• Core API index
• Core API notes
• Architecture overview
• Support matrix
• API evolution

Regenerate the reference from source with pnpm docs:api.

Store Shape Mode (sliceMode)

create() infers store shape from createState by default (sliceMode: 'auto'). 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.

• 'single' — Treat an object as a single store, even if all values are functions.
• 'slices' — Strict slices mode with validation.

const singleStore = create(
  {
    ping() {
      return 'pong';
    }
  },
  { sliceMode: 'single' }
);

const slicesStore = create(
  {
    counter: (set) => ({
      count: 0,
      increment() {
        set((draft) => {
          draft.counter.count += 1;
        });
      }
    })
  },
  { sliceMode: 'slices' }
);

Reusable Store

Refactor a general store into a multithreading reusable store — the same source runs on both the webpage and the worker, with isolated references but synchronized state:

store.js

+ const worker = globalThis.SharedWorker
+   ? new SharedWorker(new URL('./store.js', import.meta.url), { type: 'module' })
+   : undefined;

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

TypeScript note: In the webpage context, the store type is AsyncStore (methods become asynchronous and are proxied to the worker). In the worker context, it's Store. See the reusable store example.

Integration

Coaction is designed to work with a wide range of libraries and frameworks.

Frameworks

State Management Libraries

Note: Slices mode is a core coaction feature. Third-party state adapters only support whole-store binding.

Middlewares

Yjs Collaboration

For production collaboration setups with @coaction/yjs, see:

• Sync Model
• Conflict Semantics
• Provider Integration
• Compatibility & Limits
• Troubleshooting

FAQs

Contributing

Credits

• Concept inspired by Partytown
• API design inspired by Zustand
• Technical reference: React + Redux + Comlink = Off-main-thread

License

Coaction is MIT licensed.