@nifrajs/core 0.1.0-alpha.1

package/dist/server/websocket.d.ts

@@ -0,0 +1,152 @@
+/**
+ * WebSocket seam — portable types shared by `@nifrajs/core`'s `app.ws()` and every serving adapter
+ * (Bun `listen()`, `@nifrajs/node`, `@nifrajs/deno`, `toFetchHandler` on Workers). No runtime code here, so
+ * it stays edge-safe and dependency-free; each adapter implements {@link NifraWebSocket} over its
+ * runtime's native socket and dispatches to the handler.
+ *
+ * A WS upgrade can't go through `app.fetch` (which has no socket) — it's adapter-integrated. The
+ * adapter calls `app.resolveWebSocketUpgrade(req)` (runs the route's `upgrade()` guard in a real
+ * request context), then performs the runtime upgrade with the returned data.
+ */
+import type { InferOutput, StandardIssue, StandardSchemaV1 } from "../schema/standard.js";
+type MaybePromise<T> = T | Promise<T>;
+/** A received frame, normalized across runtimes: text → `string`, binary → `Uint8Array`. */
+export type WebSocketData = string | Uint8Array;
+/** The value `message` receives: the schema's validated output when a `messageSchema` is set on the
+ * handler, otherwise the raw frame (`string | Uint8Array`). */
+type WsMessageInput<Schema extends StandardSchemaV1 | undefined> = Schema extends StandardSchemaV1 ? InferOutput<Schema> : WebSocketData;
+/** The portable socket handed to WS lifecycle callbacks. Each adapter wraps its native socket. */
+export interface NifraWebSocket<Data = unknown> {
+    /** Send a text (`string`) or binary (`ArrayBuffer`/typed-array) frame. No-op once closed. */
+    send(data: string | ArrayBufferView | ArrayBuffer): void;
+    /** Close the connection (optional code 1000–4999 + short reason). */
+    close(code?: number, reason?: string): void;
+    /** `WebSocket.readyState` (0 CONNECTING · 1 OPEN · 2 CLOSING · 3 CLOSED). */
+    readonly readyState: number;
+    /** Join a pub/sub topic — `app.publish(topic, data)` then reaches this connection. Idempotent. */
+    subscribe(topic: string): void;
+    /** Leave a pub/sub topic. Idempotent. (All topics are dropped automatically on close.) */
+    unsubscribe(topic: string): void;
+    /** Per-connection state — seeded by `upgrade()`, mutable for the connection's lifetime. */
+    data: Data;
+    /** Escape hatch to the runtime's native socket (Bun `ServerWebSocket`, Web `WebSocket`, `ws`). */
+    readonly raw: unknown;
+}
+/**
+ * In-process pub/sub for `ws.subscribe(topic)` + `app.publish(topic, data)`. **Single-instance only** —
+ * topics live in this process's memory, so a multi-instance deploy (multiple servers behind a load
+ * balancer) needs an external fan-out (Redis pub/sub, a Cloudflare Durable Object, NATS, …) bridged to
+ * `app.publish`. The same registry instance is shared by an app's connections and its `publish`.
+ */
+export declare class TopicRegistry {
+    private readonly topics;
+    private readonly memberships;
+    subscribe(topic: string, ws: NifraWebSocket): void;
+    unsubscribe(topic: string, ws: NifraWebSocket): void;
+    /** Drop every subscription for a connection — called on close so a registry never leaks dead sockets. */
+    unsubscribeAll(ws: NifraWebSocket): void;
+    /** Send `data` to every connection subscribed to `topic`. Per-socket send errors are isolated. */
+    publish(topic: string, data: string | ArrayBufferView | ArrayBuffer): void;
+}
+/**
+ * The request-context subset the `upgrade()` guard sees — the same lazy accessors a route handler's
+ * `c` has (cookies/headers/env are read straight off the upgrade request). Structurally a slice of the
+ * core `RawContext`, so the real context object satisfies it.
+ */
+export interface WebSocketContext<Env = unknown> {
+    readonly req: Request;
+    readonly params: Record<string, string>;
+    readonly query: unknown;
+    readonly cookies: Readonly<Record<string, string>>;
+    readonly env: Env;
+    readonly signal: AbortSignal;
+    readonly waitUntil: (promise: Promise<unknown>) => void;
+    boundedBody(maxBytes?: number): Promise<Uint8Array>;
+    boundedJson<T = unknown>(maxBytes?: number): Promise<T>;
+}
+/** A WebSocket route's lifecycle. All callbacks optional; only `message` is needed for an echo. */
+export interface WebSocketHandler<Data = unknown, Env = unknown, Schema extends StandardSchemaV1 | undefined = undefined> {
+    /**
+     * Cross-site WebSocket hijacking (CSWSH) guard — checked BEFORE `upgrade()`. A browser does not
+     * apply CORS to WebSocket handshakes and DOES send the page's cookies, so without an Origin check
+     * any site can open an authenticated socket to your app. Set this to lock the route to known
+     * origins: a string allow-list (exact `Origin` header match) or a predicate. A request whose
+     * `Origin` doesn't match (or is absent, for the allow-list form) is rejected with `403` before any
+     * per-connection work. Omit for no built-in check (same as today — then enforce it yourself in
+     * `upgrade()`). Non-browser clients can spoof `Origin`, so this is a browser-CSWSH defense, not
+     * authentication — pair it with auth in `upgrade()`.
+     */
+    allowedOrigins?: ReadonlyArray<string> | ((origin: string | null) => boolean);
+    /**
+     * Runs in the HTTP request context **before** the upgrade (and after {@link allowedOrigins}) — the
+     * place to authenticate or rate-limit. Return the initial per-connection `data` (→ `ws.data`), or a
+     * `Response` to **reject** the upgrade (the client never connects). Omit to accept with
+     * `data: undefined`. A thrown error rejects with a flat 500.
+     */
+    upgrade?(c: WebSocketContext<Env>): MaybePromise<Data | Response>;
+    /**
+     * Contract-first messages: a Standard Schema (`t`, zod, valibot, …) validating each **inbound** frame.
+     * Text frames are parsed as JSON first. When set, `message` receives the validated, typed value; a
+     * non-JSON or schema-invalid frame is routed to `onInvalidMessage` (or dropped if that's omitted).
+     */
+    messageSchema?: Schema;
+    open?(ws: NifraWebSocket<Data>): MaybePromise<void>;
+    message?(ws: NifraWebSocket<Data>, data: WsMessageInput<Schema>): MaybePromise<void>;
+    /** Inbound frame that failed JSON parse or `messageSchema` validation (only fires when a schema is
+     * set). `raw` is the original frame; `issues` are the Standard Schema issues (one synthetic issue for
+     * a JSON parse failure). Omit to silently drop invalid frames. */
+    onInvalidMessage?(ws: NifraWebSocket<Data>, issues: ReadonlyArray<StandardIssue>, raw: WebSocketData): MaybePromise<void>;
+    close?(ws: NifraWebSocket<Data>, code: number, reason: string): MaybePromise<void>;
+    error?(ws: NifraWebSocket<Data>, error: unknown): MaybePromise<void>;
+}
+/**
+ * The outcome of `app.resolveWebSocketUpgrade(req)` — for serving adapters:
+ * - `pass` — not a WS upgrade for a registered WS route; handle as a normal HTTP request.
+ * - `reject` — a WS route matched but `upgrade()` rejected (or the path was malformed); return `response`.
+ * - `upgrade` — perform the runtime upgrade, then dispatch the native socket's events to `handler`,
+ *   seeding `ws.data` with `data`.
+ */
+export type WebSocketUpgradeOutcome = {
+    readonly kind: "pass";
+} | {
+    readonly kind: "reject";
+    readonly response: Response;
+} | {
+    readonly kind: "upgrade";
+    readonly handler: WebSocketHandler;
+    readonly data: unknown;
+    /** The app's pub/sub registry — the adapter wires `ws.subscribe` + close-cleanup to it. */
+    readonly pubsub: TopicRegistry;
+};
+/**
+ * A standard server-side `WebSocket` — the half returned by Deno's `Deno.upgradeWebSocket` and the
+ * Workers `WebSocketPair`. {@link attachWebSocket} wires one to a nifra handler, so the Deno and Workers
+ * bridges share all the dispatch/normalization/error-isolation logic (only the upgrade call differs).
+ */
+export interface StandardWebSocket {
+    send(data: string | ArrayBufferView | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    binaryType?: string;
+    addEventListener(type: string, listener: (event: never) => void): void;
+}
+/**
+ * Wire a standard server-side `WebSocket` to a nifra {@link WebSocketHandler}, returning the portable
+ * {@link NifraWebSocket}. Shared by the Deno and Workers bridges. `openNow` fires `open` immediately
+ * (Workers, where the socket is already open after `accept()`); otherwise `open` waits for the socket's
+ * `open` event (Deno). Lifecycle callbacks are error-isolated — a throw (or async rejection) routes to
+ * `error()` and never tears the process down; binary frames are normalized to `Uint8Array`.
+ */
+export declare function attachWebSocket(socket: StandardWebSocket, handler: WebSocketHandler, data: unknown, options: {
+    openNow: boolean;
+    pubsub: TopicRegistry;
+}): NifraWebSocket;
+/**
+ * If the handler declares a `messageSchema`, return a copy whose `message` validates each frame —
+ * parse as JSON, run the Standard Schema, then call the user's `message` with the typed value, or
+ * `onInvalidMessage` on failure. Returns the handler unchanged when no schema is set. Called once at
+ * `app.ws()` registration, so every adapter dispatches validated messages with no per-adapter code.
+ */
+export declare function wrapWebSocketMessageValidation(handler: WebSocketHandler): WebSocketHandler;
+export {};
+//# sourceMappingURL=websocket.d.ts.map

package/dist/server/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/server/websocket.ts"],"names":[],"mappings":"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"}

package/dist/server/websocket.js

@@ -0,0 +1,178 @@
+/**
+ * WebSocket seam — portable types shared by `@nifrajs/core`'s `app.ws()` and every serving adapter
+ * (Bun `listen()`, `@nifrajs/node`, `@nifrajs/deno`, `toFetchHandler` on Workers). No runtime code here, so
+ * it stays edge-safe and dependency-free; each adapter implements {@link NifraWebSocket} over its
+ * runtime's native socket and dispatches to the handler.
+ *
+ * A WS upgrade can't go through `app.fetch` (which has no socket) — it's adapter-integrated. The
+ * adapter calls `app.resolveWebSocketUpgrade(req)` (runs the route's `upgrade()` guard in a real
+ * request context), then performs the runtime upgrade with the returned data.
+ */
+import { validateStandard } from "../schema/standard.js";
+/**
+ * In-process pub/sub for `ws.subscribe(topic)` + `app.publish(topic, data)`. **Single-instance only** —
+ * topics live in this process's memory, so a multi-instance deploy (multiple servers behind a load
+ * balancer) needs an external fan-out (Redis pub/sub, a Cloudflare Durable Object, NATS, …) bridged to
+ * `app.publish`. The same registry instance is shared by an app's connections and its `publish`.
+ */
+export class TopicRegistry {
+    topics = new Map();
+    memberships = new WeakMap();
+    subscribe(topic, ws) {
+        let subs = this.topics.get(topic);
+        if (subs === undefined) {
+            subs = new Set();
+            this.topics.set(topic, subs);
+        }
+        subs.add(ws);
+        let mine = this.memberships.get(ws);
+        if (mine === undefined) {
+            mine = new Set();
+            this.memberships.set(ws, mine);
+        }
+        mine.add(topic);
+    }
+    unsubscribe(topic, ws) {
+        const subs = this.topics.get(topic);
+        if (subs !== undefined) {
+            subs.delete(ws);
+            if (subs.size === 0)
+                this.topics.delete(topic); // reclaim empty topics — no unbounded growth
+        }
+        this.memberships.get(ws)?.delete(topic);
+    }
+    /** Drop every subscription for a connection — called on close so a registry never leaks dead sockets. */
+    unsubscribeAll(ws) {
+        const mine = this.memberships.get(ws);
+        if (mine === undefined)
+            return;
+        for (const topic of mine) {
+            const subs = this.topics.get(topic);
+            if (subs !== undefined) {
+                subs.delete(ws);
+                if (subs.size === 0)
+                    this.topics.delete(topic);
+            }
+        }
+        this.memberships.delete(ws);
+    }
+    /** Send `data` to every connection subscribed to `topic`. Per-socket send errors are isolated. */
+    publish(topic, data) {
+        const subs = this.topics.get(topic);
+        if (subs === undefined)
+            return;
+        for (const ws of subs) {
+            try {
+                ws.send(data);
+            }
+            catch {
+                /* a single dead/closing socket must not abort the broadcast to the rest */
+            }
+        }
+    }
+}
+/** Normalize a received binary frame to `Uint8Array` (text frames stay `string`). */
+function toBinary(raw) {
+    if (raw instanceof Uint8Array)
+        return raw;
+    if (raw instanceof ArrayBuffer)
+        return new Uint8Array(raw);
+    if (ArrayBuffer.isView(raw))
+        return new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+    return new Uint8Array(0); // unknown (e.g. an unconverted Blob) — adapters set binaryType to avoid this
+}
+/**
+ * Wire a standard server-side `WebSocket` to a nifra {@link WebSocketHandler}, returning the portable
+ * {@link NifraWebSocket}. Shared by the Deno and Workers bridges. `openNow` fires `open` immediately
+ * (Workers, where the socket is already open after `accept()`); otherwise `open` waits for the socket's
+ * `open` event (Deno). Lifecycle callbacks are error-isolated — a throw (or async rejection) routes to
+ * `error()` and never tears the process down; binary frames are normalized to `Uint8Array`.
+ */
+export function attachWebSocket(socket, handler, data, options) {
+    const { pubsub } = options;
+    const ws = {
+        send: (payload) => socket.send(payload),
+        close: (code, reason) => socket.close(code, reason),
+        get readyState() {
+            return socket.readyState;
+        },
+        subscribe: (topic) => pubsub.subscribe(topic, ws),
+        unsubscribe: (topic) => pubsub.unsubscribe(topic, ws),
+        data,
+        raw: socket,
+    };
+    const reportError = (error) => {
+        if (handler.error === undefined)
+            return;
+        try {
+            const r = handler.error(ws, error);
+            if (r instanceof Promise)
+                r.catch(() => { });
+        }
+        catch {
+            /* the error handler itself failed — last resort, swallow */
+        }
+    };
+    const safe = (call) => {
+        try {
+            const r = call();
+            if (r instanceof Promise)
+                r.catch(reportError);
+        }
+        catch (error) {
+            reportError(error);
+        }
+    };
+    // Deliver binary as ArrayBuffer (→ Uint8Array) rather than Blob, where the runtime allows it.
+    if ("binaryType" in socket)
+        socket.binaryType = "arraybuffer";
+    socket.addEventListener("message", (event) => {
+        const raw = event.data;
+        const payload = typeof raw === "string" ? raw : toBinary(raw);
+        safe(() => handler.message?.(ws, payload));
+    });
+    socket.addEventListener("close", (event) => {
+        pubsub.unsubscribeAll(ws); // drop topic subscriptions so the registry never holds a dead socket
+        safe(() => handler.close?.(ws, event.code ?? 1005, event.reason ?? ""));
+    });
+    socket.addEventListener("error", (event) => reportError(event));
+    if (options.openNow) {
+        safe(() => handler.open?.(ws));
+    }
+    else {
+        socket.addEventListener("open", () => safe(() => handler.open?.(ws)));
+    }
+    return ws;
+}
+const WS_MESSAGE_DECODER = new TextDecoder();
+/**
+ * If the handler declares a `messageSchema`, return a copy whose `message` validates each frame —
+ * parse as JSON, run the Standard Schema, then call the user's `message` with the typed value, or
+ * `onInvalidMessage` on failure. Returns the handler unchanged when no schema is set. Called once at
+ * `app.ws()` registration, so every adapter dispatches validated messages with no per-adapter code.
+ */
+export function wrapWebSocketMessageValidation(handler) {
+    const schema = handler.messageSchema;
+    if (schema === undefined)
+        return handler;
+    // The handler is type-erased here; the user's `message` really accepts the schema's validated output
+    // (typed at the real call site), so widen its param to `unknown` for the internal call.
+    const userMessage = handler.message;
+    const onInvalid = handler.onInvalidMessage;
+    const validatingMessage = (ws, raw) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(typeof raw === "string" ? raw : WS_MESSAGE_DECODER.decode(raw));
+        }
+        catch {
+            return onInvalid?.(ws, [{ message: "invalid JSON" }], raw);
+        }
+        const outcome = validateStandard(schema, parsed);
+        const finish = (o) => o.ok ? userMessage?.(ws, o.value) : onInvalid?.(ws, o.issues, raw);
+        return outcome instanceof Promise ? outcome.then(finish) : finish(outcome);
+    };
+    // The wrapped `message` takes the raw frame (adapters pass that) and produces the typed value
+    // internally; the stored handler is type-erased, so the signature is sound.
+    return { ...handler, message: validatingMessage };
+}
+//# sourceMappingURL=websocket.js.map

