Chapter 19: API Reference

This chapter is a comprehensive reference for every package, class, method, and interface in OriJS. Use it as a lookup when you need the exact signature of a method or the shape of an interface.

@orijs/core

The foundation package. Provides the application builder, DI container, routing, and lifecycle management.

Ori

Static factory for creating applications.

import { Ori } from '@orijs/core';

Ori.create(options?: ApplicationOptions): OriApplication

ApplicationOptions:

OriApplication

The main application class. All methods return this for fluent chaining unless otherwise noted.

Configuration Methods:

CorsConfig:

AppLoggerOptions:

Provider Methods:

ProviderOptions:

Middleware Methods:

Controller Methods:

Event Methods:

EventRegistration (returned by .event()):

Workflow Methods:

WorkflowRegistration (returned by .workflow()):

Cache Methods:

WebSocket Methods:

WebSocket options (second parameter of .websocket()):

Lifecycle Methods:

Inspection Methods:

Container

Dependency injection container. Singletons by default.

createToken

Creates a typed injection token for named providers.

import { createToken } from '@orijs/core';

const HotCache = createToken<CacheService>('HotCache');
const ColdCache = createToken<CacheService>('ColdCache');

AppContext

Application-scoped context. Created once per application.

Properties:

LifecyclePhase: 'created' | 'bootstrapped' | 'starting' | 'ready' | 'stopping' | 'stopped'

Lifecycle Methods:

RouteBuilder

Fluent API for defining routes within a controller.

RouteSchemaOptions:

RequestContext

Request-scoped context passed to handlers, guards, and interceptors.

Properties:

Methods:

ResponseFactory

Creates standardized HTTP responses.

Interfaces

Guard:

interface Guard {
  canActivate(ctx: RequestContext): boolean | Promise<boolean>;
}

Interceptor:

interface Interceptor {
  intercept(ctx: RequestContext, next: () => Promise<Response>): Promise<Response>;
}

Pipe:

interface Pipe<TInput = unknown, TOutput = unknown> {
  transform(value: TInput, metadata?: PipeMetadata): TOutput | Promise<TOutput>;
}

OriController:

interface OriController<
  TState extends object = Record<string, unknown>,
  TParams extends Record<string, string> = Record<string, string>
> {
  configure(route: RouteBuilder<TState, TParams>): void;
}

ParamValidator:

interface ParamValidator {
  validate(value: string, key: string): string; // Returns validated value or throws
}

Built-in Param Validators: UuidParam, StringParam, NumberParam

HttpException

OriJS does not have a built-in HttpException class. Use domain error classes with an error mapping interceptor (see Chapter 17).

@orijs/validation

TypeBox-based validation with Standard Schema and custom validator support.

Type

Re-exported from @sinclair/typebox. Defines JSON Schema-compatible types.

Common methods:

String format options: 'email', 'uuid', 'uri', 'date-time', 'date', 'time', 'ipv4', 'ipv6'

Params

Pre-built parameter validation schemas.

import { Params } from '@orijs/validation';

Params.uuid()        // UUID format string
Params.string(opts?) // String with optional min/max length
Params.number(opts?) // Numeric string (parsed to number)

Query

Pre-built query parameter schemas.

import { Query } from '@orijs/validation';

Query.pagination(opts?)  // { page, limit } with defaults
Query.search(opts?)      // { q } search string
Query.sort(opts?)        // { sortBy, sortOrder }

validate / validateSync

import { validate, validateSync } from '@orijs/validation';

// Async — supports TypeBox, Standard Schema, custom validators
const result = await validate(schema, data);
// result: { success: true, data: T } | { success: false, errors: ValidationError[] }

// Sync — TypeBox only
const result = validateSync(schema, data);

Json

Safe JSON parsing with prototype pollution protection.

import { Json } from '@orijs/validation';

Json.parse(text)       // Safe parse (strips __proto__, constructor)
Json.stringify(value)  // Standard stringify
Json.sanitize(data)    // Strip prototype pollution keys from object

@orijs/events

Type-safe event system with pluggable providers.

Event.define

Creates a type-safe event definition.

import { Event } from '@orijs/core';
import { Type } from '@orijs/validation';

const UserCreated = Event.define({
  name: 'user.created',
  data: Type.Object({ userId: Type.String(), email: Type.String() }),
  result: Type.Object({ welcomeEmailSent: Type.Boolean() }),
});

EventConfig:

IEventConsumer

Interface for event consumer classes.

interface IEventConsumer<TData, TResult> {
  readonly onEvent: (ctx: EventContext<TData>) => Promise<TResult> | TResult;
  readonly onSuccess?: (ctx: EventContext<TData>, result: TResult) => Promise<void> | void;
  readonly onError?: (ctx: EventContext<TData>, error: Error) => Promise<void> | void;
}

EventContext

Context passed to event consumers.

EventProvider Interface

interface EventProvider extends EventEmitter, EventLifecycle {}

interface EventEmitter {
  emit(eventName, payload, meta?, options?): EventSubscription;
  subscribe(eventName, handler): void | Promise<void>;
}

interface EventLifecycle {
  start(): Promise<void>;
  stop(): Promise<void>;
}

