@celerity-sdk/core 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @celerity-sdk/core
 
-Core SDK for building Celerity applications - decorators, dependency injection, layers, guards, handler adapters, and the application factory.
+Core SDK for building Celerity applications — decorators, dependency injection, layers, guards, handler pipelines, and the application factory.
 
 ## Installation
 
@@ -8,15 +8,16 @@ Core SDK for building Celerity applications - decorators, dependency injection,
 pnpm add @celerity-sdk/core
 ```
 
-## Handler Styles
+Requires `reflect-metadata` and `@celerity-sdk/types` as peer dependencies.
 
-### Class-based (decorator-first)
+## Handler Types
 
-Decorators drive routing. The class is registered as a controller and methods are decorated with HTTP method decorators.
+The core package supports five handler types, each with class-based (decorator-first) and function-based (blueprint-first) styles.
 
-```typescript
-import { Controller, Get, Post, Body } from "@celerity-sdk/core";
+### HTTP
 
+```typescript
+// Class-based
 @Controller("/orders")
 class OrdersHandler {
   @Get("/{orderId}")
@@ -29,41 +30,157 @@ class OrdersHandler {
     return { created: true };
   }
 }
+
+// Function-based
+const getHealth = httpGet("/health", (req, ctx) => ({ status: "ok" }));
+const handler = createHttpHandler({}, (req, ctx) => ({ ok: true }));
+```
+
+### WebSocket
+
+```typescript
+// Class-based
+@WebSocketController()
+class ChatHandler {
+  @OnConnect()
+  connect(@ConnectionId() connId: string) {}
+
+  @OnMessage()
+  message(@ConnectionId() connId: string, @MessageBody() body: unknown) {}
+
+  @OnDisconnect()
+  disconnect(@ConnectionId() connId: string) {}
+}
+
+// Function-based
+const wsHandler = createWebSocketHandler({ route: "$default" }, (msg, ctx) => {});
 ```
 
-### Function-based (blueprint-first or handler-first)
+### Consumer
 
-Lightweight handlers created with `createHttpHandler` or shorthand helpers. Routing can be defined inline or left to the blueprint.
+```typescript
+// Class-based
+@Consumer("ordersConsumer")
+class OrderConsumer {
+  @MessageHandler()
+  async process(
+    @Messages(OrderSchema) messages: ValidatedConsumerMessage<Order>[],
+  ): Promise<EventResult> {
+    return { success: true };
+  }
+}
+
+// Function-based
+const consumer = createConsumerHandler(
+  { messageSchema: OrderSchema },
+  async (messages, ctx) => ({ success: true }),
+);
+```
+
+### Schedule
 
 ```typescript
-import { httpGet, createHttpHandler } from "@celerity-sdk/core";
+// Class-based — cross-cutting, works on any controller type
+@Controller()
+class MaintenanceTasks {
+  @ScheduleHandler("dailyCleanup")
+  async cleanup(@ScheduleInput() input: unknown): Promise<EventResult> {
+    return { success: true };
+  }
 
-// Handler-first: path and method defined in code
-const getHealth = httpGet("/health", (req, ctx) => ({ status: "ok" }));
+  @ScheduleHandler("rate(1 hour)")
+  async sync(): Promise<EventResult> {
+    return { success: true };
+  }
+}
 
-// Blueprint-first: path and method defined in the Celerity blueprint
-const handler = createHttpHandler({}, (req, ctx) => ({ ok: true }));
+// Function-based
+const scheduled = createScheduleHandler(
+  { source: "dailyCleanup", schedule: "rate(1 day)" },
+  async (event, ctx) => ({ success: true }),
+);
+```
+
+### Custom / Invocable
+
+```typescript
+// Class-based
+@Controller()
+class Reports {
+  @Invoke("generateReport")
+  async generate(@Payload() data: unknown) {
+    return { reportId: "r-1" };
+  }
+}
+
+// Function-based
+const custom = createCustomHandler(
+  { name: "generateReport" },
+  async (payload, ctx) => ({ reportId: "r-1" }),
+);
 ```
 
 ## Decorators
 
+### Class Decorators
+
 | Decorator | Purpose |
 |---|---|