package/dist/server/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.js","sourceRoot":"","sources":["../../src/server/websocket.ts"],"names":[],"mappings":"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"}

package/dist/server/ws-bun.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Bun WebSocket plumbing — the `websocket` dispatcher config `listen()` hands to Bun's serve when
+ * the app has WS routes. Lives behind the `@nifrajs/core/ws` subpath (via `ws-hook.ts`) so the base
+ * bundle of a no-WebSocket app never ships it; `server.ts` only imports the **types** from here
+ * (erased). No `Bun.*` calls here — the runtime seam stays in `server.ts` (see runtime-boundary.test).
+ */
+import type { NifraWebSocket, TopicRegistry, WebSocketHandler } from "./websocket.js";
+import type { BunWsHandlers } from "./ws-hook.js";
+/** Per-connection state Bun's `websocket` callbacks read via `ws.data`: the matched handler, the
+ * `upgrade()`-seeded user data, and the memoized portable {@link NifraWebSocket} wrapper. */
+export interface BunWsData {
+    readonly handler: WebSocketHandler;
+    data: unknown;
+    nifra?: NifraWebSocket;
+}
+/** Structural view of Bun's `ServerWebSocket` — keeps `Bun.*` types out of the public `.d.ts`
+ * (`listen()` casts for the same reason). The real socket satisfies this. */
+export interface BunSocket {
+    send(data: string | ArrayBufferView | ArrayBuffer, compress?: boolean): number;
+    close(code?: number, reason?: string): void;
+    readonly readyState: number;
+    readonly data: BunWsData;
+}
+/** The shared Bun `websocket` dispatcher config for one app — each connection's
+ * `ws.data.handler` is the matched route's handler, set by `server.upgrade`. */
+export declare function createBunWsHandlers(topics: TopicRegistry): BunWsHandlers;
+//# sourceMappingURL=ws-bun.d.ts.map

