@celerity-sdk/core

Core SDK for building Celerity applications - decorators, dependency injection, layers, guards, handler adapters, and the application factory.

Installation

pnpm add @celerity-sdk/core

Handler Styles

Class-based (decorator-first)

Decorators drive routing. The class is registered as a controller and methods are decorated with HTTP method decorators.

import { Controller, Get, Post, Body } from "@celerity-sdk/core";

@Controller("/orders")
class OrdersHandler {
  @Get("/{orderId}")
  getOrder(@Param("orderId") id: string) {
    return { id };
  }

  @Post("/")
  createOrder(@Body() body: unknown) {
    return { created: true };
  }
}

Function-based (blueprint-first or handler-first)

Lightweight handlers created with createHttpHandler or shorthand helpers. Routing can be defined inline or left to the blueprint.

import { httpGet, createHttpHandler } from "@celerity-sdk/core";

// Handler-first: path and method defined in code
const getHealth = httpGet("/health", (req, ctx) => ({ status: "ok" }));

// Blueprint-first: path and method defined in the Celerity blueprint
const handler = createHttpHandler({}, (req, ctx) => ({ ok: true }));

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 | | @Guard(name) | Declares a class as a named custom guard | | @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 | | @SetMetadata(key, value) / @Action(name) | Attaches custom metadata |

Dependency Injection

The DI container supports class, factory, and value providers with automatic constructor injection.

@Injectable()
class OrderService {
  constructor(private db: DatabaseClient) {}
}

@Module({
  providers: [OrderService, DatabaseClient],
  controllers: [OrdersHandler],
})
class AppModule {}

Layers

Layers are the cross-cutting mechanism (like middleware in Express). They wrap handler execution and can modify the request, response, or context.

import { validate } from "@celerity-sdk/core";

@Controller("/orders")
class OrdersHandler {
  @Post("/")
  @UseLayer(validate({ body: orderSchema }))
  createOrder(@Body() body: Order) {
    return { created: true };
  }
}

Application Factory

import { CelerityFactory } from "@celerity-sdk/core";

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.

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.

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.

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).

Testing

import { TestingApplication, mockRequest } from "@celerity-sdk/core";

const app = new TestingApplication(AppModule);
const response = await app.handle(mockRequest({ method: "GET", path: "/orders/1" }));

Advanced Exports

The following exports are available for adapter authors building custom serverless or runtime adapters:

| 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 | | mapRuntimeRequest / mapToRuntimeResponse | Runtime request/response mappers |

Part of the Celerity Framework

See celerityframework.io for full documentation.