Comprehensive response object with methods for setting headers, status codes, content type, caching, and state management in @hapi/hapi.
The response object contains all information about the HTTP response being sent.
interface Response {
/** HTTP status code */
statusCode: number;
/** Response headers as key-value pairs */
headers: { [key: string]: string };
/** Response payload source */
source: any;
/** Response type identifier */
variety: string;
/** Application-specific response state */
app: object;
/** Plugin-specific response state */
plugins: object;
/** Response configuration settings */
settings: ResponseSettings;
/** Response-specific event emitter */
events: Events;
/** Associated request object */
request: Request;
}
interface ResponseSettings {
/** Character encoding */
encoding?: string;
/** JSON replacer function */
replacer?: Function;
/** JSON spacing */
space?: number;
/** JSON suffix */
suffix?: string;
/** TTL in milliseconds */
ttl?: number;
/** Whether response should be compressed */
compressed?: boolean;
/** ETag settings */
etag?: object;
/** Response passthrough flag */
passthrough?: boolean;
/** Redirect settings */
location?: string;
/** Temporary redirect flag */
temporary?: boolean;
}Set and modify HTTP status codes with optional custom messages.
/**
* Set response status code
* @param statusCode - HTTP status code
* @returns Response object for chaining
*/
code(statusCode: number): Response;
/**
* Set custom HTTP status message
* @param httpMessage - Custom status message
* @returns Response object for chaining
*/
message(httpMessage: string): Response;
/**
* Set 201 Created status with location header
* @param location - Resource location URI
* @returns Response object for chaining
*/
created(location?: string): Response;Usage Examples:
server.route({
method: 'POST',
path: '/api/users',
handler: (request, h) => {
const user = { id: 123, name: request.payload.name };
return h.response(user)
.code(201)
.created(`/api/users/${user.id}`);
}
});
server.route({
method: 'GET',
path: '/custom-status',
handler: (request, h) => {
return h.response({ status: 'custom' })
.code(299)
.message('Custom Success Status');
}
});Comprehensive header manipulation including setting, modifying, and specialized headers.
/**
* Set response header
* @param name - Header name
* @param value - Header value
* @param options - Header options
* @returns Response object for chaining
*/
header(name: string, value: string, options?: HeaderOptions): Response;
/**
* Set content-type header
* @param mimeType - MIME type string
* @returns Response object for chaining
*/
type(mimeType: string): Response;
/**
* Set location header
* @param location - Location URI
* @returns Response object for chaining
*/
location(location: string): Response;
/**
* Set ETag header for caching
* @param tag - ETag value
* @param options - ETag options
* @returns Response object for chaining
*/
etag(tag: string, options?: ETagOptions): Response;
/**
* Set Vary header for cache variation
* @param header - Header name to vary on
* @returns Response object for chaining
*/
vary(header: string): Response;
interface HeaderOptions {
/** Whether to append to existing header */
append?: boolean;
/** Header separator for appending */
separator?: string;
/** Override existing header */
override?: boolean;
/** Duplicate header handling */
duplicate?: boolean;
}
interface ETagOptions {
/** Whether ETag is weak */
weak?: boolean;
/** ETag varies by request properties */
vary?: boolean;
}Usage Examples:
server.route({
method: 'GET',
path: '/api/data',
handler: (request, h) => {
const data = { timestamp: Date.now() };
return h.response(data)
.header('X-API-Version', '1.0')
.header('X-Rate-Limit', '1000')
.type('application/json')
.etag('data-v1', { weak: true })
.vary('Accept-Encoding');
}
});
// Custom headers with options
server.route({
method: 'GET',
path: '/multi-header',
handler: (request, h) => {
return h.response('OK')
.header('X-Custom', 'value1')
.header('X-Custom', 'value2', { append: true, separator: ', ' });
}
});Control response content encoding, compression, and character sets.
/**
* Set character encoding
* @param charset - Character set name
* @returns Response object for chaining
*/
charset(charset: string): Response;
/**
* Set content encoding
* @param encoding - Encoding name
* @returns Response object for chaining
*/
encoding(encoding: string): Response;
/**
* Mark response as compressed
* @param encoding - Compression encoding used
* @returns Response object for chaining
*/
compressed(encoding: string): Response;
/**
* Set content-length header
* @param bytes - Content length in bytes
* @returns Response object for chaining
*/
bytes(bytes: number): Response;Usage Examples:
server.route({
method: 'GET',
path: '/compressed',
handler: (request, h) => {
const data = 'Large response content...'.repeat(1000);
return h.response(data)
.encoding('gzip')
.compressed('gzip')
.charset('utf-8')
.bytes(Buffer.byteLength(data));
}
});Configure JSON serialization including formatting and custom replacers.
/**
* Set JSON replacer function
* @param replacer - JSON.stringify replacer function
* @returns Response object for chaining
*/
replacer(replacer: Function): Response;
/**
* Set JSON indentation spacing
* @param space - Number of spaces or string for indentation
* @returns Response object for chaining
*/
space(space: number | string): Response;
/**
* Set JSON response suffix
* @param suffix - String to append to JSON response
* @returns Response object for chaining
*/
suffix(suffix: string): Response;Usage Examples:
server.route({
method: 'GET',
path: '/formatted-json',
handler: (request, h) => {
const data = {
user: { id: 1, password: 'secret', email: 'user@example.com' },
timestamp: new Date()
};
return h.response(data)
.replacer((key, value) => {
// Hide sensitive data
if (key === 'password') return undefined;
return value;
})
.space(2)
.suffix(';\n');
}
});Create redirect responses with proper status codes and options.
/**
* Create redirect response
* @param location - Redirect URL
* @returns Response object for chaining
*/
redirect(location?: string): Response;
/**
* Set whether redirect is temporary
* @param isTemporary - Whether redirect is temporary (302 vs 301)
* @returns Response object for chaining
*/
temporary(isTemporary: boolean): Response;Usage Examples:
server.route({
method: 'GET',
path: '/old-path',
handler: (request, h) => {
return h.redirect('/new-path')
.temporary(false); // 301 permanent redirect
}
});
server.route({
method: 'POST',
path: '/login',
handler: (request, h) => {
// Process login...
return h.redirect('/dashboard')
.temporary(true); // 302 temporary redirect
}
});Set cache-related headers and TTL values.
/**
* Set cache TTL (Time To Live)
* @param ttl - TTL in milliseconds
* @returns Response object for chaining
*/
ttl(ttl: number): Response;Usage Examples:
server.route({
method: 'GET',
path: '/cached-data',
handler: (request, h) => {
const data = { cached: true, timestamp: Date.now() };
return h.response(data)
.ttl(60 * 1000) // Cache for 1 minute
.header('Cache-Control', 'public, max-age=60');
}
});Set and clear cookie state on responses.
/**
* Set cookie state
* @param name - Cookie name
* @param value - Cookie value
* @param options - Cookie options
* @returns Response object for chaining
*/
state(name: string, value: any, options?: StateOptions): Response;
/**
* Clear cookie state
* @param name - Cookie name to clear
* @param options - Clear options
* @returns Response object for chaining
*/
unstate(name: string, options?: StateOptions): Response;
interface StateOptions {
/** Cookie TTL in milliseconds */
ttl?: number;
/** Whether cookie is HTTP only */
isHttpOnly?: boolean;
/** Whether cookie is secure (HTTPS only) */
isSecure?: boolean;
/** Cookie path */
path?: string;
/** Cookie domain */
domain?: string;
/** Cookie encoding */
encoding?: string;
/** Same-site policy */
sameSite?: 'Strict' | 'Lax' | 'None';
}Usage Examples:
server.route({
method: 'POST',
path: '/login',
handler: (request, h) => {
const sessionData = { userId: 123, role: 'user' };
return h.response({ success: true })
.state('session', sessionData, {
ttl: 24 * 60 * 60 * 1000, // 1 day
isHttpOnly: true,
isSecure: true,
sameSite: 'Strict'
});
}
});
server.route({
method: 'POST',
path: '/logout',
handler: (request, h) => {
return h.response({ success: true })
.unstate('session');
}
});Control how the response is processed by the framework.
/**
* Take over response processing (bypass normal response handling)
* @returns Response object for chaining
*/
takeover(): Response;Usage Examples:
server.route({
method: 'GET',
path: '/custom-response',
handler: (request, h) => {
const response = h.response();
// Take over response handling
response.takeover();
// Manually write to raw response
request.raw.res.writeHead(200, { 'Content-Type': 'text/plain' });
request.raw.res.end('Custom response handling');
return response;
}
});interface Events {
/** Add event listener */
on(event: string, listener: Function): void;
/** Remove event listener */
off(event: string, listener: Function): void;
/** Emit event */
emit(event: string, ...args: any[]): boolean;
/** Add one-time event listener */
once(event: string, listener: Function): void;
}