package/dist/server/ws-bun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-bun.d.ts","sourceRoot":"","sources":["../../src/server/ws-bun.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAiB,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACpG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD;6FAC6F;AAC7F,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAA;IAClC,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,CAAC,EAAE,cAAc,CAAA;CACvB;AAED;6EAC6E;AAC7E,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,WAAW,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;IAC9E,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CACzB;AAwDD;gFACgF;AAChF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAqBxE"}

package/dist/server/ws-bun.js

@@ -0,0 +1,82 @@
+/**
+ * Bun WebSocket plumbing — the `websocket` dispatcher config `listen()` hands to Bun's serve when
+ * the app has WS routes. Lives behind the `@nifrajs/core/ws` subpath (via `ws-hook.ts`) so the base
+ * bundle of a no-WebSocket app never ships it; `server.ts` only imports the **types** from here
+ * (erased). No `Bun.*` calls here — the runtime seam stays in `server.ts` (see runtime-boundary.test).
+ */
+/** Normalize a received binary frame to `Uint8Array` (Bun hands a `Buffer`, already one; an
+ * `ArrayBuffer` is wrapped). Text frames stay `string`. */
+function toBinaryData(message) {
+    return message instanceof Uint8Array ? message : new Uint8Array(message);
+}
+/** Wrap a Bun `ServerWebSocket` as the portable {@link NifraWebSocket} handed to WS callbacks. */
+function wrapBunSocket(raw, topics) {
+    const ws = {
+        send: (data) => {
+            raw.send(data);
+        },
+        close: (code, reason) => raw.close(code, reason),
+        get readyState() {
+            return raw.readyState;
+        },
+        subscribe: (topic) => topics.subscribe(topic, ws),
+        unsubscribe: (topic) => topics.unsubscribe(topic, ws),
+        get data() {
+            return raw.data.data;
+        },
+        set data(value) {
+            raw.data.data = value;
+        },
+        raw,
+    };
+    return ws;
+}
+function reportWsError(error, ws, handler) {
+    if (handler.error === undefined)
+        return;
+    try {
+        const result = handler.error(ws, error);
+        if (result instanceof Promise)
+            result.catch(() => { }); // a throwing error handler is the last resort
+    }
+    catch {
+        /* swallow: the error handler itself failed; nothing left to do but not crash */
+    }
+}
+/** Run a WS lifecycle callback, routing a sync throw or async rejection to `handler.error` so a
+ * failing callback never crashes the socket loop. */
+function dispatchWsCallback(call, ws, handler) {
+    try {
+        const result = call();
+        if (result instanceof Promise)
+            result.catch((e) => reportWsError(e, ws, handler));
+    }
+    catch (error) {
+        reportWsError(error, ws, handler);
+    }
+}
+/** The shared Bun `websocket` dispatcher config for one app — each connection's
+ * `ws.data.handler` is the matched route's handler, set by `server.upgrade`. */
+export function createBunWsHandlers(topics) {
+    return {
+        open: (raw) => {
+            const ws = raw;
+            const nifra = wrapBunSocket(ws, topics);
+            ws.data.nifra = nifra;
+            dispatchWsCallback(() => ws.data.handler.open?.(nifra), nifra, ws.data.handler);
+        },
+        message: (raw, message) => {
+            const ws = raw;
+            const nifra = ws.data.nifra ?? wrapBunSocket(ws, topics);
+            const data = typeof message === "string" ? message : toBinaryData(message);
+            dispatchWsCallback(() => ws.data.handler.message?.(nifra, data), nifra, ws.data.handler);
+        },
+        close: (raw, code, reason) => {
+            const ws = raw;
+            const nifra = ws.data.nifra ?? wrapBunSocket(ws, topics);
+            topics.unsubscribeAll(nifra); // drop topic subscriptions so the registry never holds a dead socket
+            dispatchWsCallback(() => ws.data.handler.close?.(nifra, code, reason), nifra, ws.data.handler);
+        },
+    };
+}
+//# sourceMappingURL=ws-bun.js.map

