v17.0.x API Reference

Server

The server object is the main application container. The server manages all incoming requests along with all the facilities provided by the framework. Each server supports a single connection (e.g. listen to port 80).

server([options])

Creates a new server object where:

const Hapi = require('hapi');

const server = Hapi.server({ load: { sampleInterval: 1000 } });

Server options

The server options control the behavior of the server object. Note that the options object is deeply cloned (with the exception of listener which is shallowly copied) and should not contain any values that are unsafe to perform deep copy on.

All options are optionals.

address

Default value: '0.0.0.0' (all available network interfaces).

Sets the hostname or IP address the server will listen on. If not configured, defaults to host if present, otherwise to all available network interfaces. Set to '127.0.0.1' or 'localhost' to restrict the server to only those coming from the same host.

app

Default value: {}.

Provides application-specific configuration which can later be accessed via server.settings.app. The framework does not interact with this object. It is simply a reference made available anywhere a server reference is provided.

Note the difference between server.settings.app which is used to store static configuration values and server.app which is meant for storing run-time state.

autoListen

Default value: true.

Used to disable the automatic initialization of the listener. When false, indicates that the listener will be started manually outside the framework.

Cannot be set to true along with a port value.

cache

Default value: { engine: require('catbox-memory' }.

Sets up server-side caching providers. Every server includes a default cache for storing application state. By default, a simple memory-based cache is created which has limited capacity and capabilities.

hapi uses catbox for its cache implementation which includes support for common storage solutions (e.g. Redis, MongoDB, Memcached, Riak, among others). Caching is only utilized if methods and plugins explicitly store their state in the cache.

The server cache configuration only defines the storage container itself. The configuration can be assigned one or more (array):

  • a class or prototype function (usually obtained by calling require() on a catbox strategy such as require('catbox-redis')). A new catbox client will be created internally using this function.

  • a configuration object with the following:

    • engine - a class, a prototype function, or a catbox engine object.

    • name - an identifier used later when provisioning or configuring caching for server methods or plugins. Each cache name must be unique. A single item may omit the name option which defines the default cache. If every cache includes a name, a default memory cache is provisioned as well.

    • shared - if true, allows multiple cache users to share the same segment (e.g. multiple methods using the same cache storage container). Default to false.

    • partition - (optional) string used to isolate cached data. Defaults to 'hapi-cache'.

    • other options passed to the catbox strategy used. Other options are only passed to catbox when engine above is a class or function and ignored if engine is a catbox engine object).

compression

Default value: { minBytes: 1024 }.

Defines server handling of content encoding requests. If false, response content encoding is disabled and no compression is performed by the server.

minBytes

Default value: '1024'.

Sets the minimum response payload size in bytes that is required for content encoding compression. If the payload size is under the limit, no compression is performed.

debug

Default value: { request: ['implementation'] }.

Determines which logged events are sent to the console. This should only be used for development and does not affect which events are actually logged internally and recorded. Set to false to disable all console logging, or to an object with:

For example, to display all errors, set the log or request to ['error']. To turn off all output set the log or request to false. To display all server logs, set the log or request to '*'. To disable all debug information, set debug to false.

host

Default value: the operating system hostname and if not available, to 'localhost'.

The public hostname or IP address. Used to set server.info.host and server.info.uri and as address is none provided.

listener

Default value: none.

An optional node HTTP (or HTTPS) http.Server object (or an object with a compatible interface).

If the listener needs to be manually started, set autoListen to false.

If the listener uses TLS, set tls to true.

load

Default value: { sampleInterval: 0 }.

Server excessive load handling limits where:

  • sampleInterval - the frequency of sampling in milliseconds. When set to 0, the other load options are ignored. Defaults to 0 (no sampling).

  • maxHeapUsedBytes - maximum V8 heap size over which incoming requests are rejected with an HTTP Server Timeout (503) response. Defaults to 0 (no limit).

  • maxRssBytes - maximum process RSS size over which incoming requests are rejected with an HTTP Server Timeout (503) response. Defaults to 0 (no limit).

  • maxEventLoopDelay - maximum event loop delay duration in milliseconds over which incoming requests are rejected with an HTTP Server Timeout (503) response. Defaults to 0 (no limit).

mime

Default value: none.

Options passed to the mimos module when generating the mime database used by the server (and accessed via server.mime):

  • override - an object hash that is merged into the built in mime information specified here. Each key value pair represents a single mime object. Each override value must contain:

    • key - the lower-cased mime-type string (e.g. 'application/javascript').

    • value - an object following the specifications outlined here. Additional values include:

      • type - specify the type value of result objects, defaults to key.

      • predicate - method with signature function(mime) when this mime type is found in the database, this function will execute to allows customizations.

const options = {
    mime: {
        override: {
            'node/module': {
                source: 'iana',
                compressible: true,
                extensions: ['node', 'module', 'npm'],
                type: 'node/module'
            },
            'application/javascript': {
                source: 'iana',
                charset: 'UTF-8',
                compressible: true,
                extensions: ['js', 'javascript'],
                type: 'text/javascript'
            },
            'text/html': {
                predicate: function(mime) {
                    if (someCondition) {
                        mime.foo = 'test';
                    }
                    else {
                        mime.foo = 'bar';
                    }
                    return mime;
                }
            }
        }
    }
};

plugins

Default value: {}.

Plugin-specific configuration which can later be accessed via server.settings.plugins. plugins is an object where each key is a plugin name and the value is the configuration. Note the difference between server.settings.plugins which is used to store static configuration values and server.plugins which is meant for storing run-time state.

port

Default value: 0 (an ephemeral port).

The TCP port the server will listen to. Defaults the next available port when the server is started (and assigned to server.info.port).

If port is a string containing a '/' character, it is used as a UNIX domain socket path. If it starts with '\.\pipe', it is used as a Windows named pipe.

router

Default value: { isCaseSensitive: true, stripTrailingSlash: false }.

Controls how incoming request URIs are matched against the routing table:

  • isCaseSensitive - determines whether the paths '/example' and '/EXAMPLE' are considered different resources. Defaults to true.

  • stripTrailingSlash - removes trailing slashes on incoming paths. Defaults to false.

routes

Default value: none.

A route options object used as the default configuration for every route.

state

Default value:

{
    strictHeader: true,
    ignoreErrors: false,
    isSecure: true,
    isHttpOnly: true,
    isSameSite: 'Strict',
    encoding: 'none'
}

Sets the default configuration for every state (cookie) set explicitly via server.state() or implicitly (without definition) using the state configuration object.

tls

Default value: none.

Used to create an HTTPS connection. The tls object is passed unchanged to the node HTTPS server as described in the node HTTPS documentation.

Set to true when passing a listener object that has been configured to use TLS directly.

uri

Default value: constructed from runtime server information.

The full public URI without the path (e.g. 'http://example.com:8080'). If present, used as the server server.info.uri, otherwise constructed from the server settings.

Server properties

server.app

Access: read / write.

Provides a safe place to store server-specific run-time application data without potential conflicts with the framework internals. The data can be accessed whenever the server is accessible. Initialized with an empty object.

const server = Hapi.server();

server.app.key = 'value';

const handler = function (request, h) {

    return request.server.app.key;        // 'value'
};

server.auth.api

Access: authentication strategy specific.

An object where each key is an authentication strategy name and the value is the exposed strategy API. Available only when the authentication scheme exposes an API by returning an api key in the object returned from its implementation function.

const server = Hapi.server({ port: 80 });

const scheme = function (server, options) {

    return {
        api: {
            settings: {
                x: 5
            }
        },
        authenticate: function (request, h) {

            const authorization = request.headers.authorization;
            if (!authorization) {
                throw Boom.unauthorized(null, 'Custom');
            }

            return h.authenticated{ credentials: { user: 'john' } });
        }
    };
};

server.auth.scheme('custom', scheme);
server.auth.strategy('default', 'custom');

console.log(server.auth.api.default.settings.x);    // 5

server.auth.settings.default

Access: read only.

Contains the default authentication configuration is a default strategy was set via server.auth.default().

server.decorations

Access: read only.

Provides access to the decorations already applied to various framework interfaces. The object must not be modified directly, but only through server.decorate. Contains:

const Hapi = require('hapi');
const server = Hapi.server(({ port: 80 });

const success = function () {

    return this.response({ status: 'ok' });
};

server.decorate('toolkit', 'success', success);
console.log(server.decorations.toolkit);            // ['success']

server.events

Access: podium public interface.

The server events emitter. Utilizes the podium with support for event criteria validation, channels, and filters.

Use the following methods to interact with server.events:

Other methods include: server.events.removeListener(name, listener), server.events.removeAllListeners(name), and server.events.hasListeners(name).

'log' Event

The 'log' event type emits internal server events generated by the framework as well as application events logged with server.log().

The 'log' event handler uses the function signature function(event, tags) where:

  • event - an object with the following properties:

    • timestamp - the event timestamp.
    • tags - an array of tags identifying the event (e.g. ['error', 'http']).
    • channel - set to 'internal' for internally generated events, otherwise 'app' for events generated by server.log().
    • data - event-specific information. Available when event data was provided and is not an error. Errors are passed via error.
    • error - the error object related to the event if applicable. Cannot appear together with data.
  • tags - an object where each event.tag is a key and the value is true. Useful for quick identification of events.

server.events.on('log', (event, tags) => {

    if (tags.error) {
        console.log(`Server error: ${event.error ? event.error.message : 'unknown'}`);
    }
});

The internally generated events are (identified by their tags):

  • load - logs the current server load measurements when the server rejects a request due to high load. The event data contains the process load metrics.

  • connection client error - a clientError event was received from the HTTP or HTTPS listener. The event data is the error object received.

'request' Event

The 'request' event type emits internal request events generated by the framework as well as application events logged with request.log().

The 'request' event handler uses the function signature function(request, event, tags) where:

  • request - the request object.

  • event - an object with the following properties:

    • timestamp - the event timestamp.
    • tags - an array of tags identifying the event (e.g. ['error', 'http']).
    • channel - one of
      • 'app' - events generated by server.log().
      • 'error' - emitted once per request if the response had a 500 status code.
      • 'internal' - internally generated events.
    • request - the request identifier.
    • data - event-specific information. Available when event data was provided and is not an error. Errors are passed via error.
    • error - the error object related to the event if applicable. Cannot appear together with data.
  • tags - an object where each event.tag is a key and the value is true. Useful for quick identification of events.

server.events.on('request', (request, event, tags) => {

    if (tags.error) {
        console.log(`Request ${event.request} error: ${event.error ? event.error.message : 'unknown'}`);
    }
});

To listen to only one of the channels, use the event criteria object:

server.events.on({ name: 'request', channels: 'error' }, (request, event, tags) => {

    console.log(`Request ${event.request} failed`);
});

The internally generated events are (identified by their tags):

  • accept-encoding error - a request received contains an invalid Accept-Encoding header.
  • auth unauthenticated - no authentication scheme included with the request.
  • auth unauthenticated response {strategy} - the authentication strategy listed returned a non-error response (e.g. a redirect to a login page).
  • auth unauthenticated error {strategy} - the request failed to pass the listed authentication strategy (invalid credentials).
  • auth unauthenticated missing {strategy} - the request failed to pass the listed authentication strategy (no credentials found).
  • auth unauthenticated try {strategy} - the request failed to pass the listed authentication strategy in 'try' mode and will continue.
  • auth scope error - the request authenticated but failed to meet the scope requirements.
  • auth entity user error - the request authenticated but included an application entity when a user entity was required.
  • auth entity app error - the request authenticated but included a user entity when an application entity was required.
  • handler error - the route handler returned an error. Includes the execution duration and the error message.
  • pre error - a pre method was executed and returned an error. Includes the execution duration, assignment key, and error.
  • internal error - an HTTP 500 error response was assigned to the request.
  • internal implementation error - an incorrectly implemented lifecycle method.
  • request abort error - the request aborted.
  • request closed error - the request closed prematurely.
  • request error - the request stream emitted an error. Includes the error.
  • request server timeout error - the request took too long to process by the server. Includes the timeout configuration value and the duration.
  • state error - the request included an invalid cookie or cookies. Includes the cookies and error details.
  • state response error - the response included an invalid cookie which prevented generating a valid header. Includes the error.
  • payload error - failed processing the request payload. Includes the error.
  • response error - failed writing the response to the client. Includes the error.
  • response error close - failed writing the response to the client due to prematurely closed connection.
  • response error aborted - failed writing the response to the client due to prematurely aborted connection.
  • validation error {input} - input (i.e. payload, query, params, headers) validation failed. Includes the error.
  • validation response error - response validation failed. Includes the error message.
'response' Event

The 'response' event type is emitted after the response is sent back to the client (or when the client connection closed and no response sent, in which case request.response is null). A single event is emitted per request. The 'response' event handler uses the function signature function(request) where:

server.events.on('response', (request) => {

    console.log(`Response sent for request: ${request.id}`);
});
'route' Event

The 'route' event type is emitted when a route is added via server.route(). The 'route' event handler uses the function signature function(route) where:

server.events.on('route', (route) => {

    console.log(`New route added: ${route.path}`);
});
'start' Event

The 'start' event type is emitted when the server is started using server.start(). The 'start' event handler uses the function signature function().

server.events.on('start', (route) => {

    console.log('Server started');
});
'stop' Event

The 'stop' event type is emitted when the server is stopped using server.stop(). The 'stop' event handler uses the function signature function().

server.events.on('stop', (route) => {

    console.log('Server stopped');
});

server.info

Access: read only.

An object containing information about the server where:

const Hapi = require('hapi');
const server = Hapi.server(({ port: 80 });

console.log(server.info.port);            // 80

server.load

Access: read only.

An object containing the process load metrics (when load.sampleInterval is enabled):

  • eventLoopDelay - event loop delay milliseconds.
  • heapUsed - V8 heap usage.
  • rss - RSS memory usage.
const Hapi = require('hapi');
const server = Hapi.server({ load: { sampleInterval: 1000 } });

console.log(server.load.rss);

server.listener

Access: read only and listener public interface.

The node HTTP server object.

const Hapi = require('hapi');
const SocketIO = require('socket.io');

const server = Hapi.server({ port: 80 });

const io = SocketIO.listen(server.listener);
io.sockets.on('connection', (socket) => {

    socket.emit({ msg: 'welcome' });
});

server.methods

Access: read only.

Server methods are functions registered with the server and used throughout the application as a common utility. Their advantage is in the ability to configure them to use the built-in cache and share across multiple request handlers without having to create a common module.

sever.methods is an object which provides access to the methods registered via server.method() where each server method name is an object property.

const Hapi = require('hapi');
const server = Hapi.server();

server.method('add', (a, b) => (a + b));
const result = server.methods.add(1, 2);    // 3

server.mime

Access: read only and mimos public interface.

Provides access to the server MIME database used for setting content-type information. The object must not be modified directly but only through the mime server setting.

const Hapi = require('hapi');

const options = {
    mime: {
        override: {
            'node/module': {
                source: 'steve',
                compressible: false,
                extensions: ['node', 'module', 'npm'],
                type: 'node/module'
            }
        }
    }
};

const server = Hapi.server(options);
console.log(server.mime.path('code.js').type)        // 'application/javascript'
console.log(server.mime.path('file.npm').type)        // 'node/module'

server.plugins

Access: read / write.

An object containing the values exposed by each registered plugin where each key is a plugin name and the values are the exposed properties by each plugin using server.expose(). Plugins may set the value of the server.plugins[name] object directly or via the server.expose() method.

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        server.expose('key', 'value');
        server.plugins.example.other = 'other';

        console.log(server.plugins.example.key);      // 'value'
        console.log(server.plugins.example.other);    // 'other'
    }
};

server.realm

Access: read only.

The realm object contains sandboxed server settings specific to each plugin or authentication strategy. When registering a plugin or an authentication scheme, a server object reference is provided with a new server.realm container specific to that registration. It allows each plugin to maintain its own settings without leaking and affecting other plugins.

For example, a plugin can set a default file path for local resources without breaking other plugins' configured paths. When calling server.bind(), the active realm's settings.bind property is set which is then used by routes and extensions added at the same level (server root or plugin).

The server.realm object contains:

  • modifiers - when the server object is provided as an argument to the plugin register() method, modifiers provides the registration preferences passed the server.register() method and includes:

    • route - routes preferences:

      • prefix - the route path prefix used by any calls to server.route() from the server. Note that if a prefix is used and the route path is set to '/', the resulting path will not include the trailing slash.
      • vhost - the route virtual host settings used by any calls to server.route() from the server.
  • parent - the realm of the parent server object, or null for the root server.

  • plugin - the active plugin name (empty string if at the server root).

  • pluginOptions - the plugin options passed at registration.

  • plugins - plugin-specific state to be shared only among activities sharing the same active state. plugins is an object where each key is a plugin name and the value is the plugin state.

  • settings - settings overrides:

    • files.relativeTo
    • bind

The server.realm object should be considered read-only and must not be changed directly except for the plugins property which can be directly manipulated by each plugin, setting its properties inside plugins[name].

exports.register = function (server, options) {

    console.log(server.realm.modifiers.route.prefix);
};

server.registrations

Access: read only.

An object of the currently registered plugins where each key is a registered plugin name and the value is an object containing:

  • version - the plugin version.
  • name - the plugin name.
  • options - (optional) options passed to the plugin during registration.

server.settings

Access: read only.

The server configuration object after defaults applied.

const Hapi = require('hapi');
const server = Hapi.server({
    app: {
        key: 'value'
    }
});

console.log(server.settings.app);   // { key: 'value' }

server.version

Access: read only.

The hapi module version number.

const Hapi = require('hapi');
const server = Hapi.server();

console.log(server.version);        // '17.0.0'

server.auth.default(options)

Sets a default strategy which is applied to every route where:

Return value: none.

The default does not apply when a route config specifies auth as false, or has an authentication strategy configured (contains the strategy or strategies authentication settings). Otherwise, the route authentication config is applied to the defaults.

Note that if the route has authentication configured, the default only applies at the time of adding the route, not at runtime. This means that calling server.auth.default() after adding a route with some authentication config will have no impact on the routes added prior. However, the default will apply to routes added before server.auth.default() is called if those routes lack any authentication config.

The default auth strategy configuration can be accessed via server.auth.settings.default. To obtain the active authentication configuration of a route, use server.auth.lookup(request.route).

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.auth.scheme('custom', scheme);
server.auth.strategy('default', 'custom');
server.auth.default('default');

server.route({
    method: 'GET',
    path: '/',
    handler: function (request, h) {

        return request.auth.credentials.user;
    }
});

server.auth.scheme(name, scheme)

Registers an authentication scheme where:

Return value: none.

The scheme function must return an authentication scheme object when invoked.

Authentication scheme

An authentication scheme is an object with the following properties:

  • api - (optional) object which is exposed via the server.auth.api object.

  • async authenticate(request, h) - (required) a lifecycle method function called for each incoming request configured with the authentication scheme. The method is provided with two special toolkit methods for returning an authenticated or an unauthenticate result:

  • async payload(request, h) - (optional) a lifecycle method to authenticate the request payload.

  • async response(request, h) - (optional) a lifecycle method to decorate the response with authentication headers before the response headers or payload is written.

  • options - (optional) an object with the following keys:

    • payload - if true, requires payload validation as part of the scheme and forbids routes from disabling payload auth validation. Defaults to false.

When the scheme authenticate() method implementation throws an error or calls h.unauthenticated(), the specifics of the error affect whether additional authentication strategies will be attempted (if configured for the route). If the error includes a message, no additional strategies will be attempted. If the err does not include a message but does include the scheme name (e.g. Boom.unauthorized(null, 'Custom')), additional strategies will be attempted in the order of preference (defined in the route configuration). If authentication fails, the scheme names will be present in the 'WWW-Authenticate' header.

When the scheme payload() method throws an error with a message, it means payload validation failed due to bad payload. If the error has no message but includes a scheme name (e.g. Boom.unauthorized(null, 'Custom')), authentication may still be successful if the route auth.payload configuration is set to 'optional'.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const scheme = function (server, options) {

    return {
        authenticate: function (request, h) {

            const req = request.raw.req;
            const authorization = req.headers.authorization;
            if (!authorization) {
                throw Boom.unauthorized(null, 'Custom');
            }

            return h.authenticated({ credentials: { user: 'john' } });
        }
    };
};

server.auth.scheme('custom', scheme);

server.auth.strategy(name, scheme, [options])

Registers an authentication strategy where:

Return value: none.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.auth.scheme('custom', scheme);
server.auth.strategy('default', 'custom');

server.route({
    method: 'GET',
    path: '/',
    config: {
        auth: 'default',
        handler: function (request, h) {

            return request.auth.credentials.user;
        }
    }
});

await server.auth.test(strategy, request)

Tests a request against an authentication strategy where:

Return value: the authentication credentials object if authentication was successful, otherwise throws an error.

Note that the test() method does not take into account the route authentication configuration. It also does not perform payload authentication. It is limited to the basic strategy authentication execution. It does not include verifying scope, entity, or other route properties.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.auth.scheme('custom', scheme);
server.auth.strategy('default', 'custom');

server.route({
    method: 'GET',
    path: '/',
    handler: function (request, h) {

        try {
            const credentials = await request.server.auth.test('default', request);
            return { status: true, user: credentials.name };
        }
        catch (err) {
            return { status: false };
        }
    }
});

server.bind(context)

Sets a global context used as the default bind object when adding a route or an extension where:

Return value: none.

When setting a context inside a plugin, the context is applied only to methods set up by the plugin. Note that the context applies only to routes and extensions added after it has been set. Ignored if the method being bound is an arrow function.

const handler = function (request, h) {

    return this.message;    // Or h.context.message
};

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        const bind = {
            message: 'hello'
        };

        server.bind(bind);
        server.route({ method: 'GET', path: '/', handler });
    }
};

server.cache(options)

Provisions a cache segment within the server cache facility where:

  • options - catbox policy configuration where:

    • expiresIn - relative expiration expressed in the number of milliseconds since the item was saved in the cache. Cannot be used together with expiresAt.

    • expiresAt - time of day expressed in 24h notation using the 'HH:MM' format, at which point all cache records expire. Uses local time. Cannot be used together with expiresIn.

    • generateFunc - a function used to generate a new cache item if one is not found in the cache when calling get(). The method's signature is async function(id, flags) where:

      - `id` - the `id` string or object provided to the `get()` method.
      - `flags` - an object used to pass back additional flags to the cache where:
          - `ttl` - the cache ttl value in milliseconds. Set to `0` to skip storing in the
            cache. Defaults to the cache global policy.
      
    • staleIn - number of milliseconds to mark an item stored in cache as stale and attempt to regenerate it when generateFunc is provided. Must be less than expiresIn.

    • staleTimeout - number of milliseconds to wait before checking if an item is stale.

    • generateTimeout - number of milliseconds to wait before returning a timeout error when the generateFunc function takes too long to return a value. When the value is eventually returned, it is stored in the cache for future requests. Required if generateFunc is present. Set to false to disable timeouts which may cause all get() requests to get stuck forever.

    • generateOnReadError - if false, an upstream cache read error will stop the cache.get() method from calling the generate function and will instead pass back the cache error. Defaults to true.

    • generateIgnoreWriteError - if false, an upstream cache write error when calling cache.get() will be passed back with the generated value when calling. Defaults to true.

    • dropOnError - if true, an error or timeout in the generateFunc causes the stale value to be evicted from the cache. Defaults to true.

    • pendingGenerateTimeout - number of milliseconds while generateFunc call is in progress for a given id, before a subsequent generateFunc call is allowed. Defaults to 0 (no blocking of concurrent generateFunc calls beyond staleTimeout).

    • cache - the cache name configured in server.cache. Defaults to the default cache.

    • segment - string segment name, used to isolate cached items within the cache partition. When called within a plugin, defaults to '!name' where 'name' is the plugin name. When called within a server method, defaults to '#name' where 'name' is the server method name. Required when called outside of a plugin.

    • shared - if true, allows multiple cache provisions to share the same segment. Default to false.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const cache = server.cache({ segment: 'countries', expiresIn: 60 * 60 * 1000 });
await cache.set('norway', { capital: 'oslo' });
const value = await cache.get('norway');

await server.cache.provision(options)

Provisions a server cache as described in server.cache where:

  • options - same as the server cache configuration options.

Return value: none.

Note that if the server has been initialized or started, the cache will be automatically started to match the state of any other provisioned server cache.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

