Examples - Übersicht

Das Framework liefert lauffähige Beispiele unter examples/ im Repo. Jedes ist eine voll funktionsfähige App, die du klonen und starten kannst.

Was mitgeliefert wird

Beispiel	Demonstriert
Chat-Sample	Cluster + DistributedPubSub + DistributedData + sharded persistente Chat-Room- / Direktnachrichten-Entities + HTTP/WS-Endpoint.
Voice-Sample	WebSocket + Receptionist + DistributedPubSub + DistributedData ORSets - ephemer konzipiert (kein Sharding, keine Persistenz).
Eigenständige Snippets	Häppchengroße Beispiele pro Konzept - Counter, Saga, Health, etc.

Für den ersten Kontakt mit actor-ts starte mit dem Quickstart - das ist ein 5-Minuten Hello-Actor. Danach das Chat- oder Voice-Sample für eine funktionierende Multi-Feature-App.

Ein Beispiel ausführen

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

# Abhängigkeiten einmalig im Repo-Root installieren:
bun install

# Chat-Sample starten - drei Terminals, in jedem derselbe Befehl:
bun examples/chat/backend/main.ts

Jedes Beispiel hat seine eigene README mit Setup-Schritten.

In CI abgesichert

Die Beispiele sind ein Gate, keine Dekoration. bun run test:examples startet jedes lauffähige Snippet als eigenen Prozess und prüft dessen Ausgabe; der examples-Workflow führt das bei jedem Push aus, der src/ oder examples/ berührt — eine Framework-Änderung, die ein Beispiel bricht, ist damit ein roter Check und nicht etwas, das erst ein Leser entdeckt.

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

Die Klassifikation liegt in tests/examples/examples.manifest.json. Jedes eigenständige Beispiel steht dort genau einmal, entweder als:

lauffähig — mit einem Teilstring seiner Ausgabe, der erscheinen muss. Exit-Code 0 allein genügt nicht: ein Snippet, dessen externe Abhängigkeit fehlt, kann seine eigentliche Arbeit verfehlen und trotzdem mit 0 enden.
übersprungen — mit dem Grund, warum es unbeaufsichtigt nicht laufen kann. Das sind die Fälle, die einen Docker-Broker (Kafka, NATS, MQTT), Cloud- oder Kubernetes-Zugangsdaten oder eine optionale Peer-Abhängigkeit brauchen, die das Repository nicht deklariert.

Der Runner schlägt fehl, sobald diese Liste und der Baum in irgendeine Richtung auseinanderlaufen — ein neues Beispiel aufzunehmen heißt also, sich für eine der beiden Kategorien zu entscheiden. Die beiden Anwendungs-Samples sind dabei: Chat- und Voice-Smoke-Test laufen beide im Gate und bringen jeweils ihr eigenes Backend mit.

Ein Beispiel auswählen

Wenn du sehen willst…

Cluster + Entities → Chat-Sample.
PersistentActor-Patterns → Chat-Sample.
Distributed Pub/Sub → Chat- oder Voice-Sample.
Receptionist + ephemere (CRDT-)Räume → Voice-Sample.
Broker-Integration (Kafka) → das Snippet examples/io/kafka-exactly-once.ts.
HTTP + WebSocket → beide Samples.
Ein einzelnes Konzept isoliert → eigenständige Snippets.

Die Beispiele lesen

Die Beispiele folgen ein paar Konventionen:

backend/actors/ - Actor-Klassen.
backend/main.ts - Einstiegspunkt; nur Verdrahtung (Cluster-Join, Extensions, Sharding, HTTP-Singleton).
backend/routes.ts - HTTP-Directive-DSL-Routen.
shared/ - mit den Frontends geteilter Code: protocol.ts (WS-Nachrichten-Typen), rooms.ts, users.ts.

Ein Beispiel zu lesen dauert ~30 Minuten für die ganze Architektur; schneller, wenn du das Framework schon kennst.

Beispiele beitragen

Wenn du etwas mit actor-ts baust und denkst, es würde anderen helfen - ein Saga-Workflow, eine Kafka-getriebene Analytics-Pipeline, ein Multi-Tenant-SaaS-Skeleton - PRs sind willkommen.

Beispiele, die aufgenommen werden:

Self-contained - laufen ohne externe Services außer Docker / Compose.
Dokumentiert - README mit was es tut + wie es funktioniert.
Realistisch - lösen ein echtes Problem (nicht nur “zeig dieses Feature”).

Wohin als Nächstes

Chat-Sample - Cluster + PubSub.
Voice-Sample - ephemeres Pub/Sub + Presence.
Eigenständige Snippets - Code pro Konzept.
Quickstart - die 5-Minuten-Einführung.