package/dist/server/ws-bun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-bun.js","sourceRoot":"","sources":["../../src/server/ws-bun.ts"],"names":[],"mappings":"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"}

package/dist/server/ws-hook.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Lazy WebSocket runtime seam. `server.ts` never imports the WS implementation statically — the
+ * `@nifrajs/core/ws` subpath entry registers it here on import. That keeps the WS dispatcher, pub/sub
+ * registry, Bun socket plumbing, and message-schema validation out of the base server bundle for
+ * apps that never call `app.ws()` (~1.5 KB gzipped on the minimal-app benchmark).
+ *
+ * Only type imports below — this module must stay weightless, it is always in the base bundle.
+ */
+import type { NifraWebSocket, StandardWebSocket, TopicRegistry, WebSocketHandler } from "./websocket.js";
+/** The Bun serve `websocket` callback trio, closed over one app's `TopicRegistry`. The `ws`
+ * params are `unknown` so `Bun.*` types never leak into the public `.d.ts`; the implementation
+ * narrows to its structural `BunSocket` view. */
+export interface BunWsHandlers {
+    open(ws: unknown): void;
+    message(ws: unknown, message: string | ArrayBuffer | Uint8Array): void;
+    close(ws: unknown, code: number, reason: string): void;
+}
+/** What `@nifrajs/core/ws` registers: everything `server.ts` and `toFetchHandler` need at runtime. */
+export interface WsRuntime {
+    /** `wrapWebSocketMessageValidation` — applied once at `app.ws()` registration. */
+    wrapHandler(handler: WebSocketHandler): WebSocketHandler;
+    /** One in-process pub/sub registry per app (backs `ws.subscribe` + `app.publish`). */
+    createTopics(): TopicRegistry;
+    /** The Bun `websocket` config for `listen()` when the app has WS routes. */
+    bunHandlers(topics: TopicRegistry): BunWsHandlers;
+    /** `attachWebSocket` — wires a standard server socket (Workers `WebSocketPair`) to a handler. */
+    attach(socket: StandardWebSocket, handler: WebSocketHandler, data: unknown, options: {
+        openNow: boolean;
+        pubsub: TopicRegistry;
+    }): NifraWebSocket;
+}
+/** Called by `@nifrajs/core/ws` on import. Last registration wins (idempotent in practice — there is
+ * one implementation; double-import is a no-op re-set of the same functions). */
+export declare function setWsRuntime(impl: WsRuntime): void;
+export declare function getWsRuntime(): WsRuntime | undefined;
+//# sourceMappingURL=ws-hook.d.ts.map

