Eigenständige Snippets

Wenn du ein Konzept isoliert sehen willst, sind die eigenständigen Snippets der richtige Ort. Jedes ist eine einzelne Datei, die ein Pattern demonstriert - kein Docker, keine Peers, lauffähig mit bun.

Zu finden in examples/ im Repo - die grundlegenden liegen auf oberster Ebene, der Rest in themenbezogenen Unterverzeichnissen (patterns/, persistence/, cluster/, fsm/, pubsub/, crdt/, typed/, management/, …).

Was es gibt

Datei	Konzept
hello-world.ts	Der minimale Actor - extends Actor, behandelt eine Nachricht.
ping-pong.ts	Zwei Actors, die eine Nachricht hin- und herspielen.
bank-account.ts	Request/Response via ask-Pattern.
supervision.ts	Eigene Strategie mit decideBy.
become.ts	context.become(...) für State-Übergänge.
death-watch.ts	Terminated-Benachrichtigungen via Death Watch.
router.ts	Lokaler Pool-Router, Round-Robin über Worker.
scheduler.ts	scheduleOnce / scheduleAtFixedRate.
patterns/timers-heartbeat.ts	Actor-eigene context.timers.
patterns/stash-init.ts	Stash + Replay während async Initialisierung.
patterns/circuit-breaker-hello.ts	CircuitBreaker um einen fehleranfälligen Call.
patterns/backoff-supervisor.ts	Exponentielles Backoff-Restart.
typed/behaviors-receive.ts	Derselbe Counter via typisierte Behaviors-DSL.
typed/behaviors-supervise.ts	setup / withTimers / supervise kombiniert.
fsm/traffic-light.ts	FSM-DSL - when / onEnter / onTransition.
fsm/order-workflow.ts	Mehrstufige PersistentFSM (Saga).
persistence/bank-account.ts	Event-Sourced Actor - persist, recover, Snapshot.
persistence/durable-state-kv.ts	Durable-State-Persistenz (Snapshot-Stil).
persistence/projection-bank-statement.ts	Read-Side-View via ProjectionActor.
persistence/replicated-counter.ts	Multi-Master-repliziertes Event-Sourcing.
cluster/singleton-hello.ts	Cluster-Singleton mit Manager + Proxy.
cluster/sharded-daemon-hello.ts	Sharded Daemon Process - N Worker nach Index.
pubsub/chat-mediator.ts	DistributedPubSub auf einem einzelnen Node.
pubsub/event-bus-across-nodes.ts	Themenbasierter Event-Bus über Nodes.
crdt/shopping-cart-orset.ts	OR-Set-CRDT - Add-Wins bei nebenläufigen Änderungen.
management/health-endpoint.ts	/health + /cluster/members-Endpoints.
management/prometheus-endpoint.ts	/metrics Prometheus-Exposition.

Jedes Snippet ist 50-200 Zeilen. Liest sich in ein paar Minuten; verändere es, um mit dem Konzept zu spielen.

Ausführen

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

bun install
bun examples/hello-world.ts

Die meisten Snippets laufen bis zum Ende und beenden sich. Die unter examples/http/ sowie die Prometheus- und Kubernetes-Probe-Snippets sind stattdessen Server — sie binden einen Port und bleiben oben, bis du sie stoppst; genau darum geht es bei diesen Snippets.

Für cluster-bezogene Snippets (Singleton, Sharding, PubSub, DD) nutzen die Snippets MultiNodeSpec, um einen Cluster innerhalb eines Prozesses zu simulieren - kein Docker nötig.

Eine Handvoll braucht doch etwas Externes: die Broker-Snippets unter examples/io/ wollen Kafka, NATS oder MQTT (samt der passenden optionalen Peer-Abhängigkeit), und examples/coordination/k8s-lease-singleton.ts will einen Kubernetes-API-Server. Jedes davon benennt beim Ausführen, was ihm fehlt.

In CI abgesichert

Jedes Snippet auf dieser Seite wird vom Beispiel-Gate bei jedem Push ausgeführt, der src/ oder examples/ berührt — eine Framework-Änderung, die eines bricht, ist damit ein roter Check:

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

Jedes ist genau einmal in tests/examples/examples.manifest.json klassifiziert — lauffähig mit einer Ausgabe-Zusicherung oder übersprungen mit Begründung. Die Übersprungenen sind die, die einen Broker, Kubernetes oder eine nicht deklarierte optionale Peer-Abhängigkeit brauchen; in dieser Datei steht, welche das sind und warum. Ein neues Snippet aufzunehmen heißt, seinen Eintrag mitzuliefern — sonst schlägt das Gate wegen der Abweichung fehl.

Patterns

Die meisten Snippets folgen demselben Aufbau:

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

// 1. System + Actors aufsetzen.
const system = ActorSystem.create('demo');
const ref = system.spawnAnonymous(MyActor);

// 2. Ein paar Nachrichten senden.
ref.tell({ ... });
ref.tell({ ... });

// 3. Ergebnis ausgeben + aufräumen.  `terminate()` leert zuerst die
//    Mailboxen, es gibt also nichts, wofür man schlafen müsste —
//    außer das Snippet wartet auf einen Timer oder ein nicht
//    awaitetes Promise, denen der Drain nicht folgt.
console.log(...);
await system.terminate();

Für komplexere Flows (Cluster, Persistenz) nutzen die Snippets TestKit + TestProbe für sauberes Teardown.

Anpassen

Snippets sind der einfachste Ort zum Experimentieren:

# Kopieren, editieren, ausführen:
cp examples/hello-world.ts examples/my-experiment.ts
# examples/my-experiment.ts editieren
bun examples/my-experiment.ts

Das Framework wird über das actor-ts-Package des lokalen Repos eingebunden - deine Edits laufen gegen die Live-Quelle.

Snippets beitragen

Wenn du ein cleveres Pattern erarbeitet hast, stelle einen PR mit einem Snippet. Kriterien:

• Eine Datei, ≤ 200 Zeilen.
• Ein Konzept klar demonstriert.
• Self-contained - lauffähig ohne externe Services.
• Kommentare, die erklären, was der Code zeigt.

Lege sie für ein grundlegendes Konzept auf oberster Ebene von examples/ ab, sonst im passenden themenbezogenen Unterverzeichnis; füge dann eine Zeile zur obigen Tabelle hinzu.

Wohin als Nächstes

• Examples - Übersicht - größere lauffähige Apps.
• Quickstart - die 5-Minuten-Einführung.
• Fundamentals - Übersicht - die Konzept-Landkarte.