@lastshotlabs/slingshot-runtime-bun

npm install @lastshotlabs/slingshot-runtime-bun

Functions

bunRuntime

Creates a SlingshotRuntime implementation powered by the Bun runtime.

Provides the following capabilities using Bun’s built-in APIs:

• password — Bun.password.hash / Bun.password.verify (argon2id by default)
• sqlite — bun:sqlite Database (WAL mode, create: true)
• server — Bun.serve HTTP server with WebSocket upgrade support and optional TLS
• fs — Bun.write, Bun.file for async file I/O
• glob — Bun.Glob for file pattern scanning

Pass the returned runtime to createServer or createApp as the runtime option.

Remarks: This runtime is intended for use in Bun environments only. For Node.js, use nodeRuntime() from @lastshotlabs/slingshot-runtime-node.

Remarks: Signal handling: this runtime does not register SIGTERM or SIGINT handlers. Process lifecycle management belongs to the calling application — registering signal handlers from a library would conflict with consumers that already do so. Forgetting to register a handler results in hard-killed processes during deploy: in-flight requests are dropped, websocket clients receive 1006, and active SQLite transactions are rolled back. Always register handlers in production:

Remarks: ts const server = await createServer({ runtime: bunRuntime(), ...config }); const drain = async () => { try { await server.stop(); } finally { process.exit(0); } }; process.once('SIGTERM', drain); process.once('SIGINT', drain);

Remarks: Async error handling: the fetch handler is wrapped so async rejections are forwarded to opts.error (or logged with a 500 fallback if opts.error is omitted). Without this wrapper rejections from async middleware would bypass opts.error.

Remarks: WebSocket error handling: when opts.websocket is provided, every lifecycle callback (open, message, close, pong) is wrapped to log with phase context instead of crashing or being silently dropped by Bun.

function bunRuntime(options?: BunRuntimeOptions): BunSlingshotRuntime

Source: packages/runtime-bun/src/index.ts

configureRuntimeBunLogger

Replace the runtime’s structured logger. Pass null to reset to the default console-backed logger. Returns the previous logger so tests can save and restore state.

function configureRuntimeBunLogger(logger: RuntimeBunLogger | null): RuntimeBunLogger

Source: packages/runtime-bun/src/index.ts

configureRuntimeBunStructuredLogger

Replace the structured Logger used for process-safety-net events. Pass null to reset to the default JSON console logger. Returns the previous logger so tests can save and restore state.

function configureRuntimeBunStructuredLogger(logger: Logger | null): Logger

Source: packages/runtime-bun/src/index.ts

installProcessSafetyNet

Install once-per-process handlers for unhandledRejection and uncaughtException. Both are forwarded to the new structured Logger (and also surfaced via the legacy RuntimeBunLogger for tests that watch the older text-format hook). Fatal process events schedule a process exit after logging so production does not continue in an undefined state. Idempotent.

bunRuntime() calls this automatically by default — pass installProcessSafetyNet: false to opt out.

function installProcessSafetyNet(): void

Source: packages/runtime-bun/src/index.ts

resetProcessSafetyNetForTest

Reset process safety-net state for test isolation.

function resetProcessSafetyNetForTest(): void

Source: packages/runtime-bun/src/index.ts

runtimeCapabilities

Return a frozen capability descriptor for the Bun runtime platform.

This is a static report — all capabilities are true because Bun provides every runtime primitive natively (password hashing, SQLite, HTTP server, filesystem, glob, AsyncLocalStorage, and WebSocket).

function runtimeCapabilities(): BunRuntimeCapabilities

Source: packages/runtime-bun/src/index.ts

Classes

BunPasswordError

Raised when Bun password hashing or verification cannot complete safely.

Source: packages/runtime-bun/src/errors.ts

BunRuntimeError

Errors thrown by the Bun runtime implementation.

Source: packages/runtime-bun/src/errors.ts

BunServerError

Raised when the Bun runtime HTTP server cannot start or serve requests safely.

Source: packages/runtime-bun/src/errors.ts

BunSqliteError

Raised when Bun SQLite runtime operations fail.

Source: packages/runtime-bun/src/errors.ts

BunWebSocketError

Raised when Bun runtime WebSocket setup or delivery fails.

Source: packages/runtime-bun/src/errors.ts

Interfaces

BunRuntimeCapabilities

Programmatic capability report for the Bun runtime platform.

Consumers can use this to feature-detect at runtime without needing to instantiate a full runtime or catch errors from stubs.

All boolean capabilities reflect what the platform itself supports (not what an individual bunRuntime() caller configured). Since Bun exposes all major runtime primitives natively, every capability is true.

Source: packages/runtime-bun/src/index.ts

BunRuntimeOptions

Configuration for the Bun runtime.

Source: packages/runtime-bun/src/index.ts

BunRuntimeServerInstance

The server instance returned by the Bun runtime’s server.listen().

Narrows the core RuntimeServerInstance contract to what the Bun implementation actually provides: stop() always returns a promise, and upgrade() / publish() are always available (backed by Bun.serve).

Source: packages/runtime-bun/src/index.ts

BunSlingshotRuntime

The runtime returned by bunRuntime.

Narrows the core SlingshotRuntime contract to the Bun implementation’s concrete behavior: server.listen() returns synchronously (no promise) and glob.scan() always resolves to a string[].

Source: packages/runtime-bun/src/index.ts

RuntimeBunLogger

Structured logging hook for the Bun runtime. The runtime emits operational events (fetch handler errors, websocket handler errors) to the configured logger. Defaults to a console.error-backed implementation.

Pass a custom logger via configureRuntimeBunLogger to forward into pino, OpenTelemetry, etc.

Source: packages/runtime-bun/src/index.ts