package/dist/server/ws-hook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-hook.d.ts","sourceRoot":"","sources":["../../src/server/ws-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EACjB,MAAM,gBAAgB,CAAA;AAEvB;;iDAEiD;AACjD,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAAA;IACvB,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI,CAAA;IACtE,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACvD;AAED,sGAAsG;AACtG,MAAM,WAAW,SAAS;IACxB,kFAAkF;IAClF,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAAA;IACxD,sFAAsF;IACtF,YAAY,IAAI,aAAa,CAAA;IAC7B,4EAA4E;IAC5E,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAAA;IACjD,iGAAiG;IACjG,MAAM,CACJ,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,OAAO,EACb,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,GACnD,cAAc,CAAA;CAClB;AAID;iFACiF;AACjF,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAElD;AAED,wBAAgB,YAAY,IAAI,SAAS,GAAG,SAAS,CAEpD"}

package/dist/server/ws-hook.js

@@ -0,0 +1,18 @@
+/**
+ * Lazy WebSocket runtime seam. `server.ts` never imports the WS implementation statically — the
+ * `@nifrajs/core/ws` subpath entry registers it here on import. That keeps the WS dispatcher, pub/sub
+ * registry, Bun socket plumbing, and message-schema validation out of the base server bundle for
+ * apps that never call `app.ws()` (~1.5 KB gzipped on the minimal-app benchmark).
+ *
+ * Only type imports below — this module must stay weightless, it is always in the base bundle.
+ */
+let runtime;
+/** Called by `@nifrajs/core/ws` on import. Last registration wins (idempotent in practice — there is
+ * one implementation; double-import is a no-op re-set of the same functions). */
+export function setWsRuntime(impl) {
+    runtime = impl;
+}
+export function getWsRuntime() {
+    return runtime;
+}
+//# sourceMappingURL=ws-hook.js.map

