ordit

The main Ordit framework package.

Use ordit when you want the public framework API: message helpers, handler loading, local project running and the core Ordit v2 primitives reexported from one package.

Ordit is pre-1.0. The current package exposes the compatibility local runner and the v2 core primitives while the full functions/ + bindings/ discovery experience is being completed.

Install

npm install ordit

What is inside

• createCommand, createEvent, createEnvelope from @orditjs/contracts.
• NormalizeBindingDefinition, RuntimeEngine and core errors from @orditjs/core.
• loadHandler: loads a configured handler module.
• createRunner: creates a local configured project runner.
• createComposeHost: loads one compose definition and runs multiple handlers as one local service.
• ordit compose: CLI command for starting a compose service.
• Public handler/config types for authoring integrations.

Normalize a v2 binding

import { NormalizeBindingDefinition } from 'ordit'

const binding = new NormalizeBindingDefinition().execute({
  name: 'normalize-user',
  triggers: [
    {
      type: 'event',
      key: 'event.user.created',
      event: 'user.created',
    },
  ],
})

console.log(binding.handler.cwd)
// functions/normalize-user

Create an envelope

import { createEnvelope, createEvent } from 'ordit'

const envelope = createEnvelope(
  createEvent('user.created', { userId: 'u-1' }),
  {
    messageId: 'msg-1',
    correlationId: 'corr-1',
    occurredAt: new Date().toISOString(),
    metadata: {},
  }
)

Load a configured handler

import { loadHandler } from 'ordit'

const definition = await loadHandler('./handler.config.yaml')

const outcome = await definition.handler(envelope, {
  attempt: 1,
  receivedAt: new Date().toISOString(),
  runtimeMode: 'service',
  attributes: {},
})

console.log(outcome.status)

Run a local configured project

import { createRunner } from 'ordit'

const runner = await createRunner('./handler.config.yaml')
const processed = await runner.runUntilProcessed(10)

console.log({ processed })

Run a composed local service

Use createComposeHost(configPath, options?) when a project needs one process to load several configured handlers and orchestrate their local event flow.

import { createComposeHost } from 'ordit'

const host = await createComposeHost('./ordit-compose.yaml')
const result = await host.run({ ticks: 80, idleTicks: 8 })

console.log(result.processed)

From the CLI:

npx ordit compose --config ./ordit-compose.yaml

The CLI now defaults to concise operational logs and writes an append-only audit trail to ./ordit-compose.audit.jsonl next to the compose config. --log-level debug adds runtime execution detail for real handler work. --log-level verbose adds host-loop detail such as ticks and polling.

The current compose host is local-first. It is useful for development, deterministic examples and adapter testing; production adapters can replace the filesystem trigger/output pieces without changing handler code.

Compose can also route HandlerOutcome.dispatch.events to handlers declared with trigger.type: event. This keeps one product rule: every handler input is a trigger. subscribe.kind: event remains accepted as a compatibility alias for older configs, but new compose files should prefer trigger.

handlers:
  source:
    modulePath: ./handlers/source/dist/index.mjs
    trigger:
      type: file.changed
      directory: ./runtime/inbox
      eventType: message.received

  subscriber:
    modulePath: ./handlers/subscriber/dist/index.mjs
    trigger:
      type: event
      event: message.authorized
      source: compose.dispatch
    output:
      type: file.write
      directory: ./runtime/outbox

Event-triggered handlers receive routed events on the next compose tick. Existing file/custom triggers and outputs remain supported.

Package boundary

Use ordit for application-facing APIs. Use @orditjs/core directly if you are building a custom Ordit-compatible runtime. Use @orditjs/contracts when you only need portable types.