-| `@Controller(prefix)` | Marks a class as an HTTP handler controller |
-| `@Get`, `@Post`, `@Put`, `@Patch`, `@Delete`, `@Head`, `@Options` | HTTP method routing |
-| `@Body`, `@Query`, `@Param`, `@Headers`, `@Auth`, `@Req`, `@Cookies`, `@RequestId` | Parameter extraction |
-| `@Injectable()` | Marks a class for DI |
-| `@Inject(token)` | Overrides constructor parameter injection token |
-| `@Module(metadata)` | Defines a module with controllers, providers, imports, and exports |
+| `@Controller(prefix?)` | HTTP handler controller with optional path prefix |
+| `@WebSocketController()` | WebSocket handler controller |
+| `@Consumer(source?)` | Consumer controller with optional blueprint resource name |
+| `@Injectable()` | Marks a class for DI registration |
 | `@Guard(name)` | Declares a class as a named custom guard |
+| `@Module(metadata)` | Defines a module with controllers, providers, imports, and exports |
+
+### HTTP Method Decorators
+
+| Decorator | Purpose |
+|---|---|
+| `@Get(path?)`, `@Post(path?)`, `@Put(path?)`, `@Patch(path?)`, `@Delete(path?)`, `@Head(path?)`, `@Options(path?)` | HTTP method routing on controller methods |
+
+### WebSocket Event Decorators
+
+| Decorator | Purpose |
+|---|---|
+| `@OnConnect()` | Handles `$connect` events |
+| `@OnMessage(route?)` | Handles messages (custom route or `$default`) |
+| `@OnDisconnect()` | Handles `$disconnect` events |
+
+### Other Handler Decorators
+
+| Decorator | Purpose |
+|---|---|
+| `@MessageHandler(route?)` | Consumer message handler with optional routing key |
+| `@ScheduleHandler(arg?)` | Schedule handler — string or `{ source?, schedule? }` |
+| `@Invoke(name)` | Custom invocable handler |
+
+### Cross-Cutting Decorators
+
+| Decorator | Purpose |
+|---|---|
 | `@ProtectedBy(...guards)` | Declares guard requirements (class or method level) |
 | `@Public()` | Opts a method out of guard protection |
-| `@UseLayer(layer)` / `@UseLayers(...layers)` | Attaches layers to a handler method |
+| `@UseLayer(...layers)` / `@UseLayers(layers)` | Attaches layers to handler or controller |
+| `@UseResource(...names)` / `@UseResources(names)` | Declares blueprint resource dependencies |
 | `@SetMetadata(key, value)` / `@Action(name)` | Attaches custom metadata |
+| `@Inject(token)` | Overrides DI token for a constructor parameter |
+
+### Parameter Decorators
+
+| Handler Type | Decorators |
+|---|---|
+| HTTP | `@Body(schema?)`, `@Query(key?, schema?)`, `@Param(key?, schema?)`, `@Headers(key?, schema?)`, `@Auth()`, `@Token()`, `@Req()`, `@Cookies(key?)`, `@RequestId()` |
+| WebSocket | `@ConnectionId()`, `@MessageBody(schema?)`, `@MessageId()`, `@RequestContext()`, `@EventType()` |
+| Consumer | `@Messages(schema?)`, `@EventInput()`, `@Vendor()`, `@ConsumerTraceContext()` |
+| Schedule | `@ScheduleInput(schema?)`, `@ScheduleId()`, `@ScheduleExpression()`, `@ScheduleEventInputParam()` |
+| Custom | `@Payload(schema?)`, `@InvokeContext()` |
+
+Parameter decorators that accept a `schema` use any Zod-compatible `Schema<T>` (`{ parse(data): T }`) for automatic validation.
 
 ## Dependency Injection
 
-The DI container supports class, factory, and value providers with automatic constructor injection.
+The DI container supports class, factory, and value providers with automatic constructor injection, lazy resolution, and circular dependency detection.
 
 ```typescript
 @Injectable()
@@ -72,20 +189,41 @@ class OrderService {
 }
 
 @Module({
-  providers: [OrderService, DatabaseClient],
+  providers: [
+    OrderService,
+    { provide: DB_TOKEN, useFactory: () => new DatabaseClient(), onClose: (db) => db.close() },
+  ],
   controllers: [OrdersHandler],
 })
 class AppModule {}
 ```
 