package/dist/server/ws-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-hook.js","sourceRoot":"","sources":["../../src/server/ws-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAmCH,IAAI,OAA8B,CAAA;AAElC;iFACiF;AACjF,MAAM,UAAU,YAAY,CAAC,IAAe;IAC1C,OAAO,GAAG,IAAI,CAAA;AAChB,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/ws.d.ts

@@ -0,0 +1,19 @@
+/**
+ * WebSocket runtime for `@nifrajs/core` — import once at your server entry to enable `app.ws()`:
+ *
+ *   import "@nifrajs/core/ws"
+ *
+ *   const app = server().ws("/chat", { message: (ws, data) => ws.send(data) })
+ *
+ * Why a subpath: an app that never uses WebSockets shouldn't ship the WS dispatcher, pub/sub
+ * registry, and Bun socket plumbing in its server bundle (~1.5 KB gzipped on the minimal-app size
+ * benchmark). Importing this module registers the runtime with the core server (idempotent);
+ * calling `app.ws()` without it fails loud at boot with a `WS_RUNTIME_MISSING` error pointing here.
+ *
+ * Serving adapters that wire standard sockets themselves (`@nifrajs/workers`) import
+ * `attachWebSocket` / `TopicRegistry` from here too.
+ */
+import { attachWebSocket, TopicRegistry, wrapWebSocketMessageValidation } from "./server/websocket.js";
+export type { NifraWebSocket, StandardWebSocket, WebSocketContext, WebSocketData, WebSocketHandler, WebSocketUpgradeOutcome, } from "./server/websocket.js";
+export { attachWebSocket, TopicRegistry, wrapWebSocketMessageValidation };
+//# sourceMappingURL=ws.d.ts.map

