@fishenv/http 0.0.0-stage → 0.0.2

package/dist/sse/encode.d.ts

@@ -0,0 +1,10 @@
+/** SSE wire format — turning values into `text/event-stream` frames. */
+import type { SseEventOptions } from "./types.ts";
+/** Field values are attacker-reachable; CR/LF/NUL would forge extra frames. */
+export declare function sanitizeField(value: string): string;
+/** Serialize a value into a complete SSE frame (including the terminating blank line). */
+export declare function encodeSseEvent(data: unknown, opts?: SseEventOptions): string;
+/** A standalone `retry:` frame, sent without any accompanying data. */
+export declare function encodeSseRetry(ms: number): string;
+/** A comment frame — invisible to `EventSource`, used as a heartbeat. */
+export declare function encodeSseComment(text: string): string;

package/dist/sse/encode.js

@@ -0,0 +1,27 @@
+/** SSE wire format — turning values into `text/event-stream` frames. */
+/** Field values are attacker-reachable; CR/LF/NUL would forge extra frames. */
+export function sanitizeField(value) {
+    return value.replace(/[\r\n\0]/g, "");
+}
+/** Serialize a value into a complete SSE frame (including the terminating blank line). */
+export function encodeSseEvent(data, opts) {
+    let frame = "";
+    if (opts?.id != null)
+        frame += `id: ${sanitizeField(opts.id)}\n`;
+    if (opts?.event != null)
+        frame += `event: ${sanitizeField(opts.event)}\n`;
+    if (opts?.retry != null)
+        frame += `retry: ${Math.trunc(opts.retry)}\n`;
+    const text = typeof data === "string" ? data : (JSON.stringify(data) ?? "");
+    for (const line of text.split(/\r\n|\r|\n/))
+        frame += `data: ${line}\n`;
+    return `${frame}\n`;
+}
+/** A standalone `retry:` frame, sent without any accompanying data. */
+export function encodeSseRetry(ms) {
+    return `retry: ${Math.trunc(ms)}\n\n`;
+}
+/** A comment frame — invisible to `EventSource`, used as a heartbeat. */
+export function encodeSseComment(text) {
+    return `: ${sanitizeField(text)}\n\n`;
+}

package/dist/sse/hub.d.ts

@@ -0,0 +1,33 @@
+/** Keyed registry of live connections — the seam for targeted (non-broadcast) sends. */
+import type { SseConnection } from "./connection.ts";
+import type { SseEventOptions, SseHubOptions } from "./types.ts";
+/**
+ * Connections keyed by an application identifier (user id, tenant id, document
+ * id…). One key maps to many connections.
+ *
+ * Subclass it to get a DI token:
+ * ```ts
+ * class UserEvents extends SseHub {}
+ * ```
+ */
+export declare class SseHub {
+    #private;
+    constructor(options?: SseHubOptions);
+    /** Register a connection. Returns an unregister fn; also auto-removes on close. */
+    add(key: string, connection: SseConnection): () => void;
+    /** Push to every connection registered under `key`. Returns local delivery count. */
+    send(key: string, data: unknown, opts?: SseEventOptions): number;
+    /** Push to every connection under any of `keys`. Returns local delivery count. */
+    sendMany(keys: Iterable<string>, data: unknown, opts?: SseEventOptions): number;
+    /** Push to every connection in this hub. Returns local delivery count. */
+    broadcast(data: unknown, opts?: SseEventOptions): number;
+    /** Close every connection under `key`. Returns how many were closed. */
+    close(key: string): number;
+    /** Close every connection and detach the transport subscription. */
+    closeAll(): void;
+    has(key: string): boolean;
+    /** Connection count for `key`, or the hub total when `key` is omitted. */
+    count(key?: string): number;
+    keys(): string[];
+    connections(key: string): SseConnection[];
+}

package/dist/sse/hub.js

