Pigly
unobtrusive, manually configured, dependency-injection for javascript/typescript
Philosophy
don't pollute the code with DI concerns
pigly is a simple helper to manually configure a DI container to bind symbols to providers. It explicitly avoids decorators, or any other changes to existing code, and on its own doesn't require any other dependency / compilation-step to work. However, when combined with the typescript transformer @pigly/transformer
we can reduce the amount of boiler-plate and simply describe the bindings as:
let kernel = new Kernel();
kernel.bind(toSelf(Foo));
kernel.bind(toSelf(Bar));
kernel.bind<IFoo>(to<Foo>());
kernel.bind<IBar>(to<Bar>());
let foo = kernel.get<IFoo>();
Planned features
- Scoping
- Better inferring of constructors
Native Usage
native usage relates to using this package directly without any typescript transformer.
Its pretty simple: create a kernel, create symbol-to-provider bindings, then get the resolved result with get(symbol)
import { Kernel } from 'pigly';
let kernel = new Kernel();
kernel.bind(Symbol.for("Foo"), (ctx)=>{ return "foo" });
let foo = kernel.get(Symbol.for("Foo"));
.bind(symbol, provider)
bind links a specific symbol to a provider of the form (context)=>value;
kernel.bind(A, _=>{ return "hello world" })
.get(symbol)
resolve all the bindings for a symbol and return the first one
const A = Symbol.for("A")
kernel.bind(A, _=> "hello");
kernel.bind(A, _=> " world");
let result = kernel.get(A); // "hello";
.getAll(symbol)
resolve all the bindings for a symbol and return all of the results.
const A = Symbol.for("A")
kernel.bind(A, _=> "hello");
kernel.bind(A, _=> " world");
let results = kernel.getAll(A); // ["hello", " world"];
Providers
to(symbol)
used to redirect a binding to and resolve it through a different symbol.
const A = Symbol.for("A")
const B = Symbol.for("B")
kernel.bind(A, to(B));
kernel.bind(B, _ => "hello world");
toAll(symbol)
used to resolve a symbol to all its bindings
const A = Symbol.for("A")
const B = Symbol.for("A");
kernel.bind(A, _ => "hello");
kernel.bind(A, _ => "world");
kernel.bind(B, toAll(A));
kernel.get(B); // ["hello", "world"]
toClass(Ctor, ...providers)
used to provide an instantiation of a class. first parameter should be the class constructor and then it takes a list of providers that will be used, in the given order, to resolve the constructor arguments.
class Foo{
constructor(public message: string)
}
const A = Symbol.for("A")
const B = Symbol.for("B")
kernel.bind(B, _=>"hello world");
kernel.bind(A, toClass(Foo, to(B)))
toConst(value)
a more explicit way to provide a constant
kernel.bind(B, toConst("hello world"));
asSingleton(provider)
used to cache the output of the given provider so that subsequent requests will return the same result.
const A = Symbol.for("A");
const B = Symbol.for("B");
kernel.bind(A, toClass(Foo));
kernel.bind(B, asSingleton(to(A)));
when(predicate, provider)
used to predicate a provider for some condition. any provider that explicitly returns undefined
is ignored
const A = Symbol.for("A");
const B = Symbol.for("B");
const C = Symbol.for("C");
kernel.bind(A, toClass(Foo, to(C) ));
kernel.bind(B, toClass(Foo, to(C) ));
kernel.bind(C, when(x=>x.parent.target == A, toConst("a")));
kernel.bind(C, when(x=>x.parent.target == B, toConst("b")));
Predicates
injectedInto(symbol)
returns true if ctx.parent.target == symbol
const A = Symbol.for("A");
const B = Symbol.for("B");
const C = Symbol.for("C");
kernel.bind(A, toClass(Foo, to(C) ));
kernel.bind(B, toClass(Foo, to(C) ));
kernel.bind(C, when(injectedInto(A), toConst("a")));
kernel.bind(C, when(injectedInto(B), toConst("b")));
hasAncestor(symbol)
returns true if an request ancestor is equal to the symbol.
const A = Symbol.for("A");
const B = Symbol.for("B");
const C = Symbol.for("C");
kernel.bind(A, when(hasAncestor(C), toConst("foo")));
kernel.bind(A, toConst("bar")));
kernel.bind(B, to(A));
kernel.bind(C, to(B));
let c = kernel.get(C); // "foo"
let b = kernel.get(B); // "bar"
Transformer Usage
with '@pigly/transformer' installed (see https://github.com/pigly-di/pigly/tree/develop/packages/pigly-transformerr) you are able to omit manually creating a symbol. Currently
.bind<T>(provider)
.get<T>()
to<T>()
toAll<T>()
toSelf<T>(Class)
injectedInto<T>()
hasAncestor<T>()
Inject<T>()
are supported.
Example
class Foo implements IFoo{
constructor(public name: string){}
}
let kernel = new Kernel();
kernel.bind(toSelf(Foo));
kernel.bind<string>(
when(injectedInto<Foo>(
toConst("joe")));
kernel.bind<IFoo>(to<Foo>());
let foo = kernel.get<IFoo>();
toSelf(Class)
attempts to infer the constructor arguments and generate the providers needed to initialise the class. It can only do so if the constructor arguments are simple. Currently only supports the first constructor.
kernel.bind(toSelf(Foo));
is equivalent to
kernel.bind(toClass(Foo, to<IBar>, to...
SymbolFor()
calls to SymbolFor() get replaced with symbol.for("<T>")
through @pigly/transformer
and can be used if you want to be closer to the native usage i.e.
let kernel = new Kernel();
const $IFoo = SymbolFor<IFoo>();
const $IBar = SymbolFor<IBar>();
kernel.bind<IFoo>($IFoo, toClass(Foo, to<IBar>($IBar)));
kernel.bind<IBar>($IBar, toClass(Bar));
let foo = kernel.get<IFoo>($IFoo);
The current approach in the transformer, to make the type's symbol, is to use the imported name directly i.e. SymbolFor<IFoo>()
is converted to Symbol.for("IFoo")
. The intention here is to give most flexibility and consistently in how the Symbols are created, especially if you want to configure a container across multiple independently-compiled libraries, or when using the transformer in a "transform only" build stage, as is typically the case with Webpack and Vue. The downside is that you must be consistent with type names, avoid renaming during imports and do not implement two or more interfaces with the exact same identifier-name.
License
MIT
Credits
"pig" licensed under CC from Noun Project, Created by habione 404, FR
@pigly/transformer was derived from https://github.com/YePpHa/ts-di-transformer (MIT)