anneal

soften the spine so the blade doesn't shatter

CSP/Actor model architecture for TypeScript applications.

Generic building blocks for actor-model concurrency. Each type maps to a common async communication pattern, eliminating the per-actor boilerplate of defining message types, resolver callbacks, and caller wrappers.

Naming

Three libraries, three languages, three diseases, one cure.

• actor (Go) - names Go's missing enforcement. Go has channels and

goroutines but no structure for the actor pattern. You reinvent it every time.

• pickle (Rust) - names Rust's encrustation. Arc<Mutex<T>>,

lifetime annotations, &self vs &mut self - the borrow checker fights you when all you need is message-passing.

• anneal (TypeScript) - names TypeScript's brittleness. async/await

and Promises shatter under composition. Callbacks nest, errors vanish, backpressure doesn't exist.

The sword analogy: the actor loop is the tempered cutting edge - hard, precise, one message at a time. The async integration layer around it is the annealed spine - flexible, absorbs shock without shattering. A good sword needs both.

Architecture Guide

These libraries implement the intra-domain actor patterns described in Moxie Architecture Patterns - specifically sections 3.1-3.6 (the actor loop, typed operation channels, synchronous-mutation rule, construction-is-spawning, post-mortem queries, context-aware calls). The five channel types (Func, Query, Proc, Signal, Inbox) are a direct realization of the typed operation channel taxonomy from section 3.2.

The architecture document covers the full CSP/Actor/DDD model including inter-domain patterns (spawn boundaries, worker pools, pipelines, supervision, shutdown) which apply at the process level in Moxie but whose structural principles - state ownership, backpressure by buffer, bilateral protocol changes, measurement before tuning - apply identically when building actor systems in any language.

Types

Type	Caller	Actor	Pattern
Func<Req, Resp>	call(req) -> Promise<Resp>	msg.req, msg.reply(resp)	function call
Query<Resp>	call() -> Promise<Resp>	msg.reply(resp)	getter
Proc<Req>	call(req) -> Promise<void>	msg.req, msg.done()	setter / command
Signal	call() -> Promise<void>	msg.done()	trigger / reset
Inbox<T>	send(v) / trySend(v)	receive in select	fire-and-forget
Lifecycle	stop() -> Promise<void>	.on() in select	shutdown

All synchronous types resolve the caller's Promise only after the actor has processed the message. This eliminates races where a buffered write appears to succeed but the actor hasn't seen it yet.

Example

import { Signal, Query, Lifecycle, spawn, loop, select, STOP } from 'anneal';

class Counter {
    private inc = new Signal();
    private get = new Query<number>();
    private lc = new Lifecycle();

    constructor() {
        spawn(this.lc, async () => {
            let n = 0;
            await loop(
                this.lc.on(() => STOP),
                this.inc.on(msg => { n++; msg.done(); }),
                this.get.on(msg => { msg.reply(n); }),
            );
        });
    }

    incr() { return this.inc.call(); }
    value() { return this.get.call(); }
    stop() { return this.lc.stop(); }
}

const c = new Counter();
await c.incr();
await c.incr();
await c.incr();
console.log(await c.value()); // 3
await c.stop();

Design Principles

• No shared mutable state. The actor function owns all mutable

state. Callers interact through typed channel objects.

• Synchronous resolution. The caller's Promise resolves only after

the actor has processed the message. Use Inbox for intentionally async paths.

• Sequential processing. Messages are handled one at a time. No

concurrent access to actor state, ever.

• Composable. Use the channel types you need. No base class to

extend, no framework, no registration.

When to use what

• Func - caller needs a computed result based on arguments (map

lookup, filtered query)

• Query - caller needs current state, no arguments (get count, get

config)

• Proc - caller needs to mutate state and wait for confirmation

(set value, record event)

• Signal - caller needs to trigger an action and wait (reset,

flush, increment)

• Inbox - caller must not block (logging, metrics, notifications).

Use trySend to drop on backpressure.

Cancellation

All synchronous types accept an optional AbortSignal:

const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 1000);
const result = await func.call(req, ctrl.signal);

If the signal fires before the actor processes the message, the caller's Promise rejects. The actor may still process the message - same semantics as Go's CallCtx and Rust's call_timeout.

Select priority

Cases are checked in declaration order. Place the lifecycle case first for reliable shutdown under load:

await loop(
    this.lc.on(() => STOP),    // checked first
    this.work.on(msg => { ... }),
);

Install

npm install anneal

License

AGPL-3.0-or-later