exisjs 0.7.6 → 0.7.8

package/dist/server/response.js

@@ -8,30 +8,11 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const index_1 = require("../logger/index");
 const sse_1 = require("./sse");
+const helpers_1 = require("./helpers");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const contentDisposition = require('content-disposition');
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const mime = require('mime-types');
-const rs_1 = require("@exisjs/rs");
-function generateETag(content) {
-    return (0, rs_1.generateEtag)(content);
-}
-function nativeStringify(data) {
-    if (data === null || data === undefined) {
-        return 'null';
-    }
-    // If native rust serialization is available, use it
-    if (typeof rs_1.fastJsonStringifyBuffer === 'function') {
-        // Validate object can be serialized without throwing V8 check failure on circularity
-        const str = JSON.stringify(data);
-        if (str.length > 512) {
-            // For larger payloads, Rust serde serialization into Buffer gives zero V8 GC overhead
-            return (0, rs_1.fastJsonStringifyBuffer)(data);
-        }
-        return str;
-    }
-    return JSON.stringify(data);
-}
 class ExisResponse {
     constructor(raw) {
         this.raw = raw;
@@ -96,11 +77,15 @@ class ExisResponse {
         }
     }
     /**
-     * Set status `code`.
+     * Sets the HTTP response status code.
+     *
+     * @param code HTTP status code (e.g. `200`, `201`, `400`, `404`, `500`)
+     * @returns Response instance for chaining
      *
-     * @param {number} code
-     * @return {this}
-     * @public
+     * @example
+     * ```ts
+     * res.status(201).json({ created: true })
+     * ```
      */
     status(code) {
         if (this.raw.destroyed || this.raw.headersSent)
@@ -109,51 +94,24 @@ class ExisResponse {
         return this;
     }
     /**
-     * Set header `field` to `val`, or pass
-     * an object of header fields.
-     *
-     * Examples:
-     *
-     *    res.set('Foo', ['bar', 'baz']);
-     *    res.set('Accept', 'application/json');
+     * Sets a response header field to a specific value.
      *
-     * Aliased as `res.header()`.
-     *
-     * @param {string} header
-     * @param {string | string[]} value
-     * @return {this}
-     * @public
+     * @param header Header name
+     * @param value Header value or array of values
+     * @returns Response instance for chaining
      */
     set(header, value) {
         this.setHeader(header, value);
         return this;
     }
     /**
-     * Set header `field` to `val`, or pass
-     * an object of header fields.
-     *
-     * Alias for `res.set()`.
-     *
-     * @param {string} name
-     * @param {string | string[]} value
-     * @return {this}
-     * @public
+     * Sets a response header field (alias for `res.set()`).
      */
     header(name, value) {
         return this.set(name, value);
     }
     /**
-     * Send given HTTP status code.
-     *
-     * Sets the response status to `code` and the body
-     * to the string representation of the `code`.
-     *
-     * Examples:
-     *
-     *     res.sendStatus(200);
-     *
-     * @param {number} code
-     * @public
+     * Sets status code and sends its numeric string representation.
      */
     sendStatus(code) {
         this.statusCode = code;
@@ -170,18 +128,7 @@ class ExisResponse {
         return this;
     }
     /**
-     * Append additional header `field` with value `val`.
-     *
-     * Example:
-     *
-     *    res.append('Link', ['<http://localhost/>', '<http://localhost:3000/>']);
-     *    res.append('Set-Cookie', 'foo=bar; Path=/; HttpOnly');
-     *    res.append('Warning', '199 Miscellaneous warning');
-     *
-     * @param {string} field
-     * @param {string | string[]} value
-     * @return {this}
-     * @public
+     * Appends an additional value to an existing header field (e.g. `Set-Cookie`, `Link`, `Warning`).
      */
     append(field, value) {
         const prev = this.getHeader(field);
@@ -195,16 +142,14 @@ class ExisResponse {
         return this;
     }
     /**
-     * Send a response.
-     *
-     * Examples:
+     * Sends a string, Buffer, or object response to the client.
      *
-     *     res.send(Buffer.from('wahoo'));
-     *     res.send({ some: 'json' });
-     *     res.send('<p>some html</p>');
+     * @param body Response payload (string, Buffer, or object)
      *
-     * @param {string | Buffer | object} body
-     * @public
+     * @example
+     * ```ts
+     * res.send('Hello World')
+     * ```
      */
     send(body) {
         if (!this.isWritable)
@@ -221,7 +166,7 @@ class ExisResponse {
             const buf = isBuffer
                 ? body
                 : Buffer.from(body, 'utf8');
-            this.raw.setHeader('ETag', generateETag(buf));
+            this.raw.setHeader('ETag', (0, helpers_1.generateETag)(buf));
         }
         if (this.req &&
             (this.raw.hasHeader('ETag') || this.raw.hasHeader('Last-Modified')) &&
@@ -230,23 +175,20 @@ class ExisResponse {
             this.end();
             return;
         }
-        // Rely on Node.js core to automatically calculate Content-Length
-        // for strings in res.end() rather than creating a Buffer here.
         if (isBuffer && !this.raw.hasHeader('Content-Length')) {
             this.raw.setHeader('Content-Length', body.length);
         }
         this.end(body);
     }
     /**
-     * Send JSON response.
+     * Sends a JSON response with automatic native serialization and fast ETag support.
      *
-     * Examples:
+     * @param data JSON-serializable data payload
      *
-     *     res.json(null);
-     *     res.json({ user: 'tj' });
-     *
-     * @param {unknown} data
-     * @public
+     * @example
+     * ```ts
+     * res.json({ success: true, users: ['Alice', 'Bob'] })
+     * ```
      */
     json(data) {
         if (!this.isWritable)
@@ -254,7 +196,7 @@ class ExisResponse {
         let payload;
         try {
             const useSerializer = this._serializer && this.statusCode < 400;
-            payload = useSerializer ? this._serializer(data) : nativeStringify(data);
+            payload = useSerializer ? this._serializer(data) : (0, helpers_1.nativeStringify)(data);
         }
         catch (err) {
             if (this.req && this.req.log) {
@@ -275,7 +217,7 @@ class ExisResponse {
             const buf = Buffer.isBuffer(payload)
                 ? payload
                 : Buffer.from(payload, 'utf8');
-            this.raw.setHeader('ETag', generateETag(buf));
+            this.raw.setHeader('ETag', (0, helpers_1.generateETag)(buf));
         }
         if (this.req &&
             (this.raw.hasHeader('ETag') || this.raw.hasHeader('Last-Modified')) &&
@@ -287,14 +229,14 @@ class ExisResponse {
         this.end(payload);
     }
     /**
-     * Send HTML response.
-     *
-     * Examples:
+     * Sends an HTML response with `Content-Type: text/html; charset=utf-8`.
      *
-     *     res.html('<h1>Hello</h1>');
+     * @param content HTML string
      *
-     * @param {string} content
-     * @public
+     * @example
+     * ```ts
+     * res.html('<h1>Welcome to ExisJS</h1>')
+     * ```
      */
     html(content) {
         if (!this.isWritable)
@@ -305,18 +247,15 @@ class ExisResponse {
         this.end(content);
     }
     /**
-     * Redirect to the given `url` with optional response `status`
-     * defaulting to 302.
-     *
-     * Examples:
+     * Performs an HTTP redirect to a given URL with an optional status code (defaults to 302).
      *
-     *     res.redirect('/foo/bar');
-     *     res.redirect('http://example.com');
-     *     res.redirect('http://example.com', 301);
+     * @param url Target destination URL
+     * @param code HTTP status code (`301` Moved Permanently, `302` Found, `307` Temporary Redirect, `308` Permanent Redirect)
      *
-     * @param {string} url
-     * @param {number} [code=302]
-     * @public
+     * @example
+     * ```ts
+     * res.redirect('/login')
+     * ```
      */
     redirect(url, code = 302) {
         if (!this.isWritable)
@@ -326,197 +265,21 @@ class ExisResponse {
         this.end();
     }
     /**
-     * Stream a Node.js Readable stream, Web standard ReadableStream, or AsyncIterable
-     * to the client with native HTTP backpressure handling and automatic cancellation
-     * if the client disconnects prematurely.
+     * Streams a Node.js Readable stream, Web standard `ReadableStream`, or `AsyncIterable` generator
+     * to the client with native backpressure handling and client disconnect auto-cancellation.
+     *
+     * @param readable Stream or async generator instance
+     *
+     * @example
+     * ```ts
+     * // Streaming from an AI SDK or Web stream:
+     * res.sendStream(aiResponse.toReadableStream())
+     * ```
      */
     sendStream(readable) {
-        if (!this.isWritable) {
-            if (typeof readable.destroy === 'function') {
-                ;
-                readable.destroy();
-            }
-            else if (typeof readable.cancel === 'function') {
-                ;
-                readable.cancel().catch(() => {
-                    /* ignore */
-                });
-            }
-            return;
-        }
-        if (!this.hasHeader('Content-Type')) {
-            this.setHeader('Content-Type', 'application/octet-stream');
-        }
-        // 1. Web Standard ReadableStream (e.g. from fetch, OpenAI, Anthropic, AI SDKs)
-        if (typeof readable.getReader === 'function') {
-            const reader = readable.getReader();
-            let closed = false;
-            const cleanup = () => {
-                if (closed)
-                    return;
-                closed = true;
-                try {
-                    reader.cancel().catch(() => {
-                        /* ignore */
-                    });
-                }
-                catch {
-                    // ignore
-                }
-            };
-            this.raw.once('close', cleanup);
-            if (this.req && this.req.raw) {
-                ;
-                this.req.raw.once('close', cleanup);
-                this.req.raw.once('aborted', cleanup);
-            }
-            ;
-            (async () => {
-                try {
-                    while (true) {
-                        if (closed || this.raw.destroyed) {
-                            cleanup();
-                            break;
-                        }
-                        const { done, value } = await reader.read();
-                        if (done) {
-                            this.raw.removeListener('close', cleanup);
-                            if (!this.raw.writableEnded && !this.raw.destroyed) {
-                                this.end();
-                            }
-                            break;
-                        }
-                        if (value !== undefined && value !== null) {
-                            const ok = this.raw.write(value);
-                            if (!ok && !this.raw.destroyed && !this.raw.writableEnded) {
-                                await new Promise((resolve) => this.raw.once('drain', resolve));
-                            }
-                        }
-                    }
-                }
-                catch (err) {
-                    cleanup();
-                    if (this.req && this.req.log) {
-                        this.req.log.error({ err }, '[ExisJS] Error in Web ReadableStream');
-                    }
-                    else {
-                        index_1.logger.error({ err }, '[ExisJS] Error in Web ReadableStream');
-                    }
-                    if (this.isWritable && !this.headersSent) {
-                        this.statusCode = 500;
-                        this.end('{"error":"Stream transmission failed"}');
-                    }
-                    else if (!this.raw.destroyed) {
-                        this.raw.destroy(err);
-                    }
-                }
-            })();
-            return;
-        }
-        // 2. AsyncIterable / Generator stream
-        if (typeof readable[Symbol.asyncIterator] === 'function' &&
-            typeof readable.pipe !== 'function') {
-            let closed = false;
-            const cleanup = () => {
-                closed = true;
-                if (typeof readable.return === 'function') {
-                    ;
-                    readable.return().catch(() => {
-                        /* ignore */
-                    });
-                }
-            };
-            this.raw.once('close', cleanup);
-            if (this.req && this.req.raw) {
-                ;
-                this.req.raw.once('close', cleanup);
-            }
-            ;
-            (async () => {
-                try {
-                    for await (const chunk of readable) {
-                        if (closed || this.raw.destroyed)
-                            break;
-                        if (chunk !== undefined && chunk !== null) {
-                            const payload = typeof chunk === 'string' || Buffer.isBuffer(chunk)
-                                ? chunk
-                                : JSON.stringify(chunk);
-                            const ok = this.raw.write(payload);
-                            if (!ok && !this.raw.destroyed && !this.raw.writableEnded) {
-                                await new Promise((resolve) => this.raw.once('drain', resolve));
-                            }
-                        }
-                    }
-                    this.raw.removeListener('close', cleanup);
-                    if (!this.raw.writableEnded && !this.raw.destroyed) {
-                        this.end();
-                    }
-                }
-                catch (err) {
-                    cleanup();
-                    if (this.req && this.req.log) {
-                        this.req.log.error({ err }, '[ExisJS] Error in AsyncIterable stream');
-                    }
-                    else {
-                        index_1.logger.error({ err }, '[ExisJS] Error in AsyncIterable stream');
-                    }
-                    if (this.isWritable && !this.headersSent) {
-                        this.statusCode = 500;
-                        this.end('{"error":"Stream transmission failed"}');
-                    }
-                    else if (!this.raw.destroyed) {
-                        this.raw.destroy(err);
-                    }
-                }
-            })();
-            return;
-        }
-        // 3. Standard Node.js Readable Stream
-        const cleanup = () => {
-            if (typeof readable.destroy === 'function' &&
-                !readable.destroyed) {
-                ;
-                readable.destroy();
-            }
-        };
-        // Auto-destroy stream if client aborts or response closes early
-        this.raw.once('close', cleanup);
-        if (this.req && this.req.raw) {
-            ;
-            this.req.raw.once('close', cleanup);
-            this.req.raw.once('aborted', cleanup);
-        }
-        // Handle stream error to prevent process crash
-        if (typeof readable.on === 'function') {
-            ;
-            readable.once('error', (err) => {
-                this.raw.removeListener('close', cleanup);
-                if (this.req && this.req.log) {
-                    this.req.log.error({ err }, '[ExisJS] Error in sendStream');
-                }
-                else {
-                    index_1.logger.error({ err }, '[ExisJS] Error in sendStream');
-                }
-                if (this.isWritable && !this.headersSent) {
-                    this.statusCode = 500;
-                    this.end('{"error":"Stream transmission failed"}');
-                }
-                else {
-                    cleanup();
-                    if (!this.raw.destroyed) {
-                        this.raw.destroy(err);
-                    }
-                }
-            });
-        }
-        if (typeof readable.once === 'function') {
-            ;
-            readable.once('end', () => {
-                this.raw.removeListener('close', cleanup);
-            });
-        }
-        ;
-        readable.pipe(this.raw);
+        (0, helpers_1.streamToResponse)(this.raw, readable, this.isWritable, this.headersSent, (name) => this.hasHeader(name), (name, val) => this.setHeader(name, val), (code) => {
+            this.statusCode = code;
+        }, (data) => this.end(data), this.req);
     }
     /**
      * Alias for `sendStream()`.
@@ -525,29 +288,33 @@ class ExisResponse {
         this.sendStream(readable);
     }
     /**
-     * Initialize a Server-Sent Events (SSE) stream for real-time and AI streaming.
+     * Initializes a Server-Sent Events (SSE) stream for real-time data and AI token streaming.
      *
-     * Automatically sets standard SSE headers:
+     * Sets standard SSE headers automatically:
      * - `Content-Type: text/event-stream; charset=utf-8`
      * - `Cache-Control: no-cache, no-transform`
      * - `Connection: keep-alive`
-     * - `X-Accel-Buffering: no` (disables Nginx proxy buffering)
+     * - `X-Accel-Buffering: no`
      *
-     * @param options Optional configuration (heartbeat interval, custom headers)
-     * @param handler Optional callback function receiving the active `SSEStream`
+     * @param optionsOrHandler Optional SSE configuration or callback handler
+     * @param maybeHandler Callback handler when options object is provided
      * @returns Active `SSEStream` instance
      *
      * @example
-     * // Using callback handler:
-     * res.sse(async (sse) => {
-     *   sse.send({ event: 'message', data: 'hello' })
-     *   await sse.pipeFrom(openaiStream)
-     *   sse.close()
+     * ```ts
+     * // In route.ts
+     * export default controller({
+     *   events: route.get('/events', {
+     *     async handle({ res }) {
+     *       res.sse(async (sse) => {
+     *         sse.send({ event: 'ping', data: { time: Date.now() } })
+     *         await sse.pipeFrom(openAiStream)
+     *         sse.close()
+     *       })
+     *     }
+     *   })
      * })
-     *
-     * // Or assigning to variable:
-     * const sse = res.sse()
-     * sse.send({ event: 'connected', data: { time: Date.now() } })
+     * ```
      */
     sse(optionsOrHandler, maybeHandler) {
         let options = {};
@@ -573,7 +340,6 @@ class ExisResponse {
                     this.setHeader(key, value);
                 }
             }
-            // Flush headers immediately
             if (typeof this.raw.flushHeaders === 'function') {
                 this.raw.flushHeaders();
             }
@@ -611,15 +377,16 @@ class ExisResponse {
         return stream;
     }
     /**
-     * Transfer the file at the given `filePath` as an attachment.
+     * Transfers a file on disk as an attachment with automatic Content-Disposition and MIME lookup.
      *
-     * Optionally providing an alternate attachment `filename`,
-     * and optional `options`.
+     * @param filePath Absolute path to file on disk
+     * @param filename Optional override for downloaded filename
+     * @param options File stream options
      *
-     * @param {string} filePath
-     * @param {string} [filename]
-     * @param {unknown} [options]
-     * @public
+     * @example
+     * ```ts
+     * res.download('/data/reports/report.pdf', 'monthly-report.pdf')
+     * ```
      */
     download(filePath, filename, options) {
         if (this.headersSent)
@@ -644,20 +411,13 @@ class ExisResponse {
         stream.pipe(this.raw);
     }
     /**
-     * Set _Content-Type_ response header with `type` through `mime.lookup()`
-     * when it does not contain "/", or set the Content-Type to `type` otherwise.
+     * Sets Content-Type header using file extension or MIME type string.
      *
-     * Examples:
-     *
-     *     res.type('.html');
-     *     res.type('html');
-     *     res.type('json');
-     *     res.type('application/json');
-     *     res.type('png');
-     *
-     * @param {string} type
-     * @return {this}
-     * @public
+     * @example
+     * ```ts
+     * res.type('json') // sets 'application/json; charset=utf-8'
+     * res.type('png')  // sets 'image/png'
+     * ```
      */
     type(type) {
         const mimeType = mime.contentType(type) || type;
@@ -665,18 +425,7 @@ class ExisResponse {
         return this;
     }
     /**
-     * Set Link header field with the given `links`.
-     *
-     * Examples:
-     *
-     *    res.links({
-     *      next: 'http://api.example.com/users?page=2',
-     *      last: 'http://api.example.com/users?page=5'
-     *    });
-     *
-     * @param {Record<string, string>} links
-     * @return {this}
-     * @public
+     * Sets Link header field with pagination or resource relations.
      */
     links(links) {
         let linkHeader = this.getHeader('Link') || '';
@@ -688,12 +437,7 @@ class ExisResponse {
         return this;
     }
     /**
-     * Add `field` to Vary. If already present in the Vary set, then
-     * this call is simply ignored.
-     *
-     * @param {string} field
-     * @return {this}
-     * @public
+     * Adds a field to the Vary header if not already present.
      */
     vary(field) {
         if (!field)
@@ -714,94 +458,48 @@ class ExisResponse {
         return this;
     }
     /**
-     * Set cookie `name` to `value`, with the given `options`.
-     *
-     * Options:
-     *    - `maxAge`   max-age in milliseconds, converted to `expires`
-     *    - `path`     cookie path, defaults to '/'
-     *    - `domain`   cookie domain
-     *    - `secure`   secure cookie
-     *    - `httpOnly` httponly cookie
-     *    - `sameSite` samesite cookie
-     *
-     * Examples:
+     * Sets a cookie with specified security options.
      *
-     *    res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true });
-     *    res.cookie('cart', '1234');
+     * @param name Cookie name
+     * @param value Cookie value
+     * @param options Cookie options (httpOnly, secure, sameSite, maxAge, path, domain)
      *
-     * @param {string} name
-     * @param {string} value
-     * @param {CookieOptions} options
-     * @return {this}
-     * @public
+     * @example
+     * ```ts
+     * res.cookie('session_token', token, {
+     *   httpOnly: true,
+     *   secure: true,
+     *   sameSite: 'lax',
+     *   maxAge: 86400000 // 1 day
+     * })
+     * ```
      */
     cookie(name, value, options = {}) {
-        const parts = [
-            `${encodeURIComponent(name)}=${encodeURIComponent(value)}`,
-        ];
-        if (options.maxAge !== undefined)
-            parts.push(`Max-Age=${options.maxAge}`);
-        if (options.expires)
-            parts.push(`Expires=${options.expires.toUTCString()}`);
-        if (options.path ?? true)
-            parts.push(`Path=${options.path ?? '/'}`);
-        if (options.domain)
-            parts.push(`Domain=${options.domain}`);
-        if (options.httpOnly)
-            parts.push('HttpOnly');
-        if (options.secure)
-            parts.push('Secure');
-        if (options.sameSite !== undefined && options.sameSite !== false) {
-            if (options.sameSite === true) {
-                parts.push('SameSite=Strict');
-            }
-            else {
-                const str = String(options.sameSite).toLowerCase();
-                if (str === 'strict')
-                    parts.push('SameSite=Strict');
-                else if (str === 'lax')
-                    parts.push('SameSite=Lax');
-                else if (str === 'none') {
-                    parts.push('SameSite=None');
-                    if (!options.secure && !parts.includes('Secure')) {
-                        parts.push('Secure');
-                    }
-                }
-            }
-        }
-        if (options.partitioned)
-            parts.push('Partitioned');
-        if (options.priority) {
-            const p = options.priority.toLowerCase();
-            if (p === 'low')
-                parts.push('Priority=Low');
-            else if (p === 'medium')
-                parts.push('Priority=Medium');
-            else if (p === 'high')
-                parts.push('Priority=High');
-        }
-        this.append('Set-Cookie', parts.join('; '));
+        const serialized = (0, helpers_1.serializeCookie)(name, value, options);
+        this.append('Set-Cookie', serialized);
         if (process.env.NODE_ENV === 'development') {
-            this.append('X-Set-Cookie', parts.join('; '));
+            this.append('X-Set-Cookie', serialized);
         }
         return this;
     }
     /**
-     * Clear cookie `name`.
+     * Clears a cookie by setting its expiration to the past.
+     *
+     * @param name Cookie name
+     * @param options Cookie options (path, domain)
      *
-     * @param {string} name
-     * @param {CookieOptions} [options]
-     * @return {this}
-     * @public
+     * @example
+     * ```ts
+     * res.clearCookie('session_token')
+     * ```
      */
     clearCookie(name, options = {}) {
-        const { maxAge: _, expires: __, ...rest } = options;
-        return this.cookie(name, '', {
-            httpOnly: true,
-            ...rest,
-            expires: new Date(0),
-            maxAge: 0,
-        });
+        const serialized = (0, helpers_1.serializeClearCookie)(name, options);
+        this.append('Set-Cookie', serialized);
+        if (process.env.NODE_ENV === 'development') {
+            this.append('X-Set-Cookie', serialized);
+        }
+        return this;
     }
 }
 exports.ExisResponse = ExisResponse;