@ddd-components/runtime

A runtime library providing shared utilities for Domain-Driven Design (DDD) components generated by the mcp4ddd MCP server.

Overview

This package contains essential types and functions used by DDD components to ensure consistent error handling, type safety, and workflow management across your domain models.

Exports

Error Types and Functions (BasicErrorTypes)

Types

• SingleError<CODE>: Represents a single error with a specific error code and message
• ValidationError: Represents validation errors with an array of error messages
• TechError: A specialized single error for technical issues

Functions

• singleError<CODE>(code, message): Creates a SingleError with the given code and message
• validationError(messages): Creates a ValidationError from an array of error messages
• zodValidationError(error): Converts a Zod validation error to a ValidationError
• techError(message): Creates a technical error with the message

Type Branding (BasicModelTypes)

Types

• Branded<T, B>: A branded type that adds a unique brand to prevent mixing incompatible types at compile time

DynamoDB Configuration (DynamoDBConfig)

Constants

• dynamoDBClientConfiguration: Client configuration for DynamoDB, automatically configured for local development if AWS_ENDPOINT_URL_DYNAMODB is set
• documentClientConfig: Document client configuration with marshalling options optimized for ElectroDB

Workflow Utilities (WorkflowStart)

Functions

• beginWith<T>(value): Starts an asynchronous result workflow with the given value, returning an AsyncResult<T, never>. This is the entry point for functional error handling patterns using the ts-results-es library.
• safeAsync<T>(fn): Wraps an async function to return a Result type, converting exceptions to TechError. Allows async operations to be composed using the Result monad pattern.

Usage

import {
  singleError,
  validationError,
  techError,
  beginWith,
  safeAsync,
  type Branded,
  dynamoDBClientConfiguration
} from '@ddd-components/runtime';

// Error handling
const error = singleError('not-found', 'Item not found');

// Type branding for domain safety
type UserId = Branded<string, 'UserId'>;

// Workflow starting
const result = await beginWith(initialParameters)
  .andThen(processStep)
  .andThen(anotherStep);

// Using safeAsync in a workflow chain for a step that might throw
const resultWithAsync = await beginWith(initialParameters)
  .andThen((params) => safeAsync(() => fetchData(params)))
  .andThen(processData);

Dependencies

• ts-results-es: For functional error handling
• zod: For schema validation (used in error conversion)

License

MIT