Stand-alone snippets

When you want to see one concept in isolation, the stand-alone snippets are the right place. Each is a single file demonstrating one pattern — no Docker, no peers, runnable with bun.

Find them in examples/ in the repo — the core ones sit at the top level, the rest under per-topic subdirectories (patterns/, persistence/, cluster/, fsm/, pubsub/, crdt/, typed/, management/, …).

What’s there

File	Concept
hello-world.ts	The minimal actor — extends Actor, handles a message.
ping-pong.ts	Two actors bouncing a message back and forth.
bank-account.ts	Request/response via the ask pattern.
supervision.ts	Custom strategy with decideBy.
become.ts	context.become(...) for state transitions.
death-watch.ts	Terminated notifications via death watch.
router.ts	Local pool router, round-robin across workers.
scheduler.ts	scheduleOnce / scheduleAtFixedRate.
patterns/timers-heartbeat.ts	Per-actor context.timers.
patterns/stash-init.ts	Stash + replay during async init.
patterns/circuit-breaker-hello.ts	CircuitBreaker around a flaky call.
patterns/backoff-supervisor.ts	Exponential-backoff restart.
typed/behaviors-receive.ts	The same counter via the typed Behaviors DSL.
typed/behaviors-supervise.ts	setup / withTimers / supervise composition.
fsm/traffic-light.ts	FSM DSL — when / onEnter / onTransition.
fsm/order-workflow.ts	Multi-step PersistentFSM (saga).
persistence/bank-account.ts	Event-sourced actor — persist, recover, snapshot.
persistence/durable-state-kv.ts	Durable-state (snapshot-style) persistence.
persistence/projection-bank-statement.ts	Read-side view via ProjectionActor.
persistence/replicated-counter.ts	Multi-master replicated event sourcing.
cluster/singleton-hello.ts	Cluster singleton with manager + proxy.
cluster/sharded-daemon-hello.ts	Sharded daemon process — N workers by index.
pubsub/chat-mediator.ts	DistributedPubSub on a single node.
pubsub/event-bus-across-nodes.ts	Topic-based event bus across nodes.
crdt/shopping-cart-orset.ts	OR-Set CRDT — add-wins under concurrent edits.
management/health-endpoint.ts	/health + /cluster/members endpoints.
management/prometheus-endpoint.ts	/metrics Prometheus exposition.

Each snippet is 50-200 lines. Read in a few minutes; modify to play with the concept.

Running

git clone https://github.com/pathosDev/actor-ts.git
cd actor-ts

bun install
bun examples/hello-world.ts

Most snippets run to completion and exit. The ones under examples/http/, plus the Prometheus and Kubernetes-probe ones, are servers instead — they bind a port and stay up until you stop them, which is the point of those particular snippets.

For cluster-related snippets (singleton, sharding, pubsub, DD), the snippets use MultiNodeSpec to simulate a cluster inside one process — no Docker required.

A handful do need something external: the broker snippets under examples/io/ want Kafka, NATS or MQTT (and the matching optional peer dependency), and examples/coordination/k8s-lease-singleton.ts wants a Kubernetes API server. Each of those names what it needs when you run it.

Verified in CI

Every snippet on this page is run by the example gate on each push that touches src/ or examples/, so a framework change that breaks one is a red check:

bun run test:examples              # all of them, ~90 s
bun run test:examples patterns     # just the ones matching a substring

Each is classified once in tests/examples/examples.manifest.json — runnable with an output assertion, or skipped with the reason. The ones needing a broker, Kubernetes, or an undeclared optional peer are the skipped set; that file is where to look for which, and why. Adding a snippet means adding its entry, or the gate fails on the mismatch.

Patterns

Most snippets follow the same shape:

import { ActorSystem, ... } from 'actor-ts';
import { ... } from 'actor-ts/<subsystem>';

// 1. Set up the system + actors.
const system = ActorSystem.create('demo');
const ref = system.spawnAnonymous(MyActor);

// 2. Send some messages.
ref.tell({ ... });
ref.tell({ ... });

// 3. Print result + clean up.  `terminate()` drains the mailboxes
//    first, so there is nothing to sleep for — unless the snippet
//    waits on a timer or an un-awaited promise, which the drain does
//    not follow.
console.log(...);
await system.terminate();

For more complex flows (cluster, persistence), the snippets use TestKit + TestProbe for clean teardown.

Modifying

Snippets are the easiest place to experiment:

# Copy, edit, run:
cp examples/hello-world.ts examples/my-experiment.ts
# Edit examples/my-experiment.ts
bun examples/my-experiment.ts

The framework is set up via the local repo’s actor-ts package — your edits run against the live source.

Contributing snippets

If you’ve worked out a clever pattern, PR a snippet. Criteria:

• One file, ≤ 200 lines.
• One concept demonstrated clearly.
• Self-contained — runnable without external services.
• Comments explaining what the code shows.

Put it at the top level of examples/ for a core concept, or in the matching topic subdirectory; then add a row to the table above.

Where to next

• Examples overview — larger runnable apps.
• Quickstart — the 5-minute introduction.
• Fundamentals overview — the concept map.