astro-routify 1.1.0 → 1.2.1

package/dist/core/internal/createJsonStreamRoute.js

@@ -0,0 +1,92 @@
+import { defineRoute } from '../defineRoute';
+/**
+ * Creates a streaming JSON route that supports both NDJSON and JSON array formats.
+ *
+ * - Sets appropriate `Content-Type` headers
+ * - Supports cancellation via `AbortSignal`
+ * - Provides a `response` object with `send`, `close`, `write`, `setHeader` methods
+ *
+ * Use this function inside `streamJsonND()` or `streamJsonArray()` to avoid duplication.
+ *
+ * @param path - The route path (e.g. `/logs`)
+ * @param handler - A function that receives Astro `ctx` and a `JsonStreamWriter`
+ * @param options - Streaming options (`mode`, `method`)
+ * @returns A streaming-compatible Route
+ */
+export function createJsonStreamRoute(path, handler, options) {
+    const isNDJSON = options.mode === 'ndjson';
+    return defineRoute(options.method, path, async (ctx) => {
+        const encoder = new TextEncoder();
+        let controllerRef = null;
+        let closed = false;
+        let first = true;
+        const headers = {
+            'Content-Type': isNDJSON ? 'application/x-ndjson; charset=utf-8' : 'application/json; charset=utf-8',
+            ...(isNDJSON ? { 'Cache-Control': 'no-cache', 'X-Accel-Buffering': 'no' } : {}),
+        };
+        const enqueueArray = (chunk) => {
+            if (!controllerRef)
+                return;
+            if (first) {
+                controllerRef.enqueue(encoder.encode('[' + chunk));
+                first = false;
+            }
+            else {
+                controllerRef.enqueue(encoder.encode(',' + chunk));
+            }
+        };
+        const writer = {
+            send(value) {
+                if (closed || !controllerRef)
+                    return;
+                const json = JSON.stringify(value);
+                if (isNDJSON) {
+                    controllerRef.enqueue(encoder.encode(json + '\n'));
+                }
+                else {
+                    enqueueArray(json);
+                }
+            },
+            write(chunk) {
+                if (closed || !controllerRef)
+                    return;
+                const encoded = typeof chunk === 'string' ? encoder.encode(chunk) : chunk;
+                controllerRef.enqueue(encoded);
+            },
+            close() {
+                if (closed)
+                    return;
+                if (!isNDJSON && controllerRef && !first) {
+                    controllerRef.enqueue(encoder.encode(']'));
+                }
+                closed = true;
+                controllerRef?.close();
+            },
+            setHeader(key, value) {
+                headers[key] = value;
+            },
+        };
+        const body = new ReadableStream({
+            start(controller) {
+                controllerRef = controller;
+                ctx.request.signal.addEventListener('abort', () => {
+                    closed = true;
+                    controllerRef?.close();
+                });
+                Promise.resolve(handler({ ...ctx, response: writer })).catch((err) => {
+                    try {
+                        controller.error(err);
+                    }
+                    catch { /* noop */ }
+                });
+            },
+            cancel() {
+                closed = true;
+            },
+        });
+        return new Response(body, {
+            status: 200,
+            headers,
+        });
+    });
+}

package/dist/core/responseHelpers.d.ts

@@ -1,18 +1,79 @@
-import { BodyInit, HeadersInit } from "undici";
+import { BodyInit, HeadersInit } from 'undici';
+/**
+ * A standardized shape for internal route result objects.
+ * These are later converted into native `Response` instances.
+ */
 export interface ResultResponse<T = unknown> {
+    /**
+     * Optional body content (can be a string, object, or binary).
+     */
     body?: T;
+    /**
+     * HTTP status code (e.g. 200, 404, 500).
+     */
     status: number;
+    /**
+     * Optional response headers.
+     */
     headers?: HeadersInit;
 }
