Skip to content

Latest commit

 

History

History
465 lines (365 loc) · 13.9 KB

API.md

File metadata and controls

465 lines (365 loc) · 13.9 KB
Raw

API

Classes

Knifecycle

Functions

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

Instantiate the initializer builder service

initDispose()

Allow to dispose the services of an initialized silo content.

constant(name, value) ⇒ function

Decorator that creates an initializer for a constant value

service(serviceBuilder, [name], [dependencies], [singleton], [extra]) ⇒ function

Decorator that creates an initializer from a service builder

autoService(serviceBuilder) ⇒ function

Decorator that creates an initializer from a service builder by automatically detecting its name and dependencies

provider(providerBuilder, [name], [dependencies], [singleton], [extra]) ⇒ function

Decorator that creates an initializer for a provider builder

autoProvider(providerBuilder) ⇒ function

Decorator that creates an initializer from a provider builder by automatically detecting its name and dependencies

handler(handlerFunction, [name], [dependencies], [options]) ⇒ function

Shortcut to create an initializer with a simple handler

autoHandler(handlerFunction) ⇒ function

Allows to create an initializer with a simple handler automagically

parseDependencyDeclaration(dependencyDeclaration) ⇒ Object

Explode a dependency declaration an returns its parts.

stringifyDependencyDeclaration(dependencyDeclarationParts) ⇒ String

Stringify a dependency declaration from its parts.

Knifecycle

Kind: global class

new Knifecycle(options)

Create a new Knifecycle instance

Returns: Knifecycle - The Knifecycle instance

Param Type Description
options Object An object with options
options.sequential boolean Allows to load dependencies sequentially (usefull for debugging)

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, { constant } from 'knifecycle'

const $ = new Knifecycle();

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

knifecycle.destroy() ⇒ Promise

Destroy the Knifecycle instance

Kind: instance method of Knifecycle
Returns: Promise - Full destruction promise
Example

import Knifecycle, { constant } from 'knifecycle'

const $ = new Knifecycle();

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

   // Finally destroy the instance
   $.destroy()
})

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

initDispose()

Allow to dispose the services of an initialized silo content.

Kind: global function

constant(name, value) ⇒ function

Decorator that creates an initializer for a constant value

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

Param Type Description
name String The constant's name.
value 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(
    async ({ THE_NUMBER, log }) => () => log(THE_NUMBER),
    'printAnswer',
    ['THE_NUMBER', 'log'],
  ))
  .run(['printAnswer']);

printAnswer(); // 42

service(serviceBuilder, [name], [dependencies], [singleton], [extra]) ⇒ function

Decorator that creates an initializer from a service builder

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

Param Type Description
serviceBuilder function An async function to build the service
[name] String The service's name
[dependencies] Array.<String> The service's injected dependencies
[singleton] Boolean Whether the service is a singleton or not
[extra] any Eventual extra information

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(
    async ({ THE_NUMBER, log }) => () => log(THE_NUMBER),
    'printAnswer',
    ['THE_NUMBER', 'log'],
    true
  ))
  .run(['printAnswer']);

printAnswer(); // 42

autoService(serviceBuilder) ⇒ function

Decorator that creates an initializer from a service builder by automatically detecting its name and dependencies

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

Param Type Description
serviceBuilder function An async function to build the service

provider(providerBuilder, [name], [dependencies], [singleton], [extra]) ⇒ function

Decorator that creates an initializer for a provider builder

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

Param Type Description
providerBuilder function An async function to build the service provider
[name] String The service's name
[dependencies] Array.<String> The service's dependencies
[singleton] Boolean Whether the service is a singleton or not
[extra] any Eventual extra information

Example

import Knifecycle, { provider } from 'knifecycle'
import fs from 'fs';

const $ = new Knifecycle();

$.register(provider(configProvider, '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,
      });
    });
  });
}

autoProvider(providerBuilder) ⇒ function

Decorator that creates an initializer from a provider builder by automatically detecting its name and dependencies

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

Param Type Description
providerBuilder function An async function to build the service provider

handler(handlerFunction, [name], [dependencies], [options]) ⇒ 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
[name] String The name of the handler. Default to the DI prop if exists
[dependencies] Array.<String> [] The dependencies to inject in it
[options] Object Options attached to the built initializer

Example

import Knifecycle, { handler } from 'knifecycle';

new Knifecycle()
.register(handler(getUser, '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;
}

autoHandler(handlerFunction) ⇒ function

Allows to create an initializer with a simple handler automagically

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

Param Type Description
handlerFunction function The handler function

Example

import Knifecycle, { autoHandler } from 'knifecycle';

new Knifecycle()
.register(autoHandler(getUser));

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,
}

stringifyDependencyDeclaration(dependencyDeclarationParts) ⇒ String

Stringify a dependency declaration from its parts.

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

Param Type Description
dependencyDeclarationParts Object A dependency declaration string

Example

stringifyDependencyDeclaration({
  serviceName: 'pgsql',
  mappedName: 'db',
  optional: false,
});

// Returns
'pgsql>db'