await server.initialize();
await server.cache.provision({ engine: require('catbox-memory'), name: 'countries' });

const cache = server.cache({ cache: 'countries', expiresIn: 60 * 60 * 1000 });
await cache.set('norway', { capital: 'oslo' });
const value = await cache.get('norway');

server.decoder(encoding, decoder)

Registers a custom content decoding compressor to extend the built-in support for 'gzip' and 'deflate' where:

Return value: none.

const Zlib = require('zlib');
const Hapi = require('hapi');
const server = Hapi.server({ port: 80, routes: { payload: { compression: { special: { chunkSize: 16 * 1024 } } } } });

server.decoder('special', (options) => Zlib.createGunzip(options));

server.decorate(type, property, method, [options])

Extends various framework interfaces with custom methods where:

Return value: none.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const success = function () {

    return this.response({ status: 'ok' });
};

server.decorate('toolkit', 'success', success);

server.route({
    method: 'GET',
    path: '/',
    handler: function (request, h) {

        return h.success();
    }
});

When registering a handler decoration, the method must be a function using the signature function(route, options) where:

  • route - the route information.
  • options - the configuration object provided in the handler config.
const Hapi = require('hapi');
const server = Hapi.server({ host: 'localhost', port: 8000 });

// Defines new handler for routes on this server

const handler = function (route, options) {

    return function (request, h) {

        return 'new handler: ' + options.msg;
    }
};

server.decorate('handler', 'test', handler);

server.route({
    method: 'GET',
    path: '/',
    handler: { test: { msg: 'test' } }
});

await server.start();

The method function can have a defaults object or function property. If the property is set to an object, that object is used as the default route config for routes using this handler. If the property is set to a function, the function uses the signature function(method) and returns the route default configuration.

const Hapi = require('hapi');
const server = Hapi.server({ host: 'localhost', port: 8000 });

const handler = function (route, options) {

    return function (request, h) {

        return 'new handler: ' + options.msg;
    }
};

// Change the default payload processing for this handler

handler.defaults = {
    payload: {
        output: 'stream',
        parse: false
    }
};

server.decorate('handler', 'test', handler);

server.dependency(dependencies, [after])

Used within a plugin to declare a required dependency on other plugins where:

  • dependencies - a single string or an array of plugin name strings which must be registered in order for this plugin to operate. Plugins listed must be registered before the server is initialized or started.

  • after - (optional) a function that is called after all the specified dependencies have been registered and before the server starts. The function is only called if the server is initialized or started. The function signature is async function(server) where:

    • server - the server the dependency() method was called on.

Return value: none.

The after method is identical to setting a server extension point on 'onPreStart'.

If a circular dependency is detected, an exception is thrown (e.g. two plugins each has an after function to be called after the other).

The method does not provide version dependency which should be implemented using npm peer dependencies.

const after = function (server) {

    // Additional plugin registration logic
};

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        server.dependency('yar', after);
    }
};

Dependencies can also be set via the plugin dependencies property (does not support setting after):

exports.plugin = {
    name: 'test',
    version: '1.0.0',
    dependencies: 'yar',
    register: function (server, options) { }
};

server.encoder(encoding, encoder)

Registers a custom content encoding compressor to extend the built-in support for 'gzip' and 'deflate' where:

Return value: none.

const Zlib = require('zlib');
const Hapi = require('hapi');
const server = Hapi.server({ port: 80, routes: { compression: { special: { chunkSize: 16 * 1024 } } } });

server.encoder('special', (options) => Zlib.createGzip(options));

server.event(events)

Register custom application events where:

Return value: none.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.event('test');
server.events.on('test', (update) => console.log(update));
await server.events.emit('test', 'hello');

await server.events.emit(criteria, data)

Emits a custom application event to all the subscribed listeners where:

  • criteria - the event update criteria which must be one of:

    • the event name string.
    • an object with the following optional keys (unless noted otherwise):
      • name - the event name string (required).
      • channel - the channel name string.
      • tags - a tag string or array of tag strings.
  • data - the value emitted to the subscribers. If data is a function, the function signature is function() and it called once to generate (return value) the actual data emitted to the listeners. If no listeners match the event, the data function is not invoked.

Return value: none.

Note that events must be registered before they can be emitted or subscribed to by calling server.event(events). This is done to detect event name misspelling and invalid event activities.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.event('test');
server.on('test', (update) => console.log(update));
await server.emit('test', 'hello');         // await is optional

server.events.on(criteria, listener)

Subscribe to an event where:

  • criteria - the subscription criteria which must be one of:

    • event name string which can be any of the built-in server events or a custom application event registered with server.event().

    • a criteria object with the following optional keys (unless noted otherwise):

      • name - (required) the event name string.

      • channels - a string or array of strings specifying the event channels to subscribe to. If the event registration specified a list of allowed channels, the channels array must match the allowed channels. If channels are specified, event updates without any channel designation will not be included in the subscription. Defaults to no channels filter.

      • clone - if true, the data object passed to server.event.emit() is cloned before it is passed to the listener method. Defaults to the event registration option (which defaults to false).

      • count - a positive integer indicating the number of times the listener can be called after which the subscription is automatically removed. A count of 1 is the same as calling server.events.once(). Defaults to no limit.

      • filter - the event tags (if present) to subscribe to which can be one of:

        • a tag string.

        • an array of tag strings.

        • an object with the following:

          • tags - a tag string or array of tag strings.
          • all - if true, all tags must be present for the event update to match the subscription. Defaults to false (at least one matching tag).
      • spread - if true, and the data object passed to server.event.emit() is an array, the listener method is called with each array element passed as a separate argument. This should only be used when the emitted data structure is known and predictable. Defaults to the event registration option (which defaults to false).

      • tags - if true and the criteria object passed to server.event.emit() includes tags, the tags are mapped to an object (where each tag string is the key and the value is true) which is appended to the arguments list at the end. Defaults to the event registration option (which defaults to false).

  • listener - the handler method set to receive event updates. The function signature depends on the event argument, and the spread and tags options.

Return value: none.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.event('test');
server.events.on('test', (update) => console.log(update));
await server.events.emit('test', 'hello');

server.events.once(criteria, listener)

Same as calling server.events.on() with the count option set to 1.

Return value: none.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.event('test');
server.events.once('test', (update) => console.log(update));
await server.events.emit('test', 'hello');
await server.events.emit('test', 'hello');       // Ignored

await server.events.once(criteria)

Same as calling server.events.on() with the count option set to 1.

Return value: a promise that resolves when the event is emitted.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.event('test');
const pending = server.events.once('test');
await server.events.emit('test', 'hello');
const update = await pending;

server.expose(key, value)

Used within a plugin to expose a property via server.plugins[name] where:

Return value: none.

exports.plugin = 
    name: 'example',
    register: function (server, options) {

        server.expose('util', () => console.log('something'));
    }
};

server.expose(obj)

Merges an object into to the existing content of server.plugins[name] where:

  • obj - the object merged into the exposed properties container.

Return value: none.

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        server.expose({ util: () => console.log('something') });
    }
};

Note that all the properties of obj are deeply cloned into server.plugins[name], so avoid using this method for exposing large objects that may be expensive to clone or singleton objects such as database client objects. Instead favor server.expose(key, value), which only copies a reference to value.

server.ext(events)

Registers an extension function in one of the request lifecycle extension points where:

  • events - an object or array of objects with the following:

    • type - (required) the extension point event name. The available extension points include the request extension points as well as the following server extension points:

      • 'onPreStart' - called before the connection listeners are started.
      • 'onPostStart' - called after the connection listeners are started.
      • 'onPreStop' - called before the connection listeners are stopped.
      • 'onPostStop' - called after the connection listeners are stopped.
    • method - (required) a function or an array of functions to be executed at a specified point during request processing. The required extension function signature is:

      • server extension points: async function(server) where:

        • server - the server object.
        • this - the object provided via options.bind or the current active context set with server.bind().
      • request extension points: a lifecycle method.

    • options - (optional) an object with the following:

      • before - a string or array of strings of plugin names this method must execute before (on the same event). Otherwise, extension methods are executed in the order added.

      • after - a string or array of strings of plugin names this method must execute after (on the same event). Otherwise, extension methods are executed in the order added.

      • bind - a context object passed back to the provided method (via this) when called. Ignored if the method is an arrow function.

      • sandbox - if set to 'plugin' when adding a request extension points the extension is only added to routes defined by the current plugin. Not allowed when configuring route-level extensions, or when adding server extensions. Defaults to 'server' which applies to any route added to the server the extension is added to.

Return value: none.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.ext({
    type: 'onRequest',
    method: function (request, h) {

        // Change all requests to '/test'

        request.setUrl('/test');
        return h.continue;
    }
});

server.route({ method: 'GET', path: '/test', handler: () => 'ok' });
await server.start();

// All requests will get routed to '/test'

server.ext(event, method, [options])

Registers a single extension event using the same properties as used in server.ext(events), but passed as arguments.

Return value: none.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.ext('onRequest', function (request, h) {

    // Change all requests to '/test'

    request.setUrl('/test');
    return h.continue;
});

server.route({ method: 'GET', path: '/test', handler: () => 'ok' });
await server.start();

// All requests will get routed to '/test'

await server.initialize()

Initializes the server (starts the caches, finalizes plugin registration) but does not start listening on the connection port.

Return value: none.

Note that if the method fails and throws an error, the server is considered to be in an undefined state and should be shut down. In most cases it would be impossible to fully recover as the various plugins, caches, and other event listeners will get confused by repeated attempts to start the server or make assumptions about the healthy state of the environment. It is recommended to abort the process when the server fails to start properly. If you must try to resume after an error, call server.stop() first to reset the server state.

const Hapi = require('hapi');
const Hoek = require('hoek');
const server = Hapi.server({ port: 80 });

await server.initialize();

await server.inject(options)

Injects a request into the server simulating an incoming HTTP request without making an actual socket connection. Injection is useful for testing purposes as well as for invoking routing logic internally without the overhead and limitations of the network stack.

The method utilizes the shot module for performing injections, with some additional options and response properties:

  • options - can be assigned a string with the requested URI, or an object with:

    • method - (optional) the request HTTP method (e.g. 'POST'). Defaults to 'GET'.

    • url - (required) the request URL. If the URI includes an authority (e.g. 'example.com:8080'), it is used to automatically set an HTTP 'Host' header, unless one was specified in headers.

    • headers - (optional) an object with optional request headers where each key is the header name and the value is the header content. Defaults to no additions to the default shot headers.

    • payload - (optional) an string, buffer or object containing the request payload. In case of an object it will be converted to a string for you. Defaults to no payload. Note that payload processing defaults to 'application/json' if no 'Content-Type' header provided.

    • credentials - (optional) an credentials object containing authentication information. The credentials are used to bypass the default authentication strategies, and are validated directly as if they were received via an authentication scheme. Defaults to no credentials.

    • artifacts - (optional) an artifacts object containing authentication artifact information. The artifacts are used to bypass the default authentication strategies, and are validated directly as if they were received via an authentication scheme. Ignored if set without credentials. Defaults to no artifacts.

    • app - (optional) sets the initial value of request.app, defaults to {}.

    • plugins - (optional) sets the initial value of request.plugins, defaults to {}.

    • allowInternals - (optional) allows access to routes with config.isInternal set to true. Defaults to false.

    • remoteAddress - (optional) sets the remote address for the incoming connection.

    • simulate - (optional) an object with options used to simulate client request stream conditions for testing:

      • error - if true, emits an 'error' event after payload transmission (if any). Defaults to false.

      • close - if true, emits a 'close' event after payload transmission (if any). Defaults to false.

      • end - if false, does not end the stream. Defaults to true.

      • split - indicates whether the request payload will be split into chunks. Defaults to undefined, meaning payload will not be chunked.

    • validate - (optional) if false, the options inputs are not validated. This is recommended for run-time usage of inject() to make it perform faster where input validation can be tested separately.

Return value: a response object with the following properties:

  • statusCode - the HTTP status code.

  • headers - an object containing the headers set.

  • payload - the response payload string.

  • rawPayload - the raw response payload buffer.

  • raw - an object with the injection request and response objects:

    • req - the simulated node request object.
    • res - the simulated node response object.
  • result - the raw handler response (e.g. when not a stream or a view) before it is serialized for transmission. If not available, the value is set to payload. Useful for inspection and reuse of the internal objects returned (instead of parsing the response string).

  • request - the request object.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.route({ method: 'GET', path: '/', handler: () => 'Success!' });

const res = await server.inject('/');
console.log(res.result);                // 'Success!'

server.log(tags, [data, [timestamp]])

Logs server events that cannot be associated with a specific request. When called the server emits a 'log' event which can be used by other listeners or plugins to record the information or output to the console. The arguments are:

  • tags - (required) a string or an array of strings (e.g. ['error', 'database', 'read']) used to identify the event. Tags are used instead of log levels and provide a much more expressive mechanism for describing and filtering events. Any logs generated by the server internally include the 'hapi' tag along with event-specific information.

  • data - (optional) an message string or object with the application data being logged. If data is a function, the function signature is function() and it called once to generate (return value) the actual data emitted to the listeners. If no listeners match the event, the data function is not invoked.

  • timestamp - (optional) an timestamp expressed in milliseconds. Defaults to Date.now() (now).

Return value: none.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.events.on('log', (event, tags) => {

    if (tags.error) {
        console.log(event);
    }
});

server.log(['test', 'error'], 'Test event');

server.lookup(id)

Looks up a route configuration where:

Return value: the route information if found, otherwise null.

const Hapi = require('hapi');
const server = Hapi.server();
server.route({
    method: 'GET',
    path: '/',
    config: {
        id: 'root',
        handler: () => 'ok'
    }
});

const route = server.lookup('root');

server.match(method, path, [host])

Looks up a route configuration where:

  • method - the HTTP method (e.g. 'GET', 'POST').
  • path - the requested path (must begin with '/').
  • host - (optional) hostname (to match against routes with vhost).

Return value: the route information if found, otherwise null.

const Hapi = require('hapi');
const server = Hapi.server();
server.route({
    method: 'GET',
    path: '/',
    config: {
        id: 'root',
        handler: () => 'ok'
    }
});

const route = server.match('get', '/');

server.method(name, method, [options])

Registers a server method where:

  • name - a unique method name used to invoke the method via server.methods[name].

  • method - the method function with a signature async function(...args, [flags]) where:

    • ...args - the method function arguments (can be any number of arguments or none).
    • flags - when caching is enabled, an object used to set optional method result flags:
      • ttl - 0 if result is valid but cannot be cached. Defaults to cache policy.
  • options - (optional) configuration object:

    • bind - a context object passed back to the method function (via this) when called. Defaults to active context (set via server.bind() when the method is registered. Ignored if the method is an arrow function.

    • cache - the same cache configuration used in server.cache(). The generateTimeout option is required.

    • generateKey - a function used to generate a unique key (for caching) from the arguments passed to the method function (the flags argument is not passed as input). The server will automatically generate a unique key if the function's arguments are all of types 'string', 'number', or 'boolean'. However if the method uses other types of arguments, a key generation function must be provided which takes the same arguments as the function and returns a unique string (or null if no key can be generated).

Return value: none.

Method names can be nested (e.g. utils.users.get) which will automatically create the full path under server.methods (e.g. accessed via server.methods.utils.users.get).

When configured with caching enabled, server.methods[name].cache is assigned an object with the following properties and methods: - await drop(...args) - a function that can be used to clear the cache for a given key. - stats - an object with cache statistics, see catbox for stats documentation.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

// Simple arguments

const add = function (a, b) {

    return a + b;
};

server.method('sum', add, { cache: { expiresIn: 2000, generateTimeout: 100 } });

console.log(await server.methods.sum(4, 5));          // 9

// Object argument

const addArray = function (array) {

    let sum = 0;
    array.forEach((item) => {

        sum += item;
    });

    return sum;
};

server.method('sumObj', addArray, {
    cache: { expiresIn: 2000, generateTimeout: 100 },
    generateKey: function (array) {

        return array.join(',');
    }
});

console.log(await server.methods.sumObj([5, 6]));     // 11

server.method(methods)

Registers a server method function as described in server.method() using a configuration object where:

  • methods - an object or an array of objects where each one contains:

    • name - the method name.
    • method - the method function.
    • options - (optional) settings.

Return value: none.

const add = function (a, b) {

    return a + b;
};

server.method({
    name: 'sum',
    method: add,
    options: {
        cache: {
            expiresIn: 2000,
            generateTimeout: 100
        }
    }
});

server.path(relativeTo)

Sets the path prefix used to locate static resources (files and view templates) when relative paths are used where:

  • relativeTo - the path prefix added to any relative file path starting with '.'.

Return value: none.

Note that setting a path within a plugin only applies to resources accessed by plugin methods. If no path is set, the server default route configuration files.relativeTo settings is used. The path only applies to routes added after it has been set.

exports.plugin = {
    name: 'example',
    register: function (server, options) {

        // Assuming the Inert plugin was registered previously

        server.path(__dirname + '../static');
        server.route({ path: '/file', method: 'GET', handler: { file: './test.html' } });
    }
};

await server.register(plugins, [options])

Registers a plugin where:

  • plugins - one or an array of:

    • a plugin object.

    • an object with the following:

      • plugin - a plugin object.
      • options - (optional) options passed to the plugin during registration.
      • once, routes - (optional) plugin-specific registration options as defined below.
  • options - (optional) registration options (different from the options passed to the registration function):

    • once - if true, subsequent registrations of the same plugin are skipped without error. Cannot be used with plugin options. Defaults to false. If not set to true, an error will be thrown the second time a plugin is registered on the server.

    • routes - modifiers applied to each route added by the plugin:

      • prefix - string added as prefix to any route path (must begin with '/'). If a plugin registers a child plugin the prefix is passed on to the child or is added in front of the child-specific prefix.
      • vhost - virtual host string (or array of strings) applied to every route. The outer-most vhost overrides the any nested configuration.

Return value: none.

await server.register({ plugin: require('plugin_name'), options: { message: 'hello' } });

server.route(route)

Adds a route where:

Return value: none.

Note that the options object is deeply cloned (with the exception of bind which is shallowly copied) and cannot contain any values that are unsafe to perform deep copy on.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

// Handler in top level

server.route({ method: 'GET', path: '/status', handler: () => 'ok' });

// Handler in config

const user = {
    cache: { expiresIn: 5000 },
    handler: function (request, h) {

        return { name: 'John' };
    }
};

server.route({ method: 'GET', path: '/user', config: user });

// An array of routes

server.route([
    { method: 'GET', path: '/1', handler: function (request, h) { return 'ok'; } },
    { method: 'GET', path: '/2', handler: function (request, h) { return 'ok'; } }
]);

Path parameters

Parameterized paths are processed by matching the named parameters to the content of the incoming request path at that path segment. For example, '/book/{id}/cover' will match '/book/123/cover' and request.params.id will be set to '123'. Each path segment (everything between the opening '/' and the closing '/' unless it is the end of the path) can only include one named parameter. A parameter can cover the entire segment ('/{param}') or part of the segment ('/file.{ext}'). A path parameter may only contain letters, numbers and underscores, e.g. '/{file-name}' is invalid and '/{file_name}' is valid.

An optional '?' suffix following the parameter name indicates an optional parameter (only allowed if the parameter is at the ends of the path or only covers part of the segment as in '/a{param?}/b'). For example, the route '/book/{id?}' matches '/book/' with the value of request.params.id set to an empty string ''.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const getAlbum = function (request, h) {

    return 'You asked for ' +
        (request.params.song ? request.params.song + ' from ' : '') +
        request.params.album;
};

server.route({
    path: '/{album}/{song?}',
    method: 'GET',
    handler: getAlbum
});

In addition to the optional ? suffix, a parameter name can also specify the number of matching segments using the * suffix, followed by a number greater than 1. If the number of expected parts can be anything, then use * without a number (matching any number of segments can only be used in the last path segment).

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const getPerson = function (request, h) {

    const nameParts = request.params.name.split('/');
    return { first: nameParts[0], last: nameParts[1] };
};

server.route({
    path: '/person/{name*2}',   // Matches '/person/john/doe'
    method: 'GET',
    handler: getPerson
});

Path matching order

The router iterates through the routing table on each incoming request and executes the first (and only the first) matching route. Route matching is done based on the combination of the request path and the HTTP verb (e.g. 'GET, 'POST'). The query is excluded from the routing logic. Requests are matched in a deterministic order where the order in which routes are added does not matter.

Routes are matched based on the specificity of the route which is evaluated at each segment of the incoming request path. Each request path is split into its segment (the parts separated by '/'). The segments are compared to the routing table one at a time and are matched against the most specific path until a match is found. If no match is found, the next match is tried.

When matching routes, string literals (no path parameter) have the highest priority, followed by mixed parameters ('/a{p}b'), parameters ('/{p}'), and then wildcard (/{p*}).

Note that mixed parameters are slower to compare as they cannot be hashed and require an array iteration over all the regular expressions representing the various mixed parameter at each routing table node.

Catch all route

If the application needs to override the default Not Found (404) error response, it can add a catch-all route for a specific method or all methods. Only one catch-all route can be defined per server connection.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const handler = function (request, h) {

    return h.response('The page was not found').code(404);
};

server.route({ method: '*', path: '/{p*}', handler });

await server.start([callback])

Starts the server by listening for incoming requests on the configured port (unless the connection was configured with autoListen set to false).

Return value: none.

Note that if the method fails and throws an error, the server is considered to be in an undefined state and should be shut down. In most cases it would be impossible to fully recover as the various plugins, caches, and other event listeners will get confused by repeated attempts to start the server or make assumptions about the healthy state of the environment. It is recommended to abort the process when the server fails to start properly. If you must try to resume after an error, call server.stop() first to reset the server state.

If a started server is started again, the second call to server.start() is ignored. No events will be emitted and no extension points invoked.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

await server.start();
console.log('Server started at: ' + server.info.uri);

server.state(name, [options])

HTTP state management uses client cookies to persist a state across multiple requests. Registers a cookie definitions where:

  • name - the cookie name string.

  • options - are the optional cookie settings:

    • ttl - time-to-live in milliseconds. Defaults to null (session time-life - cookies are deleted when the browser is closed).

    • isSecure - sets the 'Secure' flag. Defaults to true.

    • isHttpOnly - sets the 'HttpOnly' flag. Defaults to true.

    • isSameSite - sets the 'SameSite' flag. The value must be one of:

      • false - no flag.
      • 'Strict' - sets the value to 'Strict' (this is the default value).
      • 'Lax' - sets the value to 'Lax'.
    • path - the path scope. Defaults to null (no path).

    • domain - the domain scope. Defaults to null (no domain).

    • autoValue - if present and the cookie was not received from the client or explicitly set by the route handler, the cookie is automatically added to the response with the provided value. The value can be a function with signature async function(request) where:

    • encoding - encoding performs on the provided value before serialization. Options are:

      • 'none' - no encoding. When used, the cookie value must be a string. This is the default value.
      • 'base64' - string value is encoded using Base64.
      • 'base64json' - object value is JSON-stringified then encoded using Base64.
      • 'form' - object value is encoded using the x-www-form-urlencoded method.
      • 'iron' - Encrypts and sign the value using iron.
    • sign - an object used to calculate an HMAC for cookie integrity validation. This does not provide privacy, only a mean to verify that the cookie value was generated by the server. Redundant when 'iron' encoding is used. Options are:

    • password - password used for 'iron' encoding (must be at least 32 characters long).

    • iron - options for 'iron' encoding. Defaults to require('iron').defaults.

    • ignoreErrors - if true, errors are ignored and treated as missing cookies.

    • clearInvalid - if true, automatically instruct the client to remove invalid cookies. Defaults to false.

    • strictHeader - if false, allows any cookie value including values in violation of RFC 6265. Defaults to true.

    • passThrough - used by proxy plugins (e.g. h2o2).

Return value: none.

State defaults can be modified via the server default state configuration option.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

// Set cookie definition

server.state('session', {
    ttl: 24 * 60 * 60 * 1000,     // One day
    isSecure: true,
    path: '/',
    encoding: 'base64json'
});

// Set state in route handler

const handler = function (request, h) {

    let session = request.state.session;
    if (!session) {
        session = { user: 'joe' };
    }

    session.last = Date.now();

    return h.response('Success').state('session', session);
};

Registered cookies are automatically parsed when received. Parsing rules depends on the route state.parse configuration. If an incoming registered cookie fails parsing, it is not included in request.state, regardless of the state.failAction setting. When state.failAction is set to 'log' and an invalid cookie value is received, the server will emit a 'request-internal' event. To capture these errors subscribe to the 'request-internal' events and filter on 'error' and 'state' tags:

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.events.on('request-internal', (request, event, tags) => {

    if (tags.error && tags.state) {
        console.error(event);
    }
});

await server.stop([options])

Stops the server's listener by refusing to accept any new connections or requests (existing connections will continue until closed or timeout), where:

  • options - (optional) object with:

    • timeout - overrides the timeout in millisecond before forcefully terminating a connection. Defaults to 5000 (5 seconds).

Return value: none.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

await server.stop({ timeout: 60 * 1000 });
console.log('Server stopped');

server.table([host])

Returns a copy of the routing table where:

  • host - (optional) host to filter routes matching a specific virtual host. Defaults to all virtual hosts.

Return value: an array of routes where each route contains:

  • settings - the route config with defaults applied.
  • method - the HTTP method in lower case.
  • path - the route path.
const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });
server.route({ method: 'GET', path: '/example', handler: () => 'ok' });