+/**
+ * 200 OK
+ */
 export declare const ok: <T>(body: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 201 Created
+ */
 export declare const created: <T>(body: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 204 No Content
+ */
 export declare const noContent: (headers?: HeadersInit) => ResultResponse<undefined>;
+/**
+ * 304 Not Modified
+ */
 export declare const notModified: (headers?: HeadersInit) => ResultResponse<undefined>;
+/**
+ * 400 Bad Request
+ */
 export declare const badRequest: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 401 Unauthorized
+ */
 export declare const unauthorized: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 403 Forbidden
+ */
 export declare const forbidden: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 404 Not Found
+ */
 export declare const notFound: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 405 Method Not Allowed
+ */
 export declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 500 Internal Server Error
+ */
 export declare const internalError: (err: unknown, headers?: HeadersInit) => ResultResponse<string>;
+/**
+ * Sends a binary or stream-based file response with optional content-disposition.
+ *
+ * @param content - The file data (Blob, ArrayBuffer, or stream)
+ * @param contentType - MIME type of the file
+ * @param fileName - Optional download filename
+ * @param headers - Optional extra headers
+ * @returns A ResultResponse for download-ready content
+ */
 export declare const fileResponse: (content: Blob | ArrayBuffer | ReadableStream<Uint8Array>, contentType: string, fileName?: string, headers?: HeadersInit) => ResultResponse<BodyInit>;
+/**
+ * Converts an internal `ResultResponse` into a native `Response` object
+ * for use inside Astro API routes.
+ *
+ * Automatically applies `Content-Type: application/json` for object bodies.
+ *
+ * @param result - A ResultResponse returned from route handler
+ * @returns A native Response
+ */
 export declare function toAstroResponse(result: ResultResponse | undefined): Response;

package/dist/core/responseHelpers.js

@@ -1,16 +1,61 @@
+/**
+ * Internal helper to build a typed `ResultResponse`.
+ * @param status - HTTP status code
+ * @param body - Optional response body
+ * @param headers - Optional headers
+ */
 function createResponse(status, body, headers) {
     return { status, body, headers };
 }
+/**
+ * 200 OK
+ */
 export const ok = (body, headers) => createResponse(200, body, headers);
+/**
+ * 201 Created
+ */
 export const created = (body, headers) => createResponse(201, body, headers);
+/**
+ * 204 No Content
+ */
 export const noContent = (headers) => createResponse(204, undefined, headers);
+/**
+ * 304 Not Modified
+ */
 export const notModified = (headers) => createResponse(304, undefined, headers);
+/**
+ * 400 Bad Request
+ */
 export const badRequest = (body = 'Bad Request', headers) => createResponse(400, body, headers);
+/**
+ * 401 Unauthorized
+ */
 export const unauthorized = (body = 'Unauthorized', headers) => createResponse(401, body, headers);
+/**
+ * 403 Forbidden
+ */
 export const forbidden = (body = 'Forbidden', headers) => createResponse(403, body, headers);
+/**
+ * 404 Not Found
+ */
 export const notFound = (body = 'Not Found', headers) => createResponse(404, body, headers);
+/**
+ * 405 Method Not Allowed
+ */
 export const methodNotAllowed = (body = 'Method Not Allowed', headers) => createResponse(405, body, headers);
+/**
+ * 500 Internal Server Error
+ */
 export const internalError = (err, headers) => createResponse(500, err instanceof Error ? err.message : String(err), headers);
+/**
+ * Sends a binary or stream-based file response with optional content-disposition.
+ *
+ * @param content - The file data (Blob, ArrayBuffer, or stream)
+ * @param contentType - MIME type of the file
+ * @param fileName - Optional download filename
+ * @param headers - Optional extra headers
+ * @returns A ResultResponse for download-ready content
+ */
 export const fileResponse = (content, contentType, fileName, headers) => {
     const disposition = fileName
         ? { 'Content-Disposition': `attachment; filename="${fileName}"` }
@@ -25,6 +70,15 @@ export const fileResponse = (content, contentType, fileName, headers) => {
         },
     };
 };
+/**
+ * Converts an internal `ResultResponse` into a native `Response` object
+ * for use inside Astro API routes.
+ *
+ * Automatically applies `Content-Type: application/json` for object bodies.
+ *
+ * @param result - A ResultResponse returned from route handler
+ * @returns A native Response
+ */
 export function toAstroResponse(result) {
     if (!result)
         return new Response(null, { status: 204 });

package/dist/core/stream.d.ts

@@ -0,0 +1,75 @@
+import type { APIContext } from 'astro';
+import { type Route } from './defineRoute';
+import { HttpMethod } from './HttpMethod';
+import { HeadersInit } from 'undici';
+/**
+ * A writer for streaming raw data to the response body.
+ *
+ * This is used inside the `stream()` route handler to emit bytes
+ * or strings directly to the client with backpressure awareness.
+ */
+export interface StreamWriter {
+    /**
+     * Write a string or Uint8Array chunk to the response stream.
+     * @param chunk - Text or byte chunk to emit
+     */
+    write: (chunk: string | Uint8Array) => void;
+    /**
+     * Close the stream and signal end-of-response to the client.
+     */
+    close: () => void;
+    /**
+     * Dynamically change the Content-Type header.
+     * Should be called before the first `write()` to take effect.
+     * @param type - MIME type (e.g., `text/html`, `application/json`)
+     */
+    setContentType: (type: string) => void;
+}
+/**
+ * Configuration options for the `stream()` route helper.
+ */
+export interface StreamOptions {
+    /**
+     * HTTP method (defaults to GET).
+     */
+    method?: HttpMethod;
+    /**
+     * Content-Type header (defaults to `text/event-stream`).
+     */
+    contentType?: string;
+    /**
+     * Additional custom headers.
+     */
+    headers?: HeadersInit;
+    /**
+     * Enable SSE keep-alive headers (defaults to true for SSE).
+     */
+    keepAlive?: boolean;
+}
+/**
+ * Defines a generic streaming route that can write raw chunks of data
+ * to the response in real time using a `ReadableStream`.
+ *
+ * Suitable for Server-Sent Events (SSE), long-polling, streamed HTML,
+ * logs, LLM output, or NDJSON responses.
+ *
+ * @example
+ * stream('/clock', async ({ response }) => {
+ *   const timer = setInterval(() => {
+ *     response.write(`data: ${new Date().toISOString()}\n\n`);
+ *   }, 1000);
+ *
+ *   setTimeout(() => {
+ *     clearInterval(timer);
+ *     response.close();
+ *   }, 5000);
+ * });
+ *
+ * @param path - The route path (e.g. `/clock`)
+ * @param handler - Handler that receives the API context and response writer
+ * @param options - Optional stream configuration
+ * @returns A Route object ready to be used in `defineRouter()`
+ */
+export declare function stream(path: string, handler: (ctx: APIContext & {
+    response: StreamWriter;
+}) => void | Promise<void>, options?: StreamOptions): Route;

package/dist/core/stream.js

@@ -0,0 +1,93 @@
+import { defineRoute } from './defineRoute';
+import { HttpMethod } from './HttpMethod';
+/**
+ * Defines a generic streaming route that can write raw chunks of data
+ * to the response in real time using a `ReadableStream`.
+ *
+ * Suitable for Server-Sent Events (SSE), long-polling, streamed HTML,
+ * logs, LLM output, or NDJSON responses.
+ *
+ * @example
+ * stream('/clock', async ({ response }) => {
+ *   const timer = setInterval(() => {
+ *     response.write(`data: ${new Date().toISOString()}\n\n`);
+ *   }, 1000);
+ *
+ *   setTimeout(() => {
+ *     clearInterval(timer);
+ *     response.close();
+ *   }, 5000);
+ * });
+ *
+ * @param path - The route path (e.g. `/clock`)
+ * @param handler - Handler that receives the API context and response writer
+ * @param options - Optional stream configuration
+ * @returns A Route object ready to be used in `defineRouter()`
+ */
+export function stream(path, handler, options) {
+    const method = options?.method ?? HttpMethod.GET;
+    return defineRoute(method, path, async (ctx) => {
+        let contentType = options?.contentType ?? 'text/event-stream';
+        const encoder = new TextEncoder();
+        let controllerRef = null;
+        let closed = false;
+        const writer = {
+            write: (chunk) => {
+                if (closed || !controllerRef)
+                    return;
+                const bytes = typeof chunk === 'string' ?
+                    encoder.encode(`data: ${chunk}\n\n`)
+                    : chunk;
+                controllerRef.enqueue(bytes);
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                try {
+                    controllerRef?.close();
+                }
+                catch { /* noop */ }
+            },
+            setContentType: (type) => {
+                contentType = type;
+            },
+        };
+        const body = new ReadableStream({
+            start(controller) {
+                controllerRef = controller;
+                Promise.resolve(handler({ ...ctx, response: writer }))
+                    .catch((err) => {
+                    try {
+                        controller.error(err);
+                    }
+                    catch { /* noop */ }
+                });
+                ctx.request.signal.addEventListener('abort', () => {
+                    closed = true;
+                    controller.close();
+                    console.debug('Request aborted — streaming stopped.');
+                });
+            },
+            cancel() {
+                closed = true;
+                console.debug('Stream cancelled explicitly.');
+            },
+        });
+        const defaultSseHeaders = contentType === 'text/event-stream' && options?.keepAlive !== false
+            ? {
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+                'X-Accel-Buffering': 'no',
+            }
+            : {};
+        return new Response(body, {
+            status: 200,
+            headers: {
+                'Content-Type': contentType,
+                ...defaultSseHeaders,
+                ...(options?.headers ?? {}),
+            },
+        });
+    });
+}

package/dist/core/streamJsonArray.d.ts

@@ -0,0 +1,31 @@
+import type { APIContext } from 'astro';
+import { HttpMethod } from './HttpMethod';
+import { Route } from './defineRoute';
+import { JsonStreamWriter } from './internal/createJsonStreamRoute';
+/**
+ * Defines a JSON streaming route that emits a valid JSON array.
+ *
+ * This helper returns a valid `application/json` response containing
+ * a streamable array of JSON values. Useful for large data exports
+ * or APIs where the full array can be streamed as it's generated.
+ *
+ * Unlike `streamJsonND()`, this wraps all values in `[` and `]`
+ * and separates them with commas.
+ *
+ * @example
+ * streamJsonArray('/users', async ({ response }) => {
+ *   response.send({ id: 1 });
+ *   response.send({ id: 2 });
+ *   response.close();
+ * });
+ *
+ * @param path - The route path (e.g. `/users`)
+ * @param handler - A function that receives `ctx` and a JSON stream writer
+ * @param options - Optional HTTP method override (default is GET)
+ * @returns A Route object ready to be registered with `defineRouter`
+ */
+export declare function streamJsonArray(path: string, handler: (ctx: APIContext & {
+    response: JsonStreamWriter;
+}) => void | Promise<void>, options?: {
+    method?: HttpMethod;
+}): Route;

package/dist/core/streamJsonArray.js

@@ -0,0 +1,30 @@
+import { HttpMethod } from './HttpMethod';
+import { createJsonStreamRoute } from './internal/createJsonStreamRoute';
+/**
+ * Defines a JSON streaming route that emits a valid JSON array.
+ *
+ * This helper returns a valid `application/json` response containing
+ * a streamable array of JSON values. Useful for large data exports
+ * or APIs where the full array can be streamed as it's generated.
+ *
+ * Unlike `streamJsonND()`, this wraps all values in `[` and `]`
+ * and separates them with commas.
+ *
+ * @example
+ * streamJsonArray('/users', async ({ response }) => {
+ *   response.send({ id: 1 });
+ *   response.send({ id: 2 });
+ *   response.close();
+ * });
+ *
+ * @param path - The route path (e.g. `/users`)
+ * @param handler - A function that receives `ctx` and a JSON stream writer
+ * @param options - Optional HTTP method override (default is GET)
+ * @returns A Route object ready to be registered with `defineRouter`
+ */
+export function streamJsonArray(path, handler, options) {
+    return createJsonStreamRoute(path, handler, {
+        mode: 'array',
+        method: options?.method ?? HttpMethod.GET,
+    });
+}

package/dist/core/streamJsonND.d.ts

@@ -0,0 +1,34 @@
+import type { APIContext } from 'astro';
+import { HttpMethod } from './HttpMethod';
+import { Route } from './defineRoute';
+import { JsonStreamWriter } from './internal/createJsonStreamRoute';
+/**
+ * Defines a JSON streaming route using NDJSON (Newline Delimited JSON) format.
+ *
+ * This helper streams individual JSON objects separated by newlines (`\n`)
+ * instead of a single JSON array. It sets the `Content-Type` to
+ * `application/x-ndjson` and disables buffering to allow low-latency
+ * delivery of each item.
+ *
+ * Ideal for real-time updates, event logs, progressive loading, or
+ * integrations with LLMs or dashboards where each object can be processed
+ * as soon as it's received.
+ *
+ * @example
+ * streamJsonND('/events', async ({ response }) => {
+ *   response.send({ type: 'start' });
+ *   await delay(100);
+ *   response.send({ type: 'progress', percent: 25 });
+ *   response.close();
+ * });
+ *
+ * @param path - The route path (e.g. `/events`)
+ * @param handler - A function that receives `ctx` and a JSON stream writer
+ * @param options - Optional HTTP method override (default is GET)
+ * @returns A Route object ready to be registered with `defineRouter`
+ */
+export declare function streamJsonND(path: string, handler: (ctx: APIContext & {
+    response: JsonStreamWriter;
+}) => void | Promise<void>, options?: {
+    method?: HttpMethod;
+}): Route;

package/dist/core/streamJsonND.js

@@ -0,0 +1,33 @@
+import { HttpMethod } from './HttpMethod';
+import { createJsonStreamRoute } from './internal/createJsonStreamRoute';
+/**
+ * Defines a JSON streaming route using NDJSON (Newline Delimited JSON) format.
+ *
+ * This helper streams individual JSON objects separated by newlines (`\n`)
+ * instead of a single JSON array. It sets the `Content-Type` to
+ * `application/x-ndjson` and disables buffering to allow low-latency
+ * delivery of each item.
+ *
+ * Ideal for real-time updates, event logs, progressive loading, or
+ * integrations with LLMs or dashboards where each object can be processed
+ * as soon as it's received.
+ *
+ * @example
+ * streamJsonND('/events', async ({ response }) => {
+ *   response.send({ type: 'start' });
+ *   await delay(100);
+ *   response.send({ type: 'progress', percent: 25 });
+ *   response.close();
+ * });
+ *
+ * @param path - The route path (e.g. `/events`)
+ * @param handler - A function that receives `ctx` and a JSON stream writer
+ * @param options - Optional HTTP method override (default is GET)
+ * @returns A Route object ready to be registered with `defineRouter`
+ */
+export function streamJsonND(path, handler, options) {
+    return createJsonStreamRoute(path, handler, {
+        mode: 'ndjson',
+        method: options?.method ?? HttpMethod.GET,
+    });
+}