Utility Types

import type { Data, Result, EventConsumer, EventCtx } from '@orijs/core';

type UserData = Data<typeof UserCreated>;      // Extract data type
type UserResult = Result<typeof UserCreated>;  // Extract result type
type Consumer = EventConsumer<typeof UserCreated>; // Consumer interface
type Ctx = EventCtx<typeof UserCreated>;       // Context type

@orijs/workflows

Saga-pattern workflow orchestration with distributed step execution.

Workflow.define

Creates a type-safe workflow definition with optional steps.

import { Workflow } from '@orijs/core';
import { Type } from '@orijs/validation';

// Simple workflow (no steps)
const SendEmail = Workflow.define({
  name: 'send-email',
  data: Type.Object({ to: Type.String(), subject: Type.String() }),
  result: Type.Object({ messageId: Type.String() }),
});

// Workflow with steps
const ProcessOrder = Workflow.define({
  name: 'process-order',
  data: Type.Object({ orderId: Type.String() }),
  result: Type.Object({ processedAt: Type.Number() }),
}).steps(s => s
  .sequential(s.step('validate', Type.Object({ valid: Type.Boolean() })))
  .sequential(s.step('charge', Type.Object({ chargeId: Type.String() })))
  .parallel(
    s.step('notify', Type.Object({ sent: Type.Boolean() })),
    s.step('audit', Type.Object({ logged: Type.Boolean() }))
  )
);

IWorkflowConsumer

interface IWorkflowConsumer<TData, TResult, TSteps = Record<never, never>> {
  readonly steps?: {
    [K in keyof TSteps]?: StepHandler<TData, TSteps[K], TSteps>;
  };
  readonly onComplete: (ctx: WorkflowContext<TData, TSteps>) => Promise<TResult> | TResult;
  readonly onError?: (ctx: WorkflowContext<TData, TSteps>, error: Error) => Promise<void> | void;
}

interface StepHandler<TData, TOutput, TResults = Record<string, unknown>> {
  readonly execute: (ctx: StepContext<TData, TResults>) => Promise<TOutput> | TOutput;
  readonly rollback?: (ctx: StepContext<TData, TResults>) => Promise<void> | void;
}

WorkflowContext

StepContext

WorkflowExecutor (ctx.workflows)

interface WorkflowExecutor {
  execute<TData, TResult>(
    workflow: WorkflowDefinition<TData, TResult>,
    data: TData,
    options?: WorkflowExecuteOptions
  ): Promise<WorkflowHandle<TResult>>;
}

WorkflowExecuteOptions:

WorkflowHandle:

WorkflowStatus: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'

@orijs/cache

Entity-based caching with singleflight, grace periods, and cascade invalidation.

CacheEntityRegistry

Defines cacheable entities with scope and required parameters.

import { CacheEntityRegistry } from '@orijs/cache';

const Entities = CacheEntityRegistry.create({
  User: { scope: 'account', requiredParams: ['accountUuid'] },
  Monitor: { scope: 'project', requiredParams: ['accountUuid', 'projectUuid'] },
});

CacheService

The main caching interface. Injected as a provider.

CacheProvider Interface

The interface custom cache providers must implement.

interface CacheProvider {
  get<T>(key: string): Promise<T | null>;
  set<T>(key: string, value: T, ttlSeconds: number): Promise<void>;
  del(key: string): Promise<number>;
  delMany(keys: string[]): Promise<number>;
  exists(key: string): Promise<boolean>;
  ttl(key: string): Promise<number>;
}

FactoryContext

Context passed to the factory function during cache miss.

InMemoryCacheProvider

Built-in in-memory cache provider. Suitable for development and testing.

import { InMemoryCacheProvider } from '@orijs/cache';

const provider = new InMemoryCacheProvider();

@orijs/websocket

WebSocket support with Bun’s native WebSocket server and pluggable scaling providers.

WebSocket Options

Configured via app.websocket(provider?, options?).

OriSocketRouter

Interface for WebSocket message routing.

interface OriSocketRouter<TState, TSocket> {
  configure(route: SocketRouteBuilder<TState, TSocket>): void;
}

SocketRouteBuilder

Fluent API for defining WebSocket routes.

SocketContext

Per-message context for socket handlers.

SocketEmitter Interface

interface SocketEmitter {
  publish(topic: string, message: string | ArrayBuffer): Promise<void>;
  send(socketId: string, message: string | ArrayBuffer): void;
  broadcast(message: string | ArrayBuffer): void;
  emit<TData>(message: SocketMessageLike<TData>, topic: string, data: TData): Promise<void>;
}

WebSocketProvider Interface

Full interface for scaling providers.

interface WebSocketProvider extends SocketEmitter, SocketLifecycle {
  subscribe(socketId: string, topic: string): void;
  unsubscribe(socketId: string, topic: string): void;
  disconnect(socketId: string): void;
  isConnected(socketId: string): boolean;
  getConnectionCount(): number;
  getTopicSubscriberCount(topic: string): number;
  setServer(server: BunServer): void;
}

SocketMessage.define

Creates typed WebSocket message definitions.

