@daisugi/kado

This project is part of the @daisugi monorepo.

Kado is a minimal and unobtrusive inversion of control (IoC) container.

---

🌟 Features

• 💡 Minimal size overhead (see details)
• ⚡️ Written in TypeScript
• 📦 Uses only trusted dependencies
• 🔨 Powerful and agnostic to your code
• 🧪 Well-tested
• 🤝 Used in production
• 🔀 Supports both ES Modules and CommonJS

---

📦 Installation

Using npm:

npm install @daisugi/kado

Using pnpm:

pnpm install @daisugi/kado

🔝 Back to top

---

🚀 Usage

import { Kado } from '@daisugi/kado';

const { container } = new Kado();

class Foo {
  constructor(bar) {
    this.bar = bar;
  }
}

class Bar {}

container.register([
  { token: 'Foo', useClass: Foo, params: ['Bar'] },
  { token: 'Bar', useClass: Bar }
]);

const foo = await container.resolve('Foo');

🔝 Back to top

---

📖 Table of Contents

• @daisugi/kado
  • 🌟 Features
  • 📦 Installation
  • 🚀 Usage
  • 📖 Table of Contents
  • 🎯 Motivation
    • ✅ Key Requirements
  • 📜 API
    • #register(manifestItems)
      • Example:
    • #resolve(token)
      • Example:
    • #get(token)
      • Example:
    • token
    • useClass
      • Example:
    • useValue
      • Example:
    • useFnByContainer
      • Example:
    • useFn
      • Example:
    • scope
      • Example:
    • meta
      • Example:
    • params
      • Example:
    • #list()
      • Example:
    • Kado.value
      • Example:
    • Kado.map
      • Example:
    • Kado.flatMap
      • Example:
  • 🔷 TypeScript Support
    • Example:
  • 🎯 Goal
  • 🌸 Etymology
  • 🌍 Other Projects
  • 📜 License

🔝 Back to top

---

🎯 Motivation

Kado was created to address limitations found in other IoC libraries. If these requirements align with your needs, Kado may be a good fit. Otherwise, alternatives like di-ninja or tsyringe might be worth exploring.

✅ Key Requirements

• Allows multiple container instances without global state.
• Decouples dependency injection (DI) configuration from base code.
• Supports easy dependency decoration (useful for telemetry, debugging, etc.).
• Avoids annotation-based decorators (see style guide).
• Works with pure JavaScript (does not require TypeScript).
• Keeps the API simple yet powerful.

🔝 Back to top

---

📜 API

#register(manifestItems)

Registers dependencies in the container.

Example:

container.register([{ token: 'Foo' }]);

---

#resolve(token)

Resolves a registered dependency.

Example:

const foo = await container.resolve('Foo');

---

#get(token)

Retrieves a registered manifest item by token.

Example:

const manifestItem = container.get('Foo');

---

token

A unique identifier for registered dependencies.

---

useClass

Defines a class as a dependency.

Example:

container.register([
  { token: 'Foo', useClass: Foo, params: ['Bar'] },
  { token: 'Bar', useClass: Bar }
]);

---

useValue

Registers a constant value.

Example:

container.register([{ token: 'foo', useValue: 'text' }]);

---

useFnByContainer

Passes the container to a factory function.

Example:

function bar(c) {
  return c.resolve('Foo');
}

container.register([
  { token: 'Foo', useClass: Foo },
  { token: 'bar', useFnByContainer: bar }
]);

---

useFn

Passes specified parameters to a factory function.

Example:

function bar(foo) {
  return foo;
}

container.register([
  { token: 'Foo', useClass: Foo },
  { token: 'bar', useFn: bar, params: ['Foo'] }
]);

---

scope

Defines the lifecycle of dependencies.

• Singleton (default) - Reuses the same instance.
• Transient - Creates a new instance each time.

Example:

container.register([
  { token: 'Foo', useClass: Foo, scope: 'Transient' }
]);

---

meta

Stores arbitrary metadata.

Example:

container.register([{ token: 'Foo', meta: { isFoo: true } }]);

---

params

Specifies constructor arguments.

Example:

container.register([
  { token: 'Foo', useClass: Foo, params: [{ useValue: 'text' }] }
]);

---

#list()

Returns a list of registered dependencies.

Example:

const manifestItems = container.list();

---

Kado.value

Helper for injecting values.

Example:

container.register([
  { token: 'Foo', useClass: Foo, params: [Kado.value('text')] }
]);

---

Kado.map

Helper for resolving arrays.

Example:

container.register([
  { token: 'bar', useValue: 'text' },
  { token: 'Foo', useClass: Foo, params: [Kado.map(['bar'])] }
]);

---

Kado.flatMap

Similar to Kado.map, but flattens the result.

Example:

container.register([
  { token: 'bar', useValue: ['text'] },
  { token: 'Foo', useClass: Foo, params: [Kado.flatMap(['bar'])] }
]);

🔝 Back to top

---

🔷 TypeScript Support

Kado is fully written in TypeScript.

Example:

import {
  Kado,
  type KadoManifestItem,
  type KadoContainer,
  type KadoToken,
  type KadoScope,
} from '@daisugi/kado';

const { container } = new Kado();

class Foo {}

const myContainer: KadoContainer = container;
const token: KadoToken = 'Foo';
const scope: KadoScope = Kado.scope.Transient;
const manifestItems: KadoManifestItem[] = [
  {
    token,
    useClass: Foo,
    scope,
  }
];

myContainer.register(manifestItems);

const foo = await myContainer.resolve<Foo>('Foo');

🔝 Back to top

---

🎯 Goal

Kado aims to provide a simple yet effective IoC solution with minimal overhead.

🔝 Back to top

---

🌸 Etymology

Kado (華道) is the Japanese art of flower arrangement, emphasizing form, lines, and balance—similar to how Kado structures dependencies.

🔝 Back to top

---

🌍 Other Projects

Explore the @daisugi ecosystem.

🔝 Back to top

---

📜 License

MIT

🔝 Back to top