knifecycle

knifecycle

Manage your NodeJS processes's lifecycle.

Most (maybe all) applications rely on two kinds of dependencies.

The code dependencies are fully covered by require/system modules in a testable manner (with mockery or System directly). There is no need for another dependency management system if those libraries are pure functions (involve no global states at all).

Unfortunately, applications often rely on global states where the JavaScript module system shows its limits. This is where knifecycle enters the game.

It is largely inspired by the Angular service system except it should not provide code but access to global states (time, filesystem, db). It also have an important additional feature to shutdown processes which is really useful for back-end servers and doesn't exists in Angular.

You may want to look at the architecture notes to better handle the reasonning behind knifecycle and its implementation.

At this point you may think that a DI system is useless. My advice is that it depends. But at least, you should not make a definitive choice and allow both approaches. See this Stack Overflow anser for more context about this statement.

Features

• services management: start services taking their dependencies in count and shut them down the same way for graceful exits (namely dependency injection with inverted control);
• singleton: maintain singleton services across several running execution silos.
• easy end to end testing: just replace your services per your own mocks and stubs while ensuring your application integrity between testing and production;
• isolation: isolate processing in a clean manner, per concerns;
• functional programming ready: encapsulate global states allowing the rest of your application to be purely functional;
• no circular dependencies for services: while circular dependencies are not a problem within purely functional libraries (require allows it), it may be harmful for your services, knifecycle impeach that while providing an $injector service à la Angular to allow accessing existing services references if you really need to;
• generate Mermaid graphs of the dependency tree;
• build raw initialization modules to avoid embedding Knifecycle in your builds.
• optionally autoload services dependencies with custom logic

Usage

Using knifecycle is all about declaring the services our application needs and running your application over it.

Let's say we are building a CLI script. Here is how we would proceed with Knifecycle:

First, we need to handle a configuration file so we are creating an initializer to instanciate our CONFIG service:

// bin.js
import fs from 'fs';
import Knifecycle, { initializer, constant, inject, name } from 'knifecycle';

// First of all we create a new Knifecycle instance
const $ = new Knifecycle();

// Some of our code with rely on the process environment
// let's inject it as a constant instead of directly
// pickking en vars in `process.env` to make our code
// easily testable
$.register(constant('ENV', process.env));

// Let's do so for CLI args with another constant
// in real world apps we would have create a service
// that would parse args in a complexer way
$.register(constant('ARGS', process.argv));

// We want our CLI tool to rely on some configuration
// Let's build an injectable service initializer that
// reads environment variables via an injected but
// optional `ENV` object
async function initConfig({ ENV = { CONFIG_PATH: '.' } }) {
  return new Promise((resolve, reject) => {
    fs.readFile(ENV.CONFIG_PATH, 'utf-8', (err, data) => {
      if (err) {
        reject(err);
        return;
      }
      try {
        resolve(JSON.parse(data));
      } catch (err) {
        reject(err);
      }
    });
  });
}

// We are using the `initializer` decorator to
// declare our service initializer specificities
// and register it with our Knifecycle instance
$.register(
  initializer(
    {
      // we have to give our final service a name
      // for further use in other services injections
      name: 'CONFIG',
      // we will need an `ENV` variable in the initializer
      // so adding it in the injected dependencies. The `?`
      // sign tells Knifecycle that the ENV dependency
      // is optional
      inject: ['?ENV'],
      // our initializer is simple so we use the `service`
      // type for the initializer which just indicate that
      // the initializer will return a promise of the actual
      // service
      type: 'service',
      // We don't want to read the config file everytime we
      // inject it so declaring it as a singleton
      options: { singleton: true },
    },
    initConfig,
  ),
);

// Our CLI also uses a database so let's write an
// initializer for it:
const initDB = initializer(
  {
    name: 'db',
    // Here we are injecting the previous `CONFIG` service
    // as required so that our DB cannot be connected without
    // having a proper config.
    inject: ['CONFIG', 'DB_URI', '?log'],
    // The initializer type is slightly different. Indeed,
    // we need to manage the database connection errors
    // and wait for it to flush before shutting down the
    // process.
    // A service provider returns a promise of a provider
    // descriptor exposing:
    // - a mandatory `service` property containing the
    // actual service;
    // - an optional `dispose` function allowing to
    // gracefully close the service;
    // - an optional `fatalErrorPromise` property to
    // handle the service unrecoverable failure.
    type: 'provider',
    options: { singleton: true },
  },
  async ({ CONFIG, DB_URI, log }) => {
    const db = await MongoClient.connect(
      DB_URI,
      CONFIG.databaseOptions,
    );
    let fatalErrorPromise = new Promise((resolve, reject) => {
      db.once('error', reject);
    });

    // Logging only if the `log` service is defined
    log && log('info', 'db service initialized!');

    return {
      service: db,
      dispose: db.close.bind(db, true),
      fatalErrorPromise,
    };
  },
);