+Provider types:
+
+| Type | Registration |
+|---|---|
+| Class | `@Injectable()` class or `{ provide: token, useClass: MyClass }` |
+| Factory | `{ provide: token, useFactory: (...deps) => value, inject?: [tokens] }` |
+| Value | `{ provide: token, useValue: value }` |
+
+All providers support an optional `onClose` hook for shutdown cleanup. The container also auto-detects `close`, `end`, `quit`, `disconnect`, and `destroy` methods.
+
 ## Layers
 
-Layers are the cross-cutting mechanism (like middleware in Express). They wrap handler execution and can modify the request, response, or context.
+Layers are the cross-cutting mechanism (similar to middleware). They wrap handler execution in a composable pipeline.
 
 ```typescript
-import { validate } from "@celerity-sdk/core";
+class LoggingLayer implements CelerityLayer {
+  async handle(ctx: BaseHandlerContext, next: NextFunction) {
+    console.log("before");
+    const result = await next();
+    console.log("after");
+    return result;
+  }
+}
 
 @Controller("/orders")
+@UseLayer(LoggingLayer)
 class OrdersHandler {
   @Post("/")
   @UseLayer(validate({ body: orderSchema }))
@@ -95,54 +233,150 @@ class OrdersHandler {
 }
 ```
 
+Layer execution order: `[system layers] → [app layers] → [class layers] → [method layers] → handler`.
+
+The built-in `validate()` layer factory supports schema validation for all handler types:
+
+```typescript
+validate({ body: schema })            // HTTP body
+validate({ query: schema })           // HTTP query
+validate({ consumerMessage: schema })  // Consumer messages
+validate({ scheduleInput: schema })    // Schedule input
+validate({ customPayload: schema })    // Custom payload
+validate({ wsMessageBody: schema })    // WebSocket message body
+```
+
+## Guards
+
+Guards are declarative — they annotate handlers with protection requirements but do not execute in the Node.js process. Guard enforcement happens at the Rust runtime layer (containers) or API Gateway (serverless).
+
+```typescript
+@Guard("jwt")
+class JwtGuard {
+  async check(req: GuardHandlerRequest, ctx: GuardHandlerContext) {
+    return { sub: "user-1", role: "admin" };
+  }
+}
+
+@Controller("/api")
+@ProtectedBy("jwt")
+class ApiController {
+  @Public()
+  @Get("/health")
+  health() { return { ok: true }; }
+
+  @Get("/secret")
+  secret(@Auth() claims: unknown) { return claims; }
+}
+```
+
+Function-based guards: `createGuard({ name: "jwt" }, async (req, ctx) => claims)`.
+
 ## Application Factory
 
 ```typescript
 import { CelerityFactory } from "@celerity-sdk/core";
 
+// Auto-detects platform from CELERITY_RUNTIME_PLATFORM env var
 const app = await CelerityFactory.create(AppModule);
-// Auto-detects platform from CELERITY_PLATFORM env var
 ```
 
