API Reference

The hapi plugin

Registration

Schmervice may be registered multiple times– it should be registered in any plugin that would like to use any of its features. It takes no plugin registration options and is entirely configured per-plugin using server.registerService().

Server decorations

server.registerService(ServiceClass)

Registers a service class ServiceClass with server (which may be a plugin's server or root server). It also accepts an array of service classes. Services are instanced immediately when they are registered, with server and corresponding plugin options passed to the constructor (i.e. new ServiceClass(server, options)). Note that each class must have a name (e.g. class MyServiceName {}) and that service names must be unique across the entire hapi server.

server.services([all])

Returns an object containing each service instance keyed by their instance names (if the class name was pascal-cased MyServiceName then the instance name is camel-cased myServiceName). The services that are available on this object are only those registered by server or any plugins for which server is an ancestor (e.g. if server has registered a plugin that registers services). When all is passed as true then every service registered with the hapi server– across all plugins– will be returned.

Request decorations

request.services([all])

See server.services(), where server is the one in which the request's route was declared (i.e. based upon request.route.realm).

Response toolkit decorations

h.services([all])

See server.services(), where server is the one in which the corresponding route or server extension was declared (i.e. based upon h.realm).

Schmervice.Service

This class is intended to be used as a base class for services registered with schmervice. However, it is completely reasonable to use this class independently of the schmervice plugin if desired.

new Service(server, options)

Constructor to create a new service instance. server should be a hapi plugin's server or root server, and options should be the corresponding plugin options. This is intended to mirror a plugin's registration function register(server, options). Note: creating a service instance may have side-effects on the server, e.g. adding server extensions– keep reading for details.

service.server

The server passed to the constructor. Should be a hapi plugin's server or root server.

service.options

The hapi plugin options passed to the constructor.

service.context

The context of service.server set using server.bind(). Will be null if no context has been set. This is implemented lazily as a getter based upon service.server so that services can be part of the context without introducing any circular dependencies between the two.

async service.initialize()

This is not implemented on the base service class, but when it is implemented by an extending class then it will be called during server initialization (via onPreStart server extension added when the service is instanced).

async service.teardown()

This is not implemented on the base service class, but when it is implemented by an extending class then it will be called during server stop (via onPostStop server extension added when the service is instanced).

service.caching(options)

Configures caching for the service's methods, and may be called once. The options argument should be an object where each key is the name of one of the service's methods, and each corresponding value is either,

• An object { cache, generateKey } as detailed in the server method options documentation.
• An object containing the cache options as detailed in the server method options documentation.

Note that behind the scenes an actual server method will be created on service.server and will replace the respective method on the service instance, which means that any service method configured for caching must be called asynchronously even if its original implementation is synchronous. In order to configure caching, the service class also must have a name, e.g. class MyServiceName extends Schmervice.Service {}.

Service.caching

This is not set on the base service class, but when an extending class has a static caching property (or getter) then its value will be used used to configure service method caching (via service.caching() when the service is instanced).