Ir al contenido
Español

FAQ

Esta página aún no está disponible en tu idioma.

The framework is pre-1.0. The API surface is stable enough that we use it in real applications, but expect breaking changes until 1.0 ships. See Version policy.

What that means in practice:

  • The core actor model (Actor, mailboxes, dispatchers, supervision, persistence basics) is well-tested and stable.
  • Cluster features (sharding, singleton, distributed data) have working implementations but expect API polish.
  • Some edges are explicitly experimental — replicated event sourcing, sharded daemon process variants, etc. Pages flag these.

If you’re starting a new project where you’d ship before 1.0, it’s a reasonable bet. If you’re rewriting a critical system, wait or budget time for breaking-change adoption.

Why “actor-ts”? Why not just use a JVM actor framework or vanilla TS?

Section titled “Why “actor-ts”? Why not just use a JVM actor framework or vanilla TS?”

Three reasons:

  • First-class TypeScript types. Most existing actor toolkits target a different runtime (JVM, .NET, Erlang); porting their shape to TS loses the type-level benefits. actor-ts is designed for TypeScript-first ergonomics.
  • Runtime choice. Runs on Bun (primary), Node, and Deno — no JVM, no .NET, no separate runtime.
  • Cluster + persistence + observability built in, without the “wire it yourself from 8 libraries” tax that vanilla TS would charge.

If you don’t need clustering / persistence / supervision, vanilla Promise-based code is simpler and you should use it. Reach for actor-ts when the runtime-model benefits actually matter.

No. The framework targets server-side runtimes — Bun, Node, Deno — because most actor patterns (clustering, persistence, TCP transports, file-based journals) need server-side primitives. A subset could in theory run in the browser, but there’s no browser-mode build.

For browser-side reactive patterns, look at signals/effects libraries (Solid, MobX) — different model, better fit.

Both work; both run on the same engine. Pick:

  • Untyped if you’re learning the actor model, want one-to-one parity with classic actor-framework examples, or have an actor with substantial mutable state.
  • Typed if you want functional state-machine ergonomics, cast-free child spawning, or are coming from typed actor APIs on other runtimes / from Cats Effect.

You can mix them — typed parents spawn untyped children and vice versa. See Typed overview.

  • tell is the default. Fire-and-forget. Use unless you specifically need a reply.
  • ask when you need a Promise<Reply> — typically HTTP handlers, sagas, tests. Has overhead (temporary ref) so don’t use it in tight loops.
  • pipeTo when an async operation should land as a message in an actor’s mailbox. The non-blocking alternative to await inside onReceive.

See Ask pattern and Future patterns.

Pick by whether you need history:

  • PersistentActor persists every state-changing event. Replay to recover. Use when history matters (audit, time travel, projections, append-only domains).
  • DurableStateActor persists the current state snapshot, overwriting on each update. Use when the current value is all you need.

See Persistence overview.

  • Singleton — exactly one actor cluster-wide. Coordinators, schedulers, leader-elected services.
  • Sharding — one actor per key, distributed across nodes. Per-user sessions, per-IoT-device controllers.
  • DistributedData — eventually-consistent shared state via CRDTs. Counters, flags, sets that everyone reads and writes.

See the Distribution overviews.

In rough numbers (single Bun process, 4-core machine):

  • 100 000 actors is comfortable — minimal memory overhead per actor, sub-millisecond send latency.
  • 1 000 000 actors is feasible but tight on memory. Consider passivation patterns (idle entities stop themselves).
  • 10 000 000+ actors needs sharding across nodes — one node can’t hold that many efficiently.

The dominant cost is the actor’s own state, not the framework’s bookkeeping.

Measured on Bun 1.3.14, 10 cores of an Intel i9-12900K under Linux, mean of a hundred rounds, except where a bullet names its own machine — then that is the environment its figures come from. See Benchmarks for the methodology and the comparison against other frameworks:

  • tell, end to end — about 53 ns per message with a mailbox that has depth (roughly 19 million messages/second sustained). That is the cost of the whole path: enqueue, schedule, deliver, handle. The tell() call on its own returns faster still — it only enqueues — so “how long does tell take” and “how many messages per second” are different questions with answers an order of magnitude apart.
  • ask round trip — 0.9 µs at p50, depth 1.
  • Cross-cluster tell — about 22 µs per message, and about 245 µs per ask round trip, both harness means rather than p50s, over a real TcpTransport on loopback with the far node on a worker thread (Bun 1.4.2, Windows 11, 32 hardware threads, 2026-09-18; benchmarks/cluster/tcp-message-cost.ts, every batch completion-verified). That is the same per-message cost as the thread hop measured on the worker mesh page, so the socket is not where a cross-node message pays — the protocol is. Over a LAN the round trip is the network’s: ms-range.

A mailbox with depth is doing most of the work in that first figure, and the difference is worth understanding before designing around it. An actor handles a batch of queued messages per scheduling turn, so a deep mailbox amortises the wakeup across the batch. An actor answering one request at a time cannot amortise anything — its mailbox is empty between messages — which is why the ask round trip is measured in microseconds while a flooded tell is measured in hundreds of nanoseconds. Neither number is wrong; they describe different shapes of load.

What you are buying for that time is a queue, a scheduler, supervision and location transparency — none of which a direct method call does. Comparing the two as though they were alternatives is the reason the benchmarks no longer publish a “no framework” figure at all: it is not one of the options you are choosing between.

The number that is worth designing against: several million messages a second through one actor is reachable, a hundred million is not.

