Contextizer is a transient context injection system. Contextizer simplifies complex multi-stage, pipeline, and/or promise-based code, and makes unit testing a breeze. It performs a role similar to Express's middleware system, but in a declarative dependency-injection-like style.
Inputs are what make Contextizer different from a normal dependency injection system. While normal dependency injection systems are made to initialize a program, Contextizer is designed to be used with varying inputs many times during a program's runtime.
To install to your project, use npm install --save contextizer
.
Below is a contrived of a simple context. It has an input value a
, some goals
that calculate information about a
and a constant b
, and a final goal that
prints out the information.
const Contextizer = require('contextizer');
let context = new Contextizer();
context.register('a').asInput();
context.register('b').asConstant(5);
context.register('sum').asFunction({
deps: [ 'a', 'b' ], // dependencies.
func({ a, b }) {
return a + b;
}
});
context.register('product').asFunction({
deps: [ 'a', 'b' ],
func({ a, b }) {
return a * b;
}
});
context.register('info').asFunction({
deps: [ 'sum', 'product' ],
func({ sum, product }) {
console.log(`The sum of a and b is ${sum}.`);
console.log(`The product of a and b is ${product}.`);
}
});
// Execute 'info' with input a = 4.
context.execute('info', { a: 4 });
// "The sum of a and b is 9."
// "The product of a and b is 20."
This example shows all three types of objects that can be registered.
Inputs are what makes Contextizer different from dependency injection. Inputs are not defined at registration time. Instead, they are passed in at every execution.
context.register('inputName').asInput();
Constants are constant values that do not change across multiple executions. Constants may be values or promises.
// Register value.
context.register('pi').asConstant(Math.PI);
// Register promise.
const req = require('request-promise-native'); // https://github.com/request/request-promise-native
context.register('robots').asConstant(req('https://www.google.com/robots.txt'));
Functions are where the good stuff happens. Functions can depend on inputs, constants, or other functions.
The .asFunction(arg)
method takes in a single arg
object. The object has the following properties:
deps
(REQUIRED) - List of dependencies (string array).func
(REQUIRED) - The function. Dependencies are passed in as a single argument object, so using the es6 destructuring assigment syntax is recommended. This may return a value or a promise.cleanup
(optional) - A function that is called after the execution completes, in order to clean up resources. This callback receives the same argument object asfunc
with an additional$value
property for the object returned byfunc
. This may be called even iffunc
hasn't been, due to upstream thrown exceptions. Note that this may not execute immediately so it is not reliable to changeparams
here.cached
(optional, default false) - Boolean. If true, this function will only be executed once, then the value will be saved permanently. Use with care.params
(optional) - Object, for holding state object. These parameters will always be passed in tofunc
so they can be used to hold state across calls.
context.register('sum').asFunction({
deps: [ 'a', 'b' ], // Dependencies, registration not shown in this example.
func({ a, b }) {
return a + b;
}
});
// Fibonacci sequence using params.
context.register('fib').asFunction({
deps: [], // No dependencies.
func({ vals }) { // `vals` from params.
vals.push(vals[0] + vals[1]);
return vals.shift();
},
params: {
vals: [ 1, 1 ]
}
});
For organizational purposes, objects can be registered in nested namespaces. Think of this like Java packages.
When resolving dependencies, Contextizer will start in the current namespace and move up to the global namespace. Alternatively, absolute paths can be used.
A dot prefix can be used to make a dependency path absolute.
context.register('value').asConstant(10);
context.register('package.value').asConstant(20);
context.register('package.func').asFunction({
deps: [ 'value' ],
func({ value }) {
// value === 20 because `func` is in the same namespace as `package.value`.
}
});
context.register('package.func2').asFunction({
deps: [ '.value' ],
func({ '.value': value }) {
// value === 10 because '.value' is considered an absolute path.
}
});