@daisugi/kado

This project is part of the @daisugi monorepo.

Kado is a minimal and unobtrusive inversion of control container.

🌟 Features

• 💡 Minimum size overhead.
• ⚡️ Written in TypeScript.
• 📦 Only uses trusted dependencies.
• 🔨 Powerful and agnostic to your code.
• 🧪 Well tested.
• 🤝 Is used in production.
• ⚡️ Exports ES Modules as well as CommonJS.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {
6  constructor(bar) {
7    this.bar = bar;
8  }
9}
10
11class Bar {}
12
13container.register([
14  {
15    token: 'Foo',
16    useClass: Foo,
17    params: ['Bar'],
18  },
19  {
20    token: 'Bar',
21    useClass: Bar,
22  },
23]);
24
25const foo = await container.resolve('Foo');

Table of contents

• @daisugi/kado
  • 🌟 Features
  • Usage
  • Table of contents
  • Install
  • Motivation
  • API
    • #register(manifestItems)
      • Usage
    • #resolve(token)
      • Usage
    • #get(token)
      • Usage
    • token
    • useClass
      • Usage
    • useValue
      • Usage
    • useFnByContainer
      • Usage
    • useFn
      • Usage
    • scope
      • Usage
    • meta
      • Usage
    • params
      • Usage
    • #list()
      • Usage
    • Kado.value
      • Usage
    • Kado.map
      • Usage
    • Kado.flatMap
      • Usage
  • TypeScript
  • Goal
  • Etymology
  • Other projects
  • License

Install

Using npm:

1npm install @daisugi/kado

Using yarn:

1yarn add @daisugi/kado

:top: back to top

Motivation

This library is a result of a series of the requirements that either were not met by other libraries of same type, or were partially met, or finally met everything but also brought an overhead not required by the project.

If you feel that any of the following requirements is close to your demand, feel free to use this library, otherwise there are many other good IoC libraries out there such as di-ninja or tsyringe, among many others that you can use.

