Tianyi Cui
72688a3888
cordis 4.0.0-rc.6, plugin-loader, -include, -group, -timer, -hmr, -logger-console, cosmokit 1.8.1, schemastery 3.18.0 — copied from the cordis-workspace checkout, flattened under vendor/, original npm names, private: true. vendor/README.md is the manifest: upstream repos + commit SHAs, local-modification log, sync procedure. Local modification: hmr's locale YAML imports and .i18n() call removed (avoids a runtime YAML import hook we don't vendor).
102 lines
2.7 KiB
Markdown
102 lines
2.7 KiB
Markdown
# 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
|
|
|
|
```sh
|
|
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
|
|
|
|
```ts
|
|
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](../../docs/tutorials/build-a-plugin.md)
|
|
- [Guide: plugin lifecycle](../../docs/guides/plugin-lifecycle.md)
|
|
- [Guide: loader configuration](../../docs/guides/loader-config.md)
|
|
- [API reference](../../docs/api/core.md)
|
|
|
|
## 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
|
|
|
|
```sh
|
|
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`.
|