@deepseek-ai/cordis

Cordis

Cordis is a TypeScript plugin framework for applications that need explicit dependency injection, scoped services, lifecycle-managed cleanup, and optional configuration-driven loading. The core package is published as cordis; the official packages in this repository add a loader, config-file includes, HMR, console logging, timers, and project scaffolding.

Install

yarn add cordis

Cordis is ESM-first. The repository is tested on current Node releases, and the scaffolder requires Node 22 or newer.

Quick Start

import { Context, Service } from 'cordis'

declare module 'cordis' {
  interface Context {
    counter: Counter
  }

  interface Events {
    'app/ready'(message: string): void
  }
}

class Counter extends Service {
  value = 0

  constructor(ctx: Context) {
    super(ctx, 'counter')
  }

  next() {
    return ++this.value
  }
}

const greeter = Object.assign((ctx: Context) => {
  ctx.on('app/ready', (message) => {
    ctx.logger.info('%s #%d', message, ctx.counter.next())
  })
}, {
  inject: ['counter'],
})

const root = new Context()
await root.plugin(Counter)
await root.plugin(greeter)

root.emit('app/ready', 'started')
await root.fiber.dispose()

The important pieces are:

• new Context() creates the root dependency container.
• ctx.plugin() starts a plugin and returns a Fiber.
• inject tells Cordis which services must exist before the plugin runs.
• Effects, event listeners, and services are removed when their owning fiber is disposed.

Documentation

• Tutorial: build a plugin
• Guide: plugin lifecycle
• Guide: loader configuration
• API reference

Packages

Development

yarn install
yarn build
yarn test
yarn lint

The monorepo uses Yakumo to build and test all packages. Most examples in the docs use public APIs from cordis; loader examples additionally use @cordisjs/plugin-loader and @cordisjs/plugin-include.