package/dist/ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.d.ts","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,eAAe,EACf,aAAa,EACb,8BAA8B,EAC/B,MAAM,uBAAuB,CAAA;AAW9B,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,8BAA8B,EAAE,CAAA"}

package/dist/ws.js

@@ -0,0 +1,26 @@
+/**
+ * WebSocket runtime for `@nifrajs/core` — import once at your server entry to enable `app.ws()`:
+ *
+ *   import "@nifrajs/core/ws"
+ *
+ *   const app = server().ws("/chat", { message: (ws, data) => ws.send(data) })
+ *
+ * Why a subpath: an app that never uses WebSockets shouldn't ship the WS dispatcher, pub/sub
+ * registry, and Bun socket plumbing in its server bundle (~1.5 KB gzipped on the minimal-app size
+ * benchmark). Importing this module registers the runtime with the core server (idempotent);
+ * calling `app.ws()` without it fails loud at boot with a `WS_RUNTIME_MISSING` error pointing here.
+ *
+ * Serving adapters that wire standard sockets themselves (`@nifrajs/workers`) import
+ * `attachWebSocket` / `TopicRegistry` from here too.
+ */
+import { attachWebSocket, TopicRegistry, wrapWebSocketMessageValidation, } from "./server/websocket.js";
+import { createBunWsHandlers } from "./server/ws-bun.js";
+import { setWsRuntime } from "./server/ws-hook.js";
+setWsRuntime({
+    wrapHandler: wrapWebSocketMessageValidation,
+    createTopics: () => new TopicRegistry(),
+    bunHandlers: createBunWsHandlers,
+    attach: attachWebSocket,
+});
+export { attachWebSocket, TopicRegistry, wrapWebSocketMessageValidation };
+//# sourceMappingURL=ws.js.map

package/dist/ws.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws.js","sourceRoot":"","sources":["../src/ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EACL,eAAe,EACf,aAAa,EACb,8BAA8B,GAC/B,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAElD,YAAY,CAAC;IACX,WAAW,EAAE,8BAA8B;IAC3C,YAAY,EAAE,GAAG,EAAE,CAAC,IAAI,aAAa,EAAE;IACvC,WAAW,EAAE,mBAAmB;IAChC,MAAM,EAAE,eAAe;CACxB,CAAC,CAAA;AAUF,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,8BAA8B,EAAE,CAAA"}