Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
316 lines (226 sloc) 8.95 KB

Cerise

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

Installation

Install with npm or yarn

$ npm install cerise
$ yarn add cerise

Both CommonJS and ES modules builds are included; the latter will be automatically selected if your build system supports it.

Usage

Using Cerise is dead simple. There are two concepts you'll need to understand first: containers and factories.

createContainer

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.

constant

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'));

factory

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.

service

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)).

Scopes

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 });
  });
});

Lifetimes

default lifetime

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);

singletons

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);

scoped

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();
});

Saving and restoring state

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'));
  });
});

Utils

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.

FAQ

How to overwrite a parent service in a scope?

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'));

Can a child scope service depend on a parent scope service of the same name?

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/'),
);

Examples

Head over to the examples directory for in-depth examples.

Contributing

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).

You can’t perform that action at this time.