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

Each snippet runs to completion and exits. No long-running processes; no external dependencies.

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

Patterns

Most snippets follow the same shape:

import { ActorSystem, ... } from 'actor-ts';

// 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. Wait for processing (a small await or expect on a probe).
await new Promise(r => setTimeout(r, 100));

// 4. Print result + clean up.
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.