A minimal application harness that stays out of your way and out of your code.
This is the v2 branch, which has back-compat breaking changes from v1, see billy v1.7.3 for the old version.
$ npm install billy
The primary goal and driving philosophy of Billy is to provide a cohesive and useful set of utilities for building an complex application, without creeping its way into your business logic and domain code.
Billy is not an opinionated framework that permeates all parts of your codebase, but rather the simple scaffolding that allows you to roll your own application architecture stack, your way.
The root of your application is a single instance of the Application class:
const Application = require('billy');
const app = new Application();An application is composed of several services. A service is a class that sets up and starts the various dependencies in your application. Services should be free of all business logic, and should be the only parts of the application that are aware of Billy.
app.service(AppConfigService);
app.service(PostgresDatabaseService);
app.service(SQSQueueService);
app.service(AuthAPIComponent);If a service implements a start() method, it will be called (and await-ed)
when you call app.start() to boot the application.
(async () => {
await app.start();
console.log('all services succesfully instantiated and started -- nice!');
})();All services registered (via Application#service) will be instantiated (with
injected constructors, see below) in the order in which they were
registered. After all services have been successfully (and synchronously)
instantiated, the start method will be called on each one (again, in the
order registered) if implemented. If start returns a Promise, the app will
wait for it to resolve before continuing.
If any service throws during instantiation or during the start method (or
the Promise returned is rejected), then the application will abort its
startup.
Philosophy behind the IoC container
The various
container.register*methods
Overview of
newandcallon the container, and locals
Billy is written to run in modern Javascript environments (ES2017) that support
the CommonJS module system and the latest ES2017 Spec (e.g, Node 7.10+). It
uses async / await from the ES2017 spec, as well as features introduced in
ES2015 (ES6) such as Promise, iterables, and WeakMap.
If you are not on the absolute cutting edge, you'll want to use a transpiled version of the library.
// Transpiled down to ES5 (pre-ES2015 / pre-ES6)
const Application = require('billy/es5');
// Targeting Node v6+
const Application = require('billy/node6');Some notes:
- Even when compiling down to ES5, keep in the mind the code still retains the
CommonJS module syntax (i.e
requirecalls) - There are no polyfills for the new global classes like
Promise,Map,WeakMap. If these are not available in your environment, you will need to include them first before Billy - The
es5target is dependent on a globally-available regenerator polyfill. - For more information on polyfills and regenerator, see the official Babel docs
Root application class.
const app = new Application();Register a service class with the application.
app.service(PostgresDatabaseService);Instantiate and start all services in the order they were registered.
await app.start();Give each service a chance to shut down in reverse order they were started.
await app.stop();Reference to the dependency injection container for the application.
The dependency injection container. There is no need to instantiate this
directly as a reference to the application's container is exposed as a property
on the Application instance:
const container = app.container;Store a simple value in the container. Every time the tag dependency is
resolved, the same value is returned.
app.container.registerValue('config', require('./config.json'));Store a factory function in the container. Every time the tag dependency is
resolved, the factory function will be called with its parameters injected.
app.container.registerFactory('currentTime', () => new Date());Store a class in the container. Every time the tag dependency is resolved, a
fresh instance of the class is instantiated, with its constructor parameters
injected.
app.container.registerClass('logger', ElasticSearchLogger);Store a singleton class in the container. The first time tag dependency
is resolved, the class will be instantiated and cached. Each subsequent
resolution of tag will return the original instance after that.
app.container.registerSingleton('db', PostgresDatabaseDriver);Resolve a dependency from the container via its string tag. Typically this method shouldn't be used directly, but rather rely on automatic injection to get a hold of registered dependencies.
const db = app.container.resolve('db');$ npm test