// Here we are registering our initializer apart to
// be able to reuse it, we also declare the required
// DB_URI constant it needs
$.register(constant('DB_URI', 'posgresql://xxxx').register(initDB));

// Say we need to use two different DB server
// We can reuse our initializer by tweaking
// some of its properties
$.register(constant('DB_URI2', 'posgresql://yyyy'));
$.register(
  // First we remap the injected dependencies. It will
  // take the `DB_URI2` constant and inject it as
  // `DB_URI`
  inject(
    ['CONFIG', 'DB_URI2>DB_URI', '?log'],
    // Then we override its name to make it
    // available as a different service
    name('db2', initDB),
  ),
);

// A lot of NodeJS functions have some side effects
// declaring them as constants allows you to easily
// mock/monitor/patch it. The `common-services` NPM
// module contains a few useful ones
$.register(constant('now', Date.now.bind(Date)))
  .register(constant('log', console.log.bind(console)))
  .register(constant('exit', process.exit.bind(process)));

// Finally, let's declare an `$autoload` service
// to allow us to load only the initializers needed
// to run the given commands
$.register(
  initializer(
    {
      name: '$autoload',
      type: 'service',
      inject: ['CONFIG', 'ARGS'],
      // Note that the auto loader must be a singleton
      options: { singleton: true }
    },
    async ({ CONFIG, ARGS }) => async serviceName => {
      if ('command' !== serviceName) {
        throw new Error(`${serviceName} not supported!`);
      }
      try {
        const path = CONFIG.commands + '/' + ARGS[2];
        return {
          path,
          initializer: require(path).default,
        };
      } catch (err) {
        throw new Error(`Cannot load ${serviceName}: ${ARGS[2]}!`);
      }
    },
  ),
);

// At this point, nothing is running. To instanciate the
// services, we have to create an execution silo using
// them. Note that we required the `$destroy` service
// implicitly created by `knifecycle`
$.run(['command', '$destroy', 'exit', 'log'])
  // Here, command contains the initializer eventually
  // found by automatically loading a NodeJS module
  // in the above `$autoload service`. The db connections
  // we only be instanciated if that command needs it
  .then(async ({ command, $destroy, exit, log }) => {
    try {
      command();

      log('It worked!');
    } catch (err) {
      log('It failed!', err);
    } finally {
      // Here we ensure every db connections are closed
      // properly
      await $destroy().catch(err => {
        console.error('Could not exit gracefully:', err);
        exit(1);
      });
    }
  })
  .catch(err => {
    console.error('Could not launch the app:', err);
    process.exit(1);
  });

Running the following should make the magic happen:

cat "{ commands: './commands'}" > config.json
DEBUG=knifecycle CONFIG_PATH=./config.json node -r @babel/register bin.js mycommand test
// Prints: Could not launch the app: Error: Cannot load command: mycommand!
// (...stack trace)

Or at least, we still have to create commands, let's create the mycommand one:

// commands/mycommand.js
import { initializer } from './dist';

// A simple command that prints the given args
export default initializer(
  {
    name: 'command',
    type: 'service',
    // Here we could have injected whatever we declared
    // in the previous file: db, now, exit...
    inject: ['ARGS', 'log'],
  },
  async ({ ARGS, log }) => {
    return () => log('Command args:', ARGS.slice(2));
  },
);

So now, it works:

DEBUG=knifecycle CONFIG_PATH=./config.json node -r @babel/register bin.js mycommand test
// Prints: Command args: [ 'mycommand', 'test' ]
// It worked!

This is a very simple example but you can find a complexer CLI usage with (metapak)[https://github.com/nfroidure/metapak/blob/master/bin/metapak.js].

Debugging

Simply use the DEBUG environment variable by setting it to 'knifecycle':

DEBUG=knifecycle npm t

The output is very verbose but lead to a deep understanding of mechanisms that take place under the hood.

Plans

The scope of this library won't change. However the plan is:

• improve performances;
• evolve with Node: I may not need to transpile this library at some point.
• track bugs ;).

I'll also share most of my own initializers and their stubs/mocks in order to let you reuse it through your projects easily. Here are the current projects that use this DI lib:

• common-services: contains the services I use the most in my apps.
• swagger-http-router: a complete HTTP router based on OpenAPI definitions with a few useful services compatible with Knifecycle.
• memory-kv-store: a simple in memory key-value store.

API

Classes

Knifecycle

Functions

initInitializerBuilder(services) ⇒ Promise.<function()>

Instantiate the initializer builder service

reuseSpecialProps(from, to, [amend]) ⇒ function

Apply special props to the given function from another one

wrapInitializer(wrapper, baseInitializer) ⇒ function

Allows to wrap an initializer to add extra initialization steps

inject(dependenciesDeclarations, initializer) ⇒ function

Decorator creating a new initializer with different dependencies declarations set to it.

alsoInject(dependenciesDeclarations, initializer) ⇒ function

Decorator creating a new initializer with some more dependencies declarations appended to it.

extra(extraInformations, initializer, [merge]) ⇒ function

Decorator creating a new initializer with some extra informations appended to it. It is just a way for user to store some additional informations but has no interaction with the Knifecycle internals.

options(options, initializer, [merge]) ⇒ function

Decorator to amend an initializer options.

name(name, initializer) ⇒ function

Decorator to set an initializer name.

type(type, initializer) ⇒ function

Decorator to set an initializer type.

initializer(properties, initializer) ⇒ function

Decorator to set an initializer properties.

constant(name, initializer) ⇒ function

Decorator that creates an initializer for a constant value

service(name, initializer, options) ⇒ function

Decorator that creates an initializer for a service

provider(name, provider, options) ⇒ function

Decorator that creates an initializer for a provider

handler(handlerFunction, [dependencies], [extra]) ⇒ function

Shortcut to create an initializer with a simple handler

parseDependencyDeclaration(dependencyDeclaration) ⇒ Object

Explode a dependency declaration an returns its parts.

Knifecycle

Kind: global class

• Knifecycle
  • new Knifecycle()
  • .register(initializer) ⇒ Knifecycle
  • .toMermaidGraph(options) ⇒ String
  • .run(dependenciesDeclarations) ⇒ Promise
  • ._getServiceDescriptor(siloContext, serviceName, options, serviceProvider) ⇒ Promise
  • ._initializeServiceDescriptor(siloContext, serviceName, options) ⇒ Promise
  • ._initializeDependencies(siloContext, serviceName, servicesDeclarations, options) ⇒ Promise

new Knifecycle()

Create a new Knifecycle instance

Returns: Knifecycle - The Knifecycle instance
Example

import Knifecycle from 'knifecycle'

const $ = new Knifecycle();

knifecycle.register(initializer) ⇒ Knifecycle

Register an initializer

Kind: instance method of Knifecycle
Returns: Knifecycle - The Knifecycle instance (for chaining)

Param	Type	Description
initializer	function	An initializer

knifecycle.toMermaidGraph(options) ⇒ String

Outputs a Mermaid compatible dependency graph of the declared services. See Mermaid docs

Kind: instance method of Knifecycle
Returns: String - Returns a string containing the Mermaid dependency graph

Param	Type	Description
options	Object	Options for generating the graph (destructured)
options.shapes	Array.<Object>	Various shapes to apply
options.styles	Array.<Object>	Various styles to apply
options.classes	Object	A hash of various classes contents

Example

import { Knifecycle, inject, constant, service } from 'knifecycle';
import appInitializer from './app';

const $ = new Knifecycle();

$.register(constant('ENV', process.env));
$.register(constant('OS', require('os')));
$.register(service('app', inject(['ENV', 'OS'], appInitializer)));
$.toMermaidGraph();

// returns
graph TD
  app-->ENV
  app-->OS

knifecycle.run(dependenciesDeclarations) ⇒ Promise

Creates a new execution silo

Kind: instance method of Knifecycle
Returns: Promise - Service descriptor promise

Param	Type	Description
dependenciesDeclarations	Array.<String>	Service name.

Example

import Knifecycle from 'knifecycle'

const $ = new Knifecycle();

$.register(constant('ENV', process.env));
$.run(['ENV'])
.then(({ ENV }) => {
 // Here goes your code
})

knifecycle._getServiceDescriptor(siloContext, serviceName, options, serviceProvider) ⇒ Promise

Initialize or return a service descriptor

Kind: instance method of Knifecycle
Returns: Promise - Service dependencies hash promise.

Param	Type	Description
siloContext	Object	Current execution silo context
serviceName	String	Service name.
options	Object	Options for service retrieval
options.injectOnly	Boolean	Flag indicating if existing services only should be used
options.autoloading	Boolean	Flag to indicating $autoload dependencies on the fly loading
serviceProvider	String	Service provider.

