@proc7ts/context-builder

IoC Context Builder

This library allows to build an IoC context conforming to @proc7ts/context-values API.

Creating Context

IoC context interface may be any. The only required method is get().

CxBuilder constructor accepts context builder function as its first parameter:

import { CxBuilder } from '@proc7ts/context-builder';
import { CxEntry, cxSingle, CxValues } from '@proc7ts/context-values';

export interface Foo = string;

export const Foo: CxEntry<Foo> = {
  perContext: cxSingle({ byDefault: () => 'default' }),
  toString: () => '[Foo]',
}

// Custom context interface.
export interface MyContext extends CxValues {

  readonly name: string;

  readonly foo: Foo;

}

const cxBuilder = new CxBuilder<MyContext>(get => (/* MyContext */ {
  get,
  name: 'MyContext',
  get foo() {
    return this.get(Foo);
  },
}));

const context: MyContext = cxBuilder.context;

Providing Assets

A provide method of CxBuilder can be used to provide an asset for context entry.

The entry asset is an object implementing CxAsset interface.

The @proc7ts/context-builder contains several asset implementations suitable for most use cases:

• cxAliasAsset() - Asset aliasing other context entry value.
• cxBuildAsset() - Builds asset with the given builder function.
• cxConstAsset() - Constant asset.
• cxTrackAsset() - Tracks for value asset updates.

import { cxAliasAsset, CxBuilder, cxConstAsset } from '@proc7ts/context-builder';
import { CxEntry, cxSingle } from '@proc7ts/context-values';

const Foo: CxEntry<string> = {
  perContext: cxSingle(),
  toString: () => '[Foo]',
};
const Bar: CxEntry<string> = {
  perContext: cxSingle(),
  toString: () => '[Bar]',
};

const cxBuilder = new CxBuilder(get => ({ get }));

cxBuilder.provide(cxConstAsset(Foo, 'foo'));
cxBuilder.provide(cxAliasAsset(Bar, Foo));

cxBuilder.get(Bar); // 'foo'

Context Peers

A context peer provides assets for one or more contexts. When one or more context peers passed to context builder, the assets provided by those peers precede the assets provided by builder.

A CxPeerBuilder class can be used as a context peer. It is similar to CxBuilder, but does not build any context by itself. The CxBuilder extends CxBuilder and can also be used as a peer of another context.

import { cxBuildAsset, CxBuilder, cxConstAsset, CxPeerBuilder } from '@proc7ts/context-builder';
import { CxEntry, cxSingle } from '@proc7ts/context-values';

const cxBaseBuilder = new CxPeerBuilder();

// Derive contexts from common base peer.
const cxBuilder1 = new CxBuilder(get => ({ get }), cxBaseBuilder);
const cxBuilder2 = new CxBuilder(get => ({ get }), cxBaseBuilder);

const BaseEntry: CxEntry<string> = {
  perContext: cxSingle(),
  toString: () => '[BaseEntry]',
};
const DerivedEntry: CxEntry<string> = {
  perContext: cxSingle(),
  toString: () => '[DerivedEntry]',
};

// Provide base peer assets.
cxBaseBuilder.provide(cxConstAsset(BaseEntry, 'initial'));
cxBaseBuilder.provide(cxBuildAsset(DerivedAsset, target => target.get(BaseAsset) + '!'));

// Override base asset in derived context.
cxBuilder2.provide(cxConstAsset(BaseEntry, 'overridden'));

// Derive value from base assets.
cxBuilder1.get(DerivedAsset); // 'initial!'

// Refer overridden asset.
cxBuilder2.get(DerivedAsset); // 'overridden!'