Documentation
    Preparing search index...

    The Response class provides a fluent API for constructing HTTP responses.

    It wraps Node.js ServerResponse and streamlines the process of writing response body, setting headers, handling cookies, redirects, and streaming.

    response.status(200).json({ message: 'Hello World' })
    response.redirect('/dashboard')
    response.download('/path/to/file.pdf')

    Hierarchy

    • default
      • Response
    Index

    Constructors

    • Creates a new Response instance

      Parameters

      • request: IncomingMessage

        Node.js IncomingMessage instance

      • response: ServerResponse

        Node.js ServerResponse instance

      • encryption: Encryption

        Encryption service for cookie handling

      • config: ResponseConfig

        Response configuration settings

      • router: Router

        Router instance for URL generation

      • qs: Qs

        Query string parser

      Returns Response

    Properties

    lazyBody: Partial<
        {
            content: [any, boolean, string?];
            stream: [
                ResponseStream,
                (error: NodeJS.ErrnoException) => [string, number?]?,
            ];
            fileToStream: [
                string,
                boolean,
                (error: NodeJS.ErrnoException) => [string, number?]?,
            ];
        },
    > = {}

    Lazy body container that holds response content until ready to send. Contains different types of response data: content, stream, or fileToStream.

    HTTP context reference (creates circular dependency with HttpContext)

    request: IncomingMessage

    Node.js IncomingMessage instance

    response: ServerResponse

    Node.js ServerResponse instance

    Accessors

    • get hasLazyBody(): boolean

      Indicates whether the response has any content (body, stream, or file) ready to be sent

      Returns boolean

    • get hasContent(): boolean

      Indicates whether the response has non-stream content set

      Returns boolean

    • get hasStream(): boolean

      Indicates whether the response body is set as a readable stream

      Returns boolean

    • get hasFileToStream(): boolean

      Indicates whether the response is configured to stream a file

      Returns boolean

    • get content(): undefined | [any, boolean, string?]

      The response content data

      Returns undefined | [any, boolean, string?]

    • get outgoingStream(): undefined | Readable

      The readable stream instance configured for the response

      Returns undefined | Readable

    • get fileToStream(): undefined | { path: string; generateEtag: boolean }

      Configuration for file streaming including path and etag generation flag

      Returns undefined | { path: string; generateEtag: boolean }

    • get finished(): boolean

      Indicates whether the response has been completely sent

      Returns boolean

    • get headersSent(): boolean

      Indicates whether response headers have been sent to the client

      Returns boolean

    • get isPending(): boolean

      Indicates whether the response is still pending (headers and body can still be modified)

      Returns boolean

    Methods

    • Registers a callback to be called when the response is finished

      The callback is executed when the response has been completely sent. Uses the "on-finished" package internally.

      Parameters

      • callback: (err: null | Error, response: ServerResponse) => void

        Function to call when response is finished

      Returns void

    • Transfers all buffered headers to the underlying Node.js response object

      Returns void

    • Writes the response status code and headers

      Parameters

      • OptionalstatusCode: number

        Optional status code to set

      Returns this

      The Response instance for chaining

    • Gets the value of a response header

      Parameters

      • key: string

        Header name

      Returns undefined | OutgoingHttpHeader

      The header value

    • Gets all response headers as an object

      Returns { [key: string]: undefined | OutgoingHttpHeader }

      Object containing all headers

    • Sets a response header (replaces existing value)

      Parameters

      • key: string

        Header name

      • value: CastableHeader

        Header value (ignored if null/undefined)

      Returns this

      The Response instance for chaining

      response.header('Content-Type', 'application/json')
      
    • Appends a value to an existing response header

      Parameters

      • key: string

        Header name

      • value: CastableHeader

        Header value to append (ignored if null/undefined)

      Returns this

      The Response instance for chaining

      response.append('Set-Cookie', 'session=abc123')
      
    • Sets a header only if it doesn't already exist

      Parameters

      Returns this

      The Response instance for chaining

    • Removes a response header

      Parameters

      • key: string

        Header name to remove

      Returns this

      The Response instance for chaining

    • Gets the current response status code

      Returns number

      The HTTP status code

    • Sets the response status code

      Parameters

      • code: number

        HTTP status code

      Returns this

      The Response instance for chaining

    • Sets the status code only if not explicitly set already

      Parameters

      • code: number

        HTTP status code

      Returns this

      The Response instance for chaining

    • Sets the Content-Type header based on mime type lookup

      Parameters

      • type: string

        File extension or mime type

      • Optionalcharset: string

        Optional character encoding

      Returns this

      The Response instance for chaining

      response.type('.json') // Content-Type: application/json
      response.type('html', 'utf-8') // Content-Type: text/html; charset=utf-8
    • Sets the Vary HTTP header for cache control

      Parameters

      • field: string | string[]

        Header field name(s) to vary on

      Returns this

      The Response instance for chaining

    • Sets the ETag header by computing a hash from the response body

      Parameters

      • body: any

        The response body to hash

      • weak: boolean = false

        Whether to generate a weak ETag

      Returns this

      The Response instance for chaining

    • Sets the X-Request-Id header by copying from the incoming request

      Returns this

      The Response instance for chaining

    • Checks if the response is fresh (client cache is valid)

      Compares ETags and modified dates between request and response to determine if a 304 Not Modified response should be sent.

      Returns boolean

      True if client cache is fresh, false otherwise

      response.setEtag(content)
      if (response.fresh()) {
      response.status(304).send(null)
      } else {
      response.send(content)
      }
    • Gets the response body content

      Returns any

      The response body or null if not set or is a stream

    • Sends the response body with optional ETag generation

      Parameters

      • body: any

        The response body

      • generateEtag: boolean = ...

        Whether to generate ETag header (defaults to config)

      Returns void

    • Sends a JSON response (alias for send)

      Parameters

      • body: any

        The response body to serialize as JSON

      • generateEtag: boolean = ...

        Whether to generate ETag header

      Returns void

    • Sends a JSONP response with callback wrapping

      Callback name resolution priority:

      1. Explicit callbackName parameter
      2. Query string parameter
      3. Config value
      4. Default "callback"

      Parameters

      • body: any

        The response body

      • callbackName: string = ...

        JSONP callback function name

      • generateEtag: boolean = ...

        Whether to generate ETag header

      Returns void

    • Pipes a readable stream to the response with graceful error handling

      Parameters

      • body: Readable

        The readable stream to pipe

      • OptionalerrorCallback: (error: ErrnoException) => [string, number?]

        Optional custom error handler

      Returns void

      // Auto error handling
      response.stream(fs.createReadStream('file.txt'))

      // Custom error handling
      response.stream(stream, (error) => {
      return error.code === 'ENOENT' ? ['Not found', 404] : ['Error', 500]
      })
    • Downloads a file by streaming it with appropriate headers

      Automatically sets:

      • Content-Type from file extension
      • Content-Length from file size
      • Last-Modified from file stats
      • ETag (if enabled)

      Parameters

      • filePath: string

        Path to the file to download

      • generateEtag: boolean = ...

        Whether to generate ETag header

      • OptionalerrorCallback: (error: ErrnoException) => [string, number?]

        Optional custom error handler

      Returns void

      response.download('/path/to/file.pdf')
      response.download('/images/photo.jpg', true, (err) => ['Custom error', 500])
    • Forces file download by setting Content-Disposition header

      Parameters

      • filePath: string

        Path to the file to download

      • Optionalname: string

        Optional filename for download (defaults to original filename)

      • Optionaldisposition: string

        Content-Disposition type (defaults to 'attachment')

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      • OptionalerrorCallback: (error: ErrnoException) => [string, number?]

        Optional custom error handler

      Returns void

    • Sets the Location header for redirects

      Parameters

      • url: string

        The URL to redirect to

      Returns this

      The Response instance for chaining

      response.location('/dashboard')
      
    • Returns a Redirect instance for fluent API usage

      Use this overload when you want to use methods like .toRoute(), .back(), .withQs(), or other redirect builder methods.

      Returns Redirect

      Redirect instance for chaining redirect methods

      response.redirect().toRoute('users.show', { id: 1 })
      response.redirect().back()
      response.redirect().withQs().toPath('/dashboard')
    • Performs an immediate redirect to the specified path

      This overload directly redirects the request with the provided parameters. Use this when you have a simple redirect without needing the fluent API.

      Parameters

      • path: string

        The path or URL to redirect to (use 'back' for referrer redirect)

      • OptionalforwardQueryString: boolean

        Whether to forward current query string parameters

      • OptionalstatusCode: number

        HTTP status code for redirect (defaults to 302 Found)

      Returns void

      response.redirect('/dashboard')
      response.redirect('/users', true, 301) // with query forwarding and 301 status
      response.redirect('back') // redirect to referrer
    • Aborts the request with a custom response body and status code

      Parameters

      • body: any

        Response body for the aborted request

      • Optionalstatus: number

        HTTP status code (defaults to 400)

      Returns never

      Always throws an HTTP exception

    • Conditionally aborts the request if the condition is truthy

      Parameters

      • condition: unknown

        Condition to evaluate

      • body: any

        Response body for the aborted request

      • Optionalstatus: number

        HTTP status code (defaults to 400)

      Returns asserts condition is undefined | null | false

    • Conditionally aborts the request if the condition is falsy

      Type Parameters

      • T

      Parameters

      • condition: T

        Condition to evaluate

      • body: any

        Response body for the aborted request

      • Optionalstatus: number

        HTTP status code (defaults to 400)

      Returns asserts condition is Exclude<T, undefined | null | false>

    • Sets a signed cookie in the response

      Parameters

      • key: string

        Cookie name

      • value: any

        Cookie value

      • Optionaloptions: Partial<CookieOptions>

        Cookie options (overrides config defaults)

      Returns this

      The Response instance for chaining

    • Sets an encrypted cookie in the response

      Parameters

      • key: string

        Cookie name

      • value: any

        Cookie value

      • Optionaloptions: Partial<CookieOptions>

        Cookie options (overrides config defaults)

      Returns this

      The Response instance for chaining

    • Sets a plain (unsigned/unencrypted) cookie in the response

      Parameters

      • key: string

        Cookie name

      • value: any

        Cookie value

      • Optionaloptions: Partial<CookieOptions & { encode: boolean }>

        Cookie options including encode flag

      Returns this

      The Response instance for chaining

    • Clears an existing cookie by setting it to expire

      Parameters

      • key: string

        Cookie name to clear

      • Optionaloptions: Partial<CookieOptions>

        Cookie options (should match original cookie options)

      Returns this

      The Response instance for chaining

    • Finalizes and sends the response

      Writes the buffered body (content, stream, or file) to the client. This method is idempotent - calling it multiple times has no effect.

      Returns void

    • Sends a 101 Switching Protocols response

      Returns void

    • Sends a 200 OK response

      Parameters

      • body: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 201 Created response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 202 Accepted response

      Parameters

      • body: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 203 Non-Authoritative Information response

      Parameters

      • body: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 206 Partial Content response

      Parameters

      • body: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 300 Multiple Choices response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 301 Moved Permanently response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 302 Found (Moved Temporarily) response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 303 See Other response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 304 Not Modified response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 305 Use Proxy response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 307 Temporary Redirect response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 400 Bad Request response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 401 Unauthorized response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 402 Payment Required response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 403 Forbidden response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 404 Not Found response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 405 Method Not Allowed response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 406 Not Acceptable response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 407 Proxy Authentication Required response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 408 Request Timeout response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 409 Conflict response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 410 Gone response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 411 Length Required response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 412 Precondition Failed response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 413 Payload Too Large response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 414 URI Too Long response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 415 Unsupported Media Type response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 416 Range Not Satisfiable response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 417 Expectation Failed response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 422 Unprocessable Entity response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 429 Too Many Requests response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 500 Internal Server Error response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 501 Not Implemented response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 502 Bad Gateway response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 503 Service Unavailable response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 504 Gateway Timeout response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void

    • Sends a 505 HTTP Version Not Supported response

      Parameters

      • Optionalbody: any

        Response body

      • OptionalgenerateEtag: boolean

        Whether to generate ETag header

      Returns void