wegweiser
v4.2.0
Published
A router for Quinn
Downloads
32
Readme
Wegweiser
Wegweiser {m}, Wegweiser {pl}:
- signpost; direction sign; guide sign [Am.]
- (figurative) guide [e.g. a book]
- a router for Quinn, powered by routington and footnote.
Install
npm install --save wegweiser
Example
import { createRouter, GET, PUT } from 'wegweiser';
const simpleHandler = GET('/my/scope')(req => {
return respond().body('ok');
});
class PretendingItsJava {
@PUT('/user/:username/profile')
async updateProfile(req, { username }) {
const data = await readJson(req);
return respond.json({ ok: true, firstName: data.firstName });
}
}
const objectOrInstance {
@GET('/object/:op')
getObject(req, { op }) { return respond.json({ op }); }
}
const router = // router is a quinn handler: request => response
createRouter(simpleHandler, PretendingItsJava, objectOrInstance);
For decorators,
you'll need babel with --stage 1
.
API
createRouter(...routes)
This is also the default export.
Each argument to this function should be an annotated function, a class with annotated methods, or an object with annoated methods. Both for objects and classes the prototype chain will be scanned. Routes have to be unambiguous. If the same method and path combination is configured twice, creating the router will fail.
The result is a router; a function of form request => result
.
The request
is expected to have two properties:
method: String
: An HTTP method, e.g.'GET'
.url: String
: A url path, e.g.'/foo?a=b'
.
If one of the routes matches, the router will call the route handler
with two arguments: the request
(just passed through) and params
.
params
is an object containing the path parameters.
Example
GET('/users/:id')(f);
createRouter(f)({ method: 'GET', 'url': '/users/robin' });
// Calls `f` with `(request, { id: 'robin' })`.
The return value of the router is whatever the route handler returns,
no changes or assumptions are made by wegweiser
itself.
If no route matches, the router will return undefined
.
router.resolve(req)
Can be used to retrieve the function that would be called for a given request.
It returns either undefined
(if no route matches the request)
or an object with the following properties:
params
: The route parameters.handler
: The request handler, ready to be called withreq
andparams
.
For class method routes, the handler
will have two properties itself:
ctor
: The constructor of the class.key
: The property key of the method to call on the instance.
Example
class MyResource {
constructor(db) { this.db = db; }
@GET('/my/:id')
getById(req, {id}) { return this.db.getById(id); }
}
const router = createRouter(MyResource);
const req = { method: 'GET', url: '/my/foo' };
const {params, handler} = router.resolve(req);
const instance = someDIContainer.construct(handler.ctor);
return instance[handler.key](req, params);
Route(method: String, path: String)
A footnote
annotation decorator that adds metadata to functions or methods
to turn them into valid arguments for createRouter
.
The return value is a decorator function that supports two different call styles:
Route('GET', '/')(f: Function)
: Annotates a function.Route('GET', '/')(prototype, propertyKey, propertyDescriptor)
: Annotates a method.
When a method is annotated, the constructor of the class is tracked. Whenever the route is matched, a new instance of the class will be created and the method will be called on that instance. The arguments the router passes into functions and methods are the same (see `createRouter above).
GET(path: String)
/ POST(path)
/ ...
Route
partially applied with an HTTP verb.
Unless you need to support some very exotic HTTP verbs,
you'll use these instead of Route
directly.