Intuitive Dependency Injection (DI) library for Node.js, written in JavaScript and weighing less than 10 KB. Ironically, Cerise does not depend on any package.
API documentation -- Examples -- FAQ
Install with npm or yarn
$ npm install cerise
$ yarn add ceriseBoth CommonJS and ES modules builds are included; the latter will be automatically selected if your build system supports it.
Using Cerise is dead simple. There are two concepts you'll need to understand first: containers and factories.
A container (also known as an injector) is a master object that knows how to create services, thanks to factories.
const { createContainer, constant, factory, service } = require('cerise');
// Create a container and immediately register a factory
// for the `name` service.
const container = createContainer({
package_name: constant('cerise'),
});
// You can also register a service for an existing container.
container.register('package_name', constant('cerise'));
// You can retrieve services using either container as a
// function, or its `proxy` property.
assert('cerise' === container('package_name'));
assert('cerise' === container.proxy.package_name);There are multiple ways to declare a service: using the constant, factory and service helpers.
When using constant you cannot depend on an other service. You can register any value: a number, string, function, etc.
container.register('base_url', constant('https://npmjs.com'));
container.register('concat', constant((...args) => args.join('')));
assert('string' === typeof container('base_url'));
assert('function' === typeof container('concat'));If you need to depend on an other service, use a factory. factory takes a function that will be passed container.proxy (which can be destructured to access other services) and returns a service.
container.register(
'package_url',
factory(proxy => {
return proxy.concat(proxy.base_url, '/', proxy.package_name);
}),
);
// Using destructuring
container.register(
'package_url',
factory(({ concat, base_url: baseUrl, package_name: packageName }) => {
return concat(baseUrl, '/', packageName);
}),
);
// Alternatively, call the proxy as a function
container.register(
'package_url',
factory(inject => {
return inject('concat')(inject('base_url'), '/', inject('package_name'));
}),
);
assert('https://npmjs.com/cerise' === container('package_url'));You'll notice that constant(x) is equivalent to factory(() => x): it's just sugar.
Lastly, service is passed a class and will return an instance on retrieval. Use it if you're more familiar with OOP.
class PackageUrl {
constructor({ concat, base_url: baseUrl }) {
this._concat = concat;
this._baseUrl = baseUrl;
}
get(packageName) {
return this._concat(this._baseUrl, '/', packageName);
}
}
container.register('package_url', service(PackageUrl));
assert('https://npmjs.com/cerise' === container('package_url').get('cerise'));Once again, it's just sugar: service(T) is equivalent to factory(proxy => new T(proxy)).
Oftentimes you'll want to create a scope from a container. Scopes inherit their parent and their registered service, but can also have their own service. For instance, if you're using Express, you might want to have a master container to store your database connexion, and another container for request-specific data.
const express = require('express');
const { Database } = require('sqlite3');
const { createContainer, constant } = require('cerise');
const app = express();
const container = createContainer({
db: constant(new Database(':memory:')),
});
// For each request, create a scope and fetch session data.
app.use((req, res, next) => {
const id = req.get('x-session-id');
const db = container('db');
req.scope = container.scope();
db.get('select * from sessions where id = ?', [id], (err, session) => {
// Only alter the request scope, not the parent container
req.scope.register('session', constant(session));
next();
});
});
// Session data is available on child scope.
app.get('/session', (req, res) => {
res.json(req.scope('session'));
});
// Parent container services are also available on child scope.
app.get('/time', (req, res) => {
const db = req.scope('db');
db.get('select current_timestamp as time', (err, { time }) => {
res.json({ time });
});
});By default (except for constant) the factory will be called each time you wish to retrieve a value from a factory.
// Each resolution will result in a new Thing instance being created.
container.register('thing', service(class Thing {}));
const foo = container('thing');
const bar = container('thing');
assert(foo !== bar);You may however wish to specify a lifetime to your factory in order to cache its result.
// Now the first instance will be cached and returned each time.
container.register('thing', service(class Thing {}).singleton());
const foo = container('thing');
const bar = container('thing');
assert(foo === bar);Singletons only make sense on the root container; if you wish to cache a service for scopes you will want to use the scoped lifetime qualifier:
const winston = require('winston');
container.register(
'logger',
constant(
winston.createLogger({
transports: winston.transports.Console(),
}),
),
);
// Create a scope on every request
app.use((req, res, next) => {
req.scope = container.scope();
next();
});
// Register a *scoped* logger (with request id metadata)
app.use((req, res, next) => {
req.scope.register(
'reqlog',
factory(({ logger }) =>
logger.child({ requestId: req.get('x-request-id') }),
).scoped(),
);
next();
});
// Logging middleware
app.use((req, res, next) => {
const start = Date.now();
const logger = req.scope('reqlog');
req.on('finish', () => {
const elapsed = Date.now() - start;
logger.info('[%s] %s %s', elapsed, req.method, req.path);
});
next();
});Root containers' state can be saved and restored which can be useful for testing. For instance, in Mocha's beforeEach and afterEach hooks:
describe('My API', () => {
beforeEach(() => container.save());
afterEach(() => container.restore());
it('...', () => {
// package_url service will be 'nope' but only for this particular test
container.register('package_url', constant('nope'));
});
});Middlewares: Cerise provides middlewares for Express and Koa.
See the API documentation.
Controllers: since calling req.scope gets old really fast, Cerise also provides a controller helper -- with an async error handler for convenience. Pass it a callback, and it will get called with req.scope.proxy, req, res and next.
See the API documentation.
You can register a service with the same name:
const parent = createContainer();
parent.register('scopeName', constant('parent'));
const child = parent.scope();
child.register('scopeName', constant('child'));
assert('parent' === parent('scopeName'));
assert('child' === child('scopeName'));Yes, but you cannot depend directly on the parent service.
parent.register('breadcrumb', constant('/'));
// This will break: `breadcrumb` on the child cannot depend on `breadcrumb`.
child.register(
'breadcrumb',
factory(({ breadcrumb }) => breadcrumb + 'child/'),
);
// Workaround #1: access parent scope directly
child.register('breadcrumb', factory(() => parent('breadcrumb') + 'child/'));
// Workaround #2 (preferred): register the parent as a child service
child.register('$parent', constant(parent.scope));
child.register(
'breadcrumb',
factory(({ $parent: { breadcrumb } }) => breadcrumb + 'child/'),
);Head over to the examples directory for in-depth examples.
Constructive feedback is always welcome! Feel free to create issues if you have any question, suggestion or bug reports. A pull request is also always appreciated.
Clone this repository, run npm install or yarn to install the development dependencies, launch npm test -- -w or yarn test -w and start hacking!
Before you submit your pull request, please make sur you've run Prettier (npm run lint or yarn lint) and that your test coverage is at 100% (npm run coverage or yarn coverage).