api.service.RouteParameterTypeRegistry

This service implements a registry of supported parameter types.

Background

Definitions of routes may declare parameters embedded in request paths as supported by 3rd-party library path-to-regexp. By default, those parameters are matching arbitrary strings provided as segments in a request's path.

/api/:model/:id

This example declares a path with three segments. The second segment is a parameter named model. The third one is a parameter named id.

On a client sending a request with a matching path /api/person/john, parameter model is assigned the value person and parameter id is assigned the value john.

In Hitchy, parameters in a defined route may be associated with a type of value that must be met by an incoming request's path for matching that route.

/api/:"model.keyword"/:"id.uuid"

This time, parameter model accepts values of type keyword, only. The value of parameter id must be a properly formatted UUID to match the route. Because of the latter condition, the example request path given above does not match this route anymore.

Typed parameters improve the definition and processing of routes. Think of two controller routes defined like this:

'PUT /api/:model/:id': ( req, res ) => res.text( "replacing" ),
'PUT /api/:model/clean': ( req, res ) => res.text( "cleaning up" ),

The second route is never considered for clean is always used as a possible value of parameter id in first route. This issue is recoverable by properly typing second parameter:

'PUT /api/:model/:"id.uuid"': ( req, res ) => res.text( "replacing" ),
'PUT /api/:model/clean': ( req, res ) => res.text( "cleaning up" ),

This time, a request with path /api/person/clean is not matching first route anymore and thus will be handled by the second route as intended.

Typed parameters must comply with this pattern:

:"name.type"

The colon is mandatory to indicate the beginning of a parameter. The parameter name must be wrapped in quotes to support additional characters such as the period . used to separate the parameter's name from its type. A parameter's case-insensitive type is optionally selected after the parameter's name.

Hitchy's core supports some types of parameters out of the box:

• integer is matching positive or negative integers, only.
• keyword is matching keywords, only.
• number is matching decimal numbers, only.
• uuid is matching representations of UUIDs, only

You may add support for custom parameters using the API of this service e.g. in code setting up your plugin or application.

Static methods

getValidationError()

This method is used to generate a log message on router handling an incoming request that is failing to match a route containing typed parameters. It is invoked with the parameter's type and some value found in the request's path. The returned string is included with the log message to support the debugging of an application.

const cause = api.service.RouteParameterTypeRegistry.getValidationError( "level", value );

register()

This method is adding or replacing support for a named type of parameters. The type's name is provided in first argument. It is case-insensitive. A validation callback for testing some potential parameter value must be provided in second argument. That callback is invoked with a value or an array of values to be tested. It must return true if given value(s) is/are of proper type and false otherwise.

const Levels = [ "free", "starter", "pro", "enterprise" ];

api.service.RouteParameterTypeRegistry.register( "level", value => {
	return Array.isArray( value ) 
        ? value.every( v => Levels.include( v ) ) 
        : Levels.include( value );
} );