const table = server.table();

Route options

Each route can be customized to change the default behavior of the request lifecycle.

route.options.app

Application-specific route configuration state. Should not be used by plugins which should use options.plugins[name] instead.

route.options.auth

Route authentication configuration. Value can be:

Authentication options

route.options.access

Default value: none.

An object or array of objects specifying the route access rules. Each rule is evaluated against an incoming request and access is granted if at least one of the rules matches. Each rule object must include at least one of scope or entity.

route.options.access.scope

Default value: false (no scope requirements).

The application scope required to access the route. Value can be a scope string or an array of scope strings. When authenticated, the credentials object scope property must contain at least one of the scopes defined to access the route.

If a scope string begins with a + character, that scope is required. If a scope string begins with a ! character, that scope is forbidden. For example, the scope ['!a', '+b', 'c', 'd'] means the incoming request credentials' scope must not include 'a', must include 'b', and must include one of 'c' or 'd'.

You may also access properties on the request object (query, params, payload, and credentials) to populate a dynamic scope by using the '{' and '}' characters around the property name, such as 'user-{params.id}'.

route.options.access.entity

Default value: 'any'.

The required authenticated entity type. If set, must match the entity value of the request authenticated credentials. Available values:

  • 'any' - the authentication can be on behalf of a user or application.
  • 'user' - the authentication must be on behalf of a user which is identified by the presence of a 'user' attribute in the credentials object returned by the authentication strategy.
  • 'app' - the authentication must be on behalf of an application which is identified by the lack of presence of a user attribute in the credentials object returned by the authentication strategy.
route.options.access.mode

Default value: 'required'.

The authentication mode. Available values:

  • 'required' - authentication is required.
  • 'optional' - authentication is optional - the request must include valid credentials or no credentials at all.
  • 'try' - similar to 'optional', any request credentials are attempted authentication, but if the credentials are invalid, the request proceeds regardless of the authentication error.
route.options.access.payload

Default value: false, unless the scheme requires payload authentication.

If set, the incoming request payload is authenticated after it is processed. Requires a strategy with payload authentication support (e.g. Hawk). Cannot be set to a value other than 'required' when the scheme sets the authentication options.payload to true.

Available values:

  • false - no payload authentication.
  • 'required' - payload authentication required.
  • 'optional' - payload authentication performed only when the client includes payload authentication information (e.g. hash attribute in Hawk).
route.options.access.strategies

Default value: the default strategy set via server.auth.default().

An array of string strategy names in the order they should be attempted. Cannot be used together with strategy.

route.options.access.strategy

Default value: the default strategy set via server.auth.default().

A string strategy names. Cannot be used together with strategies.

route.options.bind

Default value: null.

An object passed back to the provided handler (via this) when called. Ignored if the method is an arrow function.

route.options.cache

Default value: { privacy: 'default', statuses: [200], otherwise: 'no-cache' }.

If the route method is 'GET', the route can be configured to include HTTP caching directives in the response. Caching can be customized using an object with the following options:

  • privacy - determines the privacy flag included in client-side caching using the 'Cache-Control' header. Values are:

    • 'default' - no privacy flag.
    • 'public' - mark the response as suitable for public caching.
    • 'private' - mark the response as suitable only for private caching.
  • expiresIn - relative expiration expressed in the number of milliseconds since the item was saved in the cache. Cannot be used together with expiresAt.

  • expiresAt - time of day expressed in 24h notation using the 'HH:MM' format, at which point all cache records for the route expire. Cannot be used together with expiresIn.

  • statuses - an array of HTTP response status code numbers (e.g. 200) which are allowed to include a valid caching directive.

  • otherwise - a string with the value of the 'Cache-Control' header when caching is disabled.

The default Cache-Control: no-cache header can be disabled by setting cache to false.

route.options.compression

An object where each key is a content-encoding name and each value is an object with the desired encoder settings. Note that decoder settings are set in compression.

route.options.cors

Default value: false (no CORS headers).

The Cross-Origin Resource Sharing protocol allows browsers to make cross-origin API calls. CORS is required by web applications running inside a browser which are loaded from a different domain than the API server. To enable, set cors to true, or to an object with the following options:

  • origin - an array of allowed origin servers strings ('Access-Control-Allow-Origin'). The array can contain any combination of fully qualified origins along with origin strings containing a wildcard '*' character, or a single '*' origin string. If set to 'ignore', any incoming Origin header is ignored (present or not) and the 'Access-Control-Allow-Origin' header is set to '*'. Defaults to any origin ['*'].

  • maxAge - number of seconds the browser should cache the CORS response ('Access-Control-Max-Age'). The greater the value, the longer it will take before the browser checks for changes in policy. Defaults to 86400 (one day).

  • headers - a strings array of allowed headers ('Access-Control-Allow-Headers'). Defaults to ['Accept', 'Authorization', 'Content-Type', 'If-None-Match'].

  • additionalHeaders - a strings array of additional headers to headers. Use this to keep the default headers in place.

  • exposedHeaders - a strings array of exposed headers ('Access-Control-Expose-Headers'). Defaults to ['WWW-Authenticate', 'Server-Authorization'].

  • additionalExposedHeaders - a strings array of additional headers to exposedHeaders. Use this to keep the default headers in place.

  • credentials - if true, allows user credentials to be sent ('Access-Control-Allow-Credentials'). Defaults to false.

route.options.description

Default value: none.

Route description used for generating documentation (string).

This setting is not available when setting server route defaults using server.options.routes.

route.options.ext

Default value: none.

Route-level request extension points by setting the option to an object with a key for each of the desired extension points ('onRequest' is not allowed), and the value is the same as the server.ext(events) event argument.

route.options.files

Default value: { relativeTo: '.' }.

Defines the behavior for accessing files:

  • relativeTo - determines the folder relative paths are resolved against.

route.options.handler

Default value: none.

The route handler function performs the main business logic of the route and sets the respons. handler can be assigned:

  • a lifecycle method.

  • an object with a single property using the name of a handler type registred with the server.handler() method. The matching property value is passed as options to the registered handler generator.

const handler = function (request, h) {

    return 'success';
};

Note: handlers using a fat arrow style function cannot be bound to any bind property. Instead, the bound context is available under h.context.

route.options.id

Default value: none.

An optional unique identifier used to look up the route using server.lookup(). Cannot be assigned to routes added with an array of methods.

route.options.isInternal

Default value: false.

If true, the route cannot be accessed through the HTTP listener but only through the server.inject() interface with the allowInternals option set to true. Used for internal routes that should not be accessible to the outside world.

route.options.json

Default value: none.

Optional arguments passed to JSON.stringify() when converting an object or error response to a string payload or escaping it after stringification. Supports the following:

route.options.jsonp

Default value: none.

Enables JSONP support by setting the value to the query parameter name containing the function name used to wrap the response payload.

For example, if the value is 'callback', a request comes in with 'callback=me', and the JSON response is '{ "a":"b" }', the payload will be 'me({ "a":"b" });'. Cannot be used with stream responses.

The 'Content-Type' response header is set to 'text/javascript' and the 'X-Content-Type-Options' response header is set to 'nosniff', and will override those headers even if explicitly set by response.type().

route.options.log

Default value: { collect: false }.

Request logging options:

route.options.notes

Default value: none.

Route notes used for generating documentation (string or array of strings).

This setting is not available when setting server route defaults using server.options.routes.

route.options.payload

Determines how the request payload is processed.

route.options.payload.allow

Default value: allows parsing of the following mime types:

  • application/json
  • application/*+json
  • application/octet-stream
  • application/x-www-form-urlencoded
  • multipart/form-data
  • text/*

A string or an array of strings with the allowed mime types for the endpoint. Use this settings to limit the set of allowed mime types. Note that allowing additional mime types not listed above will not enable them to be parsed, and if parse is true, the request will result in an error response.

route.options.payload.compression

Default value: none.

An object where each key is a content-encoding name and each value is an object with the desired decoder settings. Note that encoder settings are set in compression.

route.options.payload.defaultContentType

Default value: 'application/json'.

The default content type if the 'Content-Type' request header is missing.

route.options.payload.failAction

Default value: 'error' (return a Bad Request (400) error response).

A failAction value which determines how to handle payload parsing errors.

route.options.payload.maxBytes

Default value: 1048576 (1MB).

Limits the size of incoming payloads to the specified byte count. Allowing very large payloads may cause the server to run out of memory.

route.options.payload.multipart

Default value: none.

Overrides payload processing for multipart requests. Value can be one of:

route.options.payload.output

Default value: 'data'.

The processed payload format. The value must be one of:

  • 'data' - the incoming payload is read fully into memory. If parse is true, the payload is parsed (JSON, form-decoded, multipart) based on the 'Content-Type' header. If parse is false, a raw Buffer is returned.

  • 'stream' - the incoming payload is made available via a Stream.Readable interface. If the payload is 'multipart/form-data' and parse is true, field values are presented as text while files are provided as streams. File streams from a 'multipart/form-data' upload will also have a hapi property containing the filename and headers properties. Note that payload streams for multipart payloads are a synthetic interface created on top of the entire mutlipart content loaded into memory. To avoid loading large multipart payloads into memory, set parse to false and handle the multipart payload in the handler using a streaming parser (e.g. pez).

  • 'file' - the incoming payload is written to temporary file in the directory specified by the uploads settings. If the payload is 'multipart/form-data' and parse is true, field values are presented as text while files are saved to disk. Note that it is the sole responsibility of the application to clean up the files generated by the framework. This can be done by keeping track of which files are used (e.g. using the request.app object), and listening to the server 'response' event to perform cleanup.

route.options.payload.override

Default value: none.

A mime type string overriding the 'Content-Type' header value received.

route.options.payload.parse

Default value: true.

Determines if the incoming payload is processed or presented raw. Available values:

  • true - if the request 'Content-Type' matches the allowed mime types set by allow (for the whole payload as well as parts), the payload is converted into an object when possible. If the format is unknown, a Bad Request (400) error response is sent. Any known content encoding is decoded.

  • false - the raw payload is returned unmodified.

  • 'gunzip' - the raw payload is returned unmodified after any known content encoding is decoded.

route.options.payload.timeout

Default value: to 10000 (10 seconds).

Payload reception timeout in milliseconds. Sets the maximum time allowed for the client to transmit the request payload (body) before giving up and responding with a Request Timeout (408) error response.

Set to false to disable.

route.options.payload.uploads

Default value: os.tmpdir().

The directory used for writing file uploads.

route.options.plugins

Default value: {}.

Plugin-specific configuration. plugins is an object where each key is a plugin name and the value is the plugin configuration.

route.options.pre

Default value: none.

The pre option allows defining methods for performing actions before the handler is called. These methods allow breaking the handler logic into smaller, reusable components that can be shared ascross routes, as well as provide a cleaner error handling of prerequisite operations (e.g. load required reference data from a database).

pre is assigned an ordered array of methods which are called serially in order. If the pre array contains another array of methods as one of its elements, those methods are called in parallel. Note that during parallel execution, if any of the methods error, return a takeover response, or abort signal, the other parallel methods will continue to execute but will be ignored once completed.

pre can be assigned a mixed array of:

  • an array containing the elements listed below, which are executed in parallel.

  • an object with:

    • method - a lifecycle method.
    • assign - key name used to assign the response of the method to in request.pre and request.preResponses.
    • failAction - A failAction value which determine what to do when a pre-handler method throws an error. If assign is specified and the failAction setting is not 'error', the error will be assigned.
  • a method function - same as including an object with a single method key.

Note that pre-handler methods do not behave the same way other lifecycle methods do when a value is returned. Instead of the return value becoming the new response payload, the value is used to assign the corresponding request.pre and request.preResponses properties. Otherwise, the handling of errors, takeover response response, or abort signal behave the same as any other lifecycle methods.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const pre1 = function (request, h) {

    return 'Hello';
};

const pre2 = function (request, h) {

    return 'World';
};

const pre3 = function (request, h) {

    return request.pre.m1 + ' ' + request.pre.m2;
};

server.route({
    method: 'GET',
    path: '/',
    config: {
        pre: [
            [
                // m1 and m2 executed in parallel
                { method: pre1, assign: 'm1' },
                { method: pre2, assign: 'm2' }
            ],
            { method: pre3, assign: 'm3' },
        ],
        handler: function (request, h) {

            return request.pre.m3 + '!\n';
        }
    }
});

route.options.response

Processing rules for the outgoing response.

route.options.response.emptyStatusCode

Default value: 200.

The default HTTP status code when the payload is considered empty. Value can be 200 or 204. Note that a 200 status code is converted to a 204 only at the time of response transmission (the response status code will remain 200 throughout the request lifecycle unless manually set).

route.options.response.failAction

Default value: 'error' (return an Internal Server Error (500) error response).

A failAction value which defines what to do when a response fails payload validation.

route.options.response.modify

Default value: false.

If true, applies the validation rule changes to the response payload.

route.options.response.options

Default value: none.

joi options object pass to the validation function. Useful to set global options such as stripUnknown or abortEarly (the complete list is available here). If a custom validation function is defined via schema or status then options can an arbitrary object that will be passed to this function as the second argument.

route.options.response.ranges

Default value: true.

If false, payload range support is disabled.

route.options.response.sample

Default value: 100 (all responses).

The percent of response payloads validated (0 - 100). Set to 0 to disable all validation.

route.options.response.schema

Default value: true (no validation).

The default response payload validation rules (for all non-error responses) expressed as one of:

  • true - any payload allowed (no validation).

  • false - no payload allowed.

  • a joi validation object. The options along with the request context ({ headers, params, query, payload, app, auth }) are passed to the validation function.

  • a validation function using the signature async function(value, options) where:

    • value - the pending response payload.

    • options - The options along with the request context ({ headers, params, query, payload, app, auth }).

    • if the function returns a value and modify is true, the value is used as the new response. If the original response is an error, the return value is used to override the original error output.payload. If an error is thrown, the error is processed according to failAction.

route.options.response.status

Default value: none.

Validation schemas for specific HTTP status codes. Responses (excluding errors) not matching the listed status codes are validated using the default schema.

status is set to an object where each key is a 3 digit HTTP status code and the value has the same definition as schema.

route.options.security

Default value: false (security headers disabled).

Sets common security headers. To enable, set security to true or to an object with the following options:

route.options.state

Default value: { parse: true, failAction: 'error' }.

HTTP state management (cookies) allows the server to store information on the client which is sent back to the server with every request (as defined in RFC 6265). state supports the following options:

  • parse - determines if incoming 'Cookie' headers are parsed and stored in the request.state object.

  • failAction - A failAction value which determines how to handle cookie parsing errors. Defaults to 'error' (return a Bad Request (400) error response).

route.options.tags

Default value: none.

Route tags used for generating documentation (array of strings).

This setting is not available when setting server route defaults using server.options.routes.

route.options.timeout

Default value: { server: false }.

Timeouts for processing durations.

route.options.timeout.server

Default value: false.

Response timeout in milliseconds. Sets the maximum time allowed for the server to respond to an incoming request before giving up and responding with a Service Unavailable (503) error response.

route.options.timeout.socket

Default value: none (use node default of 2 minutes).

By default, node sockets automatically timeout after 2 minutes. Use this option to override this behavior. Set to false to disable socket timeouts.

route.options.validate

Default value: { headers: true, params: true, query: true, payload: true, failAction: 'error' }.

Request input validation rules for various request components.

route.options.validate.errorFields

Default value: none.

An optional object with error fields copied into every validation error response.

route.options.validate.failAction

Default value: 'error' (return a Bad Request (400) error response).

A failAction value which determines how to handle failed validations. When set to a function, the err argument includes the type of validation error under err.output.payload.validation.source.

route.options.validate.headers

Default value: true (no validation).

Validation rules for incoming request headers:

Note that all header field names must be in lowercase to match the headers normalized by node.

route.options.validate.options

Default value: none.

An options object passed to the joi rules or the custom validation methods. Used for setting global options such as stripUnknown or abortEarly (the complete list is available here).

If a custom validation function (see headers, params, query, or payload above) is defined then options can an arbitrary object that will be passed to this function as the second parameter.

The values of the other inputs (i.e. headers, query, params, payload, app, and auth) are added to the options object under the validation context (accessible in rules as Joi.ref('$query.key')).

Note that validation is performed in order (i.e. headers, params, query, and payload) and if type casting is used (e.g. converting a string to a number), the value of inputs not yet validated will reflect the raw, unvalidated and unmodified values.

If the validation rules for headers, params, query, and payload are defined at both the server routes level and at the route level, the individual route settings override the routes defaults (the rules are not merged).

route.options.validate.params

Default value: true (no validation).

Validation rules for incoming request path parameters, after matching the path against the route, extracting any parameters, and storing them in request.params, where:

  • true - any path parameter value allowed (no validation performed).

  • a joi validation object.

  • a validation function using the signature async function(value, options) where:

    • value - the request.params object containing the request path parameters.
    • options - options.
    • if a value is returned, the value is used as the new request.params value and the original value is stored in request.orig.params. Otherwise, the path parameters are left unchanged. If an error is thrown, the error is handled according to failAction.

Note that failing to match the validation rules to the route path parameters definition will cause all requests to fail.

route.options.validate.payload

Default value: true (no validation).

Validation rules for incoming request payload (request body), where:

  • true - any payload allowed (no validation performed).

  • false - no payload allowed.

  • a joi validation object.

    • Note that empty payloads are represented by a null value. If a validation schema is provided and empty payload are allowed, the schema must be explicitly defined by setting the rule to a joi schema with null allowed (e.g. Joi.object({ /* keys here */ }).allow(null)).
  • a validation function using the signature async function(value, options) where:

    • value - the request.query object containing the request query parameters.
    • options - options.
    • if a value is returned, the value is used as the new request.payload value and the original value is stored in request.orig.payload. Otherwise, the payload is left unchanged. If an error is thrown, the error is handled according to failAction.

Note that validating large payloads and modifying them will cause memory duplication of the payload (since the original is kept), as well as the significant performance cost of validating large amounts of data.

route.options.validate.query

Default value: true (no validation).

Validation rules for incoming request URI query component (the key-value part of the URI between '?' and '#'). The query is parsed into its individual key-value pairs, decoded, and stored in request.query prior to validation. Where:

  • true - any query parameter value allowed (no validation performed).

  • false - no query parameter value allowed.

  • a joi validation object.

  • a validation function using the signature async function(value, options) where:

    • value - the request.query object containing the request query parameters.
    • options - options.
    • if a value is returned, the value is used as the new request.query value and the original value is stored in request.orig.query. Otherwise, the query parameters are left unchanged. If an error is thrown, the error is handled according to failAction.

Note that changes to the query parameters will not be reflected in request.url.

Request lifecycle

Each incoming request passes through the request lifecycle. The specific steps vary based on the server and route configurations, but the order in which the applicable steps are executed is always the same. The following is the complete list of steps a request can go through:

  • onRequest

    • always called when onRequest extensions exist.
    • the request path and method can be modified via the request.setUrl() and request.setMethod() methods. Changes to the request path or method will impact how the request is routed and can be used for rewrite rules.
    • request.route is unassigned.
    • JSONP configuration is ignored for any response returned from the extension point since no route is matched yet and the JSONP configuration is unavailable.
  • Route lookup

    • lookup based on request.path and request.method.
    • skips to onPreResponse if no route is found or if the path violates the HTTP specification.
  • JSONP processing

    • based on the route jsonp option.
    • parses JSONP parameter from request.query.
    • skips to Response validation on error.
  • Cookies processing

  • onPreAuth

    • called regardless if authentication is performed.
  • Authentication

    • based on the route auth option.
  • Payload processing

  • Payload authentication

    • based on the route auth option.
  • onCredentials

    • called only if authentication is performed.
  • Authorization

    • based on the route authentication access option.
  • onPostAuth

    • called regardless if authentication is performed.
  • Headers validation

  • Path parameters validation

  • JSONP cleanup

  • Query validation

  • Payload validation

  • onPreHandler

  • Pre-handler methods

    • based on the route pre option.
    • error handling based on each pre-handler method's failAction setting.
  • Route handler

  • onPostHandler

    • the response contained in request.response may be modified (but not assigned a new value). To return a different response type (for example, replace an error with an HTML response), return a new response value.
  • Response validation

  • onPreResponse

    • always called, unless the request is aborted.
    • the response contained in request.response may be modified (but not assigned a new value). To return a different response type (for example, replace an error with an HTML response), return a new response value. Note that any errors generated will not be passed back to onPreResponse to prevent an infinite loop.
  • Response transmission

    • may emit 'request-error' event.
  • Finalize request

    • emits 'response' event.

Lifecycle methods

Lifecycle methods are the interface between the framework and the application. Many of the request lifecycle steps: extensions, authentication, handlers, pre-handler methods, and failAction function values are lifecyle methods provided by the developer and executed by the framework.

Each lifecycle method is a function with the signature await function(request, h, [err]) where:

Each lifecycle method must return a value or a promise that resolves into a value. If a lifecycle method returns without a value or resolves to an undefined value, an Internal Server Error (500) error response is sent.

The return value must be one of:

  • Plain value:
    • null
    • string
    • number
    • boolean
  • Buffer object
  • Error object
    • plain Error.
    • a Boom object.
  • Stream object
    • must be compatible with the "streams2" API and not be in objectMode.
    • if the stream object has a statusCode property, that status code will be used as the default response code based on the passThrough option.
    • if the stream object has a headers property, the headers will be included in the response based on the passThrough option.
    • if the stream object has a function property setCompressor(compressor) and the response passes through a compressor, a reference to the compressor stream will be passed to the response stream via this method.
  • any object or array
    • must not include circular references.
  • a toolkit signal:
    • h.abandon - abort processing the request.
    • h.close - abort processing the request and call end() to ensure the response is closed.
    • h.continue - continue processing the request lifecycle without changing the response.
  • a toolkit method response:
  • a promise object that resolve to any of the above values

Any error thrown by a lifecycle method will be used as the reponse object. While errors and valid values can be returned, it is recommended to throw errors. Throwing non-error values will generate a Bad Implementation (500) error response.

const handler = function (request, h) {

    if (request.query.forbidden) {
        throw Boom.badRequest();
    }

    return 'success';
};

If the route has a bind option or server.bind() was called, the lifecycle method will be bound to the provided context via this as well as accessible via h.context.

Lifecycle workflow

The flow between each lifecyle step depends on the value returned by each lifecycle method as follows:

  • an error:

    • the lifecycle skips to the _Response validation_ step.
    • if returned by the onRequest step it skips to the onPreResponse step.
    • if returned by the Response validation step it skips to the onPreResponse step.
    • if returned by the onPreResponse step it skips to the Response transmission step.
  • an abort signal (h.abandon or h.close):

    • skips to the Finalize request step.
  • a h.continue signal:

    • continues processing the request lifecycle without changing the request response.
    • cannot be used by the authenticate() scheme method.
  • a takeover response:

    • overrides the request response with the provided value and skips to the Response validation step.
    • if returned by the Response validation step it skips to the onPreResponse step.
    • if returned by the onPreResponse step it skips to the Response transmission step.
  • any other response:

    • overrides the request response with the provided value and continues processing the request lifecycle.
    • cannot be returned from any step prior to the Pre-handler methods step.

The authenticate() method has access to two additional return values: - h.authenticated() - indicate request autheticated successfully. - h.unauthenticated() - indicate request failed to autheticate.

Note that these rules are apply somewhat differently when used in a pre-handler method.

