@orditjs/contracts

Portable TypeScript contracts for Ordit.

Use this package when you need the shared language of Ordit without pulling in the framework runtime: envelopes, messages, handler types, binding definitions, execution records, ports and workflow contracts.

Install

npm install @orditjs/contracts

What is inside

• Message primitives: ICommand, IEvent, IEnvelope.
• Factories: createCommand, createEvent, createEnvelope.
• Handler contracts: HandlerFunction, HandlerConfig, HandlerOutcome.
• Binding contracts: BindingDefinition, triggers, transport definitions, sandbox, retry, outputs and publish permissions.
• Runtime contracts: RuntimeEnvelope, RuntimeAddress, execution records and logs.
• Runtime ports: SandboxRunner, Publisher, ExecutionLedger, IdempotencyStore, RetryEngine, ReplayEngine, BindingConsumer, HandlerLoader.
• Workflow contracts used by the lower-level runtime package.

Basic usage

import { createEnvelope, createEvent } from '@orditjs/contracts'

const event = createEvent('user.created', {
  userId: 'u-123',
})

const envelope = createEnvelope(event, {
  messageId: 'msg-1',
  correlationId: 'corr-1',
  occurredAt: new Date().toISOString(),
  metadata: {
    source: 'example',
  },
})

console.log(envelope.message.type)

Defining a binding

import type { BindingDefinitionDraft } from '@orditjs/contracts'

const draft: BindingDefinitionDraft = {
  name: 'normalize-user',
  triggers: [
    {
      type: 'event',
      key: 'event.user.created',
      event: 'user.created',
    },
  ],
}

For validation and defaults, pass drafts to NormalizeBindingDefinition from @orditjs/core.

Binding triggers and transports

Bindings separate the trigger shape from the transport implementation. This keeps handlers portable across local compose, service hosts and future serverless adapters.

Generic trigger types:

• file.changed
• http
• event
• queue
• cron
• object.storage
• custom

Concrete transport providers:

• generic: explicit address and optional protocol for custom adapters.
• rabbitmq: queue/exchange/routing-key oriented AMQP bindings.
• sqs: AWS SQS queue URL/name oriented bindings.
• redis: Redis pubsub, stream or list bindings.
• s3: S3-compatible object storage bindings.
• custom: user-owned adapter source and options.

Example:

import type { BindingDefinitionDraft } from '@orditjs/contracts'

const draft: BindingDefinitionDraft = {
  name: 'normalize-order',
  triggers: [
    {
      type: 'queue',
      key: 'rabbitmq.orders',
      queue: 'orders.created',
      transport: {
        provider: 'rabbitmq',
        connectionRef: 'env:RABBITMQ_URL',
        exchange: 'orders',
        routingKey: 'orders.created',
        queue: 'orders.created',
        prefetch: 10,
      },
    },
    {
      type: 'object.storage',
      key: 's3.inbox',
      bucket: 'orders-inbox',
      eventType: 'object.created',
      transport: {
        provider: 's3',
        connectionRef: 'env:AWS_PROFILE',
        bucket: 'orders-inbox',
        prefix: 'incoming/',
      },
    },
  ],
  outputs: [
    {
      event: 'order.normalized',
      target: {
        kind: 'queue',
        id: 'orders-normalized',
      },
      transport: {
        provider: 'sqs',
        queueName: 'orders-normalized',
        region: 'us-east-1',
      },
    },
  ],
}

Transport contracts are serializable descriptions only. SDK clients, credentials, polling loops and broker-specific delivery behavior belong in framework or platform adapters, not in @orditjs/contracts.

Implementing a port

import type { Publisher } from '@orditjs/contracts'

export class ConsolePublisher implements Publisher {
  async publish(request) {
    return {
      status: 'ok',
      items: request.outputs.map((output) => ({
        eventType: output.message.type,
        status: 'published',
        target: 'console',
      })),
    }
  }
}

Package boundary

@orditjs/contracts contains types and portable factories only. It should not own framework discovery, filesystem access, HTTP servers, broker SDKs or runtime composition.