-## Handler Resolution
-
-When a handler is invoked by ID (e.g. from a blueprint's `spec.handler` field), the SDK resolves it using a multi-step strategy:
-
-1. **Direct registry ID match** - looks up the handler by its explicit `id` (set via decorator or `createHttpHandler`).
-2. **Module resolution fallback** - if the direct lookup fails, the ID is treated as a module reference and dynamically imported:
-   - `"handlers.hello"` - named export `hello` from module `handlers`
-   - `"handlers"` - default export from module `handlers`
-   - `"app.module"` - tries named export split first (`module: "app"`, `export: "module"`), then falls back to default export from module `app.module`
-3. **Path/method routing** - if both ID-based lookups fail, falls back to matching the incoming request's HTTP method and path against the registry.
+Three application types:
 
-Module resolution matches the imported function against the registry by reference (`===`). Once matched, the handler ID is assigned and subsequent invocations use the direct lookup without repeated imports.
+| Class | Purpose |
+|---|---|
+| `CelerityApplication` | Runtime container application (default) |
+| `ServerlessApplication` | Serverless adapter (created when `adapter` option provided) |
+| `TestingApplication` | Lightweight app for unit testing handlers |
 
-This is primarily relevant for blueprint-first function handlers where `spec.handler` references like `"handlers.hello"` map to exported functions that have no routing information in code.
+## Module System
 
-## Guards
+Modules organize controllers, providers, and sub-modules into a dependency graph.
 
-Guards are declarative. They annotate handlers with protection requirements but do not execute in the Node.js process. Guard enforcement happens at the Rust runtime layer (containers) or API Gateway (serverless).
+```typescript
+@Module({
+  imports: [DatabaseModule, AuthModule],
+  controllers: [UserController, OrderController],
+  providers: [UserService],
+  functionHandlers: [healthCheck],
+  guards: [JwtGuard],
+})
+class AppModule {}
+```
 
 ## Testing
 
 ```typescript
-import { TestingApplication, mockRequest } from "@celerity-sdk/core";
+import { CelerityFactory, mockRequest, mockConsumerEvent, mockScheduleEvent } from "@celerity-sdk/core";
+
+const app = await CelerityFactory.createTestingApp(AppModule);
+
+// HTTP
+const response = await app.injectHttp(mockRequest({ method: "GET", path: "/orders/1" }));
 
-const app = new TestingApplication(AppModule);
-const response = await app.handle(mockRequest({ method: "GET", path: "/orders/1" }));
+// Consumer
+const result = await app.injectConsumer("tag", mockConsumerEvent("tag"));
+
+// Schedule
+const result = await app.injectSchedule("tag", mockScheduleEvent("tag"));
+
+// Custom
+const result = await app.injectCustom("generateReport", { type: "monthly" });
+
+// WebSocket
+await app.injectWebSocket("$default", mockWebSocketMessage());
 ```
 
+## Handler Resolution
+
+When a handler is invoked by ID (e.g. from a blueprint's `spec.handler` field), the SDK resolves it using a multi-step strategy:
+
+1. **Direct registry ID match** — looks up the handler by its explicit `id`.
+2. **Module resolution fallback** — treats the ID as a module reference and dynamically imports it (e.g. `"handlers.hello"` → named export `hello` from module `handlers`).
+3. **Path/method routing** — falls back to matching the incoming request's HTTP method and path against the registry.
+
+## HTTP Exceptions
+
+All extend `HttpException(statusCode, message, details?)` and are caught by the HTTP pipeline to return structured error responses:
+
+| Exception | Status |
+|---|---|
+| `BadRequestException` | 400 |
+| `UnauthorizedException` | 401 |
+| `ForbiddenException` | 403 |
+| `NotFoundException` | 404 |
+| `MethodNotAllowedException` | 405 |
+| `NotAcceptableException` | 406 |
+| `ConflictException` | 409 |
+| `GoneException` | 410 |
+| `UnprocessableEntityException` | 422 |
+| `TooManyRequestsException` | 429 |
+| `InternalServerErrorException` | 500 |
+| `NotImplementedException` | 501 |
+| `BadGatewayException` | 502 |
+| `ServiceUnavailableException` | 503 |
+| `GatewayTimeoutException` | 504 |
+
 ## Advanced Exports
 
-The following exports are available for adapter authors building custom serverless or runtime adapters:
+For adapter authors building custom serverless or runtime integrations:
 
 | Export | Purpose |
 |---|---|
-| `resolveHandlerByModuleRef(id, registry, baseDir)` | Resolve a handler ID as a module reference via dynamic import |
-| `executeHandlerPipeline(handler, request, options)` | Execute the full layer + handler pipeline |
-| `HandlerRegistry` | Handler registry class with route and ID-based lookups |
-| `bootstrapForRuntime(modulePath?, systemLayers?)` | Bootstrap for the Celerity runtime host |
+| `HandlerRegistry` | Handler registry with route and ID-based lookups |
+| `resolveHandlerByModuleRef` | Resolve a handler ID as a module reference via dynamic import |
+| `executeHttpPipeline` | Execute the HTTP layer + handler pipeline |
+| `executeWebSocketPipeline` | Execute the WebSocket pipeline |
+| `executeConsumerPipeline` | Execute the consumer pipeline |
+| `executeSchedulePipeline` | Execute the schedule pipeline |
+| `executeCustomPipeline` | Execute the custom handler pipeline |
+| `executeGuardPipeline` | Execute the guard pipeline |
+| `bootstrapForRuntime` | Bootstrap for the Celerity runtime host |
 | `mapRuntimeRequest` / `mapToRuntimeResponse` | Runtime request/response mappers |
+| `mapWebSocketMessage` | Runtime WebSocket message mapper |
+| `mapConsumerEventInput` | Runtime consumer event mapper |
+| `mapScheduleEventInput` | Runtime schedule event mapper |
+| `mapToNapiEventResult` | Runtime EventResult mapper |
 
 ## Part of the Celerity Framework