API reference

Per-export contract for @workspace/active-state, an internal workspace package. This document describes the shape and observable behaviour of every public export; per-symbol TSDoc lives in the TypeScript sources and the compiler is authoritative on types. The decisions behind the contract are in DECISIONS.md § Besluit 5, the runtime model is in ARCHITECTURE.md, and purpose and scope are in FUNCTIONEEL-OVERZICHT.md. The public surface is pinned symbol by symbol in src/__tests__/public-api.test.ts.

Import paths#

A React consumer imports from /react only. react@^19 is an optional peer, required by /react and by the React-based parts of a test setup.

Surface at a glance#

Contexts: which calls are allowed where#

Every mutating or lifecycle call first checks where it runs. The rules apply to every section below.

A rejection inside an open Transaction fails that Transaction even when user code catches the error.

Store<T>#

The writable state authority. One type parameter; writing is invariant in T.

new Store<T>(initial: T, options?: StoreOptions<T>)
interface StoreOptions<T> {  equal?: (a: T, b: T) => boolean; // "unchanged"; no default (see below)  label?: string;                  // value-free identifier for instrumentation  scope?: Scope;                   // disposed with this Scope}

Acceptance. A write passes equal(current, candidate) when equal is set; an equal candidate is not accepted and publishes nothing. An accepted write is stored before the call returns, and no user callback runs between acceptance and storage.

Publication. A Store with an accepted write publishes at the next publication boundary, when it has no equal, or when !equal(lastPublished, current). Subscribers receive (value, previous), where previous is the last published value; unpublished intermediate values never become previous.

No default equality. A Store without equal accepts and publishes every write, also an identical value. Whether a default should exist (Object.is or shallow) is an open decision (ROADMAP R7). Supply equal explicitly where you rely on it.

Disposed Stores ignore writes silently; with an instrumentation listener attached, each ignored call is a write.ignored event (see /testing).

Readables: Source<T>, ReadableStore<T>, Listener<T>, Unsubscribe#

interface ReadableStore<T> {  readonly state: T;  subscribe(listener: Listener<T>): Unsubscribe;}type Listener<T> = (value: T, previous: T) => void;type Unsubscribe = () => void;

• ReadableStore<T> is the smallest readable shape. useStore accepts any value that satisfies it.

• Source<T> is a native graph source: a Store, a readonly projection, a Derived or an Operation's status. It is exported as a type only; the runtime recognises a source by a private brand, not by its shape, so a cast or impostor is rejected as an input. Source<T> is covariant and exposes only state and subscribe.

Derived<T, I>#

Computed state over explicit inputs.

new Derived({  inputs: [a, b],                 // native sources, copied and frozen at construction  compute: (valueA, valueB) => …, // positional input values; pure and deterministic  equal?: (x, y) => boolean,      // default Object.is  label?: string,  scope?: Scope,});
type ValuesOf<I extends readonly Source<unknown>[]> = {  readonly [K in keyof I]: I[K] extends Source<infer V> ? V : never;};

I is inferred from inputs (a const type parameter), so no as const is needed; Derived<T> alone names any Derived of T.

• Freshness and publication are independent. A read never creates, suppresses or consumes a notification. An observed Derived publishes when its settled value differs from its last published value under equal; the same command notifies the same observers with or without intermediate reads.

• A Derived is a value, not a reducer: compute receives the input values and nothing else. Memory across evaluations belongs in a Store.

• Failure. A throwing compute or equal reaches the reader; nothing is cached and a later read retries. During settlement the failure goes to the error sink and the node and its dependents publish nothing that round.

• Cycles. Declared inputs cannot form a cycle. A compute that reads its own Derived through a closure throws DependencyCycleError. A read of an undeclared source is not tracked (unsupported; visible as derived.undeclared-read with a listener).

• Disposed. Reads return the frozen value; a Derived disposed before it ever produced a value throws DisposedResourceError.

Scope#

A lifetime container.

new Scope(options?: {parent?: Scope; pending?: boolean; label?: string})type ScopeState = 'pending' | 'active' | 'disposing' | 'disposed';

• Ownership. Stores and Deriveds may be unowned; Effects and Operations always have a Scope. Individually disposed members leave their Scope at once.

• Pending Scopes (pending: true, or any child of a pending parent) are acquisition-free: nothing they own starts an Effect, admits an invocation or observes an outside source until the root is activated. A pending owner only delays the start: an invocation made inside a Transaction or ctx.commit that reverts ends cancelled('transaction-reverted') and a later activation does not start it. A discarded pending model is referenced by nothing in the runtime. A factory that builds one must only construct resources; fetch, direct external subscriptions and DOM work belong in an Effect or Operation.

• Disposed resources are inert: writes are ignored, invoke returns an already cancelled invocation, subscribe returns a no-op handle, reads return the frozen value. Two calls still throw: a call from a pure context, and reading a Derived that was disposed before it ever produced a value (DisposedResourceError).

Effect<I>#

An owned reaction to published input transitions. Not a Derived and not React's useEffect.

new Effect({  scope,                          // required  inputs: [a, b],  run: ([valueA, valueB], ctx) => { …; return () => {/* cleanup */}; },  immediate?: boolean,  label?: string,});interface EffectContext { readonly scope: Scope } // the run Scope

• When it runs. In the reaction phase of a round in which at least one input published, after every subscriber of that round, with the complete input tuple captured before the round's first callback. Runs never nest. If an input failed or stayed undecided in that round, the Effect is skipped.

• immediate. The Effect is owed an initial run. It never begins before the constructor has returned; it runs at the first publication boundary after the start (a later write, the close of an enclosing batch/Transaction, a later round, or the activation of a pending Scope). No microtask or timer is introduced.

• Run Scope. Each run receives ctx.scope. Resources created in it live until the run ends, and only the Effect disposes it.

• Teardown order, on every path (rerun, dispose(), owner disposal, disposal during the run): the cleanup, then the run Scope, then, when the Effect stops, unobserving the inputs.

• Synchronous only. A run or cleanup that returns a promise is a diagnosed misuse (TypeError to the error sink or the dispose() caller). It is never awaited, and its rejection is reported, never left unhandled. The type cannot rule out an async cleanup; the runtime check is the guarantee.

• Failures of a run or cleanup go to the error sink; the Effect stays started and runs again on its next trigger.

Operation<TInput, TResult>#

Owned in-flight work with identity, policy, status and typed outcomes.

new Operation<TInput = void, TResult = unknown>({  scope,                                    // required; disposal cancels everything  policy: 'latest-wins' | 'drop-while-running' | 'queue',  run: (input, ctx) => PromiseLike<TResult> | TResult,  label?: string,});

Policies. latest-wins: a new admission supersedes the running invocation. drop-while-running: a new invocation is cancelled('dropped') while one runs. queue: FIFO, one at a time. "Latest" is creation order.

Invocation<TResult>: id (per Operation, in creation order), status ('queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'superseded'), outcome (a promise that never rejects), cancel() (requested; no effect once ended; rejected inside an open Transaction).

Outcome<TResult>: {status: 'succeeded', value}, {status: 'failed', error: unknown} (the original thrown or rejected value), {status: 'cancelled', reason: CancelReason} or {status: 'superseded', by: InvocationId}. CancelReason is 'requested' | 'owner-disposed' | 'dropped' | 'transaction-reverted'. Cancellation and supersession are outcomes, not failures.

OperationContext (the ctx of run):

• signal: an AbortSignal, aborted when the invocation is cancelled or superseded.

• invocation: its InvocationId.

• commit(fn): runs fn as an atomic commit authorized for this invocation. Result, in this order: not current at entry → fn does not run, false; currency lost during the commit → everything reverted, false; otherwise a failure inside it (also one user code caught) → everything reverted and that first failure rethrown; otherwise committed, true. Cancelling or disposing from inside a commit is rejected and reverts it. A commit inside another open Transaction throws CommitNestingError. A callback that visibly returns a promise does not compile.

• isCurrent(): whether a commit would be admitted now. Not a substitute for commit.

The stale-write guarantee covers ctx.commit only. A direct Store write from the async body after an await is unsupported and unprotected; nothing can attribute it to the invocation. Late settlements after a terminal outcome are absorbed, never unhandled.

batch(fn) and transaction(fn)#

function batch<T>(fn: () => NotThenable<T>): T;function transaction<T>(fn: () => NotThenable<T>): T;type NotThenable<T> = T extends PromiseLike<unknown> ? never : T;

batch groups publication only. Writes inside are accepted and readable at once; nothing is published until the outermost batch (or open Transaction) closes, and then synchronously, before batch returns. It never reverts anything: if fn throws, its writes survive, are published, and then the error is rethrown. Nested batches deepen the grouping.

transaction is synchronous, local and all-or-nothing:

• Writes happen in place, so reads inside see them, for Stores and Deriveds alike.

• A nested transaction joins the open one: one frame, no savepoints.

• The frame fails when a failure crosses an active-state boundary inside it (a nested transaction or batch that throws, a throwing updater or equality, a failing Derived read, a rejected call), also when user code catches it; fn throwing fails it too. A plain throw caught entirely inside user code does not.

• A failed frame restores every Store and Derived cache it touched, publishes nothing of its own work (whatever the equality) and rethrows its first failure. A committed frame publishes when the outermost hold closes, before the outermost call returns.

• Structural and lifecycle calls are rejected inside it. invoke() is deferred: admitted after commit (or, for an Operation whose Scope is pending, after that Scope's activation), cancelled('transaction-reverted') after a revert, whatever its owner's state.

• Only local state is reverted; network requests, DOM changes or copies made to other variables are not.

Nesting. A Transaction inside a batch is atomic on its own; the batch's earlier writes survive its failure. A batch inside a Transaction shares its publication, and an error escaping the batch fails the Transaction.

Synchronous only. A callback that returns a thenable is refused with a TypeError (the Transaction reverts; a batch publishes its writes first), and a rejection handler is attached so nothing becomes unhandled. NotThenable catches direct async callbacks at compile time; it cannot see through unknown, void, wide types or generic callbacks, and the runtime check is the guarantee.

shallow(a, b)#

Shallow equality over an explicit set of value families: Object.is; arrays (same length, same holes, element-wise Object.is); Maps and Sets; Dates by timestamp; URLs by href; two objects with the same prototype and the same own keys (strings and symbols, enumerable or not) with Object.is values; two empty plain objects. Everything else is not equal: an instance that owns no property (a Promise, a WeakMap, a class keeping its state in private fields or prototype getters) is never called equal to another instance. Symmetric for deterministic values; reads own properties, so an own getter or proxy trap runs and may throw. It compares one level deep. It is the default equality of useStore and the usual equal for an object- or array-valued Store.

Errors#

All are Error subclasses with a matching name.

Where failures go. Failures of your own call (an updater, an acceptance equality, a failing read, a batch/transaction callback, a rejected call) reach you synchronously. Failures without a synchronous caller (subscribers, Effect runs and cleanups, settlement, publication decisions, the budget) are collected per turn and reported once when the turn ends: one error as itself, several as an AggregateError, to the error sink. The default sink calls globalThis.reportError where available and otherwise rethrows in a microtask. They do not reach React Error Boundaries. Tests replace the sink through /testing.

useStore(readable, selector?, options?) — /react#

function useStore<T>(  readable: ReadableStore<T>,  selector?: undefined,  options?: UseStoreOptions<T>,): T;function useStore<T, S>(  readable: ReadableStore<T>,  selector: (state: T) => S,  options?: UseStoreOptions<S>,): S;interface UseStoreOptions<S> {  readonly equal?: (a: S, b: S) => boolean;} // default shallow

• useSyncExternalStore and nothing more: the snapshot is readable.state read during render; React subscribes after commit and releases on cleanup. Subscribing to a Derived activates it; the last release deactivates it. Passing a different readable replaces the subscription.

• Selection cache. A retained selection is reused only for the same readable and the same equality function; it is returned without re-selecting only when the selector and the snapshot are identical too, and kept by reference when equal calls the new selection equal. An inline selector that builds a new object every render does not loop.

• The selector and equal run during render and must be pure.

• The server snapshot is the same getter; it is consistent only where the host supplies the same per-request initial data to server and client. No Provider or context is read.

useScoped(factory) — /react, EXPERIMENTAL#

type ScopedFactory<T> = (scope: Scope) => T;function useScoped<T>(factory: ScopedFactory<T>): T;

Owns a model for the committed lifetime of a component. Experimental: exported after its exit gate passed (EXP-01 … EXP-08, see ARCHITECTURE.md § 11) and the export was approved (R14, T8-1). It has one production consumer and stays experimental: its shape and behaviour may still change with evidence from further use.

Supported host (the evidence). React 19.3.0 with react-dom 19.3.0 (createRoot, hydrateRoot), development and production builds, in Chromium (through playwright-core) and in jsdom. Other React versions are not claimed.

Lifecycle contract.

• Render. The first render calls factory with a pending Scope. A render that is discarded, or rendered twice in development, builds a model that never starts anything and that nothing references.

• Commit. The model is activated in the layout phase of the commit that keeps it, before any passive subscription of that commit.

• End. When React tears the component's effects down (unmount, or a hidden Activity), the component's subscriptions are released at once and it does not render again for the model. The model itself is disposed at the next microtask checkpoint; from then on its Effects are stopped, its invocations end cancelled('owner-disposed') and later commits are refused. A development StrictMode rehearsal sets the effects up again before that checkpoint and keeps the model. A tree hidden by a re-suspending Suspense boundary keeps its model.

• The grace before the disposal is not side-effect-free. Until the checkpoint the model's Scope is still active: a continuation queued ahead of it still runs and may commit, and the model's own Effects react to that commit, including any external work they do. Only the disposal ends the model's authority.

• Identity. One model per component lifetime; new props do not rebuild it, so a consumer that needs a new model remounts with a key. The one exception is a component whose model was disposed while React kept its state (a hidden Activity shown again): it gets a new model from the latest factory; the old one stays disposed.

• After the end. A disposed model's lifetime is over, whether it ended with its component or was replaced: its Operations never regain commit authority, and its subscriptions and Effects are released. A command still invoked on it, such as a handler that captured it, obeys the disposed-resource rules of Scope: writes are ignored and invocations end cancelled, but reading a model Derived that was never evaluated throws DisposedResourceError (R12). Consumers avoid invoking commands on an ended model, for example by first checking that its Scope is still active.

• A failing activation reaches the nearest error boundary; the model stays pending and ends with the component.

Factory obligations. The factory runs during render and must only construct resources in the Scope it receives: Stores, Deriveds, Effects, Operations, child Scopes, and invocations of its own Operations. It must not fetch, subscribe to an outside source directly, write outside state or touch the DOM; that work belongs in an Effect or Operation of the model. A factory that disposes its Scope gets a LifecycleViolation.

Known limits.

• The absence of React subscribers is no guard. A side effect that must not outlive the component bases its decision on the model's ownership where it acts: an outcome that succeeded before unmount stays succeeded, so a side effect after an awaited outcome, such as navigation, checks at that point that the model's Scope is still active; during the grace the Scope still reports active.

• A settlement failure of an observed Derived is not a React update; it surfaces through the error sink, and in the component at its next render.

The testing entry: /testing#

Test seams that work on the core without React, and the internal, unstable instrumentation protocol. Not for production code paths. No export gives access to a revision, depth, edge list or private member.

Instrumentation events carry a sequence number, a type from a closed set, detached resource and Scope references (identifiers and labels), a cause chain (direct, batch, transaction, operation, effect, subscriber, disposal, each with its parent) and value-free detail. They never contain state values, diffs, error objects, stacks or timings. Without a listener nothing is produced. Misuse diagnostics are events (write.ignored, derived.undeclared-read, lifetime.inversion, turn.suspended); the runtime itself never logs, warns or reads process.env. A development or test setup that wants warnings attaches a listener through record().

What is proved, and what is not#

• Core and useStore: Node/jsdom behaviour tests under src/**/__tests__/, including a real React.StrictMode wrapper, a suspended transition, hydrateRoot with matching data, server rendering and readable replacement. The tests are the executable specification of this document.

• useScoped: the eight exit criteria in jsdom and in Chromium on the host stated above.

• Not claimed: other React versions, React Compiler compatibility, serialization or hydration of state (the host supplies consistent data), and every browser beyond Chromium.

All exports, from the source#

@workspace/active-state#

class Scope {
  constructor(options?: ScopeOptions);
  get state(): ScopeState;
  activate(): void;
  dispose(): void;
  onDispose(disposer: () => void): () => void;
}

class Operation<TInput = void, TResult = unknown> {
  readonly status: Source<OperationStatus<TResult>>;
  constructor(options: OperationOptions<TInput, TResult>);
  invoke(...args: [
    TInput
  ] extends [
    void
  ] ? [
  ] : [
    input: TInput
  ]): Invocation<TResult>;
  dispose(): void;
}

class Derived<T, const I extends readonly Source<unknown>[] = readonly Source<unknown>[]> extends Source<T> {
  constructor(options: DerivedOptions<T, I>);
  get state(): T;
  subscribe(listener: Listener<T>): Unsubscribe;
  dispose(): void;
}

class Effect<const I extends readonly Source<unknown>[] = readonly Source<unknown>[]> {
  constructor(options: EffectOptions<I>);
  dispose(): void;
}

class Store<T> extends Source<T> {
  constructor(initial: T, options?: StoreOptions<T>);
  get state(): T;
  readonly setState: (next: T) => void;
  readonly update: (fn: (current: T) => T) => void;
  subscribe(listener: Listener<T>): Unsubscribe;
  asReadonly(): Source<T>;
  dispose(): void;
}

class CommitNestingError extends Error {
  constructor();
}

class CommitRevoked extends Error {
  constructor();
}

class DependencyCycleError extends Error {
  constructor();
}

class DisposedResourceError extends Error {
  constructor(message: string);
}

class FeedbackLimitExceeded extends Error {
  readonly steps: number;
  constructor(steps: number);
}

class LifecycleViolation extends Error {
  constructor(message: string);
}

class PurityViolation extends Error {
  readonly call: GuardedCall;
  constructor(call: GuardedCall);
}

class StructuralMutationInTransaction extends Error {
  readonly call: GuardedCall;
  constructor(call: GuardedCall);
}

type NotThenable<T> = T extends PromiseLike<unknown> ? never : T;

type Listener<T> = (value: T, previous: T) => void;

interface ReadableStore<T> {
  readonly state: T;
  subscribe(listener: Listener<T>): Unsubscribe;
}

abstract class Source<out T> {
  protected constructor();
  abstract get state(): T;
  abstract subscribe(listener: Listener<T>): Unsubscribe;
}

interface ScopeOptions {
  readonly parent?: Scope;
  readonly pending?: boolean;
  readonly label?: string;
}

type ScopeState = 'pending' | 'active' | 'disposing' | 'disposed';

type CancelReason =
  'requested' | 'owner-disposed' | 'dropped' | 'transaction-reverted';

interface Invocation<TResult> {
  readonly id: InvocationId;
  readonly status: InvocationStatus;
  readonly outcome: Promise<Outcome<TResult>>;
  cancel(): void;
}

type InvocationStatus =
  'queued' | 'running' | Outcome<unknown>['status'];

interface OperationContext {
  readonly signal: AbortSignal;
  readonly invocation: InvocationId;
  commit<R>(fn: () => NotThenable<R>): boolean;
  isCurrent(): boolean;
}

interface OperationOptions<TInput, TResult> {
  readonly scope: Scope;
  readonly policy: Policy;
  readonly run: (
    input: TInput,
    ctx: OperationContext,
  ) => PromiseLike<TResult> | TResult;
  readonly label?: string;
}

interface OperationStatus<TResult> {
  readonly phase: 'idle' | 'running';
  readonly running: InvocationId | null;
  readonly queued: number;
  readonly last: Outcome<TResult> | null;
}

type Outcome<TResult> =
  | {readonly status: 'succeeded'; readonly value: TResult}
  | {readonly status: 'failed'; readonly error: unknown}
  | {readonly status: 'cancelled'; readonly reason: CancelReason}
  | {readonly status: 'superseded'; readonly by: InvocationId};

type Policy = 'latest-wins' | 'drop-while-running' | 'queue';

interface DerivedOptions<T, I extends readonly Source<unknown>[]> {
  readonly inputs: I;
  readonly compute: (...values: ValuesOf<I>) => T;
  readonly equal?: (a: T, b: T) => boolean;
  readonly label?: string;
  readonly scope?: Scope;
}

type ValuesOf<I extends readonly Source<unknown>[]> = {
  readonly [K in keyof I]: I[K] extends Source<infer V> ? V : never;
};

interface EffectContext {
  readonly scope: Scope;
}

interface EffectOptions<I extends readonly Source<unknown>[]> {
  readonly scope: Scope;
  readonly inputs: I;
  readonly run: (
    values: ValuesOf<I>,
    ctx: EffectContext,
  ) => void | (() => void);
  readonly immediate?: boolean;
  readonly label?: string;
}

interface StoreOptions<T> {
  readonly equal?: (a: NoInfer<T>, b: NoInfer<T>) => boolean;
  readonly label?: string;
  readonly scope?: Scope;
}

type GuardedCall =
  | 'setState'
  | 'update'
  | 'subscribe'
  | 'unsubscribe'
  | 'dispose'
  | 'construct'
  | 'activate'
  | 'onDispose'
  | 'resume'
  | 'batch'
  | 'transaction'
  | 'invoke'
  | 'cancel'
  | 'commit';

@workspace/active-state/react#

The root entry again, plus:

{ <T>(readable: ReadableStore<T>, selector?: undefined, options?: UseStoreOptions<T>): T; <T, S>(readable: ReadableStore<T>, selector: (state: NoInfer<T>) => S, options?: UseStoreOptions<S>): S; }

interface UseStoreOptions<S> {
  readonly equal?: (a: S, b: S) => boolean;
}

@workspace/active-state/testing#

class UnassertedErrors extends AggregateError {
  constructor(errors: readonly unknown[]);
}

(events: readonly InstrumentationEvent[]) => string[][]

<I extends readonly Source<unknown>[]>(effect: Effect<I>) => EffectDescription

<TInput, TResult>(operation: Operation<TInput, TResult>) => OperationDescription

<TResult>(invocation: Invocation<TResult>) => void

<TInput = void, TResult = unknown>(options?: ControlledRunOptions<TInput>) => ControlledRun<TInput, TResult>

interface InstrumentationEvent {
  readonly seq: number;
  readonly type: EventType;
  readonly resource?: ResourceRef;
  readonly scope?: ScopeRef;
  readonly cause: Cause;
  readonly suppressed?: number;
  readonly detail?: EventDetail;
}

interface ErrorCapture {
  take(): unknown[];
  release(): void;
}

interface Recorder {
  readonly events: readonly InstrumentationEvent[];
  ofType(type: EventType): InstrumentationEvent[];
  about(resource: object): InstrumentationEvent[];
  idOf(resource: object): number;
  detach(): void;
}

interface ScopeInspection {
  readonly state: ScopeState;
  readonly members: readonly MemberDescription[];
}

interface ControlledRunOptions<TInput> {
  readonly prefix?: (input: TInput, ctx: OperationContext) => void;
  readonly onAbort?: (id: InvocationId, ctx: OperationContext) => void;
}

interface ControlledRun<TInput, TResult> {
  readonly run: (input: TInput, ctx: OperationContext) => Promise<TResult>;
  readonly started: readonly InvocationId[];
  input(id: InvocationId): TInput;
  context(id: InvocationId): OperationContext;
  aborted(id: InvocationId): boolean;
  resolve(id: InvocationId, value: TResult): void;
  reject(id: InvocationId, reason: unknown): void;
}