The framework doesn’t allocate aggressively, but it does allocate. Hot paths (tell, mailbox enqueue/dequeue) create envelopes per message; high-throughput actors can show in GC profiles.

For low-allocation hot paths:

  • Reuse message objects when safe (but only if the receiver doesn’t keep a reference).
  • Use MicrotaskDispatcher for compute-heavy actors that don’t share the event loop with HTTP I/O.

One node is valid. Cluster.join with no seeds (or unreachable seeds) gives you a singleton cluster — the local node auto-promotes to leader. Every cluster extension (sharding, singleton, pubsub) works in single-node mode.

This means you can develop and test cluster code without a Docker Compose setup.

Two layers:

  • Downing strategies that force a winner during partition — with one configured, the failure detector only parks a silent member, and the strategy decides who is removed. See Downing strategies, and Failure detector for what the cluster does without one.
  • Optional leases for sharding coordinator and singletons. See Singleton with lease.

Without a downing strategy — the default — the failure detector removes a member it has given up on itself, once it declares it down (down-after on the default detector; actor-ts.cluster.failure-detector.auto-down ships on), and the last available node takes over its shards and singletons. That is right for a crashed node and forks the cluster under a partition: every side removes the others at the same moment and carries on as a cluster of its own, and the two do not merge again when the network heals (issue #930). With two or more survivors, a removed member can also come back as unreachable for a while, when one survivor’s gossip still carries it after the other’s removal. So pick a strategy for production — lease-majority, or another one from Downing strategies.

auto-down = off is the opt-out: the member is parked at unreachable instead, its shards stay homed on it and its remote watchers get no Terminated, until an operator downs it (Cluster.down(address), or POST /cluster/down with actor-ts.management.enable-down-endpoint = on), a strategy is configured, or the node restarts on the same address, which ends the old run before the new one joins. A heartbeat brings a parked member back only after a pause — never after a symmetric partition, which leaves both sides parked and the cluster split until an operator acts. Parking does not keep the leader where it was, either: the leader is the first up member in a node’s view, so the members that can still reach each other elect another one, and a singleton without a role moves with it — under a partition, each side can end up hosting its own.

Can I use Kubernetes for cluster discovery?

Section titled “Can I use Kubernetes for cluster discovery?”

Yes — the kubernetes-api seed provider lists pods matching a label selector and uses them as seeds. See Discovery — Kubernetes API.

For lease-based singletons in K8s, the Kubernetes lease implementation uses K8s native Lease CRDs.

  • InMemoryJournal for tests and dev.
  • SqliteJournal for single-node production (best performance-to-simplicity ratio).
  • CassandraJournal when multiple nodes need to share the same event stream.
  • Custom when none of these fit — implement the Journal interface against your storage.

See Journals — In-memory and SQLite.

Use event adapters. Every event persists in a versioned envelope ({ _v, _t, _e }); the adapter’s upcast(stored, version) is called on read to migrate older versions to the current shape.

See Migration overview.

Each projection persists its own offset; if a projection crashes after processing event N but before persisting offset N, it’ll re-process N on restart. In that sense, at-least-once. A projection with a grouped handler (handleGroup) persists its offset once per group, so what it re-processes is the whole group that contained N.

For exactly-once semantics, the projection must be idempotent (use the event’s seqNr as a dedup key) or transactional (commit the view + offset atomically). See Projections.

The framework itself builds and typechecks with TypeScript 7 (the native compiler); the published types are consumable from TypeScript 5.6+ (the typescript peer-dependency range is ^5.6 || ^6 || ^7). Earlier versions may work but aren’t supported.

It’s the cleanest way we found to express match().exhaustive() in TS — the discriminated-union dispatch pattern is everywhere in the codebase and a hand-rolled switch loses the exhaustiveness check.

It’s installed automatically alongside actor-ts, so there’s nothing extra to add. See Pattern matching.

Bun if you can. Faster startup, faster cold paths, native SQLite, native test runner. We test Bun as the primary runtime.

Node is fully supported as a fallback. Some performance is left on the table compared to Bun, but the feature surface is identical.

Deno is supported but receives less testing — file a bug if you hit a Deno-specific issue.

See Runtime — Compatibility matrix.

Is this an actor framework from another runtime, in TypeScript?

Section titled “Is this an actor framework from another runtime, in TypeScript?”

Spiritually yes — the actor model, supervision, sharding, persistence, distributed data, the cluster gossip protocol all have prior art on the JVM (Akka, Pekko) and .NET (Orleans), and the framework draws from that lineage. See the migration guides for the closest concept-by-concept maps.

Differences from the JVM-style actor toolkits:

  • No Scala / JVM — pure TypeScript, runs on JS runtimes.
  • No fiber-based concurrency — JavaScript is single-threaded per process; we use the microtask/macrotask queue.
  • No streaming DSL — backpressure-driven async pipelines aren’t ported. Use a separate library for that.
  • Smaller surface — only the actor-model parts. HTTP routing, persistence-query, and broker integrations have analogs but are intentionally simpler than the JVM counterparts.

If you need exact behavioural compatibility with another framework, use that framework. This is a TypeScript-first port that picks the most-useful 80% of the actor-model toolkit.

Orleans actors are virtual — addressed by ID, auto-spawned on first message, auto-passivated when idle. actor-ts sharding is the closest analog (see Sharding overview). Differences:

  • Sharding entities are not virtual by default — they’re passivated explicitly (or by idle timeout).
  • Sharded entity placement is one-actor-per-key, like Orleans grains, but the placement strategy is hash-mod-region by default, not Orleans’s directory-based.

Migration guide: from-orleans.