Takeover response

A takeover response is a response object on which response.takeover() was called to signal that the lifecycle method return value should be set as the response and skip to immediately validate and trasmit the value, bypassing other lifecycle steps.

failAction configuration

Various configuration options allows defining how errors are handled. For example, when invalid payload is received or malformed cookie, instead of returning an error, the framework can be configured to perform another action. When supported the failAction option supports the following values:

Errors

hapi uses the boom error library for all its internal error generation. boom provides an expressive interface to return HTTP errors. Any error thrown by a lifecycle method is converted into a boom object and defaults to status code 500 if the error is not already a boom object.

When the error is sent back to the client, the response contains a JSON object with the statusCode, error, and message keys.

const Hapi = require('hapi');
const Boom = require('boom');

const server = Hapi.server();

server.route({
    method: 'GET',
    path: '/badRequest',
    handler: function (request, h) {

        throw Boom.badRequest('Unsupported parameter');     // 400
    }
});

server.route({
    method: 'GET',
    path: '/internal',
    handler: function (request, h) {

        throw new Error('unexpect error');                  // 500
    }
});
Error transformation

Errors can be customized by changing their output content. The boom error object includes the following properties:

  • isBoom - if true, indicates this is a Boom object instance.

  • message - the error message.

  • output - the formatted response. Can be directly manipulated after object construction to return a custom error response. Allowed root keys:

    • statusCode - the HTTP status code (typically 4xx or 5xx).

    • headers - an object containing any HTTP headers where each key is a header name and value is the header content.

    • payload - the formatted object used as the response payload (stringified). Can be directly manipulated but any changes will be lost if reformat() is called. Any content allowed and by default includes the following content:

      • statusCode - the HTTP status code, derived from error.output.statusCode.

      • error - the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived from statusCode.

      • message - the error message derived from error.message.

  • inherited Error properties.

It also supports the following method:

  • reformat() - rebuilds error.output using the other object properties.
const Boom = require('boom');

const handler = function (request, h) {

    const error = Boom.badRequest('Cannot feed after midnight');
    error.output.statusCode = 499;    // Assign a custom error code
    error.reformat();
    error.output.payload.custom = 'abc_123'; // Add custom key
    throw error;
});

When a different error representation is desired, such as an HTML page or a different payload format, the 'onPreResponse' extension point may be used to identify errors and replace them with a different response object.

const Hapi = require('hapi');
const Vision = require('vision');

const server = Hapi.server({ port: 80 });
server.register(Vision, (err) => {
    server.views({
        engines: {
            html: require('handlebars')
        }
    });
});

const preResponse = function (request, h) {

    const response = request.response;
    if (!response.isBoom) {
        return h.continue;
    }

    // Replace error with friendly HTML

      const error = response;
      const ctx = {
          message: (error.output.statusCode === 404 ? 'page not found' : 'something went wrong')
      };

      return h.view('error', ctx).code(error.output.statusCode);
};

server.ext('onPreResponse', preResponse);

Response Toolkit

Access: read only.

The response toolkit is a collection of properties and utilities passed to every lifecycle method. It is somewhat hard to define as it provides both utilities for manipulating responses as well as other information. Since the toolkit is passed as a function argument, developers can name it whatever they want. For the purpose of this document the h notation is used. It is named in the spirit of the RethinkDB r method, with h for hapi.

Toolkit properties

h.abandon

Access: read only.

A response symbol. When returned by a lifecycle method, the request lifecycle skips to the finalizing step without further interaction with the node response stream. It is the developer's responsibility to write and end the response directly via request.raw.res.

h.close

Access: read only.

A response symbol. When returned by a lifecycle method, the request lifecycle skips to the finalizing step after calling request.raw.res.end()) to close the the node response stream.

h.context

Access: read / write (will impact the shared context if the object is modified).

A response symbol. Provides access to the route or server context set via the route bind option or server.bind().

h.continue

Access: read only.

A response symbol. When returned by a lifecycle method, the request lifecycle continues without changing the response.

h.realm

Access: read only.

The server realm associated with the matching route. Defaults to the root server realm in the onRequest step.

h.request

Access: read only and public request interface.

The [request] object. This is a duplication of the request lifecycle method argument used by toolkit decorations to access the current request.

h.authenticated(data)

Used by the [authentication] method to pass back valid credentials where:

  • data - an object with:

    • credentials - (required) object representing the authenticated entity.
    • artifacts - (optional) authentication artifacts object specific to the authentication scheme.

Return value: an internal authentication object.

h.entity(options)

Sets the response 'ETag' and 'Last-Modified' headers and checks for any conditional request headers to decide if the response is going to qualify for an HTTP 304 (Not Modified). If the entity values match the request conditions, h.entity() returns a response object for the lifecycle method to return as its value which will set a 304 response. Otherwise, it sets the provided entity headers and returns undefined. The method argumetns are:

Return value: - a response object if the response is unmodified. - undefined if the response has changed.

If undefined is returned, the developer must return a valid lifecycle method value. If a response is returned, it should be used as the return value (but may be customize using the response methods).

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

server.route({
    method: 'GET',
    path: '/',
    config: {
        cache: { expiresIn: 5000 },
        handler: function (request, h) {

            const response = h.entity({ etag: 'abc' });
            if (response) {
                response.header('X', 'y');
                return response;
            }

            return 'ok';
        }
    }
});

h.redirect(uri)

Redirects the client to the specified uri. Same as calling h.response().redirect(uri).

Returns a response object.

const handler = function (request, h) {

    return h.redirect('http://example.com');
};

h.response([value])

Wraps the provided value and returns a response object which allows customizing the response (e.g. setting the HTTP status code, custom headers, etc.), where:

  • value - (optional) return value. Defaults to null.

Returns a response object.

// Detailed notation

const handler = function (request, h) {

    const response = h.response('success');
    response.type('text/plain');
    response.header('X-Custom', 'some-value');
    return response;
};

// Chained notation

const handler = function (request, h) {

    return h.response('success')
        .type('text/plain')
        .header('X-Custom', 'some-value');
};

h.state(name, value, [options])

Sets a response cookie using the same arguments as response.state().

Return value: none.

const ext = function (request, h) {

    h.state('cookie-name', 'value');
    return h.continue;
};

h.unauthenticated(error, [data])

Used by the [authentication] method to indicate authentication failed and pass back the credentials received where:

  • error - (required) the authentication error.
  • data - (optional) an object with:
    • credentials - (required) object representing the authenticated entity.
    • artifacts - (optional) authentication artifacts object specific to the authentication scheme.

The method is used to pass both the authentication error and the credentials. For example, if a request included expired credentials, it allows the method to pass back the user information (combined with a 'try' authentication mode) for error customization.

There is no difference between throwing the error or passing it with the h.unauthenticated() method is no credentials are passed, but it might still be helpful for code clarity.

h.unstate(name, [options])

Clears a response cookie using the same arguments as response.unstate().

const ext = function (request, h) {

    h.unstate('cookie-name');
    return h.continue;
};

Response object

The response object contains the request response value along with various HTTP headers and flags. When a lifecycle method returns a value, the value is wrapped in a response object along with some default flags (e.g. 200 status code). In order to customize a response before it is returned, the h.response() method is provided.

Response properties

response.app

Access: read / write.

Default value: {}.

Application-specific state. Provides a safe place to store application data without potential conflicts with the framework. Should not be used by plugins which should use plugins[name].

response.events

Access: read only and the public podium interface.

The response.events object supports the following events:

  • 'peek' - emitted for each chunk of data written back to the client connection. The event method signature is function(chunk, encoding).

  • 'finish' - emitted when the response finished writing but before the client response connection is ended. The event method signature is function ().

const Crypto = require('crypto');
const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const preResponse = function (request, h) {

    const response = request.response;
    if (response.isBoom) {
        return null;
    }

    const hash = Crypto.createHash('sha1');
    response.events.on('peek', (chunk) => {

        hash.update(chunk);
    });

    response.events.once('finish', () => {

        console.log(hash.digest('hex'));
    });

    return h.continue;
};

server.ext('onPreResponse', preResponse);
response.headers

Access: read only.

Default value: {}.

An object containing the response headers where each key is a header field name and the value is the string header value or array of string.

Note that this is an incomplete list of headers to be included with the response. Additional headers will be added once the response is prepared for transmission.

response.plugins

Access: read / write.

Default value: {}.

Plugin-specific state. Provides a place to store and pass request-level plugin data. plugins is an object where each key is a plugin name and the value is the state.

response.settings

Access: read only.

Object containing the response handling flags.

response.settings.passThrough

Access: read only.

Defaults value: true.

If true and source is a Stream, copies the statusCode and headers properties of the stream object to the outbound response.

response.settings.stringify

Access: read only.

Default value: null (use route defaults).

Override the route json options used when source value requires stringification.

response.settings.ttl

Access: read only.

Default value: null (use route defaults).

If set, overrides the route cache with an expiration value in milliseconds.

response.settings.varyEtag

Default value: false.

If true, a suffix will be automatically added to the 'ETag' header at transmission time (separated by a '-' character) when the HTTP 'Vary' header is present.

response.source

Access: read only.

The raw value returned by the lifecycle method.

response.statusCode

Access: read only.

Default value: 200.

The HTTP response status code.

response.variety

Access: read only.

A string indicating the type of source with available values:

  • 'plain' - a plain response such as string, number, null, or simple object.
  • 'buffer' - a Buffer.
  • 'stream' - a Stream.

response.bytes(length)

Sets the HTTP 'Content-Length' header (to avoid chunked transfer encoding) where:

  • length - the header value. Must match the actual payload size.

Return value: the current response object.

response.charset(charset)

Sets the 'Content-Type' HTTP header 'charset' property where:

  • charset - the charset property value.

Return value: the current response object.

response.code(statusCode)

Sets the HTTP status code where:

  • statusCode - the HTTP status code (e.g. 200).

Return value: the current response object.

response.message(httpMessage)

Sets the HTTP status message where:

  • httpMessage - the HTTP status message (e.g. 'Ok' for status code 200).

Return value: the current response object.

response.created(uri)

Sets the HTTP status code to Created (201) and the HTTP 'Location' header where:

  • uri - an absolute or relative URI used as the 'Location' header value.

Return value: the current response object.

response.encoding(encoding)

Sets the string encoding scheme used to serial data into the HTTP payload where:

Return value: the current response object.

response.etag(tag, options)

Sets the representation entity tag where:

  • tag - the entity tag string without the double-quote.

  • options - (optional) settings where:

    • weak - if true, the tag will be prefixed with the 'W/' weak signifier. Weak tags will fail to match identical tags for the purpose of determining 304 response status. Defaults to false.

    • vary - if true and content encoding is set or applied to the response (e.g 'gzip' or 'deflate'), the encoding name will be automatically added to the tag at transmission time (separated by a '-' character). Ignored when weak is true. Defaults to true.

Return value: the current response object.

response.header(name, value, options)

Sets an HTTP header where:

  • name - the header name.

  • value - the header value.

  • options - (optional) object where:

    • append - if true, the value is appended to any existing header value using separator. Defaults to false.

    • separator - string used as separator when appending to an existing value. Defaults to ','.

    • override - if false, the header value is not set if an existing value present. Defaults to true.

    • duplicate - if false, the header value is not modified if the provided value is already included. Does not apply when append is false or if the name is 'set-cookie'. Defaults to true.

Return value: the current response object.

response.location(uri)

Sets the HTTP 'Location' header where:

  • uri - an absolute or relative URI used as the 'Location' header value.

Return value: the current response object.

response.redirect(uri)

Sets an HTTP redirection response (302) and decorates the response with additional methods, where:

  • uri - an absolute or relative URI used to redirect the client to another resource.

Return value: the current response object.

Decorates the response object with the response.temporary(), response.permanent(), and response.rewritable() methods to easily change the default redirection code (302).

Permanent Temporary
Rewritable 301 302
Non-rewritable 308 307

response.replacer(method)

Sets the JSON.stringify() replacer argument where:

  • method - the replacer function or array. Defaults to none.

Return value: the current response object.

response.spaces(count)

Sets the JSON.stringify() space argument where:

  • count - the number of spaces to indent nested object keys. Defaults to no indentation.

Return value: the current response object.

response.state(name, value, [options])

Sets an HTTP cookie where:

Return value: the current response object.

response.suffix(suffix)

Sets a string suffix when the response is process via JSON.stringify() where:

  • suffix - the string suffix.

Return value: the current response object.

response.ttl(msec)

Overrides the default route cache expiration rule for this response instance where:

  • msec - the time-to-live value in milliseconds.

Return value: the current response object.

response.type(mimeType)

Sets the HTTP 'Content-Type' header where:

  • value - is the mime type.

Return value: the current response object.

Should only be used to override the built-in default for each response type.

response.unstate(name, [options])

Clears the HTTP cookie by setting an expired value where:

Return value: the current response object.

response.vary(header)

Adds the provided header to the list of inputs affected the response generation via the HTTP 'Vary' header where:

  • header - the HTTP request header name.

Return value: the current response object.

response.takeover()

Marks the response object as a takeover response.

Return value: the current response object.

response.temporary(isTemporary)

Sets the status code to 302 or 307 (based on the response.rewritable() setting) where:

  • isTemporary - if false, sets status to permanent. Defaults to true.

Return value: the current response object.

Only available after calling the response.redirect() method.

response.permanent(isPermanent)

Sets the status code to 301 or 308 (based on the response.rewritable() setting) where:

  • isPermanent - if false, sets status to temporary. Defaults to true.

Return value: the current response object.

Only available after calling the response.redirect() method.

response.rewritable(isRewritable)

Sets the status code to 301/302 for rewritable (allows changing the request method from 'POST' to 'GET') or 307/308 for non-rewritable (does not allow changing the request method from 'POST' to 'GET'). Exact code based on the response.temporary() or response.permanent() setting. Arguments:

  • isRewritable - if false, sets to non-rewritable. Defaults to true.

Return value: the current response object.

Only available after calling the response.redirect() method.

Request

The request object is created internally for each incoming request. It is not the same object received from the node HTTP server callback (which is available via request.raw.req). The request properties change throughout the request lifecycle.

Request properties

request.app

Access: read / write.

Application-specific state. Provides a safe place to store application data without potential conflicts with the framework. Should not be used by plugins which should use plugins[name].

request.auth

Access: read only.

Authentication information:

request.events

Access: read only and the public podium interface.

The request.events supports the following events:

  • 'peek' - emitted for each chunk of payload data read from the client connection. The event method signature is function(chunk, encoding).

  • 'finish' - emitted when the request payload finished reading. The event method signature is function ().

  • 'disconnect' - emitted when a request errors or aborts unexpectedly.

const Crypto = require('crypto');
const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const onRequest = function (request, h) {

    const hash = Crypto.createHash('sha1');
    request.events.on('peek', (chunk) => {

        hash.update(chunk);
    });

    request.events.once('finish', () => {

        console.log(hash.digest('hex'));
    });

    request.events.once('disconnect', () => {

        console.error('request aborted');
    });

    return h.continue;
};

server.ext('onRequest', onRequest);

request.headers

Access: read only.

The raw request headers (references request.raw.req.headers).

request.info

Access: read only.

Request information:

  • acceptEncoding - the request preferred encoding.

  • cors - if CORS is enabled for the route, contains the following:

    • isOriginMatch - true if the request 'Origin' header matches the configured CORS restrictions. Set to false if no 'Origin' header is found or if it does not match. Note that this is only available after the 'onRequest' extension point as CORS is configured per-route and no routing decisions are made at that point in the request lifecycle.
  • host - content of the HTTP 'Host' header (e.g. 'example.com:8080').

  • hostname - the hostname part of the 'Host' header (e.g. 'example.com').

  • id - a unique request identifier (using the format '{now}:{connection.info.id}:{5 digits counter}').

  • received - request reception timestamp.

  • referrer - content of the HTTP 'Referrer' (or 'Referer') header.

  • remoteAddress - remote client IP address.

  • remotePort - remote client port.

  • responded - request response timestamp (0 is not responded yet).

Note that the request.info object is not meant to be modified.

request.logs

Access: read only.

An array containing the logged request events.

Note that this array will be empty if route log.collect is set to false.

request.method

Access: read only.

The request method in lower case (e.g. 'get', 'post').

request.mime

Access: read only.

The parsed content-type header. Only available when payload parsing enabled and no payload error occurred.

request.orig

Access: read only.

An object containing the values of params, query, and payload before any validation modifications made. Only set when input validation is performed.

request.params

Access: read only.

An object where each key is a path parameter name with matching value as described in Path parameters.

request.paramsArray

Access: read only.

An array containing all the path params values in the order they appeared in the path.

request.path

Access: read only.

The request URI's pathname component.

request.payload

Access: read only.

The request payload based on the route payload.output and payload.parse settings.

request.plugins

Access: read / write.

Plugin-specific state. Provides a place to store and pass request-level plugin data. The plugins is an object where each key is a plugin name and the value is the state.

request.pre

Access: read only.

An object where each key is the name assigned by a route pre-handler methods function. The values are the raw values provided to the continuation function as argument. For the wrapped response object, use responses.

request.response

Access: read / write (see limitations below).

The response object when set. The object can be modified but must not be assigned another object. To replace the response with another from within an extension point, use reply(response) to override with a different response. Contains null when no response has been set (e.g. when a request terminates prematurely when the client disconnects).

request.preResponses

Access: read only.

Same as pre but represented as the response object created by the pre method.

request.query

Access: read only.

By default the object outputted from node's URL parse() method. Might also be set indirectly via request.setUrl in which case it may be a string (if url is set to an object with the query attribute as an unparsed string).

request.raw

Access: read only.

An object containing the Node HTTP server objects. Direct interaction with these raw objects is not recommended.

  • req - the node request object.
  • res - the node response object.

request.route

Access: read only.

The request route information object, where:

request.server

Access: read only and the public server interface.

The server object.

request.state

Access: read only.

An object containing parsed HTTP state information (cookies) where each key is the cookie name and value is the matching cookie content after processing using any registered cookie definition.

request.url

Access: read only.

The parsed request URI.

request.generateResponse(source, [options])

Returns a response which you can pass into the reply interface where:

  • source - the value to set as the source of the reply interface, optional.
  • options - options for the method, optional.

request.log(tags, [data])

Logs request-specific events. When called, the server emits a 'request' event which can be used by other listeners or plugins. The arguments are:

  • tags - a string or an array of strings (e.g. ['error', 'database', 'read']) used to identify the event. Tags are used instead of log levels and provide a much more expressive mechanism for describing and filtering events.
  • data - (optional) an message string or object with the application data being logged. If data is a function, the function signature is function() and it called once to generate (return value) the actual data emitted to the listeners.

Any logs generated by the server internally will be emitted only on the 'request-internal' channel and will include the event.internal flag set to true.

const Hapi = require('hapi');
const server = Hapi.server({ port: 80, routes: { log: true } });

server.on('request', (request, event, tags) => {

    if (tags.error) {
        console.log(event);
    }
});

const handler = function (request, h) {

    request.log(['test', 'error'], 'Test event');
    return null;
};

request.route.auth.access(request)

Validates a request against the route's authentication access configuration, where:

Return value: true if the request would have passed the route's access requirements.

Note that the route's authentication mode and strategies are ignored. The only match is made between the request.auth.credentials scope and entity information and the route access configuration.

If the route uses dynamic scopes, the scopes are constructed against the request.query, request.params, request.payload, and request.auth.credentials which may or may not match between the route and the request's route. If this method is called using a request that has not been authenticated (yet or not at all), it will return false if the route requires any authentication.

request.setMethod(method)

Changes the request method before the router begins processing the request where:

  • method - is the request HTTP method (e.g. 'GET').
const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const onRequest = function (request, h) {

    // Change all requests to 'GET'
    request.setMethod('GET');
    return h.continue;
};

server.ext('onRequest', onRequest);

Can only be called from an 'onRequest' extension method.