knifecycle._initializeServiceDescriptor(siloContext, serviceName, options) ⇒ Promise

Initialize a service descriptor

Kind: instance method of Knifecycle
Returns: Promise - Service dependencies hash promise.

Param	Type	Description
siloContext	Object	Current execution silo context
serviceName	String	Service name.
options	Object	Options for service retrieval
options.injectOnly	Boolean	Flag indicating if existing services only should be used
options.autoloading	Boolean	Flag to indicating $autoload dependendencies on the fly loading.

knifecycle._initializeDependencies(siloContext, serviceName, servicesDeclarations, options) ⇒ Promise

Initialize a service dependencies

Kind: instance method of Knifecycle
Returns: Promise - Service dependencies hash promise.

Param	Type	Description
siloContext	Object	Current execution silo siloContext
serviceName	String	Service name.
servicesDeclarations	String	Dependencies declarations.
options	Object	Options for service retrieval
options.injectOnly	Boolean	Flag indicating if existing services only should be used
options.autoloading	Boolean	Flag to indicating $autoload dependendencies on the fly loading.

initInitializerBuilder(services) ⇒ Promise.<function()>

Instantiate the initializer builder service

Kind: global function
Returns: Promise.<function()> - A promise of the buildInitializer function

Param	Type	Description
services	Object	The services to inject
services.$autoload	Object	The dependencies autoloader

Example

import initInitializerBuilder from 'knifecycle/dist/build';

const buildInitializer = await initInitializerBuilder({
  $autoload: async () => {},
});

initInitializerBuilder~buildInitializer(dependencies) ⇒ Promise.<String>

Create a JavaScript module that initialize a set of dependencies with hardcoded import/awaits.

Kind: inner method of initInitializerBuilder
Returns: Promise.<String> - The JavaScript module content

Param	Type	Description
dependencies	Array.<String>	The main dependencies

Example

import initInitializerBuilder from 'knifecycle/dist/build';

const buildInitializer = await initInitializerBuilder({
  $autoload: async () => {},
});

const content = await buildInitializer(['entryPoint']);

reuseSpecialProps(from, to, [amend]) ⇒ function

Apply special props to the given function from another one

Kind: global function
Returns: function - The newly built function

Param	Type	Default	Description
from	function		The initialization function in which to pick the props
to	function		The initialization function from which to build the new one
[amend]	Object	{}	Some properties to override

wrapInitializer(wrapper, baseInitializer) ⇒ function

Allows to wrap an initializer to add extra initialization steps

Kind: global function
Returns: function - The new initializer

Param	Type	Description
wrapper	function	A function taking dependencies and the base service in arguments
baseInitializer	function	The initializer to decorate

inject(dependenciesDeclarations, initializer) ⇒ function

Decorator creating a new initializer with different dependencies declarations set to it.

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Description
dependenciesDeclarations	Array.<String>	List of dependencies declarations to declare which services the initializer needs to resolve its own service
initializer	function	The initializer to tweak

Example

import { inject, getInstance } from 'knifecycle'
import myServiceInitializer from './service';

getInstance()
.service('myService',
  inject(['ENV'], myServiceInitializer)
);

alsoInject(dependenciesDeclarations, initializer) ⇒ function

Decorator creating a new initializer with some more dependencies declarations appended to it.

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Description
dependenciesDeclarations	Array.<String>	List of dependencies declarations to append
initializer	function	The initializer to tweak

Example

import { alsoInject, getInstance } from 'knifecycle'
import myServiceInitializer from './service';

getInstance()
.service('myService',
  alsoInject(['ENV'], myServiceInitializer)
);

extra(extraInformations, initializer, [merge]) ⇒ function

Decorator creating a new initializer with some extra informations appended to it. It is just a way for user to store some additional informations but has no interaction with the Knifecycle internals.

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Default	Description
extraInformations	Object		An object containing those extra informations.
initializer	function		The initializer to tweak
[merge]	Boolean	false	Whether the extra object should be merged with the existing one or not

Example

import { extra, getInstance } from 'knifecycle'
import myServiceInitializer from './service';

getInstance()
.service('myService',
  extra({ httpHandler: true }, myServiceInitializer)
);

options(options, initializer, [merge]) ⇒ function

Decorator to amend an initializer options.

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Default	Description
options	Object		Options to set to the initializer
options.singleton	Object		Define the initializer service as a singleton (one instance for several runs)
initializer	function		The initializer to tweak
[merge]	function	true	Whether options should be merged or not

Example

import { inject, options, getInstance } from 'knifecycle';
import myServiceInitializer from './service';

