@daloyjs/core 0.2.0 → 0.3.0

package/README.md

@@ -27,7 +27,7 @@ DaloyJS exists to be the framework you'd build if you took the best ideas from e
 | **Supply-chain-hardened installs and publishing** | [pnpm](https://pnpm.io/motivation) + hardened CI/CD | `ignore-scripts`, release-age cooldown, explicit build allowlist, SHA-pinned actions, isolated OIDC publish with provenance. |
 
 ```
-119/119 framework tests passing · 100% line + function coverage · clean strict TypeScript 6
+159/159 framework tests passing · 100% line + function coverage · clean strict TypeScript 6
 runs on Node, Bun, Deno, Cloudflare, Vercel
 ~12.3M static-route ops/sec · ~1.5M dynamic-route ops/sec on M-class CPU
 ```
@@ -177,7 +177,7 @@ import { swaggerUiHtml, htmlResponse } from "@daloyjs/core/docs";
 ```
 
 Mount at `/docs` and the UI is always contract-accurate — never stale.
-`create-daloy@0.1.10` mounts Swagger UI at `/docs` and the live spec at `/openapi.json` by default.
+`create-daloy@0.1.11` mounts Swagger UI at `/docs` and the live spec at `/openapi.json` by default.
 
 ---
 
@@ -310,11 +310,12 @@ Full, versioned plan: [ROADMAP.md](./ROADMAP.md).
 - [x] `SECURITY.md` and vulnerability disclosure process
 - [x] `pnpm create daloy` project scaffolder (Node + Vercel Edge + Cloudflare templates)
 - [x] Docs site discoverability pass: page metadata, sitemap, robots, OpenGraph image, ORM guides
+- [x] Streaming response helpers: SSE + NDJSON with backpressure-safe writers (`sseStream` / `sseResponse` / `ndjsonStream` / `ndjsonResponse`)
 - [ ] Branch coverage push to `>= 98%`
 - [ ] Release checklist and publishing docs cleanup
 
-**On deck (`0.3.0` and beyond):** SSE/NDJSON streaming, OpenTelemetry,
-multipart/form-data ergonomics, CSRF helper, scaffolder, Redis rate-limit store,
+**On deck (`0.3.0` and beyond):** OpenTelemetry,
+multipart/form-data ergonomics, CSRF helper, Redis rate-limit store,
 CLI route and schema inspector, WebSockets, and HTTP/2 + HTTP/3 adapters.
 
 ## License

package/dist/index.d.ts

@@ -10,4 +10,6 @@ export { requestId, secureHeaders, cors, rateLimit, timing, bearerAuth, } from "
 export type { RequestIdOptions, SecureHeadersOptions, CorsOptions, RateLimitOptions, RateLimitStore, } from "./middleware.js";
 export { createLogger, noopLogger } from "./logger.js";
 export type { Logger, LogLevel, ConsoleLoggerOptions } from "./logger.js";
+export { sseStream, sseResponse, ndjsonStream, ndjsonResponse, } from "./streaming.js";
+export type { SSEMessage, StreamOptions, SSEStreamOptions, SSEResponseOptions, NDJSONResponseOptions, } from "./streaming.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE9D,YAAY,EACV,eAAe,EACf,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,KAAK,EACL,WAAW,EACX,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,eAAe,EACf,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EACL,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,EACT,aAAa,EACb,IAAI,EACJ,SAAS,EACT,MAAM,EACN,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,gBAAgB,EAChB,cAAc,GACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE9D,YAAY,EACV,eAAe,EACf,UAAU,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,QAAQ,EACR,KAAK,EACL,WAAW,EACX,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,SAAS,EACT,eAAe,EACf,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExE,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EACL,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,EACT,aAAa,EACb,IAAI,EACJ,SAAS,EACT,MAAM,EACN,UAAU,GACX,MAAM,iBAAiB,CAAC;AACzB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,WAAW,EACX,gBAAgB,EAChB,cAAc,GACf,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAE1E,OAAO,EACL,SAAS,EACT,WAAW,EACX,YAAY,EACZ,cAAc,GACf,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,UAAU,EACV,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -4,4 +4,5 @@ export { validate, isStandardSchema } from "./schema.js";
 export { readBodyLimited, safeJsonParse, sanitizeHeaderName, sanitizeHeaderValue, timingSafeEqual, randomId, } from "./security.js";
 export { requestId, secureHeaders, cors, rateLimit, timing, bearerAuth, } from "./middleware.js";
 export { createLogger, noopLogger } from "./logger.js";
+export { sseStream, sseResponse, ndjsonStream, ndjsonResponse, } from "./streaming.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAoB/B,OAAO,EACL,SAAS,EACT,eAAe,EACf,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EACL,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,EACT,aAAa,EACb,IAAI,EACJ,SAAS,EACT,MAAM,EACN,UAAU,GACX,MAAM,iBAAiB,CAAC;AASzB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAoB/B,OAAO,EACL,SAAS,EACT,eAAe,EACf,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACrB,oBAAoB,EACpB,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,GACd,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,EACL,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EACf,QAAQ,GACT,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,SAAS,EACT,aAAa,EACb,IAAI,EACJ,SAAS,EACT,MAAM,EACN,UAAU,GACX,MAAM,iBAAiB,CAAC;AASzB,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,EACL,SAAS,EACT,WAAW,EACX,YAAY,EACZ,cAAc,GACf,MAAM,gBAAgB,CAAC"}

package/dist/streaming.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Streaming response helpers — Server-Sent Events (SSE) and NDJSON.
+ *
+ * Both helpers return a `ReadableStream<Uint8Array>` (or, in the `*Response`
+ * forms, a `Response`) that is **backpressure-safe**: data is only pulled
+ * from the underlying `AsyncIterable`/generator when the consumer asks for
+ * the next chunk. They also honor an optional `AbortSignal` and call
+ * `iterator.return()` so caller-owned resources (DB cursors, fetches, queues)
+ * are released when the client disconnects.
+ *
+ * ```ts
+ * import { sseStream } from "@daloyjs/core";
+ *
+ * app.route({
+ *   method: "GET",
+ *   path: "/events",
+ *   operationId: "events",
+ *   responses: { 200: { description: "SSE stream" } },
+ *   handler: ({ request }) => ({
+ *     status: 200,
+ *     headers: { "content-type": "text/event-stream" },
+ *     body: sseStream(async function* () {
+ *       yield { event: "ping", data: { now: Date.now() } };
+ *     }, { signal: request.signal }),
+ *   }),
+ * });
+ * ```
+ *
+ * For NDJSON, each yielded value is JSON-encoded and terminated with `\n`.
+ */
+/** A single SSE event. `data` may be a string or any JSON-serializable value. */
+export interface SSEMessage {
+    data: unknown;
+    event?: string;
+    id?: string;
+    /** Reconnection delay in milliseconds. */
+    retry?: number;
+    /** Comment line (sent as `: <comment>`). Useful for keep-alive pings. */
+    comment?: string;
+}
+export interface StreamOptions {
+    /** Abort the stream when this signal fires. */
+    signal?: AbortSignal;
+}
+export interface SSEStreamOptions extends StreamOptions {
+    /**
+     * Send a comment (`:keep-alive`) every N milliseconds to keep the
+     * connection open through proxies. Set to `0`/`undefined` to disable.
+     */
+    keepAliveMs?: number;
+}
+export interface SSEResponseOptions extends SSEStreamOptions {
+    status?: number;
+    headers?: HeadersInit;
+}
+export interface NDJSONResponseOptions extends StreamOptions {
+    status?: number;
+    headers?: HeadersInit;
+}
+type IterableSource<T> = AsyncIterable<T> | Iterable<T> | (() => AsyncIterable<T> | Iterable<T>);
+/**
+ * Build a backpressure-safe `ReadableStream` from an async iterable of SSE
+ * messages. The iterator is only advanced when the consumer pulls the next
+ * chunk, so a slow client cannot cause unbounded buffering.
+ */
+export declare function sseStream(source: IterableSource<SSEMessage | string>, opts?: SSEStreamOptions): ReadableStream<Uint8Array>;
+/**
+ * Wrap `sseStream` in a `Response` with the proper SSE headers
+ * (`text/event-stream`, no caching, keep-alive). Caller-supplied headers win.
+ */
+export declare function sseResponse(source: IterableSource<SSEMessage | string>, opts?: SSEResponseOptions): Response;
+/**
+ * Build a backpressure-safe `ReadableStream` of NDJSON (newline-delimited
+ * JSON) records from an async iterable. Each yielded value is encoded with
+ * `JSON.stringify` and terminated with `\n`. Values that stringify to
+ * `undefined` throw because they cannot be represented as valid NDJSON.
+ */
+export declare function ndjsonStream<T>(source: IterableSource<T>, opts?: StreamOptions): ReadableStream<Uint8Array>;
+/**
+ * Wrap `ndjsonStream` in a `Response` with `application/x-ndjson` and
+ * cache-busting headers. Caller-supplied headers win.
+ */
+export declare function ndjsonResponse<T>(source: IterableSource<T>, opts?: NDJSONResponseOptions): Response;
+export {};
+//# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,KAAK,cAAc,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AA2DjG;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,cAAc,CAAC,UAAU,GAAG,MAAM,CAAC,EAC3C,IAAI,GAAE,gBAAqB,GAC1B,cAAc,CAAC,UAAU,CAAC,CAuE5B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,cAAc,CAAC,UAAU,GAAG,MAAM,CAAC,EAC3C,IAAI,GAAE,kBAAuB,GAC5B,QAAQ,CASV;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EACzB,IAAI,GAAE,aAAkB,GACvB,cAAc,CAAC,UAAU,CAAC,CAuD5B;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EACzB,IAAI,GAAE,qBAA0B,GAC/B,QAAQ,CAOV"}

package/dist/streaming.js

@@ -0,0 +1,261 @@
+/**
+ * Streaming response helpers — Server-Sent Events (SSE) and NDJSON.
+ *
+ * Both helpers return a `ReadableStream<Uint8Array>` (or, in the `*Response`
+ * forms, a `Response`) that is **backpressure-safe**: data is only pulled
+ * from the underlying `AsyncIterable`/generator when the consumer asks for
+ * the next chunk. They also honor an optional `AbortSignal` and call
+ * `iterator.return()` so caller-owned resources (DB cursors, fetches, queues)
+ * are released when the client disconnects.
+ *
+ * ```ts
+ * import { sseStream } from "@daloyjs/core";
+ *
+ * app.route({
+ *   method: "GET",
+ *   path: "/events",
+ *   operationId: "events",
+ *   responses: { 200: { description: "SSE stream" } },
+ *   handler: ({ request }) => ({
+ *     status: 200,
+ *     headers: { "content-type": "text/event-stream" },
+ *     body: sseStream(async function* () {
+ *       yield { event: "ping", data: { now: Date.now() } };
+ *     }, { signal: request.signal }),
+ *   }),
+ * });
+ * ```
+ *
+ * For NDJSON, each yielded value is JSON-encoded and terminated with `\n`.
+ */
+const TEXT_ENCODER = new TextEncoder();
+function getAsyncIterator(src) {
+    const it = typeof src === "function" ? src() : src;
+    if (it == null) {
+        throw new TypeError("Streaming source is null/undefined");
+    }
+    if (typeof it[Symbol.asyncIterator] === "function") {
+        return it[Symbol.asyncIterator]();
+    }
+    if (typeof it[Symbol.iterator] === "function") {
+        const sync = it[Symbol.iterator]();
+        const wrapped = {
+            next: async () => sync.next(),
+        };
+        if (sync.return) {
+            wrapped.return = async (value) => sync.return(value);
+        }
+        return wrapped;
+    }
+    throw new TypeError("Streaming source is not iterable");
+}
+function encodeSSE(msg) {
+    const message = typeof msg === "string" ? { data: msg } : msg;
+    let out = "";
+    if (message.comment) {
+        for (const line of String(message.comment).split(/\r?\n/)) {
+            out += `: ${line}\n`;
+        }
+    }
+    if (message.event !== undefined) {
+        // Event names cannot contain newlines per the spec.
+        out += `event: ${String(message.event).replace(/[\r\n]+/g, " ")}\n`;
+    }
+    if (message.id !== undefined) {
+        out += `id: ${String(message.id).replace(/[\r\n]+/g, " ")}\n`;
+    }
+    if (message.retry !== undefined && Number.isFinite(message.retry)) {
+        out += `retry: ${Math.max(0, Math.floor(message.retry))}\n`;
+    }
+    if (message.data !== undefined) {
+        const raw = typeof message.data === "string" ? message.data : JSON.stringify(message.data);
+        for (const line of raw.split(/\r?\n/)) {
+            out += `data: ${line}\n`;
+        }
+    }
+    out += "\n";
+    return TEXT_ENCODER.encode(out);
+}
+function encodeNDJSON(value) {
+    const line = JSON.stringify(value);
+    if (line === undefined) {
+        throw new TypeError("NDJSON values must be JSON-serializable");
+    }
+    return TEXT_ENCODER.encode(line + "\n");
+}
+/**
+ * Build a backpressure-safe `ReadableStream` from an async iterable of SSE
+ * messages. The iterator is only advanced when the consumer pulls the next
+ * chunk, so a slow client cannot cause unbounded buffering.
+ */
+export function sseStream(source, opts = {}) {
+    const iterator = getAsyncIterator(source);
+    let keepAliveTimer;
+    let abortHandler;
+    const cleanup = async (cancelValue) => {
+        if (keepAliveTimer !== undefined) {
+            clearInterval(keepAliveTimer);
+            keepAliveTimer = undefined;
+        }
+        if (opts.signal && abortHandler) {
+            opts.signal.removeEventListener("abort", abortHandler);
+            abortHandler = undefined;
+        }
+        if (typeof iterator.return === "function") {
+            try {
+                await iterator.return(cancelValue);
+            }
+            catch {
+                /* swallow — the consumer is already gone */
+            }
+        }
+    };
+    return new ReadableStream({
+        start(controller) {
+            if (opts.signal?.aborted) {
+                controller.close();
+                void cleanup();
+                return;
+            }
+            if (opts.signal) {
+                abortHandler = () => {
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        /* already closed */
+                    }
+                    void cleanup();
+                };
+                opts.signal.addEventListener("abort", abortHandler, { once: true });
+            }
+            if (opts.keepAliveMs && opts.keepAliveMs > 0) {
+                keepAliveTimer = setInterval(() => {
+                    try {
+                        if ((controller.desiredSize ?? 0) > 0) {
+                            controller.enqueue(TEXT_ENCODER.encode(": keep-alive\n\n"));
+                        }
+                    }
+                    catch {
+                        /* stream closed — interval will be cleared on cancel */
+                    }
+                }, opts.keepAliveMs);
+            }
+        },
+        async pull(controller) {
+            try {
+                const { value, done } = await iterator.next();
+                if (done) {
+                    controller.close();
+                    await cleanup();
+                    return;
+                }
+                controller.enqueue(encodeSSE(value));
+            }
+            catch (err) {
+                controller.error(err);
+                await cleanup(err);
+            }
+        },
+        async cancel(reason) {
+            await cleanup(reason);
+        },
+    });
+}
+/**
+ * Wrap `sseStream` in a `Response` with the proper SSE headers
+ * (`text/event-stream`, no caching, keep-alive). Caller-supplied headers win.
+ */
+export function sseResponse(source, opts = {}) {
+    const stream = sseStream(source, opts);
+    const headers = new Headers(opts.headers);
+    if (!headers.has("content-type"))
+        headers.set("content-type", "text/event-stream; charset=utf-8");
+    if (!headers.has("cache-control"))
+        headers.set("cache-control", "no-cache, no-transform");
+    if (!headers.has("connection"))
+        headers.set("connection", "keep-alive");
+    // Disable proxy buffering (nginx).
+    if (!headers.has("x-accel-buffering"))
+        headers.set("x-accel-buffering", "no");
+    return new Response(stream, { status: opts.status ?? 200, headers });
+}
+/**
+ * Build a backpressure-safe `ReadableStream` of NDJSON (newline-delimited
+ * JSON) records from an async iterable. Each yielded value is encoded with
+ * `JSON.stringify` and terminated with `\n`. Values that stringify to
+ * `undefined` throw because they cannot be represented as valid NDJSON.
+ */
+export function ndjsonStream(source, opts = {}) {
+    const iterator = getAsyncIterator(source);
+    let abortHandler;
+    const cleanup = async (cancelValue) => {
+        if (opts.signal && abortHandler) {
+            opts.signal.removeEventListener("abort", abortHandler);
+            abortHandler = undefined;
+        }
+        if (typeof iterator.return === "function") {
+            try {
+                await iterator.return(cancelValue);
+            }
+            catch {
+                /* swallow */
+            }
+        }
+    };
+    return new ReadableStream({
+        start(controller) {
+            if (opts.signal?.aborted) {
+                controller.close();
+                void cleanup();
+                return;
+            }
+            if (opts.signal) {
+                abortHandler = () => {
+                    try {
+                        controller.close();
+                    }
+                    catch {
+                        /* already closed */
+                    }
+                    void cleanup();
+                };
+                opts.signal.addEventListener("abort", abortHandler, { once: true });
+            }
+        },
+        async pull(controller) {
+            try {
+                const { value, done } = await iterator.next();
+                if (done) {
+                    controller.close();
+                    await cleanup();
+                    return;
+                }
+                controller.enqueue(encodeNDJSON(value));
+            }
+            catch (err) {
+                controller.error(err);
+                await cleanup(err);
+            }
+        },
+        async cancel(reason) {
+            await cleanup(reason);
+        },
+    });
+}
+/**
+ * Wrap `ndjsonStream` in a `Response` with `application/x-ndjson` and
+ * cache-busting headers. Caller-supplied headers win.
+ */
+export function ndjsonResponse(source, opts = {}) {
+    const stream = ndjsonStream(source, opts);
+    const headers = new Headers(opts.headers);
+    if (!headers.has("content-type"))
+        headers.set("content-type", "application/x-ndjson; charset=utf-8");
+    if (!headers.has("cache-control"))
+        headers.set("cache-control", "no-cache, no-transform");
+    if (!headers.has("x-accel-buffering"))
+        headers.set("x-accel-buffering", "no");
+    return new Response(stream, { status: opts.status ?? 200, headers });
+}
+//# sourceMappingURL=streaming.js.map

package/dist/streaming.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daloyjs/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "DaloyJS is a runtime-portable, contract-first TypeScript web framework with built-in OpenAPI (Hey API), typed client generation, large-scale maintainability, and security-first defaults. Hono-grade portability, Elysia-grade DX, FastAPI-grade docs, Fastify-grade ops — distributed via pnpm.",
   "type": "module",
   "publishConfig": {
@@ -61,6 +61,10 @@
     "./contract": {
       "types": "./dist/contract.d.ts",
       "import": "./dist/contract.js"
+    },
+    "./streaming": {
+      "types": "./dist/streaming.d.ts",
+      "import": "./dist/streaming.js"
     }
   },
   "files": [