import { SocketMessage } from '@orijs/core';
import { Type } from '@orijs/validation';

const IncidentCreated = SocketMessage.define({
  name: 'incident.created',
  data: Type.Object({ uuid: Type.String(), title: Type.String() }),
});

// Usage: await socket.emit(IncidentCreated, 'account:123', { uuid: '...', title: '...' });

@orijs/config

Environment-based configuration with validation.

EnvConfigProvider

Reads configuration from environment variables.

import { EnvConfigProvider } from '@orijs/config';

const config = new EnvConfigProvider();
const value = await config.get('DATABASE_URL');
const required = await config.getRequired('DATABASE_URL'); // throws if missing

ValidatedConfig

Validates configuration at startup.

import { ValidatedConfig } from '@orijs/config';

const config = new ValidatedConfig({
  DATABASE_URL: { required: true },
  PORT: { required: true, transform: Number },
  LOG_LEVEL: { required: false, default: 'info' },
});

await config.validate(); // Throws if required keys are missing

NamespacedConfig / createConfigProvider

Creates namespaced configuration with type-safe access.

import { createConfigProvider } from '@orijs/config';

const config = createConfigProvider({
  db: { url: 'DATABASE_URL', pool: { max: 'DB_POOL_MAX' } },
  redis: { host: 'REDIS_HOST', port: 'REDIS_PORT' },
});

@orijs/mapper

SQL result to TypeScript object mapping.

Mapper.defineTable

Defines table schemas for SQL result mapping.

import { Mapper, field } from '@orijs/mapper';

const Tables = Mapper.defineTable({
  User: {
    tableName: 'user',
    uuid: field('uuid').string(),
    displayName: field('display_name').string().optional(),
    email: field('email').string(),
    createdAt: field('created_at').date(),
    isActive: field('is_active').boolean(),
    metadata: field('metadata').any(), // JSONB
  },
});

Field types:

Mapper.for / .build

Creates a mapper for a specific table.

const UserMapper = Mapper.for<User>(Tables.User).build();

// Map a single row
const user: User = UserMapper.map(row);

// Map multiple rows
const users: User[] = UserMapper.mapMany(rows);

MapResult / MapOptions:

interface MapOptions {
  strict?: boolean; // Throw on missing columns (default: false)
}

@orijs/logging

Pino-inspired structured logging with transports.

Logger

import { Logger } from '@orijs/logging';

const log = new Logger('MyService', { level: 'info', transports: [...] });

Logger methods:

Static methods:

Transports

import { consoleTransport, fileTransport, filterTransport, multiTransport } from '@orijs/logging';

consoleTransport(options?)   // Console output (colorize, JSON)
fileTransport(options)       // File output with rotation
filterTransport(options)     // Level-filtered transport
multiTransport(transports)   // Fan-out to multiple transports

@orijs/test-utils

Testing utilities and infrastructure helpers.

createBunTestPreload

Creates a Bun test preload setup function.

import { createBunTestPreload } from '@orijs/test-utils';

const preload = createBunTestPreload({
  packageName: 'my-app',
  dependencies: ['redis'],
});

await preload();

teardownBunTest

Cleans up test containers.

import { teardownBunTest } from '@orijs/test-utils';

afterAll(() => teardownBunTest('my-app'));

createRedisTestHelper

Creates a Redis test helper for Testcontainer-based testing.

import { createRedisTestHelper } from '@orijs/test-utils';

const helper = createRedisTestHelper('my-app');
const redis = helper.createRedisClient();

Async Helpers

WaitForOptions:

@orijs/bullmq

BullMQ providers for distributed events and workflows.

BullMQEventProvider

import { BullMQEventProvider, Redis } from '@orijs/bullmq';

const redis = new Redis({ host: 'localhost', port: 6379 });
const provider = new BullMQEventProvider({ connection: redis });

Ori.create()
  .eventProvider(provider)
  .event(UserCreated).consumer(UserCreatedConsumer, [EmailService])
  .listen(3000);

createBullMQWorkflowProvider

import { createBullMQWorkflowProvider, Redis } from '@orijs/bullmq';

const redis = new Redis({ host: 'localhost', port: 6379 });
const provider = createBullMQWorkflowProvider({ connection: redis });

Ori.create()
  .workflowProvider(provider)
  .workflow(SendEmail).consumer(SendEmailWorkflow, [SmtpClient])
  .listen(3000);

@orijs/cache-redis

Redis cache provider with dependency tracking.

createRedisCacheProvider

import { createRedisCacheProvider } from '@orijs/cache-redis';

const provider = createRedisCacheProvider({
  connection: { host: 'localhost', port: 6379 },
});

Ori.create()
  .cache(provider)
  .listen(3000);

RedisCacheProviderOptions:

@orijs/websocket-redis

Redis WebSocket provider for horizontal scaling.

createRedisWsProvider

import { createRedisWsProvider } from '@orijs/websocket-redis';

const provider = createRedisWsProvider({
  connection: { host: 'localhost', port: 6379 },
});

Ori.create()
  .websocket(provider)
  .listen(3000);

RedisWsProviderOptions:

Previous: Migration from NestJS ← | Back to Table of Contents →