@@ -0,0 +1,133 @@
+/** Keyed registry of live connections — the seam for targeted (non-broadcast) sends. */
+/**
+ * Connections keyed by an application identifier (user id, tenant id, document
+ * id…). One key maps to many connections.
+ *
+ * Subclass it to get a DI token:
+ * ```ts
+ * class UserEvents extends SseHub {}
+ * ```
+ */
+export class SseHub {
+    #byKey = new Map();
+    #nodeId = crypto.randomUUID();
+    #transport;
+    #unsubscribe;
+    constructor(options = {}) {
+        this.#transport = options.transport;
+        this.#unsubscribe = options.transport?.subscribe((message) => {
+            if (message.origin === this.#nodeId)
+                return;
+            this.#deliver(message.key, message.data, {
+                event: message.event,
+                id: message.id,
+                retry: message.retry,
+            });
+        });
+    }
+    /** Register a connection. Returns an unregister fn; also auto-removes on close. */
+    add(key, connection) {
+        let set = this.#byKey.get(key);
+        if (set == null) {
+            set = new Set();
+            this.#byKey.set(key, set);
+        }
+        set.add(connection);
+        const remove = () => {
+            const current = this.#byKey.get(key);
+            if (current == null)
+                return;
+            current.delete(connection);
+            if (current.size === 0)
+                this.#byKey.delete(key);
+        };
+        connection.onClose(remove);
+        return remove;
+    }
+    /** Push to every connection registered under `key`. Returns local delivery count. */
+    send(key, data, opts) {
+        this.#publish(key, data, opts);
+        return this.#deliver(key, data, opts);
+    }
+    /** Push to every connection under any of `keys`. Returns local delivery count. */
+    sendMany(keys, data, opts) {
+        let delivered = 0;
+        for (const key of keys)
+            delivered += this.send(key, data, opts);
+        return delivered;
+    }
+    /** Push to every connection in this hub. Returns local delivery count. */
+    broadcast(data, opts) {
+        this.#publish(null, data, opts);
+        return this.#deliver(null, data, opts);
+    }
+    /** Close every connection under `key`. Returns how many were closed. */
+    close(key) {
+        const set = this.#byKey.get(key);
+        if (set == null)
+            return 0;
+        const connections = [...set];
+        for (const connection of connections)
+            connection.close();
+        return connections.length;
+    }
+    /** Close every connection and detach the transport subscription. */
+    closeAll() {
+        for (const set of [...this.#byKey.values()]) {
+            for (const connection of [...set])
+                connection.close();
+        }
+        this.#byKey.clear();
+        this.#unsubscribe?.();
+        this.#unsubscribe = undefined;
+    }
+    has(key) {
+        return (this.#byKey.get(key)?.size ?? 0) > 0;
+    }
+    /** Connection count for `key`, or the hub total when `key` is omitted. */
+    count(key) {
+        if (key != null)
+            return this.#byKey.get(key)?.size ?? 0;
+        let total = 0;
+        for (const set of this.#byKey.values())
+            total += set.size;
+        return total;
+    }
+    keys() {
+        return [...this.#byKey.keys()];
+    }
+    connections(key) {
+        return [...(this.#byKey.get(key) ?? [])];
+    }
+    #deliver(key, data, opts) {
+        const targets = key == null
+            ? [...this.#byKey.values()].flatMap((set) => [...set])
+            : [...(this.#byKey.get(key) ?? [])];
+        let delivered = 0;
+        for (const connection of targets) {
+            if (connection.send(data, opts))
+                delivered++;
+        }
+        return delivered;
+    }
+    #publish(key, data, opts) {
+        if (this.#transport == null)
+            return;
+        try {
+            const result = this.#transport.publish({
+                key,
+                data,
+                event: opts?.event,
+                id: opts?.id,
+                retry: opts?.retry,
+                origin: this.#nodeId,
+            });
+            if (result instanceof Promise) {
+                result.catch((err) => console.error("[fishenv.sse] transport publish failed:", err));
+            }
+        }
+        catch (err) {
+            console.error("[fishenv.sse] transport publish failed:", err);
+        }
+    }
+}

package/dist/sse/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Server-Sent Events for `@fishenv/http`.
+ *
+ * An SSE route is an ordinary `GET` route whose handler returns a streaming
+ * `Response`, so middleware, path-param validation, interceptors and the error
+ * chain all work unchanged — no core dispatch branching is required.
+ *
+ * Live connections can be registered in an {@link SseHub} so that any service
+ * can push to a specific client later:
+ *
+ * ```ts
+ * class UserEvents extends SseHub {}
+ *
+ * api.sse("/events").keepalive(30_000).subscribe(UserEvents, ({ ctx }) => ctx.user.id);
+ *
+ * // elsewhere, e.g. inside a use case
+ * userEvents.send(userId, { type: "order.shipped" }, { event: "notification" });
+ * ```
+ *
+ * Module layout:
+ * - `types.ts`         — shared data types
+ * - `encode.ts`        — `text/event-stream` framing
+ * - `connection.ts`    — `SseConnection`, a single live stream
+ * - `response.ts`      — `createSseResponse()`, request → streaming response
+ * - `hub.ts`           — `SseHub`, keyed registry for targeted sends
+ * - `route-builder.ts` — `SseRouteBuilder`
+ * - `router.ts`        — `withSse()` mixin
+ */
+export { SseConnection } from "./connection.ts";
+export { encodeSseComment, encodeSseEvent, encodeSseRetry } from "./encode.ts";
+export { SseHub } from "./hub.ts";
+export type { SseOpenFn } from "./response.ts";
+export { createSseResponse } from "./response.ts";
+export type { SseHandlerArgs, SseHandlerFn } from "./route-builder.ts";
+export { SseRouteBuilder } from "./route-builder.ts";
+export type { SseRouter } from "./router.ts";
+export { withSse } from "./router.ts";
+export type { SseCleanupFn, SseConnectionOptions, SseEventOptions, SseHubOptions, SseOverflowPolicy, SseTransport, SseTransportMessage, } from "./types.ts";

package/dist/sse/index.js

@@ -0,0 +1,40 @@
+/**
+ * Server-Sent Events for `@fishenv/http`.
+ *
+ * An SSE route is an ordinary `GET` route whose handler returns a streaming
+ * `Response`, so middleware, path-param validation, interceptors and the error
+ * chain all work unchanged — no core dispatch branching is required.
+ *
+ * Live connections can be registered in an {@link SseHub} so that any service
+ * can push to a specific client later:
+ *
+ * ```ts
+ * class UserEvents extends SseHub {}
+ *
+ * api.sse("/events").keepalive(30_000).subscribe(UserEvents, ({ ctx }) => ctx.user.id);
+ *
+ * // elsewhere, e.g. inside a use case
+ * userEvents.send(userId, { type: "order.shipped" }, { event: "notification" });
+ * ```
+ *
+ * Module layout:
+ * - `types.ts`         — shared data types
+ * - `encode.ts`        — `text/event-stream` framing
+ * - `connection.ts`    — `SseConnection`, a single live stream
+ * - `response.ts`      — `createSseResponse()`, request → streaming response
+ * - `hub.ts`           — `SseHub`, keyed registry for targeted sends
+ * - `route-builder.ts` — `SseRouteBuilder`
+ * - `router.ts`        — `withSse()` mixin
+ */
+// Connection
+export { SseConnection } from "./connection.js";
+// Framing
+export { encodeSseComment, encodeSseEvent, encodeSseRetry } from "./encode.js";
+// Hub
+export { SseHub } from "./hub.js";
+// Response
+export { createSseResponse } from "./response.js";
+// Route builder
+export { SseRouteBuilder } from "./route-builder.js";
+// Router mixin
+export { withSse } from "./router.js";

package/dist/sse/response.d.ts

@@ -0,0 +1,10 @@
+/** Turning a request into a streaming `text/event-stream` response. */
+import { SseConnection } from "./connection.ts";
+import type { SseCleanupFn, SseConnectionOptions } from "./types.ts";
+export type SseOpenFn = (sse: SseConnection) => void | SseCleanupFn | Promise<void | SseCleanupFn>;
+/**
+ * `onOpen` runs after the response has been handed to the client, so anything
+ * it throws can no longer change the status code — it is logged and the stream
+ * is closed.
+ */
+export declare function createSseResponse(req: Request, options: SseConnectionOptions, onOpen: SseOpenFn): Response;

package/dist/sse/response.js

@@ -0,0 +1,50 @@
+/** Turning a request into a streaming `text/event-stream` response. */
+import { DEFAULT_HIGH_WATER_MARK, SseConnection } from "./connection.js";
+/**
+ * `onOpen` runs after the response has been handed to the client, so anything
+ * it throws can no longer change the status code — it is logged and the stream
+ * is closed.
+ */
+export function createSseResponse(req, options, onOpen) {
+    const highWaterMark = options.highWaterMark ?? DEFAULT_HIGH_WATER_MARK;
+    let connection;
+    const stream = new ReadableStream({
+        start(controller) {
+            const sse = new SseConnection(controller, req, options);
+            connection = sse;
+            if (options.retryMs != null)
+                sse.retry(options.retryMs);
+            if (options.keepaliveMs != null && options.keepaliveMs > 0) {
+                const timer = setInterval(() => sse.comment("ka"), options.keepaliveMs);
+                sse.onClose(() => clearInterval(timer));
+            }
+            // Not awaited: a handler that never resolves must not block the stream.
+            void (async () => {
+                try {
+                    const cleanup = await onOpen(sse);
+                    if (typeof cleanup === "function")
+                        sse.onClose(cleanup);
+                }
+                catch (err) {
+                    console.error("[fishenv.sse] handler error after stream start:", err);
+                    sse.close();
+                }
+            })();
+        },
+        cancel() {
+            // Sole disconnect signal: `req.signal` semantics differ between
+            // runtimes (some abort it on *successful* delivery), which would tear
+            // down healthy streams.
+            connection?.close();
+        },
+    }, new ByteLengthQueuingStrategy({ highWaterMark }));
+    return new Response(stream, {
+        status: 200,
+        headers: {
+            "content-type": "text/event-stream; charset=utf-8",
+            // `no-transform` stops proxies (and server-side compression) from buffering.
+            "cache-control": "no-cache, no-store, no-transform",
+            "x-accel-buffering": "no",
+        },
+    });
+}

package/dist/sse/route-builder.d.ts

@@ -0,0 +1,44 @@
+/** Fluent builder for SSE routes, layered on the core `RouteBuilder`. */
+import type { AnySchema, DIContainer, FinishedRoute, InputOptions, MergeParam, MiddlewareFn, RouteBuilder, RouteMeta } from "../core/index.ts";
+import type { SseConnection } from "./connection.ts";
+import type { SseHub } from "./hub.ts";
+import type { SseCleanupFn, SseConnectionOptions, SseOverflowPolicy } from "./types.ts";
+export interface SseHandlerArgs<Ctx extends Record<string, unknown>, Params extends Record<string, unknown>> {
+    sse: SseConnection;
+    path: Params;
+    ctx: Ctx;
+    req: Request;
+    container: DIContainer;
+}
+export type SseHandlerFn<Ctx extends Record<string, unknown>, Params extends Record<string, unknown>> = (args: SseHandlerArgs<Ctx, Params>) => void | SseCleanupFn | Promise<void | SseCleanupFn>;
+/**
+ * Delegates to the core `RouteBuilder`, so `.param()` / `.with()` carry exactly
+ * the same generics as HTTP routes.
+ */
+export declare class SseRouteBuilder<RouterCtx extends Record<string, unknown>, RouteCtx extends Record<string, unknown>, Params extends Record<string, unknown>> {
+    #private;
+    constructor(inner: RouteBuilder<RouterCtx, RouteCtx, "none", InputOptions<"none">, Params, undefined>, options?: SseConnectionOptions);
+    meta(data: RouteMeta): this;
+    /** Heartbeat interval. Also how the server notices a socket died. */
+    keepalive(intervalMs: number): this;
+    /** Reconnection delay hint sent to the client on connect. */
+    retry(ms: number): this;
+    backpressure(opts: {
+        highWaterMark?: number;
+        onOverflow?: SseOverflowPolicy;
+    }): this;
+    param<Name extends string & keyof Params, S extends AnySchema>(name: Name, schema: S): SseRouteBuilder<RouterCtx, RouteCtx, MergeParam<Params, Name, S>>;
+    with<NewCtx extends Record<string, unknown>>(mw: MiddlewareFn<RouterCtx & RouteCtx, NewCtx>): SseRouteBuilder<RouterCtx, RouteCtx & NewCtx, Params>;
+    /**
+     * Terminal. The returned function (if any) runs when the connection closes.
+     *
+     * `.catch()` on the result only covers failures raised *before* the stream
+     * opens (middleware, param validation) — after that the status is already sent.
+     */
+    handle(fn: SseHandlerFn<RouterCtx & RouteCtx, Params>): FinishedRoute;
+    /**
+     * Terminal shorthand: resolve a hub from the container and register the
+     * connection under the key derived from the request.
+     */
+    subscribe<H extends SseHub>(token: abstract new (...args: any[]) => H, key: (args: SseHandlerArgs<RouterCtx & RouteCtx, Params>) => string): FinishedRoute;
+}

package/dist/sse/route-builder.js

@@ -0,0 +1,65 @@
+/** Fluent builder for SSE routes, layered on the core `RouteBuilder`. */
+import { createSseResponse } from "./response.js";
+/**
+ * Delegates to the core `RouteBuilder`, so `.param()` / `.with()` carry exactly
+ * the same generics as HTTP routes.
+ */
+export class SseRouteBuilder {
+    #inner;
+    #options;
+    constructor(inner, options = {}) {
+        this.#inner = inner;
+        this.#options = options;
+    }
+    meta(data) {
+        this.#inner.meta(data);
+        return this;
+    }
+    /** Heartbeat interval. Also how the server notices a socket died. */
+    keepalive(intervalMs) {
+        this.#options.keepaliveMs = intervalMs;
+        return this;
+    }
+    /** Reconnection delay hint sent to the client on connect. */
+    retry(ms) {
+        this.#options.retryMs = ms;
+        return this;
+    }
+    backpressure(opts) {
+        if (opts.highWaterMark != null) {
+            this.#options.highWaterMark = opts.highWaterMark;
+        }
+        if (opts.onOverflow != null)
+            this.#options.onOverflow = opts.onOverflow;
+        return this;
+    }
+    param(name, schema) {
+        return new SseRouteBuilder(this.#inner.param(name, schema), {
+            ...this.#options,
+        });
+    }
+    with(mw) {
+        return new SseRouteBuilder(this.#inner.with(mw), { ...this.#options });
+    }
+    /**
+     * Terminal. The returned function (if any) runs when the connection closes.
+     *
+     * `.catch()` on the result only covers failures raised *before* the stream
+     * opens (middleware, param validation) — after that the status is already sent.
+     */
+    handle(fn) {
+        const options = { ...this.#options };
+        const route = this.#inner.handle(({ req, path, ctx, container }) => createSseResponse(req, options, (sse) => fn({ sse, path, ctx, req, container })));
+        route.definition.kind = "sse";
+        return route;
+    }
+    /**
+     * Terminal shorthand: resolve a hub from the container and register the
+     * connection under the key derived from the request.
+     */
+    subscribe(
+    // biome-ignore lint/suspicious/noExplicitAny: intentional any
+    token, key) {
+        return this.handle((args) => args.container.get(token).add(key(args), args.sse));
+    }
+}

package/dist/sse/router.d.ts

@@ -0,0 +1,11 @@
+/** The `withSse()` mixin that adds `.sse()` to a core `Router`. */
+import type { BasePathParams, Router } from "../core/index.ts";
+import { SseRouteBuilder } from "./route-builder.ts";
+export interface SseRouter<Ctx extends Record<string, unknown>> {
+    sse<P extends string>(path: P): SseRouteBuilder<Ctx, Record<never, never>, BasePathParams<P>>;
+}
+/**
+ * `.use()` returns a *new* router, so apply `withSse` last:
+ * `withSse(r({ prefix: "/api" }).use(auth))`.
+ */
+export declare function withSse<Ctx extends Record<string, unknown>, Req extends Record<string, unknown> = Record<never, never>>(router: Router<Ctx, Req>): Router<Ctx, Req> & SseRouter<Ctx>;

package/dist/sse/router.js

@@ -0,0 +1,16 @@
+/** The `withSse()` mixin that adds `.sse()` to a core `Router`. */
+import { createRouteBuilder } from "../core/index.js";
+import { SseRouteBuilder } from "./route-builder.js";
+/**
+ * `.use()` returns a *new* router, so apply `withSse` last:
+ * `withSse(r({ prefix: "/api" }).use(auth))`.
+ */
+export function withSse(router) {
+    const target = router;
+    Object.defineProperty(target, "sse", {
+        value: (path) => new SseRouteBuilder(createRouteBuilder(router, "GET", path), {}),
+        enumerable: false,
+        configurable: true,
+    });
+    return target;
+}

package/dist/sse/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared SSE data types. Deliberately free of class references so every other
+ * module in this package can import from here without a cycle.
+ */
+export interface SseEventOptions {
+    /** `event:` field — the client-side listener name. Defaults to `message`. */
+    event?: string;
+    /** `id:` field — echoed back by the browser as `Last-Event-ID` on reconnect. */
+    id?: string;
+    /** `retry:` field — reconnection delay in milliseconds. */
+    retry?: number;
+}
+/** Return value is ignored; a returned promise is awaited only for error logging. */
+export type SseCleanupFn = () => unknown;
+/** What to do when a client is too slow to drain the send buffer. */
+export type SseOverflowPolicy = "close" | "drop";
+export interface SseConnectionOptions {
+    /** Send a `:` comment every N ms. Also how dead sockets get detected. */
+    keepaliveMs?: number;
+    /** Initial `retry:` hint sent as soon as the stream opens. */
+    retryMs?: number;
+    /** Send-buffer size in bytes before the overflow policy kicks in. */
+    highWaterMark?: number;
+    /** Default `"close"` — a stalled client is dropped and reconnects on its own. */
+    onOverflow?: SseOverflowPolicy;
+}
+/** Cross-process fan-out envelope. Must be JSON-serializable. */
+export interface SseTransportMessage {
+    /** `null` means broadcast to every connection. */
+    key: string | null;
+    data: unknown;
+    event?: string;
+    id?: string;
+    retry?: number;
+    /** Node that published it — used to suppress echo back to the sender. */
+    origin: string;
+}
+/** Seam for multi-instance deployments (Redis pub/sub, NATS, Postgres LISTEN…). */
+export interface SseTransport {
+    publish(message: SseTransportMessage): void | Promise<void>;
+    subscribe(onMessage: (message: SseTransportMessage) => void): () => void;
+}
+export interface SseHubOptions {
+    transport?: SseTransport;
+}

package/dist/sse/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared SSE data types. Deliberately free of class references so every other
+ * module in this package can import from here without a cycle.
+ */

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@fishenv/http",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.2",
+  "description": "Type-safe HTTP router for Bun with valibot validation, contracts and Server-Sent Events.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/core/index.d.ts",
+      "default": "./dist/core/index.js"
+    },
+    "./sse": {
+      "types": "./dist/sse/index.d.ts",
+      "default": "./dist/sse/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract/index.d.ts",
+      "default": "./dist/contract/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "bun test",
+    "check": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "bun run build"
+  },
+  "dependencies": {
+    "valibot": "^1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.15",
+    "@types/bun": "^1.4.3",
+    "typescript": "^7.0.2"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.