@arki/dot

Compose an app from typed plugins. The compiler checks the wiring. The kernel boots the plugins in declaration order and disposes them in reverse.

A Dot app is a chain of plugins. Each plugin says what it needs, what it provides, and what to do at each of five lifecycle hooks: configure, boot, start, stop and dispose. There is no hidden core: remove every plugin and nothing is left. The plugins are the app.

defineApp('acme')  .use(database)  .use(billing)  .start()
                        │               │
     boot / start:      1st ──────────▶ 2nd
     stop / dispose:    2nd ◀────────── 1st

Install

bun add @arki/dot
# or
npm install @arki/dot

The dot command ships in the same package.

Quick start

import { defineApp, plugin } from '@arki/dot';
import { isFailure } from '@arki/failure';
 
// Stand-ins for your real database and Stripe clients.
type Db = { query(sql: string): Promise<unknown[]>; close(): Promise<void> };
const openDb = async (url = 'memory://'): Promise<Db> => ({ query: async sql => [url, sql], close: async () => {} });
const makeStripeClient = (db: Db) => ({ charge: (cents: number) => db.query(`charge ${cents}`) });
 
const dbPlugin = plugin({
  name: 'database',
  provides: {
    db: () => openDb(process.env.DATABASE_URL), // ← one factory per key; may be async
  },
  async dispose({ db }) {
    await db.close();
  },
});
 
const billingPlugin = plugin({
  name: 'billing',
  needs: { db: dbPlugin.provides.db }, // typed handle — destructure in hooks
  configure(ctx) {
    // Validate config, register schemas, no I/O.
    ctx.registerService('stripe', 'custom');
  },
  provides: {
    stripe: ({ db }) => makeStripeClient(db), // factories see the needs
  },
  async boot({ stripe }) {
    await stripe.charge(0); // side effects only (seed, warm-up). Returns nothing.
  },
  async start({ stripe }) {
    await stripe.charge(0); // begin processing — workers, subscriptions, schedulers.
  },
  async stop({ db }) {
    await db.query('select 1'); // stop processing — drain workers, unsubscribe.
  },
});
 
const app = await defineApp('acme')
  .use(dbPlugin) // providers before consumers — enforced at compile time
  .use(billingPlugin)
  .start();
if (isFailure(app)) throw new Error(app.code);
 
// app.manifest, app.diagnostics — agent-friendly envelopes.
const order = app.manifest.plugins.map(p => p.name).join(' → ');
if (order !== 'database → billing') throw new Error(`plugins boot in declaration order, got ${order}`);
 
await app.stop();
await app.dispose();

There is no registry to configure, no decorators, no reflection. The needs shape is the injection contract; the provides factories are the provision contract; the builder's type-level guard connects the two.

The Quickstart builds a small app step by step, breaks it on purpose, and reads the error with dot explain and dot doctor.

When not to use this

• You need a web server or a router. Dot composes services. Serve HTTP with TanStack Start, Hono or oRPC, and mount the server as a plugin.
• You want plugins loaded from disk or from config. Dot never auto-loads. The app is the .use() chain that the compiler reads.
• The program has one or two services. A function with try/finally is shorter. Dot pays off when several packages bring services with their own setup and teardown.
• You need a scope per request. Dot has one service graph per app. Keep per-request values in your router's context.

Runtime support

The portable entries (@arki/dot, @arki/dot/plugin, @arki/dot/feature, @arki/dot/log, @arki/dot/test-harness) run on Node, Bun, Deno, browsers and Hermes (React Native). The kernel reads process, performance and timers at call time, never at import, and falls back where the runtime has none: hookSignals hooks nothing without a process, and durations use Date.now() without performance.

The adapter entries need more:

bun run test:runtimes boots a small app through the portable API on every leg, from the built dist/.

Public imports

Read Ownership for resource descriptors, children, lazy retries and cancellation.

Failure behaviour

