exisjs 0.7.6 → 0.7.8

package/dist/server/response.d.ts

@@ -19,128 +19,95 @@ export declare class ExisResponse<TResponse = any> {
     hasHeader(name: string): boolean;
     end(data?: unknown): void;
     /**
-     * Set status `code`.
+     * Sets the HTTP response status code.
      *
-     * @param {number} code
-     * @return {this}
-     * @public
+     * @param code HTTP status code (e.g. `200`, `201`, `400`, `404`, `500`)
+     * @returns Response instance for chaining
+     *
+     * @example
+     * ```ts
+     * res.status(201).json({ created: true })
+     * ```
      */
     status(code: number): this;
     /**
-     * Set header `field` to `val`, or pass
-     * an object of header fields.
-     *
-     * Examples:
-     *
-     *    res.set('Foo', ['bar', 'baz']);
-     *    res.set('Accept', 'application/json');
-     *
-     * Aliased as `res.header()`.
+     * Sets a response header field to a specific value.
      *
-     * @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: string, value: string | string[]): 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: string, value: string | string[]): this;
     /**
-     * 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: number): void;
     removeHeader(name: string): this;
     setStrHeaders(headers: Record<string, string>): 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: string, value: string | string[]): 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: string | Buffer | object): void;
     /**
-     * Send JSON response.
-     *
-     * Examples:
+     * Sends a JSON response with automatic native serialization and fast ETag support.
      *
-     *     res.json(null);
-     *     res.json({ user: 'tj' });
+     * @param data JSON-serializable data payload
      *
-     * @param {unknown} data
-     * @public
+     * @example
+     * ```ts
+     * res.json({ success: true, users: ['Alice', 'Bob'] })
+     * ```
      */
     json(data: unknown extends TResponse ? any : TResponse): void;
     /**
-     * Send HTML response.
+     * Sends an HTML response with `Content-Type: text/html; charset=utf-8`.
      *
-     * Examples:
+     * @param content HTML string
      *
-     *     res.html('<h1>Hello</h1>');
-     *
-     * @param {string} content
-     * @public
+     * @example
+     * ```ts
+     * res.html('<h1>Welcome to ExisJS</h1>')
+     * ```
      */
     html(content: string): void;
     /**
-     * Redirect to the given `url` with optional response `status`
-     * defaulting to 302.
+     * Performs an HTTP redirect to a given URL with an optional status code (defaults to 302).
      *
-     * Examples:
+     * @param url Target destination URL
+     * @param code HTTP status code (`301` Moved Permanently, `302` Found, `307` Temporary Redirect, `308` Permanent Redirect)
      *
-     *     res.redirect('/foo/bar');
-     *     res.redirect('http://example.com');
-     *     res.redirect('http://example.com', 301);
-     *
-     * @param {string} url
-     * @param {number} [code=302]
-     * @public
+     * @example
+     * ```ts
+     * res.redirect('/login')
+     * ```
      */
     redirect(url: string, code?: number): void;
     /**
-     * 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: NodeJS.ReadableStream | ReadableStream | AsyncIterable<any>): void;
     /**
@@ -148,114 +115,94 @@ export declare class ExisResponse<TResponse = any> {
      */
     stream(readable: NodeJS.ReadableStream | ReadableStream | AsyncIterable<any>): void;
     /**
-     * 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?: SSEOptions | ((sse: SSEStream) => void | Promise<void>), maybeHandler?: (sse: SSEStream) => void | Promise<void>): SSEStream;
     /**
-     * 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: string, filename?: string, options?: unknown): void;
     /**
-     * Set _Content-Type_ response header with `type` through `mime.lookup()`
-     * when it does not contain "/", or set the Content-Type to `type` otherwise.
-     *
-     * Examples:
+     * Sets Content-Type header using file extension or MIME type string.
      *
-     *     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: string): 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: Record<string, string>): 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: string): 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
+     * Sets a cookie with specified security options.
      *
-     * Examples:
+     * @param name Cookie name
+     * @param value Cookie value
+     * @param options Cookie options (httpOnly, secure, sameSite, maxAge, path, domain)
      *
-     *    res.cookie('rememberme', '1', { expires: new Date(Date.now() + 900000), httpOnly: true });
-     *    res.cookie('cart', '1234');
-     *
-     * @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: string, value: string, options?: CookieOptions): this;
     /**
-     * Clear cookie `name`.
+     * Clears a cookie by setting its expiration to the past.
      *
-     * @param {string} name
-     * @param {CookieOptions} [options]
-     * @return {this}
-     * @public
+     * @param name Cookie name
+     * @param options Cookie options (path, domain)
+     *
+     * @example
+     * ```ts
+     * res.clearCookie('session_token')
+     * ```
      */
     clearCookie(name: string, options?: CookieOptions): this;
 }

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

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