astro-routify 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -16,41 +16,187 @@ declare const ALLOWED_HTTP_METHODS: Set<string>;
  */
 declare function normalizeMethod(method: string): HttpMethod;
 
+/**
+ * A standardized shape for internal route result objects.
+ * These are later converted into native `Response` instances.
+ */
 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
+ */
 declare const ok: <T>(body: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 201 Created
+ */
 declare const created: <T>(body: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 204 No Content
+ */
 declare const noContent: (headers?: HeadersInit) => ResultResponse<undefined>;
+/**
+ * 304 Not Modified
+ */
 declare const notModified: (headers?: HeadersInit) => ResultResponse<undefined>;
+/**
+ * 400 Bad Request
+ */
 declare const badRequest: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 401 Unauthorized
+ */
 declare const unauthorized: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 403 Forbidden
+ */
 declare const forbidden: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 404 Not Found
+ */
 declare const notFound: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 405 Method Not Allowed
+ */
 declare const methodNotAllowed: <T = string>(body?: T, headers?: HeadersInit) => ResultResponse<T>;
+/**
+ * 500 Internal Server Error
+ */
 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
+ */
 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
+ */
 declare function toAstroResponse(result: ResultResponse | undefined): Response;
 
+/**
+ * A flexible route handler that can return:
+ * - a native `Response` object,
+ * - a structured `ResultResponse` object,
+ * - or a file stream (Blob, ArrayBuffer, or ReadableStream).
+ */
 type Handler = (ctx: APIContext) => Promise<ResultResponse | Response> | ResultResponse | Response;
+/**
+ * Wraps a `Handler` function into an `APIRoute` that:
+ * - logs requests and responses,
+ * - supports all valid `ResultResponse` return formats,
+ * - auto-converts structured responses into Astro `Response`s,
+ * - handles errors with standardized 500 output.
+ *
+ * @param handler - A handler function returning a `Response` or `ResultResponse`
+ * @returns An Astro-compatible `APIRoute` function
+ */
 declare function defineHandler(handler: Handler): APIRoute;
+/**
+ * Type guard to detect ReadableStreams, used for streamed/binary responses.
+ *
+ * @param value - Any value to test
+ * @returns True if it looks like a ReadableStream
+ */
 declare function isReadableStream(value: unknown): value is ReadableStream<Uint8Array>;
 
+/**
+ * Represents a single route definition.
+ */
 interface Route {
+    /**
+     * HTTP method to match (GET, POST, PUT, etc.).
+     */
     method: HttpMethod;
+    /**
+     * Path pattern, starting with `/`, supporting static or param segments (e.g., `/users/:id`).
+     */
     path: string;
+    /**
+     * The function that handles the request when matched.
+     */
     handler: Handler;
 }
+/**
+ * Defines a route using a `Route` object.
+ *
+ * @example
+ * defineRoute({ method: 'GET', path: '/users', handler });
+ *
+ * @param route - A fully constructed route object
+ * @returns The validated Route object
+ */
 declare function defineRoute(route: Route): Route;
+/**
+ * Defines a route by specifying its method, path, and handler explicitly.
+ *
+ * @example
+ * defineRoute('POST', '/login', handler);
+ *
+ * @param method - HTTP method to match
+ * @param path - Route path (must start with `/`)
+ * @param handler - Function to handle the matched request
+ * @returns The validated Route object
+ */
 declare function defineRoute(method: HttpMethod, path: string, handler: Handler): Route;
 
+/**
+ * Optional configuration for the router instance.
+ */
 interface RouterOptions {
+    /**
+     * A base path to strip from the incoming request path (default: `/api`).
+     * Only routes beneath this prefix will be matched.
+     */
     basePath?: string;
-    /** Custom 404 handler */
+    /**
+     * Custom handler to return when no route is matched (404).
+     */
     onNotFound?: () => ReturnType<typeof notFound>;
 }
+/**
+ * Defines a router that dynamically matches registered routes based on method and path.
+ *
+ * This allows building a clean, centralized API routing system with features like:
+ * - Trie-based fast route lookup
+ * - Per-method matching with 405 fallback
+ * - Parameter extraction (e.g. `/users/:id`)
+ * - Customizable basePath and 404 behavior
+ *
+ * @example
+ * defineRouter([
+ *   defineRoute('GET', '/users', handler),
+ *   defineRoute('POST', '/login', loginHandler),
+ * ], {
+ *   basePath: '/api',
+ *   onNotFound: () => notFound('No such route')
+ * });
+ *
+ * @param routes - An array of route definitions (see `defineRoute`)
+ * @param options - Optional router config (basePath, custom 404)
+ * @returns An Astro-compatible APIRoute handler
+ */
 declare function defineRouter(routes: Route[], options?: RouterOptions): APIRoute;
 
 /**
@@ -267,5 +413,167 @@ declare class RouterBuilder {
     build(): astro.APIRoute;
 }
 
-export { ALLOWED_HTTP_METHODS, HttpMethod, RouteGroup, RouteTrie, RouterBuilder, badRequest, created, defineGroup, defineHandler, defineRoute, defineRouter, fileResponse, forbidden, internalError, isReadableStream, methodNotAllowed, noContent, normalizeMethod, notFound, notModified, ok, toAstroResponse, unauthorized };
-export type { Handler, ResultResponse, Route, RouterOptions };
+/**
+ * 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.
+ */
+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.
+ */
+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()`
+ */
+declare function stream(path: string, handler: (ctx: APIContext & {
+    response: StreamWriter;
+}) => void | Promise<void>, options?: StreamOptions): Route;
+
+type JsonValue = any;
+/**
+ * A writer interface for streaming JSON data to the response body.
+ * Supports both NDJSON and array formats.
+ */
+interface JsonStreamWriter {
+    /**
+     * Send a JSON-serializable value to the response stream.
+     * - In `ndjson` mode: appends a newline after each object.
+     * - In `array` mode: adds commas and wraps with brackets.
+     * @param value - Any serializable object or array item
+     */
+    send: (value: JsonValue) => void;
+    /**
+     * Write raw text or bytes to the stream.
+     * Used for low-level control if needed.
+     */
+    write: (chunk: string | Uint8Array) => void;
+    /**
+     * Close the stream. In `array` mode, it writes the closing `]`.
+     */
+    close: () => void;
+    /**
+     * Override response headers dynamically before the response is sent.
+     * Only safe before the first write.
+     * @param key - Header name
+     * @param value - Header value
+     */
+    setHeader: (key: string, value: string) => void;
+}
+
+/**
+ * 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`
+ */
+declare function streamJsonND(path: string, handler: (ctx: APIContext & {
+    response: JsonStreamWriter;
+}) => void | Promise<void>, options?: {
+    method?: HttpMethod;
+}): Route;
+
+/**
+ * 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`
+ */
+declare function streamJsonArray(path: string, handler: (ctx: APIContext & {
+    response: JsonStreamWriter;
+}) => void | Promise<void>, options?: {
+    method?: HttpMethod;
+}): Route;
+
+export { ALLOWED_HTTP_METHODS, HttpMethod, RouteGroup, RouteTrie, RouterBuilder, badRequest, created, defineGroup, defineHandler, defineRoute, defineRouter, fileResponse, forbidden, internalError, isReadableStream, methodNotAllowed, noContent, normalizeMethod, notFound, notModified, ok, stream, streamJsonArray, streamJsonND, toAstroResponse, unauthorized };
+export type { Handler, JsonStreamWriter, ResultResponse, Route, RouterOptions, StreamOptions, StreamWriter };

package/dist/index.js

@@ -6,3 +6,6 @@ export * from './core/RouteTrie';
 export * from './core/HttpMethod';
 export * from './core/responseHelpers';
 export * from './core/RouterBuilder';
+export * from './core/stream';
+export * from './core/streamJsonND';
+export * from './core/streamJsonArray';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-routify",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A high-performance API router for Astro using a Trie-based matcher.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,13 +16,19 @@
   ],
   "keywords": [
     "astro",
-    "router",
+    "astrojs",
     "api-router",
-    "typescript",
+    "router",
     "routing",
-    "astrojs",
+    "typescript",
     "esm",
-    "trie"
+    "trie",
+    "streaming",
+    "sse",
+    "ndjson",
+    "json-stream",
+    "response-helpers",
+    "astro-api"
   ],
   "author": "Alex Mora",
   "license": "MIT",