• ✅ Should allow to create multiple instances of the container, and not share the state globally (useful when multiple packages are using it, or for monorepo).
• ✅ The DI configuration must be abstracted from the base code, and must be able to be easily ported (Composition Root).
• ✅ Dependencies must be able easily decorated (useful to add telemetry, debug ...).
• ✅ Avoid use of decorators by annotations (see style guide).
• ✅ Should work with pure JavaScript (don't depend of any superset like TypeScript).
• ✅ Keep the API simple (singleton, transient, classes, values, factories, and not much more), but with enough pieces to cover the most common use cases.

:top: back to top

API

#register(manifestItems)

Used for registration of manifest items in the container.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5container.register([{ token: 'Foo' }]);

:top: back to top

#resolve(token)

Use this method when you need to resolve the registered dependency.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5container.register([{ token: 'Foo' }]);
6
7const foo = await container.resolve('Foo');

:top: back to top

#get(token)

Returns registered manifest item by token.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {}
6
7container.register([
8  {
9    token: 'Foo',
10    useClass: Foo,
11    scope: 'Transient',
12  },
13]);
14
15const manifestItem = container.get('Foo');

:top: back to top

token

Is the name used to register the dependency, to later be resolved.

:top: back to top

useClass

Can go along with params property, which contains tokens with which the class should be resolved.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {
6  constructor(bar) {
7    this.bar = bar;
8  }
9}
10
11class Bar {}
12
13container.register([
14  {
15    token: 'Foo',
16    useClass: Foo,
17    params: ['Bar'],
18  },
19  {
20    token: 'Bar',
21    useClass: Bar,
22  },
23]);
24
25const foo = await container.resolve('Foo');

:top: back to top

useValue

Useful for storing constants.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5container.register([
6  {
7    token: 'foo',
8    useValue: 'text',
9  },
10]);
11
12const foo = await container.resolve('foo');

:top: back to top

useFnByContainer

Provides container as argument to the factory method.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {}
6
7function bar(c) {
8  return c.resolve('Foo');
9}
10
11container.register([
12  {
13    token: 'Foo',
14    useClass: Foo,
15  },
16  {
17    token: 'bar',
18    useFnByContainer: bar,
19  },
20]);
21
22const foo = await container.resolve('bar');

:top: back to top

useFn

Same as useFnByContainer, except provides params to it, instead of the container.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {}
6
7function bar(foo) {
8  return foo;
9}
10
11container.register([
12  {
13    token: 'Foo',
14    useClass: Foo,
15  },
16  {
17    token: 'bar',
18    useFn: bar,
19    params: ['Foo'],
20  },
21]);
22
23const foo = await container.resolve('bar');

:top: back to top

scope

Scope can be Transient or Singleton, by default it's Singleton. Can be used along with useClass, useFnByContainer and useFn. Having scope as Transient it will create a new instance every time the dependency is resolved, Singleton will reuse the already created instance.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {}
6
7container.register([
8  {
9    token: 'Foo',
10    useClass: Foo,
11    scope: 'Transient',
12  },
13]);
14
15const foo = await container.resolve('Foo');

:top: back to top

meta

Can be used to store arbitrary values.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {}
6
7container.register([
8  {
9    token: 'Foo',
10    meta: {
11      isFoo: true,
12    }
13  },
14]);
15
16const foo = container.get('Foo');
17foo.meta.isFoo; // true

:top: back to top

params

As can be observed in the previous examples the params key can receive an array of tokens, but also you can provide manifest items, you have an example below where we are injecting a text to the Foo class. Also for the convenience Kado provides some helpers Kado.value, Kado.map and Kado.flatMap, behind the scene these helpers are returning a simple manifest items.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {
6  constructor(bar) {
7    this.bar = bar;
8  }
9}
10
11container.register([
12  {
13    token: 'Foo',
14    useClass: Foo,
15    param: [{
16      useValue: 'text',
17    }],
18  },
19]);
20
21const foo = await container.resolve('Foo');
22
23foo.bar; // 'text'

:top: back to top

#list()

Get the list of the registered dependencies.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {}
6
7container.register([
8  {
9    token: 'Foo',
10    useClass: Foo,
11    scope: 'Transient',
12  },
13]);
14
15const manifestItems = container.list();
16
17// Now you can iterate over the manifest items and decorate them.

:top: back to top

Kado.value

Useful when you want to inject a value.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {
6  constructor(bar) {
7    this.bar = bar;
8  }
9}
10
11container.register([
12  {
13    token: 'Foo',
14    useClass: Foo,
15    param: [Kado.value('text')],
16  },
17]);
18
19const foo = await container.resolve('Foo');
20
21foo.bar; // 'text'

:top: back to top

Kado.map

Useful when you want to resolve an array of items.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {
6  constructor(args) {
7    this.bar = args[0];
8  }
9}
10
11container.register([
12  {
13    token: 'bar',
14    useValue: 'text',
15  },
16  {
17    token: 'Foo',
18    useClass: Foo,
19    param: [Kado.map(['bar'])],
20  },
21]);
22
23const foo = await container.resolve('Foo');
24
25foo.bar; // 'text'

:top: back to top

Kado.flatMap

The same as Kado.map but also it flats the array result.

Usage

1import { Kado } from '@daisugi/kado';
2
3const { container } = new Kado();
4
5class Foo {
6  constructor(args) {
7    this.bar = args[0];
8  }
9}
10
11container.register([
12  {
13    token: 'bar',
14    useValue: ['text'],
15  },
16  {
17    token: 'Foo',
18    useClass: Foo,
19    param: [Kado.flatMap(['bar'])],
20  },
21]);
22
23const foo = await container.resolve('Foo');
24
25foo.bar; // 'text'

:top: back to top

TypeScript

The Kado is fully written in TypeScript, therefore you have available some types.

1import {
2  Kado,
3  type KadoManifestItem,
4  type KadoContainer,
5  type KadoToken,
6  type KadoScope,
7} from '@daisugi/kado';
8
9const { container } = new Kado();
10
11class Foo {}
12
13const myContainer: KadoContainer = container;
14const token: KadoToken = 'Foo';
15const scope: KadoScope = Kado.scope.Transient;
16const manifestItems: KadoManifestItem[] = [
17  {
18    token,
19    useClass: Foo,
20    scope,
21  }
22];
23
24myContainer.register(manifestItems);
25
26const foo = await myContainer.resolve<Foo>('Foo');

:top: back to top

Goal

The project aims to provide the basic functionality for IoC. The functionality will be kept simple and will not be overextended.

:top: back to top

Etymology

Kado is a Japanese art that involves an arrangement of a variety of plants. A characteristic of Japanese Kado is an emphasis on shapes and lines, as well as the manner in which the flower is placed into the dish.

:top: back to top

Other projects

Meet the ecosystem

:top: back to top

License

MIT