Every managed phase returns typed @arki/failure values. Check isFailure(builder.configure()) before reading the manifest, and inspect awaited boot, start, stop and dispose outcomes. Concrete callback refusals remain inferred; unknown exceptions become canonical UnexpectedDefect values. Static declaration helpers can still throw outside a managed boundary. See Upgrade typed phases for the breaking changes and exact phase outcomes.

Legacy ARKI_DOT_E* IDs remain diagnostic metadata, not top-level failure codes. Kernel-generated defects retain their DotLifecycleError (phase, plugin and original cause) inside UnexpectedDefect.cause. Owned provider/boot task defects retain the original private cause; diagnostics record phase, owner and legacy ID with safe remediation and docs links. Codes are never renumbered or reused (E009 and E010 are retired). FeatureError (E022–E031) and DotManifestError (E032) can still escape unmanaged static declarations; CLI module loading supervises them.

The legacy rows below describe diagnostic IDs and their private cause classes. Match returned failures by their canonical definition; inspect legacy IDs locally in the private cause or in diagnostics.

The dot command returns dot.* failure codes (dot.app_not_found, dot.doctor_failed, ...) in the arki.cli/1 envelope; see the agent guide and The dot command. Exit codes: 0 ok, 1 bug, 2 usage, 3 a returned failure.

Limits

• configure is synchronous. A configure that returns a Promise fails with ARKI_DOT_E001, even when the Promise is already resolved. Do async work in boot or in a provides factory.
• Declaration order is boot order. Nothing sorts the plugins for you. .use(orders).use(database), where orders needs database, is a compile error. With the types erased (plain JavaScript, or Bun running a file without a type check) it is ARKI_DOT_E020 at configure. The Quickstart shows both.
• One copy of each plugin. .use(cache).use(cache) is ARKI_DOT_E011. A second copy needs rename.
• One logging plugin per app. A second one is ARKI_DOT_E018.
• No hook watchdog by default. A hook that never settles hangs the app until you pass hookTimeoutMs. With it, the slow hook fails with ARKI_DOT_E015.
• dot doctor never calls start. Workers and servers that begin in start are not checked by it. Test them in your app's tests.
• Lists are checked up to 1024 units. A .useAll() or .infra() list with more entries is a compile error.
• Manifest data is plain JSON. Functions, Dates, Maps and cycles in action or contract meta fail with ARKI_DOT_E017, ARKI_DOT_E031 or ARKI_DOT_E032.

Documentation

Start with Principles: five rules every API and error is measured against. Then pick the page for your task. The full index is docs/README.md.

Agents start at llms.txt.

Benchmarks

A 20-service graph where each service depends on the two before it, built with @arki/dot plugins and with awilix, the most used dependency-injection container for Node. A hand-wired version is the floor: no container at all.

Node v22.13.1 on Apple M2 Max, 2026-10-13. Median time per operation, lower is better.

Build the graph and bring it up (boot + dispose, 20 services)

dot: declare 20 plugins, boot, dispose. awilix: create a container, register 20 factories, resolve all 20, dispose. Hand-wired: build the 20 objects in order.

Look up a service after boot

The hot path: code that already has a booted app asks for one service. dot services are plain properties; awilix resolve and cradle go through a cache lookup.

Read the rows with the contracts in mind:

• @arki/dot and awilix do different jobs. awilix is a container: it registers factories and builds them on first use. dot runs an application lifecycle: it orders plugins by their declared needs, runs configure, boot and dispose hooks in order (and in reverse on shutdown), checks the wiring at compile time, and records a manifest and diagnostics for every plugin.
• The boot rows therefore measure more work in dot than in awilix. They are shown so you can see what that lifecycle costs, not to say the two are interchangeable.
• Boot is async in dot (plugin hooks may await). awilix resolves synchronously.

Reproduce with bun run bench in the package directory; regenerate this section with bun run bench --write-readme.

Support

Report bugs and ask questions at github.com/arki-labs/arki/issues. Include the output of dot doctor --json and the code of the error you saw. Changes are listed in CHANGELOG.md.

License

MIT — see LICENSE.

Read Action boundaries and Upgrade action boundaries.