Aller au contenu
actor-ts
Français

Bun

Ce contenu n’est pas encore disponible dans votre langue.

Bun is the primary runtime actor-ts targets. Tested first; performance benchmarks run against Bun; the docs assume Bun by default.

Why Bun

Section titled “Why Bun”
ReasonDetail
Fast startup~3-5× faster cold start vs Node.
Built-in SQLitebun:sqlite — no peer deps.
Built-in test runnerbun:test — works for the framework’s tests + your own.
Native HTTP / WebSocketBun.serve for production-grade HTTP.
Fewer peer depsBun replaces ws, better-sqlite3, and several others.

Installation

Section titled “Installation”
Terminal window
curl -fsSL https://bun.sh/install | bash
# or via Homebrew: brew install oven-sh/bun/bun

Check:

Terminal window
bun --version    # need 1.1+

For Docker:

FROM oven/bun:1.1
WORKDIR /app
COPY . .
RUN bun install
CMD ["bun", "run", "dist/main.js"]

Creating a project

Section titled “Creating a project”
Terminal window
bun init
bun add actor-ts
bun add ts-pattern    # peer dep used by the framework's examples

For specific protocol actors:

Terminal window
bun add kafkajs       # for KafkaActor
bun add mqtt          # for MqttActor
bun add amqplib       # for AmqpActor
bun add nats          # for NatsActor / JetStreamActor
bun add redis         # for RedisStreamsActor
bun add @grpc/grpc-js @grpc/proto-loader   # for GrpcActor

Most peer deps you skip unless using that specific protocol.

Running tests

Section titled “Running tests”
Terminal window
bun test

Bun’s test runner is drop-in compatible with Jest’s API (describe / it / expect). TestKit works directly:

import { describe, it, beforeEach, afterEach } from 'bun:test';
import { TestKit } from 'actor-ts/testkit';


describe('Counter', () => {
  let tk: TestKit;
  beforeEach(() => { tk = TestKit.create(); });
  afterEach(async () => { await tk.shutdown(); });


  it('increments', async () => {
    // ...
  });
});

For Bun-specific test features, see the Bun docs.

SQLite on Bun

Section titled “SQLite on Bun”
import { SqliteJournal } from 'actor-ts';


// Bun auto-detects bun:sqlite — no driver setup needed.
new SqliteJournal({ path: '/var/lib/events.db' });

bun:sqlite is a built-in. No better-sqlite3 install required.

TCP + HTTP

Section titled “TCP + HTTP”

Bun has native APIs for both, but the framework picks them automatically via runtime detection. No config needed.

For HTTP backend, the lightest option is HonoBackend, which Hono builds on the WHATWG fetch adapter Bun already exposes:

import { HonoBackend } from 'actor-ts/http';


await http.newServerAt('0.0.0.0', 8080)
  .useBackend(new HonoBackend())
  .bind(routes);

Hono is fast on Bun and tree-shakes to a tiny bundle. For the broader Node ecosystem (Fastify plugins, middleware), stick with the default Fastify backend.

Performance on Bun

Section titled “Performance on Bun”

Rough numbers (single Bun process, M-series Mac):

  • Tell throughput: ~10M msgs/sec on MicrotaskDispatcher.
  • HTTP throughput: ~150K req/sec for trivial routes.
  • SQLite append throughput: ~50K events/sec.

Bun consistently wins on startup time (sub-100ms vs Node’s ~300-500ms). Helpful for fast test iteration.

Bun-specific limitations

Section titled “Bun-specific limitations”

Where to next

Section titled “Where to next”