@mettlecast/domain-runtime

Type-safe runtime types, factory functions, and context interface for TIB Domain Module handlers. Zero AWS dependencies in the main export — all infrastructure concerns are delegated to the CDK packer.

Install

npm install @mettlecast/domain-runtime

Quick Start

Define a domain with an API handler:

import {
  defineDomain,
  defineApi,
  defineEvent,
  type DomainContext,
} from '@mettlecast/domain-runtime';

const domain = defineDomain({
  name: 'payments',
  version: '1.0.0',
});

const paymentCreated = defineEvent({
  name: 'payment.created',
  schema: {
    type: 'object',
    properties: {
      paymentId: { type: 'string' },
      amount: { type: 'number' },
    },
  },
});

export const chargeHandler = defineApi({
  domain,
  path: '/charge',
  method: 'POST',
  handler: async (event, ctx: DomainContext) => {
    const amount = event.body.amount;
    
    // Use context surfaces
    await ctx.db.query('INSERT INTO charges ...');
    await ctx.publish(paymentCreated, { paymentId: '123', amount });
    await ctx.cache.set('last_charge', amount);
    
    return { statusCode: 200, body: { success: true } };
  },
});

Factory Functions

9 factory functions help you define domain primitives with schema validation and type safety:

| Function | Purpose | Produces | |---|---|---| | defineDomain() | Declare a domain and version | Domain metadata | | defineApi() | HTTP handler with route + method | API handler + EventBridge integration | | defineEvent() | Event type with schema | Typed event publisher | | defineWebhook() | Inbound GitHub webhook handler | Webhook + validation | | defineSubscriber() | Event subscriber handler | EventBridge rule + Lambda | | defineSchedule() | Cron-triggered handler | EventBridge Scheduler rule | | defineJob() | Async queue-based task | SQS queue + Lambda consumer | | defineAction() | Flow Designer action | Workspace-invoked handler | | defineIntegration() | External service integration | Async integration handler |

Context Surfaces

14 surfaces available in DomainContext:

| Surface | Purpose | |---|---| | ctx.db | PostgreSQL connection pool via drizzle-orm | | ctx.publish() | Publish an event to EventBridge | | ctx.actions | Invoke other domain actions | | ctx.integrations | Call external integrations | | ctx.jobs | Enqueue async tasks to SQS | | ctx.flows | Trigger TIB Flow Designer flows | | ctx.cache | In-memory or distributed cache (Redis) | | ctx.secrets | Fetch AWS Secrets Manager values | | ctx.fetch() | HTTP client with request/response tracing | | ctx.idempotency | Deduplication by request ID | | ctx.logger | Pino JSON logger | | ctx.tracer | AWS X-Ray tracing | | ctx.request | Original HTTP request object | | ctx.requestId | Unique request UUID |

Design Principles

This package is intentionally framework-agnostic. It exports types and factory functions only — all infrastructure (Lambdas, API Gateway, EventBridge, SQS, etc.) is provisioned by @mettlecast/domain-cdk-packer.

Exports by concern:

• @mettlecast/domain-runtime — types, factories, DomainContext
• @mettlecast/domain-runtime/primitives — factory functions only
• @mettlecast/domain-runtime/ctx — context interfaces
• @mettlecast/domain-runtime/types — TypeScript types
• @mettlecast/domain-runtime/schema — Zod schema utilities

See wiki/how-it-works/domain-module.md for the full design.