deepseek-harness/vendor/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

Package	Purpose
cordis	Core context, plugin registry, fiber lifecycle, events, services, and logger.
create-cordis	Interactive project scaffolder.
@cordisjs/plugin-loader	Runtime plugin tree and loader service.
@cordisjs/plugin-include	YAML/JSON config-file include support for the loader.
@cordisjs/plugin-group	Nested plugin groups for loader configs.
@cordisjs/plugin-hmr	Hot module replacement for loader-managed plugins.
@cordisjs/plugin-logger-console	Console exporter for the built-in logger.
@cordisjs/plugin-timer	Disposal-aware timeout, interval, throttle, and debounce helpers.
@cordisjs/utils	Shared utilities used by Cordis 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.