request.setUrl(url, [stripTrailingSlash]

Changes the request URI before the router begins processing the request where:

const Hapi = require('hapi');
const server = Hapi.server({ port: 80 });

const onRequest = function (request, h) {

    // Change all requests to '/test'
    request.setUrl('/test');
    return h.continue;
};

server.ext('onRequest', onRequest);

To use another query string parser:

const Url = require('url');
const Hapi = require('hapi');
const Qs = require('qs');

const server = Hapi.server({ port: 80 });

const onRequest = function (request, h) {

    const uri = request.url.href;
    const parsed = Url.parse(uri, false);
    parsed.query = Qs.parse(parsed.query);
    request.setUrl(parsed);

    return h.continue;
};

server.ext('onRequest', onRequest);

Can only be called from an 'onRequest' extension method.

Plugins

Plugins provide a way to organize application code by splitting the server logic into smaller components. Each plugin can manipulate the server through the standard server interface, but with the added ability to sandbox certain properties. For example, setting a file path in one plugin doesn't affect the file path set in another plugin.

A plugin is an object with the following properties:

  • register - (required) the registration function with the signature async function(server, options) where:

    • server - the server object with a plugin-specific server.realm.
    • options - any options passed to the plugin during registration via server.register().
  • name - (required) the plugin name string. The name is used as a unique key. Published plugins (e.g. published in the npm registry) should use the same name as the name field in their 'package.json' file. Names must be unique within each application.

  • version - (optional) plugin version string. The version is only used informatively to enable other plugins to find out the versions loaded. The version should be the same as the one specified in the plugin's 'package.json' file.

  • multiple - (optional) if true, allows the plugin to be registered multiple times with the same server. Defaults to false.

  • dependencies - (optional) a string or an array of strings indicating a plugin dependency. Same as setting dependencies via server.dependency().

  • once - (optional) if true, will only register the plugin once per server. If set, overrides the once option passed to server.register(). Defaults to no override.

const plugin = {
    name: 'test',
    version: '1.0.0',
    register: function (server, options) {

        server.route({
            method: 'GET',
            path: '/test',
            handler: function (request, h) {

                return 'ok';
            }
        });
    }
};

Alternatively, the name and version can be included via the pkg property containing the 'package.json' file for the module which already has the name and version included:

const plugin = {
    pkg: require('./package.json'),
    register: function (server, options) {

        server.route({
            method: 'GET',
            path: '/test',
            handler: function (request, h) {

                return 'ok';
            }
        });
    }
};

Modules

API Reference

Good

good is a process monitor that listens for one or more of the below 'event types'. All of these events, except 'ops' map to a hapi event documented here.

Applications with multiple server instances, each with its own monitor should only include one log subscription per destination as general events are a process-wide facility and will result in duplicated log events.

Options

  • [includes] - optional configuration object
    • [request] - array of extra hapi request object fields to supply to reporters on "request", "response", and "error" events. Valid values ['headers', 'payload']. Defaults to [].
    • [response] - array of extra hapi response object fields to supply to reporters on "response" events. Valid values ['headers', 'payload']. Defaults to [].
  • [ops] - options for controlling the ops reporting from good. Set to false to disable ops monitoring completely.
    • config - options passed directly into the Oppsy constructor as the config value. Defaults to {}
    • interval - interval used when calling Oppsy.start(). Defaults to 15000.
  • [extensions] - an array of hapi event names to listen for and report via the good reporting mechanism. Can not be any of ['log', 'ops', 'request', 'response', 'tail']. Disclaimer This option should be used with caution. This option will allow users to listen to internal events that are not meant for public consumption. The list of available events can change with any changes to the hapi event system. Also, none of the official hapijs reporters have been tested against these custom events. The schema for these events can not be guaranteed because they vary from version to version of hapi.
  • [reporters] - Defaults to {}. reporters is a key, value pair where the key is a reporter name and the value is an array of mixed value types. Valid values for the array items are:
    • streams specifications object with the following keys
      • module - can be :
        • a string that will be used to import a module from node_modules or a local file. Should export a single constructor function that can be invoked with new.
        • a function that is the constructor of your stream. It's a safer alternative to the string version when you risk having module conflicts.
      • [name] - if the imported module exports more than one constructor function, use name to specify which one to use.
      • [args] - an array of arguments to pass to the constructor when this stream object is created via new.
    • instantiated stream objects
    • string name of a built in process stream. Valid values are 'stdout' and 'stderr'.

Reporter Interface

The reporter interface uses the standard stream-and-pipe interface found commonly in the node ecosystem. Each item in the array of streams will be piped together in the array order. Any stream described using a stream specification object will be constructed with new to prevent any cross contamination from one reporter to another. For example, when passing the following specification for an "ops-console" reporter:

{
    'ops-console': [{
        module: 'good-squeeze',
        name: 'Squeeze',
        args: [{ ops: '*' }]
    }, {
        module: 'good-squeeze',
        name: 'SafeJson'
    }, 'stdout']
}

Internally, this would create an array (streams), import good-squeeze from node_modules, and then create a new "Squeeze" transform stream via new Squeeze({ ops: '*' }) and push that result into streams. Then it would create a "SafeJson" transform stream via new SafeJson() and push that into streams. Finally, since 'stdout' is an existing process stream, it gets pushed directly into streams. Once all of the streams have been created and collected, the algorithm does essentially the following:

const result = streams[0].pipe(streams[1]).pipe(streams[2]);

Any time one of the "good events" occurs, a unique copy of the event is pushed into each reporter stream pipeline. It is up to the developer to filter events they don't care about on a per pipeline basis. The "Squeeze" transform stream provides the basic event type and tag filtering used in previous versions of good which should meet many filtering needs.

It is also up to the developer to manage objectMode in each pipeline from one stream to the next. The first stream will always receive an object. After that, it's up to the developer to manage the message type throughout the pipeline. In the above example, because we want to write to stdout, we needed to add a transform stream to convert the payload coming out of "Squeeze" to a string using "SafeJson" before sending it to process.stdout. Objects can not be written directly to process.stdout, so "SafeJson" was used to safely stringify the message coming from the "Squeeze" stream.

Finally, the developer must make sure the reporting pipeline makes sense. In the above example, we pipe through two transform streams, convert the object to a string, and then write send it to process.stdout which is a write stream. If the developer mixes up the order, this pipeline would crash the process.

Each reporter pipeline receives it's own copy of the message from good. That means the payload can be freely modified without worrying about impacting other reporters. Just add more and more transform streams into the pipeline to fine-tune any reporting needs. Need a different filtering mechanism? Write a new transform stream to filter based on IP, request route, payload type... Want to add extra data about events? Just add a transform stream into the mix to add the current date, something specific to your company, filter out sensitive information before logging it... the sky is the limit.

These changes address the two most common requests; "how do I filter on X?" and "how do I add Y to the message payload?". Now developers are empowered to customize the reporting pipeline to suit their needs. While there is far less hand-holding with this interface, developers have much more control of reporting coming out of good.

This change also allows user to leverage any existing transform or write stream in the node ecosystem to be used with good.

Stream Transforms Using Plugin Configs

To drive route or request level behavior in your stream transform one option is to use the plugin config feature of hapi. Here is an example where a plugin config is used to drive a stream transform that will suppress "response" events when suppressResponseEvent === true.

Setting plugin config at the route level:

var routeConfig = {
    plugins: {
        good: {
            suppressResponseEvent: true
        }
    }
};

server.route({ method: 'GET', path: '/user', config: routeConfig });

Setting plugin config at the request level:

const handler = function (request, reply) {

    request.plugins.good = {
        suppressResponseEvent: true
    };

    reply.continue();
}

Consuming the plugin config in the stream transform:

_transform(data, enc, next) {

    if (data.event === 'response' && data.config.suppressResponseEvent === true) {
        return next();
    }

    return next(null, data);
}

Reporter Lifecycle

Startup

  1. When "onPreStart" is emitted from the hapi server, the monitoring operation starts.
  2. All of the streams are created via new (if needed) and collected into a temporary internal array.
  3. All of the streams in the temporary array are piped together. This will cause any standard Node stream events to occur that instances can listen for.

At this point, data will start flowing to each of the reporters through the pipe interface. Data can be accessed in individual instances though any of the standard stream methods and events.

Shutdown

  1. When "onPostStop" is emitted from the hapi server, the shutdown sequence starts.
  2. null is pushed through each reporter pipeline. Any synchronous teardown can happen on stream instances in "end" or "finish" events. See Node stream for more information about end-of-stream events. The callback signaling to hapi that our logic is done executing will happen on the next tick.

Event Types

  • ops - System and process performance - CPU, memory, disk, and other metrics.
  • response - Information about incoming requests and the response. This maps to either the "response" or "tail" event emitted from hapi servers.
  • log - logging information not bound to a specific request such as system errors, background processing, configuration errors, etc. Maps to the "log" event emitted from hapi servers.
  • error - request responses that have a status code of 500. This maps to the "request" hapi event on the "error" channel.
  • request - Request logging information. This maps to the hapi 'request' event that is emitted via request.log().

Event Payloads

Each event emitted from Good has a unique object representing the payload. This is useful for three reasons:

  1. It provides a predictable interface.
  2. It makes tracking down issues with MDB much easier because the payloads aren't just generic objects.
  3. It is more likely to be optimized because the V8 runtime has a better idea of what the structure of each object is going to be much sooner.

ServerLog

Event object associated with 'log' events.

  • event - 'log'
  • timestamp - JavaScript timestamp indicating when the 'log' event occurred.
  • tags - array of strings representing any tags associated with the 'log' event.
  • data - string or object passed via server.log() calls.
  • error - error object, replacing data if only an error object is passed to server.log()
  • pid - the current process id.

RequestError

Event object associated with 'error' events.

  • event - 'error'
  • timestamp - JavaScript timestamp indicating when the 'log' event occurred.
  • id - request id. Maps to request.id.
  • url - url of the request that originated the error. Maps to request.url.
  • method - method of the request that originated the error. Maps to request.method.
  • pid - the current process id.
  • error - the raw error object.
  • config - plugin-specific config object combining request.route.settings.plugins.good and request.plugins.good. Request-level overrides route-level. Reporters could use config for additional filtering logic.
  • headers - the request headers if includes.request includes "headers"

The toJSON method of GreatError has been overwritten because Error objects can not be stringified directly. A stringified GreatError will have error.message and error.stack in place of the raw Error object.

RequestSent

Event object associated with the response event option into Good.

  • event - 'response'
  • timestamp - JavaScript timestamp that maps to request.info.received.
  • id - id of the request, maps to request.id.
  • instance - maps to server.info.uri.
  • labels - maps to server.settings.labels
  • method - method used by the request. Maps to request.method.
  • path - incoming path requested. Maps to request.path.
  • query - query object used by request. Maps to request.query.
  • responseTime - calculated value of request.info.responded - request.info.received.
  • statusCode - the status code of the response.
  • pid - the current process id.
  • httpVersion - the http protocol information from the request.
  • source - object with the following values:
    • remoteAddress - information about the remote address. maps to request.info.remoteAddress
    • userAgent - the user agent of the incoming request.
    • referer - the referer headed of the incoming request.
  • route - route path used by request. Maps to request.route.path.
  • log - maps to request.logs of the hapi request object.
  • tags - array of strings representing any tags from route config. Maps to request.route.settings.tags.
  • config - plugin-specific config object combining request.route.settings.plugins.good and request.plugins.good. Request-level overrides route-level. Reporters could use config for additional filtering logic.
  • headers - the request headers if includes.request includes "headers"
  • requestPayload - the request payload if includes.request includes "payload"
  • responsePayload - the response payload if includes.response includes "payload"

Ops

Event object associated with the 'ops' event emitted from Oppsy.

  • event - 'ops'
  • timestamp - current time when the object is created.
  • host - the host name of the current machine.
  • pid - the current process id.
  • os - object with the following values:
    • load - array containing the 1, 5, and 15 minute load averages.
    • mem - object with the following values:
      • total - total system memory in bytes.
      • free - total free system memory in bytes.
    • uptime - system uptime in seconds.
  • proc - object with the following values:
    • uptime - uptime of the running process in seconds
    • mem - returns result of process.memoryUsage()
      • rss - 'resident set size' which is the amount of the process held in memory.
      • heapTotal - V8 heap total
      • heapUsed - V8 heap used
    • delay - the calculated Node event loop delay in milliseconds.
  • load - object with the following values:
    • requests - object containing information about all the requests passing through the server.
    • concurrents - object containing information about the number of concurrent connections associated with each listener object associated with the hapi server.
    • responseTimes - object with calculated average and max response times for requests.
    • sockets - object with the following values:
      • http - socket information http connections. Each value contains the name of the socket used and the number of open connections on the socket. It also includes a total for total number of open http sockets.
      • https - socket information https connections. Each value contains the name of the socket used and the number of open connections on the socket. It also includes a total for total number of open https sockets.

RequestLog

Event object associated with the "request" event. This is the hapi event emitter via request.log().

  • event - 'request'
  • timestamp - timestamp of the incoming event object.
  • tags - array of strings representing any tags associated with the 'log' event.
  • data - the string or object mapped to event.data.
  • error - the error instance mapped to event.error.
  • pid - the current process id.
  • id - id of the request, maps to request.id.
  • method - method used by the request. Maps to request.method.
  • path - incoming path requested. Maps to request.path.
  • config - plugin-specific config object combining request.route.settings.plugins.good and request.plugins.good. Request-level overrides route-level. Reporters could use config for additional filtering logic.
  • headers - the request headers if includes.request includes "headers"

Extension Payloads

Because the extension payloads from hapi can vary from one version to another and one event to another, the payload is only loosely defined.

  • event - the event name.
  • timestamp - the time the event occurred.
  • payload - array of arguments hapi passed to our event handler function

Table of Contents

Hoek

Object

Hoek provides several helpful methods for objects and arrays.

clone(obj, [options])

Clones an object or an array. A deep copy is made (duplicates everything, including values that are objects, as well as non-enumerable properties) where:

  • obj - the object to be cloned.
  • options - optional settings:
    • symbols - clone symbol properties. Defaults to false.
var nestedObj = {
        w: /^something$/ig,
        x: {
            a: [1, 2, 3],
            b: 123456,
            c: new Date()
        },
        y: 'y',
        z: new Date()
    };

var copy = Hoek.clone(nestedObj);

copy.x.b = 100;

console.log(copy.y);        // results in 'y'
console.log(nestedObj.x.b); // results in 123456
console.log(copy.x.b);      // results in 100

cloneWithShallow(obj, keys, [options])

Clones an object or array excluding some keys which are shallow copied where:

  • obj - the object to be cloned.
  • keys - an array of key names to shallow copy.
  • options - optional settings:
    • symbols - clone symbol properties. Defaults to false.
var nestedObj = {
        w: /^something$/ig,
        x: {
            a: [1, 2, 3],
            b: 123456,
            c: new Date()
        },
        y: 'y',
        z: new Date()
    };

var copy = Hoek.cloneWithShallow(nestedObj, ['x']);

copy.x.b = 100;

console.log(copy.y);        // results in 'y'
console.log(nestedObj.x.b); // results in 100
console.log(copy.x.b);      // results in 100

merge(target, source, isNullOverride, isMergeArrays)

isNullOverride, isMergeArrays default to true

Merge all the properties of source into target, source wins in conflict, and by default null and undefined from source are applied. Merge is destructive where the target is modified. For non destructive merge, use applyToDefaults.

var target = {a: 1, b : 2};
var source = {a: 0, c: 5};
var source2 = {a: null, c: 5};

Hoek.merge(target, source);         // results in {a: 0, b: 2, c: 5}
Hoek.merge(target, source2);        // results in {a: null, b: 2, c: 5}
Hoek.merge(target, source2, false); // results in {a: 1, b: 2, c: 5}

var targetArray = [1, 2, 3];
var sourceArray = [4, 5];

Hoek.merge(targetArray, sourceArray);              // results in [1, 2, 3, 4, 5]
Hoek.merge(targetArray, sourceArray, true, false); // results in [4, 5]

applyToDefaults(defaults, options, isNullOverride)

isNullOverride defaults to false

Apply options to a copy of the defaults

var defaults = { host: "localhost", port: 8000 };
var options = { port: 8080 };

var config = Hoek.applyToDefaults(defaults, options); // results in { host: "localhost", port: 8080 }

Apply options with a null value to a copy of the defaults

var defaults = { host: "localhost", port: 8000 };
var options = { host: null, port: 8080 };

var config = Hoek.applyToDefaults(defaults, options, true); // results in { host: null, port: 8080 }

applyToDefaultsWithShallow(defaults, options, keys)

keys is an array of dot-separated, or array-based, key paths to shallow copy

Apply options to a copy of the defaults. Keys specified in the last parameter are shallow copied from options instead of merged.

var defaults = {
    db: {
        server: {
            host: "localhost",
            port: 8000
        },
        name: 'example'
    }
};

var options = { server: { port: 8080 } };

var config = Hoek.applyToDefaultsWithShallow(defaults, options, ['db.server']); // results in { db: { server: { port: 8080 }, name: 'example' } }
var config = Hoek.applyToDefaultsWithShallow(defaults, options, [['db', 'server']]); // results in { db: { server: { port: 8080 }, name: 'example' } }

deepEqual(b, a, [options])

Performs a deep comparison of the two values including support for circular dependencies, prototype, and enumerable properties. To skip prototype comparisons, use options.prototype = false and to include symbols, used options.symbols = true.

Hoek.deepEqual({ a: [1, 2], b: 'string', c: { d: true } }, { a: [1, 2], b: 'string', c: { d: true } }); //results in true
Hoek.deepEqual(Object.create(null), {}, { prototype: false }); //results in true
Hoek.deepEqual(Object.create(null), {}); //results in false

intersect(array1, array2)

Find the common unique items in two arrays

var array1 = [1, 2, 3];
var array2 = [1, 4, 5];

var newArray = Hoek.intersect(array1, array2); // results in [1]

contain(ref, values, [options])

Tests if the reference value contains the provided values where:

  • ref - the reference string, array, or object.
  • values - a single or array of values to find within the ref value. If ref is an object, values can be a key name, an array of key names, or an object with key-value pairs to compare.
  • options - an optional object with the following optional settings:
    • deep - if true, performed a deep comparison of the values.
    • once - if true, allows only one occurrence of each value.
    • only - if true, does not allow values not explicitly listed.
    • part - if true, allows partial match of the values (at least one must always match).

Note: comparing a string to overlapping values will result in failed comparison (e.g. contain('abc', ['ab', 'bc'])). Also, if an object key's value does not match the provided value, false is returned even when part is specified.

Hoek.contain('aaa', 'a', { only: true });							// true
Hoek.contain([{ a: 1 }], [{ a: 1 }], { deep: true });				// true
Hoek.contain([1, 2, 2], [1, 2], { once: true });					// false
Hoek.contain({ a: 1, b: 2, c: 3 }, { a: 1, d: 4 }, { part: true }); // true

flatten(array, [target])

Flatten an array

var array = [1, [2, 3]];

var flattenedArray = Hoek.flatten(array); // results in [1, 2, 3]

array = [1, [2, 3]];
target = [4, [5]];

flattenedArray = Hoek.flatten(array, target); // results in [4, [5], 1, 2, 3]

reach(obj, chain, [options])

Converts an object key chain string or array to reference

  • options - optional settings
    • separator - string to split chain path on, defaults to '.'
    • default - value to return if the path or value is not present, default is undefined
    • strict - if true, will throw an error on missing member, default is false
    • functions - if true allow traversing functions for properties. false will throw an error if a function is part of the chain.

A chain can be a string that will be split into key names using separator, or an array containing each individual key name.

A chain including negative numbers will work like negative indices on an array.

If chain is null, undefined or false, the object itself will be returned.

var chain = 'a.b.c';
var obj = {a : {b : { c : 1}}};

Hoek.reach(obj, chain); // returns 1

var chain = ['a', 'b', -1];
var obj = {a : {b : [2,3,6]}};

Hoek.reach(obj, chain); // returns 6

reachTemplate(obj, template, [options])

Replaces string parameters ({name}) with their corresponding object key values by applying the reach() method where:

  • obj - the context object used for key lookup.
  • template - a string containing {} parameters.
  • options - optional reach() options.
var chain = 'a.b.c';
var obj = {a : {b : { c : 1}}};

Hoek.reachTemplate(obj, '1+{a.b.c}=2'); // returns '1+1=2'

stringify(obj)

Converts an object to string using the built-in JSON.stringify() method with the difference that any errors are caught and reported back in the form of the returned string. Used as a shortcut for displaying information to the console (e.g. in error message) without the need to worry about invalid conversion.

var a = {};
a.b = a;
Hoek.stringify(a);		// Returns '[Cannot display object: Converting circular structure to JSON]'

Bench

Same as Timer with the exception that ts stores the internal node clock which is not related to Date.now() and cannot be used to display human-readable timestamps. More accurate for benchmarking or internal timers.

Escaping Characters

Hoek provides convenient methods for escaping html characters. The escaped characters are as followed:

internals.htmlEscaped = {
    '&': '&',
    '<': '&lt;',
    '>': '&gt;',
    '"': '&quot;',
    "'": '&#x27;',
    '`': '&#x60;'
};

escapeHtml(string)

var string = '<html> hey </html>';
var escapedString = Hoek.escapeHtml(string); // returns &lt;html&gt; hey &lt;/html&gt;

escapeHeaderAttribute(attribute)

Escape attribute value for use in HTTP header

var a = Hoek.escapeHeaderAttribute('I said "go w\\o me"');  //returns I said \"go w\\o me\"

escapeJson(string)

Unicode escapes the characters <, >, and & to prevent mime-sniffing older browsers mistaking JSON as HTML, and escapes line and paragraph separators for JSONP and script contexts.

var lineSeparator = String.fromCharCode(0x2028);
var a = Hoek.escapeJson('I said <script>confirm(&).' + lineSeparator);  //returns I said \\u003cscript\\u003econfirm(\\u0026).\\u2028

escapeRegex(string)

Escape string for Regex construction

var a = Hoek.escapeRegex('4^f$s.4*5+-_?%=#!:@|~\\/`"(>)[<]d{}s,');  // returns 4\^f\$s\.4\*5\+\-_\?%\=#\!\:@\|~\\\/`"\(>\)\[<\]d\{\}s\,

Errors

assert(condition, message)

var a = 1, b = 2;

Hoek.assert(a === b, 'a should equal b');  // Throws 'a should equal b'

Note that you may also pass an already created Error object as the second parameter, and assert will throw that object.

var a = 1, b = 2;

Hoek.assert(a === b, new Error('a should equal b')); // Throws the given error object

Function

once(fn)

Returns a new function that can be run multiple times, but makes sure fn is only run once.

var myFn = function () {
    console.log('Ran myFn');
};

var onceFn = Hoek.once(myFn);
onceFn(); // results in "Ran myFn"
onceFn(); // results in undefined

ignore

A simple no-op function. It does nothing at all.

Miscellaneous

uniqueFilename(path, extension)

path to prepend with the randomly generated file name. extension is the optional file extension, defaults to ''.

Returns a randomly generated file name at the specified path. The result is a fully resolved path to a file.

var result = Hoek.uniqueFilename('./test/modules', 'txt'); // results in "full/path/test/modules/{random}.txt"

Promises

wait(timeout)

Resolve the promise after timeout. Provide the timeout in milliseconds.

await Hoek.wait(2000); // waits for 2 seconds

block()

A no-op Promise. Does nothing.

14.3.1 API Reference

Joi

version

Property showing the current version of joi being used.

validate(value, schema, [options], [callback])

Validates a value using the given schema and options where:

  • value - the value being validated.
  • schema - the validation schema. Can be a joi type object or a plain object where every key is assigned a joi type object using Joi.compile (be careful of the cost of compiling repeatedly the same schemas).
  • options - an optional object with the following optional keys:
    • abortEarly - when true, stops validation on the first error, otherwise returns all the errors found. Defaults to true.
    • convert - when true, attempts to cast values to the required types (e.g. a string to a number). Defaults to true.
    • allowUnknown - when true, allows object to contain unknown keys which are ignored. Defaults to false.
    • skipFunctions - when true, ignores unknown keys with a function value. Defaults to false.
    • stripUnknown - remove unknown elements from objects and arrays. Defaults to false.
      • when an object :
        • arrays - set to true to remove unknown items from arrays.
        • objects - set to true to remove unknown keys from objects.
      • when true, it is equivalent to having { arrays: false, objects: true }.
    • language - overrides individual error messages. Defaults to no override ({}). Messages apply the following rules :
      • variables are put between curly braces like {{var}}, if prefixed by a ! like {{!var}}, it will be html escaped if the option escapeHtml is also set to true
      • strings are always preceeded by the key name, unless a {{label}} is found elsewhere or if the string is prefixed by a !!
      • to better understand the structure of the language, it's advised to have a look at the existing messages you want to override here
    • presence - sets the default presence requirements. Supported modes: 'optional', 'required', and 'forbidden'. Defaults to 'optional'.
    • context - provides an external data set to be used in references. Can only be set as an external option to validate() and not using any.options().
    • noDefaults - when true, do not apply default values. Defaults to false.
    • escapeHtml - when true, error message templates will escape special characters to HTML entities, for security purposes. Defaults to false.
  • callback - the optional synchronous callback method using the signature function(err, value) where:
    • err - if validation failed, the error reason, otherwise null.
    • value - the validated value with any type conversions and other modifiers applied (the input is left unchanged). value can be incomplete if validation failed and abortEarly is true. If callback is not provided, then returns an object with error and value properties.

When used without a callback, this function returns a Promise-like object that can be used as a promise, or as a simple object like in the below examples.

const schema = {
    a: Joi.number()
};

const value = {
    a: '123'
};

Joi.validate(value, schema, (err, value) => { });
// err -> null
// value.a -> 123 (number, not string)

// or
const result = Joi.validate(value, schema);
// result.error -> null
// result.value -> { "a" : 123 }

// or
const promise = Joi.validate(value, schema);
promise.then((value) => {
    // value -> { "a" : 123 }
});

compile(schema)

Converts literal schema definition to joi schema object (or returns the same back if already a joi schema object) where:

  • schema - the schema definition to compile.
const definition = ['key', 5, { a: true, b: [/^a/, 'boom'] }];
const schema = Joi.compile(definition);

// Same as:

const schema = Joi.alternatives().try([
    Joi.string().valid('key'),
    Joi.number().valid(5),
    Joi.object().keys({
        a: Joi.boolean().valid(true),
        b: Joi.alternatives().try([
            Joi.string().regex(/^a/),
            Joi.string().valid('boom')
        ])
    })
]);

describe(schema)

Returns an object that represents the internal configuration of a joi schema. Useful for debugging and exposing a schema's configuration to other systems, like valid values in a user interface.

  • schema - the schema to describe.
const schema = Joi.any().valid([ 'foo', 'bar' ]);

console.log(Joi.describe(schema));

Results in:

{ type: 'any',
  flags: { allowOnly: true },
  valids: [ 'foo', 'bar' ] }

assert(value, schema, [message])

Validates a value against a schema and throws if validation fails where:

  • value - the value to validate.
  • schema - the validation schema. Can be a joi type object or a plain object where every key is assigned a joi type object using Joi.compile (be careful of the cost of compiling repeatedly the same schemas).
  • message - optional message string prefix added in front of the error message. may also be an Error object.
Joi.assert('x', Joi.number());

attempt(value, schema, [message])

Validates a value against a schema, returns valid object, and throws if validation fails where:

  • value - the value to validate.
  • schema - the validation schema. Can be a joi type object or a plain object where every key is assigned a joi type object using Joi.compile (be careful of the cost of compiling repeatedly the same schemas).
  • message - optional message string prefix added in front of the error message. may also be an Error object.
Joi.attempt('x', Joi.number()); // throws error
const result = Joi.attempt('4', Joi.number()); // result -> 4

ref(key, [options])

Generates a reference to the value of the named key. References are resolved at validation time and in order of dependency so that if one key validation depends on another, the dependent key is validated second after the reference is validated. References support the following arguments:

  • key - the reference target. References cannot point up the object tree, only to sibling keys, but they can point to their siblings' children (e.g. 'a.b.c') using the . separator. If a key starts with $ is signifies a context reference which is looked up in the context option object.
  • options - optional settings:
    • separator - overrides the default . hierarchy separator.
    • contextPrefix - overrides the default $ context prefix signifier.
    • Other options can also be passed based on what Hoek.reach supports.

Note that references can only be used where explicitly supported such as in valid() or invalid() rules. If upwards (parents) references are needed, use object.assert().

const schema = Joi.object().keys({
    a: Joi.ref('b.c'),
    b: {
        c: Joi.any()
    },
    c: Joi.ref('$x')
});

Joi.validate({ a: 5, b: { c: 5 } }, schema, { context: { x: 5 } }, (err, value) => {});

isRef(ref)

Checks whether or not the provided argument is a reference. It's especially useful if you want to post-process error messages.

const ref = Joi.ref('a');
Joi.isRef(ref); // returns true

reach(schema, path)

Get a sub-schema of an existing schema based on a path that can be either a string or an array of strings For string values path separator is a dot (.).

const schema = Joi.object({ foo: Joi.object({ bar: Joi.number() }) });
const number = Joi.reach(schema, 'foo.bar');

//or
const result = Joi.reach(schema, ['foo', 'bar']); //same as number

defaults(fn)

Creates a new Joi instance that will apply defaults onto newly created schemas through the use of the fn function that takes exactly one argument, the schema being created.

The function must always return a schema, even if untransformed.

const defaultJoi = Joi.defaults((schema) => {

    switch (schema.schemaType) {
        case 'string':
            return schema.allow('');
        case 'object':
            return schema.min(1);
        default:
            return schema;
    }
});

const schema = defaultJoi.object(); // Equivalent to a Joi.object().min(1)

bind()

By default, some Joi methods to function properly need to rely on the Joi instance they are attached to because they use this internally. So Joi.string() works but if you extract the function from it and call string() it won't. bind() creates a new Joi instance where all the functions relying on this are bound to the Joi instance.

const { object, string } = require('joi').bind();

const schema = object({
  property: string().min(4)
});

extend(extension)

Creates a new Joi instance customized with the extension(s) you provide included.

It is important to understand that original Joi library is not modified by this.

Terms

The extension makes use of some common structures that need to be described prior :

  • value - the value being processed by Joi.
  • state - an object containing the current context of validation.
    • key - the key of the current value.
    • path - the full path of the current value.
    • parent - the potential parent of the current value.
  • options - options object provided through any().options() or Joi.validate().

Extension

extension can be :

  • a single extension object
  • a factory function generating an extension object
  • or an array of those

Extension objects use the following parameters :

  • name - name of the new type you are defining, this can be an existing type. Required.
  • base - an existing Joi schema to base your type upon. Defaults to Joi.any().
  • coerce - an optional function that runs before the base, usually serves when you want to coerce values of a different type than your base. It takes 3 arguments value, state and options.
  • pre - an optional function that runs first in the validation chain, usually serves when you need to cast values. It takes 3 arguments value, state and options.
  • language - an optional object to add error definitions. Every key will be prefixed by the type name.
  • describe - an optional function taking the fully formed description to post-process it.
  • rules - an optional array of rules to add.
    • name - name of the new rule. Required.
    • params - an optional object containing Joi schemas of each parameter ordered. You can also pass a single Joi schema as long as it is a Joi.object(), of course some methods such as pattern or rename won't be useful or won't work at all in this given context.
    • setup - an optional function that takes an object with the provided parameters to allow for internals manipulation of the schema when a rule is set, you can optionally return a new Joi schema that will be taken as the new schema instance. At least one of setup or validate must be provided.
    • validate - an optional function to validate values that takes 4 parameters params, value, state and options. At least one of setup or validate must be provided.
    • description - an optional string or function taking the parameters as argument to describe what the rule is doing.

Factory functions are advised if you intend to publish your extensions for others to use, because they are capable of using an extended joi being built, thus avoiding any erasure when using multiple extensions at the same time. See an example of a factory function in the section below.

The params of rules rely on the fact that all engines, even though not stated in the ECMA specifications, preserve the order of object keys, this is a conscious choice to simplify the API for the end-user. If you ever see an engine misbehaving or are uncomfortable relying on this, you can use a single option object to describe your parameters, like:

params: { options: Joi.object({ param1: Joi.number().required(), param2: Joi.string() }) }

Any of the coerce, pre and validate functions should use this.createError(type, context, state, options[, flags]) to create and return errors. This function potentially takes 5 arguments:

  • type - the dotted type of the error matching predefined language elements or the ones defined in your extension. Required.
  • context - a free-form object that can contain anything you want to provide context on regarding the error. This object's properties are inserted in the error message where bracketted placeholders are. Required.
  • state - state that the validation was in, which contains the current key, path, parent if any, or reference if any. Usually you just have to pass the state you were given. Required.
  • options - options that were used for the validation. Usually you just have to pass the options you were given. Required.
  • flags - optional flags that you want to be shown for the error. Defaults to the schema's current flags.

npm note

If you publish your extension on npm, make sure to add joi and extension as keywords so that it's discoverable more easily.

Examples

const Joi = require('joi');
const customJoi = Joi.extend((joi) => ({
    base: joi.number(),
    name: 'number',
    language: {
        round: 'needs to be a rounded number', // Used below as 'number.round'
        dividable: 'needs to be dividable by {{q}}'
    },
    pre(value, state, options) {

        if (options.convert && this._flags.round) {
            return Math.round(value); // Change the value
        }

        return value; // Keep the value as it was
    },
    rules: [
        {
            name: 'round',
            setup(params) {

                this._flags.round = true; // Set a flag for later use
            },
            validate(params, value, state, options) {

                if (value % 1 !== 0) {
                    // Generate an error, state and options need to be passed
                    return this.createError('number.round', { v: value }, state, options);
                }

                return value; // Everything is OK
            }
        },
        {
            name: 'dividable',
            params: {
                q: joi.alternatives([joi.number().required(), joi.func().ref()])
            },
            validate(params, value, state, options) {

                if (value % params.q !== 0) {
                    // Generate an error, state and options need to be passed, q is used in the language
                    return this.createError('number.dividable', { v: value, q: params.q }, state, options);
                }

                return value; // Everything is OK
            }
        }
    ]
}));

const schema = customJoi.number().round().dividable(3);

any

Generates a schema object that matches any data type.

const any = Joi.any();
any.validate('a', (err, value) => { });

schemaType

Gets the type of the schema.

const schema = Joi.string();

schema.schemaType === 'string';   // === true

any.validate(value, [options], [callback])

Validates a value using the schema and options where:

const schema = Joi.object({
    a: Joi.number()
});

const value = {
    a: '123'
};

schema.validate(value, (err, value) => { });
// err -> null
// value.a -> 123 (number, not string)

// or
const result = schema.validate(value);
// result.error -> null
// result.value -> { "a" : 123 }

// or
const promise = schema.validate(value);

any.allow(value)

Whitelists a value where:

  • value - the allowed value which can be of any type and will be matched against the validated value before applying any other rules. value can be an array of values, or multiple values can be passed as individual arguments. value supports references.

Note that this whitelist of allowed values is in addition to any other permitted values. To create an exclusive whitelist of values, see any.valid(value).

const schema = {
    a: Joi.any().allow('a'),
    b: Joi.any().allow('b', 'B'),
    c: Joi.any().allow(['c', 'C'])
};

any.valid(value) - aliases: only, equal

Adds the provided values into the allowed whitelist and marks them as the only valid values allowed where:

  • value - the allowed value which can be of any type and will be matched against the validated value before applying any other rules. value can be an array of values, or multiple values can be passed as individual arguments. value supports references.
const schema = {
    a: Joi.any().valid('a'),
    b: Joi.any().valid('b', 'B'),
    c: Joi.any().valid(['c', 'C'])
};

💥 Possible validation errors:any.allowOnly

any.invalid(value) - aliases: disallow, not

Blacklists a value where:

  • value - the forbidden value which can be of any type and will be matched against the validated value before applying any other rules. value can be an array of values, or multiple values can be passed as individual arguments. value supports references.
const schema = {
    a: Joi.any().invalid('a'),
    b: Joi.any().invalid('b', 'B'),
    c: Joi.any().invalid(['c', 'C'])
};

💥 Possible validation errors:any.invalid

any.required() - aliases: exist

Marks a key as required which will not allow undefined as value. All keys are optional by default.

const schema = Joi.any().required();

💥 Possible validation errors:any.required

any.optional()

Marks a key as optional which will allow undefined as values. Used to annotate the schema for readability as all keys are optional by default.

Note: this does not allow a null value. To do that, use any.allow(value). Or both!

const schema = Joi.any().optional();

any.forbidden()

Marks a key as forbidden which will not allow any value except undefined. Used to explicitly forbid keys.

const schema = {
    a: Joi.any().forbidden()
};

💥 Possible validation errors:any.unknown

any.strip()

Marks a key to be removed from a resulting object or array after validation. Used to sanitize output.

const schema = Joi.object({
    username: Joi.string(),
    password: Joi.string().strip()
});

schema.validate({ username: 'test', password: 'hunter2' }, (err, value) => {
    // value = { username: 'test' }
});

const schema = Joi.array().items(Joi.string(), Joi.any().strip());

schema.validate(['one', 'two', true, false, 1, 2], (err, value) => {
    // value = ['one', 'two']
});

any.description(desc)

Annotates the key where:

  • desc - the description string.
const schema = Joi.any().description('this key will match anything you give it');

any.notes(notes)

Annotates the key where:

  • notes - the notes string or array of strings.
const schema = Joi.any().notes(['this is special', 'this is important']);

any.tags(tags)

Annotates the key where:

  • tags - the tag string or array of strings.
const schema = Joi.any().tags(['api', 'user']);

any.meta(meta)

Attaches metadata to the key where:

  • meta - the meta object to attach.
const schema = Joi.any().meta({ index: true });

any.example(...values)

Adds examples to the schema where:

  • values - each argument is either an example value, or an array of the shape [value, options]:
    • value - single value example.
    • options - optional object argument to pass options to the validation:
      • parent - parent value in case you used normal references in your schema.
      • context - context of the validation in case you used context references in your schema.

If any of the examples fail to pass validation, the function will throw.

Calling this function again will override the previous examples.

// Valid examples
const schema = Joi.string().min(4).example('abcd');

const refSchema = Joi.number().min(Joi.ref('sibling')).example([42, { parent: { sibling: 10 } }]);

const contextSchema = Joi.number().min(Joi.ref('$threshold')).example([42, { context: { $threshold: 10 } }]);

// Invalid examples
const invalidSchema = Joi.string().min(4).example('abc');

const invalidRefSchema = Joi.number().min(Joi.ref('sibling')).example([42, { parent: { sibling: 50 } }]);

const invalidContextSchema = Joi.number().min(Joi.ref('$threshold')).example([42, { context: { $threshold: 50 } }]);

// Multiple examples
const after = Joi.date().min(Joi.ref('before'))
                    .example(
                        ['2016-01-01', { parent: { before: '2015-01-01' } }],
                        ['2016-01-01', { parent: { before: '2015-12-31' } }]
                    )

any.unit(name)

Annotates the key where:

  • name - the unit name of the value.
const schema = Joi.number().unit('milliseconds');

any.options(options)

Overrides the global validate() options for the current key and any sub-key where:

const schema = Joi.any().options({ convert: false });

any.strict(isStrict)

Strict mode sets the options.convert options to false which prevent type casting for the current key and any child keys.

  • isStrict - whether strict mode is enabled or not. Defaults to true.
const schema = Joi.any().strict();

any.default([value, [description]])

Sets a default value if the original value is undefined where:

  • value - the value.
    • value supports references.
    • value may also be a function which returns the default value. If value is specified as a function that accepts a single parameter, that parameter will be a context object that can be used to derive the resulting value.
      • Use a function when setting a dynamic value, such as the current time. Ex: default(Date.now, 'time of creation')
      • Caution: this clones the object, which incurs some overhead so if you don't need access to the context define your method so that it does not accept any parameters.
    • without any value, default has no effect, except for object that will then create nested defaults (applying inner defaults of that object).

Note that if value is an object, any changes to the object after default() is called will change the reference and any future assignment.

Additionally, when specifying a method you must either have a description property on your method or the second parameter is required.

const generateUsername = (context) => {

  return context.firstname.toLowerCase() + '-' + context.lastname.toLowerCase();
};
generateUsername.description = 'generated username';

const schema = {
    username: Joi.string().default(generateUsername),
    firstname: Joi.string(),
    lastname: Joi.string(),
    created: Joi.date().default(Date.now, 'time of creation'),
    status: Joi.string().default('registered')
};

Joi.validate({
    firstname: 'Jane',
    lastname: 'Doe'
}, schema, (err, value) => {

    // value.status === 'registered'
    // value.username === 'jane-doe'
    // value.created will be the time of validation
});

💥 Possible validation errors:any.default

any.concat(schema)

Returns a new type that is the result of adding the rules of one type to another where:

  • schema - a joi type to merge into the current schema. Can only be of the same type as the context type or any. If applied to an any type, the schema can be any other schema.
const a = Joi.string().valid('a');
const b = Joi.string().valid('b');
const ab = a.concat(b);

any.when(condition, options)

Converts the type into an alternatives type where the conditions are merged into the type definition where:

  • condition - the key name or reference, or a schema.
  • options - an object with:
    • is - the required condition joi type. Anything that is not a joi schema will be converted using Joi.compile. Forbidden when condition is a schema.
    • then - the alternative schema type if the condition is true. Required if otherwise is missing.
    • otherwise - the alternative schema type if the condition is false. Required if then is missing.

Note: by default, the is condition schema allows for undefined values. Use .required() to override. For example, use is: Joi.number().required() to guarantee that a joi reference exists and is a number.

const schema = {
    a: Joi.any().valid('x').when('b', { is: Joi.exist(), then: Joi.valid('y'), otherwise: Joi.valid('z') }),
    b: Joi.any()
};

Or with a schema:

const schema = Joi.object({
    a: Joi.any().valid('x'),
    b: Joi.any()
}).when(Joi.object({ b: Joi.exist() }).unknown(), {
    then: Joi.object({
        a: Joi.valid('y')
    }),
    otherwise: Joi.object({
        a: Joi.valid('z')
    })
});

Note that this style is much more useful when your whole schema depends on the value of one of its property, or if you find yourself repeating the check for many keys of an object. For example to validate this logic:

const schema = Joi.object({
    capacity: Joi.string()
        .valid(["A", "B", "C"])
        .required(),
    // required if capacity == "A"
    foo: Joi.when("capacity", {
        is: "A",
        then: Joi.string()
        .valid(["X", "Y", "Z"])
        .required()
    }),
    // required if capacity === "A" and foo !== "Z"
    bar: Joi.string()
}).when(
    Joi.object({
        capacity: Joi.only("A").required(),
        foo: Joi.not("Z")
    }).unknown(),
    {
        then: Joi.object({
            bar: Joi.required()
        })
    }
);

Alternatively, if you want to specify a specific type such as string, array, etc, you can do so like this:

const schema = {
    a: Joi.valid('a', 'b', 'other'),
    other: Joi.string()
        .when('a', { is: 'other', then: Joi.required() }),
};

If you need to validate a child key inside a nested object based on a sibling's value, you can do so like this:

const schema = Joi.object().keys({
    a: Joi.boolean().required(),
    b: Joi.object()
        .keys({
            c: Joi.string(),
            d: Joi.number().required()
        })
        .required()
        .when('a', {
            is: true,
            then: Joi.object({ c: Joi.required() })		// b.c is required only when a is true
        })
});

If you want to validate one key based on the existence of another key, you can do so like the following (notice the use of required()):

const schema = Joi.object().keys({
    min: Joi.number(),
    max: Joi.number().when('min', {
        is: Joi.number().required(),
        then: Joi.number().greater(Joi.ref('min')),
    }),
});

any.label(name)

Overrides the key name in error messages.

  • name - the name of the key.
const schema = {
    first_name: Joi.string().label('First Name')
};

any.raw(isRaw)

Outputs the original untouched value instead of the casted value.

  • isRaw - whether to enable raw mode or not. Defaults to true.
const timestampSchema = Joi.date().timestamp();
timestampSchema.validate('12376834097810'); // { error: null, value: Sat Mar 17 2362 04:28:17 GMT-0500 (CDT) }

const rawTimestampSchema = Joi.date().timestamp().raw();
rawTimestampSchema.validate('12376834097810'); // { error: null, value: '12376834097810' }

any.empty(schema)

Considers anything that matches the schema to be empty (undefined).

  • schema - any object or joi schema to match. An undefined schema unsets that rule.
let schema = Joi.string().empty('');
schema.validate(''); // returns { error: null, value: undefined }
schema = schema.empty();
schema.validate(''); // returns { error: "value" is not allowed to be empty, value: '' }

any.error(err, [options])

Overrides the default joi error with a custom error if the rule fails where:

  • err can be:
    • an instance of Error - the override error.
    • a function(errors), taking an array of errors as argument, where it must either:
      • return a string - substitutes the error message with this text
      • return a single object or an Array of it, where:
        • type - optional parameter providing the type of the error (eg. number.min).
        • message - optional parameter if template is provided, containing the text of the error.
        • template - optional parameter if message is provided, containing a template string, using the same format as usual joi language errors.
        • context - optional parameter, to provide context to your error if you are using the template.
      • return an Error - same as when you directly provide an Error, but you can customize the error message based on the errors.
  • options:
    • self - Boolean value indicating whether the error handler should be used for all errors or only for errors occurring on this property (true value). This concept only makes sense for array or object schemas as other values don't have children. Defaults to false.

Note that if you provide an Error, it will be returned as-is, unmodified and undecorated with any of the normal joi error properties. If validation fails and another error is found before the error override, that error will be returned and the override will be ignored (unless the abortEarly option has been set to false).

let schema = Joi.string().error(new Error('Was REALLY expecting a string'));
schema.validate(3);     // returns error.message === 'Was REALLY expecting a string'

let schema = Joi.object({
    foo: Joi.number().min(0).error(() => '"foo" requires a positive number')
});
schema.validate({ foo: -2 });    // returns error.message === 'child "foo" fails because ["foo" requires a positive number]'

let schema = Joi.object({
    foo: Joi.number().min(0).error(() => '"foo" requires a positive number')
}).required().error(() => 'root object is required', { self: true });
schema.validate();               // returns error.message === 'root object is required'
schema.validate({ foo: -2 });    // returns error.message === 'child "foo" fails because ["foo" requires a positive number]'

let schema = Joi.object({
    foo: Joi.number().min(0).error((errors) => {

        return 'found errors with ' + errors.map((err) => `${err.type}(${err.context.limit}) with value ${err.context.value}`).join(' and ');
    })
});
schema.validate({ foo: -2 });    // returns error.message === 'child "foo" fails because [found errors with number.min(0) with value -2]'

let schema = Joi.object({
    foo: Joi.number().min(0).error((errors) => {

        return {
            template: 'contains {{errors}} errors, here is the list : {{codes}}',
            context: {
                errors: errors.length,
                codes: errors.map((err) => err.type)
            }
        };
    })
});
schema.validate({ foo: -2 });    // returns error.message === 'child "foo" fails because ["foo" contains 1 errors, here is the list : [number.min]]'

Note that if you want to intercept errors on nested structures such as objects and arrays, you will also get a nested structure to explore the children errors, going one level down through the err.context.reason property.

If you want a full substitution of the error system, you can hook at the root and render that errors array with whatever templating system you want, just be aware that you will have to crawl the nested errors for the information you want to actually show.

any.describe()

Behaves the same as describe(schema) and returns an object that represents the internal configuration of the joi schema.

const schema = Joi.any().valid([ 'foo', 'bar' ]);

console.log(schema.describe());

Results in:

{ type: 'any',
  flags: { allowOnly: true },
  valids: [ 'foo', 'bar' ] }

array - inherits from Any

Generates a schema object that matches an array data type. Note that undefined values inside arrays are not allowed by default but can be by using sparse(). If the validation convert option is on (enabled by default), a string will be converted to an array if specified via JSON.parse(). Also, if convert array.single() are both on, then when a single value is specified it will be converted to an array.

Supports the same methods of the any() type.

const array = Joi.array().items(Joi.string().valid('a', 'b'));
array.validate(['a', 'b', 'a'], (err, value) => { });

💥 Possible validation errors:array.base

array.sparse([enabled])

Allows this array to be sparse. enabled can be used with a falsy value to go back to the default behavior.

let schema = Joi.array().sparse(); // undefined values are now allowed
schema = schema.sparse(false); // undefined values are now denied

💥 Possible validation errors:array.sparse

array.single([enabled])

Allows single values to be checked against rules as if it were provided as an array.

enabled can be used with a falsy value to go back to the default behavior.

Note: convert option must be enabled.

const schema = Joi.array().items(Joi.number()).single();
schema.validate([4]); // returns `{ error: null, value: [ 4 ] }`
schema.validate(4); // returns `{ error: null, value: [ 4 ] }`

💥 Possible validation errors:array.excludesSingle, array.includesSingle

array.items(type)

Lists the types allowed for the array values where:

  • type - a joi schema object to validate each array item against. type can be an array of values, or multiple values can be passed as individual arguments.

If a given type is .required() then there must be a matching item in the array. If a type is .forbidden() then it cannot appear in the array. Required items can be added multiple times to signify that multiple items must be found. Errors will contain the number of items that didn't match. Any unmatched item having a label will be mentioned explicitly.

const schema = Joi.array().items(Joi.string(), Joi.number()); // array may contain strings and numbers
const schema = Joi.array().items(Joi.string().required(), Joi.string().required()); // array must contain at least two strings
const schema = Joi.array().items(Joi.string().valid('not allowed').forbidden(), Joi.string()); // array may contain strings, but none of those strings can match 'not allowed'
const schema = Joi.array().items(Joi.string().label('My string').required(), Joi.number().required()); // If this fails it can result in `[ValidationError: "value" does not contain [My string] and 1 other required value(s)]`

💥 Possible validation errors:array.excludes, [array.includesRequiredBoth], [array.includesRequiredKnowns], [array.includesRequiredUnknowns], array.includes

array.ordered(type)

Lists the types in sequence order for the array values where:

  • type - a joi schema object to validate against each array item in sequence order. type can be an array of values, or multiple values can be passed as individual arguments.

If a given type is .required() then there must be a matching item with the same index position in the array. Errors will contain the number of items that didn't match. Any unmatched item having a label will be mentioned explicitly.

const schema = Joi.array().ordered(Joi.string().required(), Joi.number().required()); // array must have first item as string and second item as number
const schema = Joi.array().ordered(Joi.string().required()).items(Joi.number().required()); // array must have first item as string and 1 or more subsequent items as number
const schema = Joi.array().ordered(Joi.string().required(), Joi.number()); // array must have first item as string and optionally second item as number

💥 Possible validation errors:array.excludesSingle, array.includesSingle, array.orderedLength

array.min(limit)

Specifies the minimum number of items in the array where:

  • limit - the lowest number of array items allowed.
const schema = Joi.array().min(2);

It can also be a reference to another field.

const schema = Joi.object({
  limit: Joi.number().integer().required(),
  numbers: Joi.array().min(Joi.ref('limit')).required()
});

💥 Possible validation errors:array.min, array.ref

array.max(limit)

Specifies the maximum number of items in the array where:

  • limit - the highest number of array items allowed.
const schema = Joi.array().max(10);

It can also be a reference to another field.

const schema = Joi.object({
  limit: Joi.number().integer().required(),
  numbers: Joi.array().max(Joi.ref('limit')).required()
});

💥 Possible validation errors:array.max, array.ref

array.length(limit)

Specifies the exact number of items in the array where:

  • limit - the number of array items allowed.
const schema = Joi.array().length(5);

It can also be a reference to another field.

const schema = Joi.object({
  limit: Joi.number().integer().required(),
  numbers: Joi.array().length(Joi.ref('limit')).required()
});

💥 Possible validation errors:array.length, array.ref

array.unique([comparator], [options])

Requires the array values to be unique.

You can provide a custom comparator that is either :

  • a function that takes 2 parameters to compare. This function should return whether the 2 parameters are equal or not, you are also responsible for this function not to fail, any Error would bubble out of Joi.
  • a string in dot notation representing the path of the element to do uniqueness check on. Any missing path will be considered undefined, and can as well only exist once. You can also provide an options object containing:
  • ignoreUndefined. When set to true, undefined values for the dot notation string comparator will not cause the array to fail on uniqueness.

Note: remember that if you provide a custom comparator function, different types can be passed as parameter depending on the rules you set on items.

Be aware that a deep equality is performed on elements of the array having a type of object, a performance penalty is to be expected for this kind of operation.

const schema = Joi.array().unique();
const schema = Joi.array().unique((a, b) => a.property === b.property);
const schema = Joi.array().unique('customer.id');
let schema = Joi.array().unique('identifier');

schema.validate([{}, {}]);
// ValidationError: "value" position 1 contains a duplicate value

schema = Joi.array().unique('identifier', { ignoreUndefined: true });

schema.validate([{}, {}]);
// error: null

💥 Possible validation errors:array.unique

array.has(schema)

Verifies that a schema validates at least one of the values in the array, where:

  • schema - the validation rules required to satisfy the check. If the schema includes references, they are resolved against the array item being tested, not the value of the ref target.
const schema = Joi.array().items(
  Joi.object({
    a: Joi.string(),
    b: Joi.number()
  })
).has(Joi.object({ a: Joi.string().valid('a'), b: Joi.number() }))

💥 Possible validation errors:array.hasKnown, array.hasUnknown

boolean - inherits from Any

Generates a schema object that matches a boolean data type. Can also be called via bool(). If the validation convert option is on (enabled by default), a string (either "true" or "false") will be converted to a boolean if specified.

Supports the same methods of the any() type.

const boolean = Joi.boolean();
boolean.validate(true, (err, value) => { }); // Valid

boolean.validate(1, (err, value) => { }); // Invalid

💥 Possible validation errors:boolean.base

boolean.truthy(value)

Allows for additional values to be considered valid booleans by converting them to true during validation. Accepts a value or an array of values.

String comparisons are by default case insensitive, see boolean.insensitive() to change this behavior.

const boolean = Joi.boolean().truthy('Y');
boolean.validate('Y', (err, value) => { }); // Valid

boolean.falsy(value)

Allows for additional values to be considered valid booleans by converting them to false during validation. Accepts a value or an array of values.

String comparisons are by default case insensitive, see boolean.insensitive() to change this behavior.

const boolean = Joi.boolean().falsy('N');
boolean.validate('N', (err, value) => { }); // Valid

boolean.insensitive([enabled])

Allows the values provided to truthy and falsy as well as the "true" and "false" default conversion (when not in strict() mode) to be matched in a case insensitive manner.

Parameters are:

  • enabled - optional parameter defaulting to true which allows you to reset the behavior of insensitive by providing a falsy value.
const schema = Joi.boolean().truthy('yes').falsy('no').insensitive(false);

binary - inherits from Any

Generates a schema object that matches a Buffer data type. If the validation convert option is on (enabled by default), a string will be converted to a Buffer if specified.

Supports the same methods of the any() type.

const schema = Joi.binary();

💥 Possible validation errors:binary.base

binary.encoding(encoding)

Sets the string encoding format if a string input is converted to a buffer where:

  • encoding - the encoding scheme.
const schema = Joi.binary().encoding('base64');

binary.min(limit)

Specifies the minimum length of the buffer where:

  • limit - the lowest size of the buffer.
const schema = Joi.binary().min(2);

💥 Possible validation errors:binary.min

binary.max(limit)

Specifies the maximum length of the buffer where:

  • limit - the highest size of the buffer.
const schema = Joi.binary().max(10);

💥 Possible validation errors:binary.max

binary.length(limit)

Specifies the exact length of the buffer:

  • limit - the size of buffer allowed.
const schema = Joi.binary().length(5);

💥 Possible validation errors:binary.length

date - inherits from Any

Generates a schema object that matches a date type (as well as a JavaScript date string or number of milliseconds). If the validation convert option is on (enabled by default), a string or number will be converted to a Date if specified.

Supports the same methods of the any() type.

const date = Joi.date();
date.validate('12-21-2012', (err, value) => { });

💥 Possible validation errors:date.base, date.strict

date.min(date)

Specifies the oldest date allowed where:

  • date - the oldest date allowed.
const schema = Joi.date().min('1-1-1974');

Notes: 'now' can be passed in lieu of date so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future.

const schema = Joi.date().min('now');

It can also be a reference to another field.

const schema = Joi.object({
  from: Joi.date().required(),
  to: Joi.date().min(Joi.ref('from')).required()
});

💥 Possible validation errors:date.min, date.ref

date.max(date)

Specifies the latest date allowed where:

  • date - the latest date allowed.
const schema = Joi.date().max('12-31-2020');

Notes: 'now' can be passed in lieu of date so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future.

const schema = Joi.date().max('now');

It can also be a reference to another field.

const schema = Joi.object({
  from: Joi.date().max(Joi.ref('to')).required(),
  to: Joi.date().required()
});

💥 Possible validation errors:date.max, date.ref

date.greater(date)

Specifies that the value must be greater than date.

const schema = Joi.date().greater('1-1-1974');

Notes: 'now' can be passed in lieu of date so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future.

const schema = Joi.date().greater('now');

It can also be a reference to another field.

const schema = Joi.object({
  from: Joi.date().required(),
  to: Joi.date().greater(Joi.ref('from')).required()
});

💥 Possible validation errors:date.greater, date.ref

date.less(date)

Specifies that the value must be less than date.

const schema = Joi.date().less('12-31-2020');

Notes: `'now'` can be passed in lieu of `date` so as to always compare relatively to the current date, allowing to explicitly ensure a date is either in the past or in the future.

```js
const schema = Joi.date().max('now');

It can also be a reference to another field.

const schema = Joi.object({
  from: Joi.date().less(Joi.ref('to')).required(),
  to: Joi.date().required()
});

💥 Possible validation errors:date.less, date.ref

date.iso()

Requires the string value to be in valid ISO 8601 date format.

const schema = Joi.date().iso();

💥 Possible validation errors:date.isoDate

date.timestamp([type])

Requires the value to be a timestamp interval from Unix Time.

  • type - the type of timestamp (allowed values are unix or javascript [default])
const schema = Joi.date().timestamp(); // defaults to javascript timestamp
const schema = Joi.date().timestamp('javascript'); // also, for javascript timestamp (milliseconds)
const schema = Joi.date().timestamp('unix'); // for unix timestamp (seconds)

💥 Possible validation errors:date.timestamp.javascript, date.timestamp.unix

func - inherits from Any

Generates a schema object that matches a function type.

Supports the same methods of the object() type. Note that validating a function keys will cause the function to be cloned. While the function will retain its prototype and closure, it will lose its length property value (will be set to 0).

const func = Joi.func();
func.validate(function () {}, (err, value) => { });

💥 Possible validation errors:function.base

func.arity(n)

Specifies the arity of the function where:

  • n - the arity expected.
const schema = Joi.func().arity(2);

💥 Possible validation errors:function.arity

func.minArity(n)

Specifies the minimal arity of the function where:

  • n - the minimal arity expected.
const schema = Joi.func().minArity(1);

💥 Possible validation errors:function.minArity

func.maxArity(n)

Specifies the maximal arity of the function where:

  • n - the maximum arity expected.
const schema = Joi.func().maxArity(3);

💥 Possible validation errors:function.maxArity

func.class()

Requires the function to be a class.

const schema = Joi.func().class();

💥 Possible validation errors:function.class

func.ref()

Requires the function to be a Joi reference.

const schema = Joi.func().ref();

💥 Possible validation errors:function.ref

number - inherits from Any

Generates a schema object that matches a number data type (as well as strings that can be converted to numbers).

By default, it only allows safe numbers, see number.unsafe().

If the validation convert option is on (enabled by default), a string will be converted to a number if specified. Also, if convert is on and number.precision() is used, the value will be converted to the specified precision as well.

Infinity and -Infinity are invalid by default, you can change that behavior by calling allow(Infinity, -Infinity).

Supports the same methods of the any() type.

const number = Joi.number();
number.validate(5, (err, value) => { });

💥 Possible validation errors:number.base

number.unsafe([enabled])

By default, numbers must be within JavaScript's safety range (Number.MIN_SAFE_INTEGER & Number.MAX_SAFE_INTEGER), and when given a string, should be converted without loss of information. You can allow unsafe numbers at your own risks by calling number.unsafe().

Parameters are:

  • enabled - optional parameter defaulting to true which allows you to reset the behavior of unsafe by providing a falsy value.
const safeNumber = Joi.number();
safeNumber.validate(90071992547409924);
// error -> "value" must be a safe number

const unsafeNumber = Joi.number().unsafe();
unsafeNumber.validate(90071992547409924);
// error -> null
// value -> 90071992547409920

💥 Possible validation errors:number.unsafe

number.min(limit)

Specifies the minimum value where:

  • limit - the minimum value allowed.
const schema = Joi.number().min(2);

It can also be a reference to another field.

const schema = Joi.object({
  min: Joi.number().required(),
  max: Joi.number().min(Joi.ref('min')).required()
});

💥 Possible validation errors:number.min, number.ref

number.max(limit)

Specifies the maximum value where:

  • limit - the maximum value allowed.
const schema = Joi.number().max(10);

It can also be a reference to another field.

const schema = Joi.object({
  min: Joi.number().max(Joi.ref('max')).required(),
  max: Joi.number().required()
});

💥 Possible validation errors:number.max, number.ref

number.greater(limit)

Specifies that the value must be greater than limit.

const schema = Joi.number().greater(5);
const schema = Joi.object({
  min: Joi.number().required(),
  max: Joi.number().greater(Joi.ref('min')).required()
});

💥 Possible validation errors:number.greater, number.ref

number.less(limit)

Specifies that the value must be less than limit.

const schema = Joi.number().less(10);

It can also be a reference to another field.

const schema = Joi.object({
  min: Joi.number().less(Joi.ref('max')).required(),
  max: Joi.number().required()
});

💥 Possible validation errors:number.less, number.ref

number.integer()

Requires the number to be an integer (no floating point).

const schema = Joi.number().integer();

💥 Possible validation errors:number.base

number.precision(limit)

Specifies the maximum number of decimal places where:

  • limit - the maximum number of decimal places allowed.
const schema = Joi.number().precision(2);

💥 Possible validation errors:number.integer

number.multiple(base)

Specifies that the value must be a multiple of base:

const schema = Joi.number().multiple(3);

Notes: Joi.number.multiple(base) uses the modulo operator (%) to determine if a number is multiple of another number. Therefore, it has the normal limitations of Javascript modulo operator. The results with decimal/floats may be incorrect.

💥 Possible validation errors:number.multiple, number.ref

number.positive()

Requires the number to be positive.

const schema = Joi.number().positive();

💥 Possible validation errors:number.positive

number.negative()

Requires the number to be negative.

const schema = Joi.number().negative();

💥 Possible validation errors:number.negative

number.port()

Requires the number to be a TCP port, so between 0 and 65535.

const schema = Joi.number().port();

💥 Possible validation errors:number.port

object - inherits from Any

Generates a schema object that matches an object data type (as well as JSON strings that parsed into objects). Defaults to allowing any child key. If the validation convert option is on (enabled by default), a string will be converted to an object if specified via JSON.parse().

Supports the same methods of the any() type.

const object = Joi.object().keys({
    a: Joi.number().min(1).max(10).integer(),
    b: 'some string'
});

object.validate({ a: 5 }, (err, value) => { });

💥 Possible validation errors:object.base

object.keys([schema])

Sets or extends the allowed object keys where:

  • schema - optional object where each key is assigned a joi type object. If schema is {} no keys allowed. If schema is null or undefined, any key allowed. If schema is an object with keys, the keys are added to any previously defined keys (but narrows the selection if all keys previously allowed). Defaults to 'undefined' which allows any child key.
const base = Joi.object().keys({
    a: Joi.number(),
    b: Joi.string()
});
// Validate keys a, b and c.
const extended = base.keys({
    c: Joi.boolean()
});

Notes: We have three different ways to define a schema for performing a validation

  • Using the plain JS object notation:
const schema = {
    a: Joi.string(),
    b: Joi.number()
};
  • Using the Joi.object([schema]) notation
const schema = Joi.object({
    a: Joi.string(),
    b: Joi.number()
});
  • Using the Joi.object().keys([schema]) notation
const schema = Joi.object().keys({
    a: Joi.string(),
    b: Joi.number()
});

💥 Possible validation errors:object.allowUnknown

While all these three objects defined above will result in the same validation object, there are some differences in using one or another:

{} notation

When using the {} notation, you are just defining a plain JS object, which isn't a schema object. You can pass it to the validation method but you can't call validate() method of the object because it's just a plain JS object.

Besides, passing the {} object to the validate() method each time, will perform an expensive schema compilation operation on every validation.

Joi.object([schema]) notation

Using Joi.object([schema]) will return a schema object, so you can call the validate() method directly, e.g:

const schema = Joi.object({
    a: Joi.boolean()
});

schema.validate(true, (err, value) => {
    console.log('err: ', err);
});

When you use Joi.object([schema]), it gets compiled the first time, so you can pass it to the validate() method multiple times and no overhead is added.

Another benefits of using Joi.object([schema]) instead of a plain JS object is that you can set any options on the object like allowing unknown keys, e.g:

const schema = Joi.object({
    arg: Joi.string().valid('firstname', 'lastname', 'title', 'company', 'jobtitle'),
    value: Joi.string(),
}).pattern(/firstname|lastname/, Joi.string().min(2));
Joi.object().keys([schema]) notation

This is basically the same as Joi.object([schema]), but using Joi.object().keys([schema]) is more useful when you want to add more keys (e.g. call keys() multiple times). If you are only adding one set of keys, you can skip the keys() method and just use object() directly.

Some people like to use keys() to make the code more explicit (this is style only).

object.append([schema])

Appends the allowed object keys where:

  • schema - optional object where each key is assigned a joi type object. If schema is null,undefined or {} no changes will be applied. Uses object.keys([schema]) to append keys.
// Validate key a
const base = Joi.object().keys({
    a: Joi.number()
});
// Validate keys a, b.
const extended = base.append({
    b: Joi.string()
});

object.min(limit)

Specifies the minimum number of keys in the object where:

  • limit - the lowest number of keys allowed.
const schema = Joi.object().min(2);

💥 Possible validation errors:object.min

object.max(limit)

Specifies the maximum number of keys in the object where:

  • limit - the highest number of object keys allowed.
const schema = Joi.object().max(10);

💥 Possible validation errors:object.max

object.length(limit)

Specifies the exact number of keys in the object where:

  • limit - the number of object keys allowed.
const schema = Joi.object().length(5);

💥 Possible validation errors:object.length

object.pattern(pattern, schema)

Specify validation rules for unknown keys matching a pattern where:

  • pattern - a pattern that can be either a regular expression or a joi schema that will be tested against the unknown key names.
  • schema - the schema object matching keys must validate against.
const schema = Joi.object({
    a: Joi.string()
}).pattern(/\w\d/, Joi.boolean());

// OR

const schema = Joi.object({
    a: Joi.string()
}).pattern(Joi.string().min(2).max(5), Joi.boolean());

object.and(peers)

Defines an all-or-nothing relationship between keys where if one of the peers is present, all of them are required as well where:

  • peers - the key names of which if one present, all are required. peers can be a single string value, an array of string values, or each peer provided as an argument.
const schema = Joi.object().keys({
    a: Joi.any(),
    b: Joi.any()
}).and('a', 'b');

💥 Possible validation errors:object.and

object.nand(peers)

Defines a relationship between keys where not all peers can be present at the same time where:

  • peers - the key names of which if one present, the others may not all be present. peers can be a single string value, an array of string values, or each peer provided as an argument.
const schema = Joi.object().keys({
    a: Joi.any(),
    b: Joi.any()
}).nand('a', 'b');

💥 Possible validation errors:object.nand

object.or(peers)

Defines a relationship between keys where one of the peers is required (and more than one is allowed) where:

  • peers - the key names of which at least one must appear. peers can be a single string value, an array of string values, or each peer provided as an argument.
const schema = Joi.object().keys({
    a: Joi.any(),
    b: Joi.any()
}).or('a', 'b');

💥 Possible validation errors:object.missing

object.xor(peers)

Defines an exclusive relationship between a set of keys where one of them is required but not at the same time where:

  • peers - the exclusive key names that must not appear together but where one of them is required. peers can be a single string value, an array of string values, or each peer provided as an argument.
const schema = Joi.object().keys({
    a: Joi.any(),
    b: Joi.any()
}).xor('a', 'b');

💥 Possible validation errors:object.xor, object.missing

object.oxor(...peers)

Defines an exclusive relationship between a set of keys where only one is allowed but none are required where:

  • peers - the exclusive key names that must not appear together but where none are required.
const schema = Joi.object().keys({
    a: Joi.any(),
    b: Joi.any()
}).oxor('a', 'b');

💥 Possible validation errors:object.oxor

object.with(key, peers)

Requires the presence of other keys whenever the specified key is present where:

  • key - the reference key.
  • peers - the required peer key names that must appear together with key. peers can be a single string value or an array of string values.

Note that unlike object.and(), with() creates a dependency only between the key and each of the peers, not between the peers themselves.

const schema = Joi.object().keys({
    a: Joi.any(),
    b: Joi.any()
}).with('a', 'b');

💥 Possible validation errors:object.with

object.without(key, peers)

Forbids the presence of other keys whenever the specified is present where:

  • key - the reference key.
  • peers - the forbidden peer key names that must not appear together with key. peers can be a single string value or an array of string values.
const schema = Joi.object().keys({
    a: Joi.any(),
    b: Joi.any()
}).without('a', ['b']);

💥 Possible validation errors:object.without

object.rename(from, to, [options])

Renames a key to another name (deletes the renamed key) where:

  • from - the original key name or a regular expression matching keys.
  • to - the new key name.
  • options - an optional object with the following optional keys:
    • alias - if true, does not delete the old key name, keeping both the new and old keys in place. Defaults to false.
    • multiple - if true, allows renaming multiple keys to the same destination where the last rename wins. Defaults to false.
    • override - if true, allows renaming a key over an existing key. Defaults to false.
    • ignoreUndefined - if true, skip renaming of a key if it's undefined. Defaults to false.

Keys are renamed before any other validation rules are applied.

const object = Joi.object().keys({
    a: Joi.number()
}).rename('b', 'a');

object.validate({ b: 5 }, (err, value) => { });

It can also rename keys using a regular expression:

const regex = /^foobar$/i;

const schema = Joi.object().keys({
  fooBar: Joi.string()
}).rename(regex, 'fooBar');

schema.validate({ FooBar: 'a'}, (err, value) => {});

💥 Possible validation errors:object.rename.multiple, object.rename.override, object.rename.regex.multiple, object.rename.regex.override

object.assert(ref, schema, [message])

Verifies an assertion where:

  • ref - the key name or reference.
  • schema - the validation rules required to satisfy the assertion. If the schema includes references, they are resolved against the object value, not the value of the ref target.
  • message - optional human-readable message used when the assertion fails. Defaults to 'failed to pass the assertion test'.
const schema = Joi.object().keys({
    a: {
        b: Joi.string(),
        c: Joi.number()
    },
    d: {
        e: Joi.any()
    }
}).assert('d.e', Joi.ref('a.c'), 'equal to a.c');

💥 Possible validation errors:object.assert

object.unknown([allow])

Overrides the handling of unknown keys for the scope of the current object only (does not apply to children) where:

  • allow - if false, unknown keys are not allowed, otherwise unknown keys are ignored.
const schema = Joi.object({ a: Joi.any() }).unknown();

💥 Possible validation errors:object.allowUnknown

object.type(constructor, [name])

Requires the object to be an instance of a given constructor where:

  • constructor - the constructor function that the object must be an instance of.
  • name - an alternate name to use in validation errors. This is useful when the constructor function does not have a name.
const schema = Joi.object().type(RegExp);

💥 Possible validation errors:object.type

object.schema()

Requires the object to be a Joi schema instance.

const schema = Joi.object().schema();

💥 Possible validation errors:object.schema

object.requiredKeys(children)

Sets the specified children to required.

  • children - can be a single string value, an array of string values, or each child provided as an argument.
const schema = Joi.object().keys({ a: { b: Joi.number() }, c: { d: Joi.string() } });
const requiredSchema = schema.requiredKeys('', 'a.b', 'c', 'c.d');

Note that in this example '' means the current object, a is not required but b is, as well as c and d.

object.optionalKeys(children)

Sets the specified children to optional.

  • children - can be a single string value, an array of string values, or each child provided as an argument.
const schema = Joi.object().keys({ a: { b: Joi.number().required() }, c: { d: Joi.string().required() } });
const optionalSchema = schema.optionalKeys('a.b', 'c.d');

The behavior is exactly the same as requiredKeys.

object.forbiddenKeys(children)

Sets the specified children to forbidden.

  • children - can be a single string value, an array of string values, or each child provided as an argument.
const schema = Joi.object().keys({ a: { b: Joi.number().required() }, c: { d: Joi.string().required() } });
const optionalSchema = schema.forbiddenKeys('a.b', 'c.d');

The behavior is exactly the same as requiredKeys.

string - inherits from Any

Generates a schema object that matches a string data type. Note that empty strings are not allowed by default and must be enabled with allow(''). However, if you want to specify a default value in case of empty string you have to use a different pattern: Joi.string().empty('').default('default value'). This tells Joi that the empty string should be considered as an empty value (instead of invalid) and which value to use as default.

If the validation convert option is on (enabled by default), a string will be converted using the specified modifiers for string.lowercase(), string.uppercase(), string.trim(), and each replacement specified with string.replace().

Supports the same methods of the any() type.

const schema = Joi.string().min(1).max(10);
schema.validate('12345', (err, value) => { });

💥 Possible validation errors:string.base, any.empty

string.insensitive()

Allows the value to match any whitelist or blacklist item in a case insensitive comparison.

const schema = Joi.string().valid('a').insensitive();

string.min(limit, [encoding])

Specifies the minimum number string characters where:

  • limit - the minimum number of string characters required.
  • encoding - if specified, the string length is calculated in bytes using the provided encoding.
const schema = Joi.string().min(2);

It can also be a reference to another field.

const schema = Joi.object({
  min: Joi.string().required(),
  value: Joi.string().min(Joi.ref('min'), 'utf8').required()
});

💥 Possible validation errors:string.min, string.ref

string.max(limit, [encoding])

Specifies the maximum number of string characters where:

  • limit - the maximum number of string characters allowed.
  • encoding - if specified, the string length is calculated in bytes using the provided encoding.
const schema = Joi.string().max(10);

It can also be a reference to another field.

const schema = Joi.object({
  max: Joi.string().required(),
  value: Joi.string().max(Joi.ref('max'), 'utf8').required()
});

💥 Possible validation errors:string.max, string.ref

string.truncate([enabled])

Specifies whether the string.max() limit should be used as a truncation.

Parameters are:

  • enabled - optional parameter defaulting to true which allows you to reset the behavior of truncate by providing a falsy value.
const schema = Joi.string().max(5).truncate();

string.creditCard()

Requires the number to be a credit card number (Using Luhn Algorithm).

const schema = Joi.string().creditCard();

💥 Possible validation errors:string.creditCard

string.length(limit, [encoding])

Specifies the exact string length required where:

  • limit - the required string length.
  • encoding - if specified, the string length is calculated in bytes using the provided encoding.
const schema = Joi.string().length(5);

It can also be a reference to another field.

const schema = Joi.object({
  length: Joi.string().required(),
  value: Joi.string().length(Joi.ref('length'), 'utf8').required()
});

💥 Possible validation errors:string.length, string.ref

string.regex(pattern, [name | options])

Defines a regular expression rule where:

  • pattern - a regular expression object the string value must match against.
  • name - optional name for patterns (useful with multiple patterns).
  • options - an optional configuration object with the following supported properties:
    • name - optional pattern name.
    • invert - optional boolean flag. Defaults to false behavior. If specified as true, the provided pattern will be disallowed instead of required.
const schema = Joi.string().regex(/^[abc]+$/);

const inlineNamedSchema = Joi.string().regex(/^[0-9]+$/, 'numbers');
inlineNamedSchema.validate('alpha'); // ValidationError: "value" with value "alpha" fails to match the numbers pattern

const namedSchema = Joi.string().regex(/^[0-9]+$/, { name: 'numbers'});
namedSchema.validate('alpha'); // ValidationError: "value" with value "alpha" fails to match the numbers pattern

const invertedSchema = Joi.string().regex(/^[a-z]+$/, { invert: true });
invertedSchema.validate('lowercase'); // ValidationError: "value" with value "lowercase" matches the inverted pattern: [a-z]

const invertedNamedSchema = Joi.string().regex(/^[a-z]+$/, { name: 'alpha', invert: true });
invertedNamedSchema.validate('lowercase'); // ValidationError: "value" with value "lowercase" matches the inverted alpha pattern

💥 Possible validation errors:string.regex.base, string.regex.invert.base, string.regex.invert.name, string.regex.name

string.replace(pattern, replacement)

Replace characters matching the given pattern with the specified replacement string where:

  • pattern - a regular expression object to match against, or a string of which all occurrences will be replaced.
  • replacement - the string that will replace the pattern.
const schema = Joi.string().replace(/b/gi, 'x');
schema.validate('abBc', (err, value) => {
  // here value will be 'axxc'
});

When pattern is a string all its occurrences will be replaced.

string.alphanum()

Requires the string value to only contain a-z, A-Z, and 0-9.

const schema = Joi.string().alphanum();

💥 Possible validation errors:string.alphanum

string.token()

Requires the string value to only contain a-z, A-Z, 0-9, and underscore _.

const schema = Joi.string().token();

💥 Possible validation errors:string.token

string.email([options])

Requires the string value to be a valid email address.

  • options - optional settings:
    • errorLevel - Numerical threshold at which an email address is considered invalid.
    • tldWhitelist - Specifies a list of acceptable TLDs.
    • minDomainAtoms - Number of atoms required for the domain. Be careful since some domains, such as io, directly allow email.

Have a look at isemail’s documentation for a detailed description of the options.

const schema = Joi.string().email();

💥 Possible validation errors:string.email

string.ip([options])

Requires the string value to be a valid ip address.

  • options - optional settings:
    • version - One or more IP address versions to validate against. Valid values: ipv4, ipv6, ipvfuture
    • cidr - Used to determine if a CIDR is allowed or not. Valid values: optional, required, forbidden
// Accept only ipv4 and ipv6 addresses with a CIDR
const schema = Joi.string().ip({
  version: [
    'ipv4',
    'ipv6'
  ],
  cidr: 'required'
});

💥 Possible validation errors:string.ip, string.ipVersion

string.uri([options])

Requires the string value to be a valid RFC 3986 URI.

  • options - optional settings:
    • scheme - Specifies one or more acceptable Schemes, should only include the scheme name. Can be an Array or String (strings are automatically escaped for use in a Regular Expression).
    • allowRelative - Allow relative URIs. Defaults to false.
    • relativeOnly - Restrict only relative URIs. Defaults to false.
    • allowQuerySquareBrackets - Allows unencoded square brackets inside the query string. This is NOT RFC 3986 compliant but query strings like abc[]=123&abc[]=456 are very common these days. Defaults to false.
// Accept git or git http/https
const schema = Joi.string().uri({
  scheme: [
    'git',
    /git\+https?/
  ]
});

💥 Possible validation errors:string.uri, string.uriCustomScheme, string.uriRelativeOnly

string.guid() - aliases: uuid

Requires the string value to be a valid GUID.

  • options - optional settings:
    • version - Specifies one or more acceptable versions. Can be an Array or String with the following values: uuidv1, uuidv2, uuidv3, uuidv4, or uuidv5. If no version is specified then it is assumed to be a generic guid.
const schema = Joi.string().guid({
    version: [
        'uuidv4',
        'uuidv5'
    ]
});

💥 Possible validation errors:string.guid

string.hex([options])

Requires the string value to be a valid hexadecimal string.

  • options - optional settings:
    • byteAligned - Boolean specifying whether you want to check that the hexadecimal string is byte aligned. If convert is true, a 0 will be added in front of the string in case it needs to be aligned. Defaults to false.
const schema = Joi.string().hex();

💥 Possible validation errors:string.hex, string.hexAlign

string.base64([options])

Requires the string value to be a valid base64 string; does not check the decoded value.

  • options - optional settings:
    • paddingRequired - optional parameter defaulting to true which will require = padding if true or make padding optional if false.

Padding characters are not required for decoding, as the number of missing bytes can be inferred from the number of digits. With that said, try to use padding if at all possible.

const schema = Joi.string().base64();
schema.validate('VE9PTUFOWVNFQ1JFVFM'); // ValidationError: "value" must be a valid base64 string
schema.validate('VE9PTUFOWVNFQ1JFVFM='); // No Error

const paddingRequiredSchema = Joi.string().base64({ paddingRequired: true });
paddingRequiredSchema.validate('VE9PTUFOWVNFQ1JFVFM'); // ValidationError: "value" must be a valid base64 string
paddingRequiredSchema.validate('VE9PTUFOWVNFQ1JFVFM='); // No Error

const paddingOptionalSchema = Joi.string().base64({ paddingRequired: false });
paddingOptionalSchema.validate('VE9PTUFOWVNFQ1JFVFM'); // No Error
paddingOptionalSchema.validate('VE9PTUFOWVNFQ1JFVFM='); // No Error

💥 Possible validation errors:string.base64

string.dataUri([options])

Requires the string value to be a valid data URI string.

  • options - optional settings:
    • paddingRequired - optional parameter defaulting to true which will require = padding if true or make padding optional if false.
const schema = Joi.string().dataUri();
schema.validate('VE9PTUFOWVNFQ1JFVFM='); // ValidationError: "value" must be a valid dataUri string
schema.validate('data:image/png;base64,VE9PTUFOWVNFQ1JFVFM='); // No Error

💥 Possible validation errors:string.dataUri

string.hostname()

Requires the string value to be a valid hostname as per RFC1123.

const schema = Joi.string().hostname();

💥 Possible validation errors:string.hostname

string.normalize([form])

Requires the string value to be in a unicode normalized form. If the validation convert option is on (enabled by default), the string will be normalized.

  • form - The unicode normalization form to use. Valid values: NFC [default], NFD, NFKC, NFKD
const schema = Joi.string().normalize(); // defaults to NFC
const schema = Joi.string().normalize('NFC'); // canonical composition
const schema = Joi.string().normalize('NFD'); // canonical decomposition
const schema = Joi.string().normalize('NFKC'); // compatibility composition
const schema = Joi.string().normalize('NFKD'); // compatibility decomposition

💥 Possible validation errors:string.normalize

string.lowercase()

Requires the string value to be all lowercase. If the validation convert option is on (enabled by default), the string will be forced to lowercase.

const schema = Joi.string().lowercase();

💥 Possible validation errors:string.lowercase

string.uppercase()

Requires the string value to be all uppercase. If the validation convert option is on (enabled by default), the string will be forced to uppercase.

const schema = Joi.string().uppercase();

💥 Possible validation errors:string.uppercase

string.trim([enabled])

Requires the string value to contain no whitespace before or after. If the validation convert option is on (enabled by default), the string will be trimmed.

Parameters are:

  • enabled - optional parameter defaulting to true which allows you to reset the behavior of trim by providing a falsy value.
const schema = Joi.string().trim();
const schema = Joi.string().trim(false); // disable trim flag

💥 Possible validation errors:string.trim

string.isoDate()

Requires the string value to be in valid ISO 8601 date format. If the validation convert option is on (enabled by default), the string will be forced to simplified extended ISO format (ISO 8601). Be aware that this operation uses javascript Date object, which does not support the full ISO format, so a few formats might not pass when using convert.

const schema = Joi.string().isoDate();

💥 Possible validation errors:string.isoDate

symbol - inherits from Any

Generates a schema object that matches a Symbol data type.

If the validation convert option is on (enabled by default), the mappings declared in map() will be tried for an eventual match.

Supports the same methods of the any() type.

const schema = Joi.symbol().map({ 'foo': Symbol('foo'), 'bar': Symbol('bar') });
schema.validate('foo', (err, value) => { });

💥 Possible validation errors:symbol.base

symbol.map(map)

Allows values to be transformed into Symbols, where:

  • map - mapping declaration that can be:
    • an object, where keys are strings, and values are Symbols
    • an array of arrays of length 2, where for each sub-array, the 1st element must be anything but an object, a function or a Symbol, and the 2nd element must be a Symbol
    • a Map, following the same principles as the array above
const schema = Joi.symbol().map([
    [1, Symbol('one')],
    ['two', Symbol('two')]
]);

💥 Possible validation errors:symbol.map

alternatives - inherits from Any

Generates a type that will match one of the provided alternative schemas via the try() method. If no schemas are added, the type will not match any value except for undefined.

Supports the same methods of the any() type.

Alternatives can be expressed using the shorter [] notation.

const alt = Joi.alternatives().try(Joi.number(), Joi.string());
// Same as [Joi.number(), Joi.string()]

💥 Possible validation errors:alternatives.base

alternatives.try(schemas)

Adds an alternative schema type for attempting to match against the validated value where:

  • schema - an array of alternative joi types. Also supports providing each type as a separate argument.
const alt = Joi.alternatives().try(Joi.number(), Joi.string());
alt.validate('a', (err, value) => { });

alternatives.when(condition, options)

Adds a conditional alternative schema type, either based on another key (not the same as any.when()) value, or a schema peeking into the current value, where:

  • condition - the key name or reference, or a schema.
  • options - an object with:
    • is - the required condition joi type. Forbidden when condition is a schema.
    • then - the alternative schema type to try if the condition is true. Required if otherwise is missing.
    • otherwise - the alternative schema type to try if the condition is false. Required if then is missing.
const schema = {
    a: Joi.alternatives().when('b', { is: 5, then: Joi.string(), otherwise: Joi.number() }),
    b: Joi.any()
};
const schema = Joi.alternatives().when(Joi.object({ b: 5 }).unknown(), {
    then: Joi.object({
        a: Joi.string(),
        b: Joi.any()
    }),
    otherwise: Joi.object({
        a: Joi.number(),
        b: Joi.any()
    })
});

Note that when() only adds additional alternatives to try and does not impact the overall type. Setting a required() rule on a single alternative will not apply to the overall key. For example, this definition of a:

const schema = {
    a: Joi.alternatives().when('b', { is: true, then: Joi.required() }),
    b: Joi.boolean()
};

Does not turn a into a required key when b is true. Instead, it tells the validator to try and match the value to anything that's not undefined. However, since Joi.alternatives() by itself allows undefined, the rule does not accomplish turning a to a required value. This rule is the same as Joi.alternatives([Joi.required()]) when b is true which will allow any value including undefined.

To accomplish the desired result above use:

const schema = {
    a: Joi.when('b', { is: true, then: Joi.required() }),
    b: Joi.boolean()
};

lazy(fn[, options]) - inherits from Any

Generates a placeholder schema for a schema that you would provide where:

  • fn - is a function returning the actual schema to use for validation.
  • options:
    • once - enables or disables the single evaluation behavior. When false, the function will be called every time a validation happens, otherwise the schema will be cached for further re-use. Defaults to true.

Supports the same methods of the any() type.

This is mostly useful for recursive schemas, like :

const Person = Joi.object({
    firstName: Joi.string().required(),
    lastName: Joi.string().required(),
    children: Joi.array().items(Joi.lazy(() => Person).description('Person schema'))
});

💥 Possible validation errors:lazy.base, lazy.schema

Errors

Joi throws classical javascript Errors containing :

  • name - 'ValidationError'.
  • isJoi - true.
  • details - an array of errors :
    • message - string with a description of the error.
    • path - ordered array where each element is the accessor to the value where the error happened.
    • type - type of the error.
    • context - object providing context of the error containing at least:
      • key - key of the value that errored, equivalent to the last element of details.path.
      • label - label of the value that errored, or the key if any, or the default language.root.
  • annotate - function that returns a string with an annotated version of the object pointing at the places where errors occurred. Takes an optional parameter that, if truthy, will strip the colors out of the output.
  • _object - the original object to validate.

List of errors

alternatives.base

Description

No alternative matched the input.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string // Label if defined, otherwise it's the key
}

any.allowOnly

Description

Only some values were allowed, the input didn't match any of them.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    valids: Array<any> // Contains the list of the valid values that were expected
}

any.default

Description

If your any.default() generator function throws error, you will have it here.

Context

{
    error: Error // Error generated during the default value function call
}

any.empty

Description

When an empty string is found and denied by invalid values.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: '', // Empty string
    invalids: Array<any> // Contains the list of the invalid values that should be rejected
}

any.invalid

Description

The value matched a value listed in the invalid values.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any, // Value being validated
    invalids: Array<any> // Contains the list of the invalid values that should be rejected
}

any.required

Description

A required value wasn't present.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string // Label if defined, otherwise it's the key
}

any.unknown

Description

A value was present while it wasn't expected.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string // Label if defined, otherwise it's the key
}

array.base

Description

The value is not of Array type or could not be cast to an Array from a string.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string // Label if defined, otherwise it's the key
}

array.excludes

Description

The array contains a value that is part of the exclusion list.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    pos: number, // Index where the value was found in the array
    value: any // Value that matched an exclude condition
}

array.excludesSingle

Description

Same as array.excludes but the value was a single value. Happens with array.single().

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    pos: number, // Index where the value was found in the array
    value: any // Value that matched an exclude condition
}

array.includesRequiredBoth

Description

Some values were expected to be present in the array and are missing. This error happens when we have a mix of labelled and unlabelled schemas.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    knownMisses: Array<string>, // Labels of all the missing values
    unknownMisees: number // Count of missing values that didn't have a label
}

array.includesRequiredKnowns

Description

Some values were expected to be present in the array and are missing. This error happens when we only have labelled schemas.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    knownMisses: Array<string> // Labels of all the missing values
}

array.includesRequiredUnknowns

Description

Some values were expected to be present in the array and are missing. This error happens when we only have unlabelled schemas.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    unknownMisees: number // Count of missing values that didn't have a label
}

array.includes

Description

The value didn't match any of the allowed types for that array.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    pos: number, // Index where the value was found in the array
    value: any // Value that failed all the schemas
}

array.includesSingle

Description

Same as array.includes but the value was a single value. Happens with array.single().

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    pos: number, // Index where the value was found in the array
    value: any // Value that failed all the schemas
}

array.length

Description

The array is not of the expected length.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Length that was expected for this array
    value: Array<any> // The array itself
}

array.max

Description

The array has more elements than the maximum allowed.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Maximum length that was expected for this array
    value: Array<any> // The array itself
}

array.min

Description

The array has less elements than the minimum allowed.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Minimum length that was expected for this array
    value: Array<any> // The array itself
}

array.orderedLength

Description

Given an array.ordered(), that array has more elements than it should.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    pos: number, // Index where the value was found in the array
    limit: number // Maximum length that was expected for this array
}

array.ref

Description

A reference was used in one of array.min(), array.max() or array.length() and the value pointed to by that reference in the input is not a valid number for those rules.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    ref: Reference, // Reference used
    value: any // Value found using the reference
}

array.sparse

Description

An undefined value was found in an array that shouldn't be sparse.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    pos: number // Index where an undefined value was found in the array
}

array.unique

Description

A duplicate value was found in an array.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    pos: number, // Index where the duplicate value was found in the array
    value: any, // Value that is duplicated
    dupePos: number, // Index where the first appearance of the duplicate value was found in the array
    dupeValue: any // Value with which the duplicate was met
}

array.hasKnown

Description

The schema on an array.has() was not found in the array. This error happens when the schema is labelled.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    patternLabel: string // Label of assertion schema
}

array.hasUnknown

Description

The schema on an array.has() was not found in the array. This error happens when the schema is unlabelled.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
}

binary.base

Description

The value is either not a Buffer or could not be cast to a Buffer from a string.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string // Label if defined, otherwise it's the key
}

binary.length

Description

The buffer was not of the specified length.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Length that was expected for this buffer
    value: Buffer // The buffer itself
}

binary.max

Description

The buffer contains more bytes than expected.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Maximum length that was expected for this buffer
    value: Buffer // The buffer itself
}

binary.min

Description

The buffer contains less bytes than expected.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Minimum length that was expected for this buffer
    value: Buffer // The buffer itself
}

boolean.base

Description

The value is either not a boolean or could not be cast to a boolean from one of the truthy or falsy values.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

date.base

Description

The value is either not a date or could not be cast to a date from a string or a number.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

date.greater

Description

The date is over the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: Date, // Maximum date
    value: Date // Input value as Date
}

date.isoDate

Description

The date does not match the ISO 8601 format.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

date.less

Description

The date is under the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: Date, // Minimum date
    value: Date // Input value as Date
}

date.max

Description

The date is over or equal to the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: Date, // Maximum date
    value: Date // Input value as Date
}

date.min

Description

The date is under or equal to the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: Date, // Minimum date
    value: Date // Input value as Date
}

date.ref

Description

A reference was used in one of date.min(), date.max(), date.less() or date.greater() and the value pointed to by that reference in the input is not a valid date.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    ref: Reference, // Reference used
    value: any // Value found using the reference
}

date.strict

Description

Occurs when the input is not a Date type and convert is disabled.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Value
}

date.timestamp.javascript

Description

Failed to be converted from a string or a number to a date as JavaScript timestamp.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

date.timestamp.unix

Description

Failed to be converted from a string or a number to a date as Unix timestamp.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

function.arity

Description

The number of arguments for the function doesn't match the required number.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    n: number // Expected arity
}

function.base

Description

The input is not a function.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

function.class

Description

The input is not a JavaScript class.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

function.maxArity

Description

The number of arguments for the function is over the required number.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    n: number // Maximum expected arity
}

function.minArity

Description

The number of arguments for the function is under the required number.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    n: number // Minimum expected arity
}

function.ref

Description

The function is not a Joi.ref().

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: function // Input value
}

lazy.base

Description

The lazy function is not set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string // Label if defined, otherwise it's the key
}

lazy.schema

Description

The lazy function didn't return a joi schema.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    schema: any // The value return by the generator function
}

number.base

Description

The value is not a number or could not be cast to a number.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

number.greater

Description

The number is lower or equal to the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Minimum value that was expected for this number
    value: number // The number itself
}

number.integer

Description

The number is not a valid integer.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: number // Value that failed, likely a floating number
}

number.less

Description

The number is higher or equal to the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Maximum value that was expected for this number
    value: number // The number itself
}

number.max

Description

The number is higher than the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Maximum value that was expected for this number
    value: number // The number itself
}

number.min

Description

The number is lower than the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Minimum value that was expected for this number
    value: number // The number itself
}

number.multiple

Description

The number could not be divided by the multiple you provided.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    multiple: number, // The number of which the input is supposed to be a multiple of
    value: number // The number itself
}

number.negative

Description

The number was positive.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: number // The number itself
}

number.port

Description

The number didn't look like a port number.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: number // The number itself 
}

number.positive

Description

The number was negative.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: number // The number itself
}

number.precision

Description

The number didn't have the required precision.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // The precision that it should have had
    value: number // The number itself
}

number.ref

Description

A reference was used in one of number.min(), number.max(), number.less(), number.greater(), or number.multiple() and the value pointed to by that reference in the input is not a valid number.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    ref: Reference, // Reference used
    value: any // Value found using the reference
}

number.unsafe

Description

The number is not within the safe range of JavaScript numbers.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

object.allowUnknown

Description

An unexpected property was found in the object.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    child: string, // Property that is unexpected
    value: any // Value of that property
}

object.and

Description

The AND condition between the properties you specified was not satisfied in that object.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    present: Array<string>, // List of properties that are set
    presentWithLabels: Array<string>, // List of labels for the properties that are set
    missing: Array<string>, // List of properties that are not set
    missingWithLabels: Array<string> // List of labels for the properties that are not set
}

object.assert

Description

The schema on an object.assert() failed to validate.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    ref: string, // Dotted path to the property that was checked
    message: string // Custom message or default one
}

object.base

Description

The value is not of object type or could not be cast to an object from a string.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

object.length

Description

The number of keys for this object is not of the expected length.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Number of keys that was expected for this object
    value: object // The object itself
}

object.max

Description

The number of keys for this object is over or equal to the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Maximum number of keys
    value: object // Input value
}

object.min

Description

The number of keys for this object is under or equal to the limit that you set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Minimum number of keys
    value: object // Input value
}

object.missing

Description

The OR or XOR condition between the properties you specified was not satisfied in that object, none of it were set.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    peers: Array<string>, // List of properties were none of it was set
    peersWithLabels: Array<string> // List of labels for the properties were none of it was set
}

object.nand

Description

The NAND condition between the properties you specified was not satisfied in that object.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    main: string, // One of the properties that was present
    mainWithLabel: string, // The label of the `main` property
    peers: Array<string>, // List of the other properties that were present
    peersWithLabels: Array<string> // List of the labels of the other properties that were present
}

object.rename.multiple

Description

Another rename was already done to the same target property.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    from: string, // Origin property name of the rename
    to: string // Target property of the rename
}

object.rename.override

Description

The target property already exists and you disallowed overrides.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    from: string, // Origin property name of the rename
    to: string // Target property of the rename
}

object.rename.regex.multiple

Description

The target property already exists and you disallowed overrides.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    from: Array<string>, // List of property names that matched the regex
    to: string // Target property of the rename
}

object.rename.regex.override

Description

The target property already exists and you disallowed overrides.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    from: Array<string>, // List of property names that matched the regex
    to: string // Target property of the rename
}

object.schema

Description

The object was not a joi schema.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string // Label if defined, otherwise it's the key
}

object.type

Description

The object is not of the type you specified.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    type: string, // Type name the object should have been
    value: object // Input value
}

object.with

Description

Property that should have been present at the same time as another one was missing.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    main: string, // Property that triggered the check
    mainWithLabel: string, // Label of the property that triggered the check
    peer: string, // Property that was missing
    peerWithLabels: string // Label of the other property that was missing
}

object.without

Description

Property that should have been absent at the same time as another one was present.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    main: string, // Property that triggered the check
    mainWithLabel: string, // Label of the property that triggered the check
    peer: string, // Property that was present
    peerWithLabels: string // Label of the other property that was present
}

object.xor

Description

The XOR condition between the properties you specified was not satisfied in that object.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    peers: Array<string>, // List of properties where none of it or too many of it was set
    peersWithLabels: Array<string> // List of labels for the properties where none of it or too many of it was set
}

object.oxor

Description

The optional XOR condition between the properties you specified was not satisfied in that object.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    peers: Array<string>, // List of properties where too many of it was set
    peersWithLabels: Array<string> // List of labels for the properties where too many of it was set
}

string.alphanum

Description

The string doesn't only contain alphanumeric characters.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.base64

Description

The string isn't a valid base64 string.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.base

Description

The input is not a string.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: any // Input value
}

string.creditCard

Description

The string is not a valid credit card number.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.dataUri

Description

The string is not a valid data URI.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.email

Description

The string is not a valid e-mail.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.guid

Description

The string is not a valid GUID.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.hexAlign

Description

The string contains hexadecimal characters but they are not byte-aligned.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.hex

Description

The string is not a valid hexadecimal string.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.hostname

Description

The string is not a valid hostname.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.ipVersion

Description

The string is not a valid IP address considering the provided constraints.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    cidr: string, // CIDR used for the validation
    version: Array<string>, // List of IP version accepted
    value: string // Input value
}

string.ip

Description

The string is not a valid IP address.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    cidr: string, // CIDR used for the validation
    value: string // Input value
}

string.isoDate

Description

The string is not a valid ISO date string.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.length

Description

The string is not of the expected length.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Length that was expected for this string
    encoding: undefined | string, // Encoding specified for the check if any
    value: string // Input value
}

string.lowercase

Description

The string isn't all lower-cased.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.max

Description

The string is larger than expected.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Maximum length that was expected for this string
    encoding: undefined | string, // Encoding specified for the check if any
    value: string // Input value
}

string.min

Description

The string is smaller than expected.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    limit: number, // Minimum length that was expected for this string
    encoding: undefined | string, // Encoding specified for the check if any
    value: string // Input value
}

string.normalize

Description

The string isn't valid in regards of the normalization form expected.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    form: string, // Normalization form that is expected
    value: string // Input value
}

string.ref

Description

A reference was used in one of string.min(), string.max() or string.length() and the value pointed to by that reference in the input is not a valid number for those rules.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    ref: Reference, // Reference used
    value: any // Value found using the reference
}

string.regex.base

Description

The string didn't match the regular expression.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    name: undefined, // Undefined since the regular expression has no name
    pattern: string, // Regular expression
    value: string // Input value
}

string.regex.name

Description

The string didn't match the named regular expression.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    name: string, // Name of the regular expression
    pattern: string, // Regular expression
    value: string // Input value
}

string.regex.invert.base

Description

The string matched the regular expression while it shouldn't.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    name: undefined, // Undefined since the regular expression has no name
    pattern: string, // Regular expression
    value: string // Input value
}

string.regex.invert.name

Description

The string matched the named regular expression while it shouldn't.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    name: string, // Name of the regular expression
    pattern: string, // Regular expression
    value: string // Input value
}

string.token

Description

The string isn't a token.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.trim

Description

The string contains whitespaces around it.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.uppercase

Description

The string isn't all upper-cased.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}

string.uri

Description

The string isn't a valid URI.

Context

{
    key: string, // Last element of the path accessing the value, `undefined` if at the root
    label: string, // Label if defined, otherwise it's the key
    value: string // Input value
}