`options`

(no submodules)

Purpose

The options module declares the public configuration surface accepted by createBunSseEngine and exposes resolveOptions, a Zod-backed validator that applies every documented default and fails fast on misconfigured input. Splitting this from the engine module lets the engine focus on stream lifetime while options handle validation, defaults, and the runtime-vs-config split (the broker and authenticator are runtime values and bypass the schema; the primitive knobs go through Zod).

Features

Zod-validated primitive knobs: buffer size, buffer ttl, keep-alive cadence, per-tenant cap, max event bytes, compression on/off, retry ms.
SseAuthenticator hook signature for handshake-time auth bridge.
SseHandshakeRequest minimal request view (headers, url, method) so unit tests can inject synthesised values without a live socket.
Fully defaulted ResolvedBunSseEngineOptions view consumed downstream.
DEFAULT_MAX_EVENT_BYTES = 64 KiB exposed so callers can reason about the cap without redeclaring it.

Usage: Basic

import { resolveOptions } from "@suaveplan/api-sse-bun";

const resolved = resolveOptions({
    authenticate: async () => ({
        tenantId: "acme" as never,
        principal: null,
    }),
});
console.log(resolved.eventBufferSize); // 256

Usage: Advanced

import { resolveOptions } from "@suaveplan/api-sse-bun";

const resolved = resolveOptions({
    eventBufferSize: 1024,
    eventBufferMs: 600_000,
    keepAliveCommentMs: 30_000,
    maxConnectionsPerTenant: 2_000,
    compressionEnabled: false,
    retryMs: 5_000,
    authenticate: async (req) => {
        const token = req.headers.get("authorization") ?? "";
        if (token === "") {
            return { tenantId: null, principal: null };
        }
        return {
            tenantId: "acme" as never,
            principal: null,
            topics: ["billing", "audit"],
        };
    },
});

API Reference

interface BunSseEngineOptions — public options bundle; every primitive field is optional, the authenticate hook is required.
interface ResolvedBunSseEngineOptions — fully-defaulted view; primitive fields are non-optional.
interface SseAuthenticationResult — { tenantId, principal, topics? }.
type SseAuthenticator = (req) => SseAuthenticationResult | Promise<…>.
interface SseHandshakeRequest — minimal { headers, url, method }.
function resolveOptions(options): ResolvedBunSseEngineOptions — Zod-parses primitives, applies defaults, throws SSE_BUN.HANDSHAKE_REJECTED on invalid input.
const DEFAULT_MAX_EVENT_BYTES = 65_536.

Implementation Notes

The Zod schema deliberately accepts only the primitive knobs. Runtime values (authenticate, broker, clock, plugin) bypass schema validation because Zod cannot meaningfully describe a function or an external broker. The schema uses .strict() so a misspelled option key fails at boot rather than silently using a default. Defaults are pinned to match api-ws-bun's reconnect window so a deployment running both engines exhibits the same buffer-life surface to clients on either transport.

3.2 KiB Raw Blame History

options