getInstance()
.service('myService',
  inject(['ENV'],
    options({ singleton: true}, myServiceInitializer)
  )
);

name(name, initializer) ⇒ function

Decorator to set an initializer name.

Kind: global function
Returns: function - Returns a new initializer with that name set

Param	Type	Description
name	String	The name of the service the initializer resolves to.
initializer	function	The initializer to tweak

Example

import { name, getInstance } from 'knifecycle';
import myServiceInitializer from './service';

getInstance()
.register(name('myService', myServiceInitializer));

type(type, initializer) ⇒ function

Decorator to set an initializer type.

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Description
type	String	The type to set to the initializer.
initializer	function	The initializer to tweak

Example

import { name, type, getInstance } from 'knifecycle';
import myServiceInitializer from './service';

getInstance()
.register(
  type('service',
    name('myService',
      myServiceInitializer
    )
  )
 );

initializer(properties, initializer) ⇒ function

Decorator to set an initializer properties.

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Description
properties	Object	Properties to set to the service.
initializer	function	The initializer to tweak

Example

import { initializer, getInstance } from 'knifecycle';
import myServiceInitializer from './service';

getInstance()
.register(initializer({
  name: 'myService',
  type: 'service',
  inject: ['ENV'],
  options: { singleton: true }
}, myServiceInitializer));

constant(name, initializer) ⇒ function

Decorator that creates an initializer for a constant value

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Description
name	String	The constant's name.
initializer	any	The constant's value

Example

import { Knifecycle, constant, service } from 'knifecycle';

const { printAnswer } = new Knifecycle()
  .register(constant('THE_NUMBER', value))
  .register(constant('log', console.log.bind(console)))
  .register(service(
    'printAnswer',
    async ({ THE_NUMBER, log }) => () => log(THE_NUMBER),
    {
      inject: ['THE_NUMBER', 'log'],
    }
  .run(['printAnswer']);

printAnswer(); // 42

service(name, initializer, options) ⇒ function

Decorator that creates an initializer for a service

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Description
name	String	The service's name.
initializer	function	An initializer returning the service promise
options	Object	Options attached to the initializer

Example

import { Knifecycle, constant, service } from 'knifecycle';

const { printAnswer } = new Knifecycle()
  .register(constant('THE_NUMBER', value))
  .register(constant('log', console.log.bind(console)))
  .register(service(
    'printAnswer',
    async ({ THE_NUMBER, log }) => () => log(THE_NUMBER),
    {
      inject: ['THE_NUMBER', 'log'],
    }
  .run(['printAnswer']);

printAnswer(); // 42

provider(name, provider, options) ⇒ function

Decorator that creates an initializer for a provider

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Description
name	String	The provider's name.
provider	function	A provider returning the service builder promise
options	Object	Options attached to the initializer

Example

import Knifecycle from 'knifecycle'
import fs from 'fs';

const $ = new Knifecycle();

$.register(provider('config', async function configProvider() {
  return new Promise((resolve, reject) {
    fs.readFile('config.js', function(err, data) {
      let config;

      if(err) {
        reject(err);
        return;
      }

      try {
        config = JSON.parse(data.toString);
      } catch (err) {
        reject(err);
        return;
      }

      resolve({
        service: config,
      });
    });
  });
}));

handler(handlerFunction, [dependencies], [extra]) ⇒ function

Shortcut to create an initializer with a simple handler

Kind: global function
Returns: function - Returns a new initializer

Param	Type	Default	Description
handlerFunction	function		The handler function
[dependencies]	Array	[]	The dependencies to inject in it
[extra]	Object		Optional extra data to associate with the handler

Example

import { initializer, getInstance } from 'knifecycle';

getInstance()
.register(handler(getUser, ['db', '?log']));

const QUERY = `SELECT * FROM users WHERE id=$1`
async function getUser({ db }, userId) {
  const [row] = await db.query(QUERY, userId);

  return row;
}

parseDependencyDeclaration(dependencyDeclaration) ⇒ Object

Explode a dependency declaration an returns its parts.

Kind: global function
Returns: Object - The various parts of it

Param	Type	Description
dependencyDeclaration	String	A dependency declaration string

Example

parseDependencyDeclaration('pgsql>db');
// Returns
{
  serviceName: 'pgsql',
  mappedName: 'db',
  optional: false,
}

Authors

• Nicolas Froidure

License

MIT

Changelog

3.1.0 (2018-10-14)

Features

• Knifecycle instance: Add extra errors for bad use (a43aa30)

<a name="3.0.0"></a>