@celerity-sdk/core 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,433 @@
+import { Schema, Type, CelerityLayer, InjectionToken, ModuleMetadata, HandlerContext, HandlerResponse, HandlerMetadata, ServiceContainer, Provider, HttpRequest, HttpResponse, FunctionHandlerDefinition, HttpMethod, CelerityLogger } from '@celerity-sdk/types';
+export { CelerityLayer, FunctionHandlerDefinition, HandlerContext, HandlerMetadata, HandlerResponse, HttpMethod, HttpRequest, HttpResponse, InjectionToken, ModuleMetadata, Provider, Schema, ServiceContainer, Type } from '@celerity-sdk/types';
+import { Request, Response } from '@celerity-sdk/runtime';
+
+type ControllerMetadata = {
+    prefix?: string;
+};
+declare function Controller(prefix?: string): ClassDecorator;
+
+declare function Get(path?: string): MethodDecorator;
+declare function Post(path?: string): MethodDecorator;
+declare function Put(path?: string): MethodDecorator;
+declare function Patch(path?: string): MethodDecorator;
+declare function Delete(path?: string): MethodDecorator;
+declare function Head(path?: string): MethodDecorator;
+declare function Options(path?: string): MethodDecorator;
+
+type ParamType = "body" | "query" | "param" | "headers" | "auth" | "request" | "cookies" | "requestId";
+type ParamMetadata = {
+    index: number;
+    type: ParamType;
+    key?: string;
+    schema?: Schema;
+};
+declare function Body(schema?: Schema): ParameterDecorator;
+declare function Query(): ParameterDecorator;
+declare function Query(key: string): ParameterDecorator;
+declare function Query(schema: Schema): ParameterDecorator;
+declare function Query(key: string, schema: Schema): ParameterDecorator;
+declare function Param(): ParameterDecorator;
+declare function Param(key: string): ParameterDecorator;
+declare function Param(schema: Schema): ParameterDecorator;
+declare function Param(key: string, schema: Schema): ParameterDecorator;
+declare function Headers(): ParameterDecorator;
+declare function Headers(key: string): ParameterDecorator;
+declare function Headers(schema: Schema): ParameterDecorator;
+declare function Headers(key: string, schema: Schema): ParameterDecorator;
+declare function Auth(): ParameterDecorator;
+declare function Req(): ParameterDecorator;
+declare function Cookies(key?: string): ParameterDecorator;
+declare function RequestId(): ParameterDecorator;
+
+/**
+ * Marks a handler class as a custom guard implementation.
+ * The handler IS the guard — in serverless it becomes a Lambda Authorizer,
+ * in containers the Rust runtime invokes it before protected handlers.
+ *
+ * Other handlers reference this guard via `@ProtectedBy("name")`.
+ */
+declare function Guard(name: string): ClassDecorator;
+/**
+ * Declares that a handler or method is protected by one or more named guards.
+ * Multiple `@ProtectedBy` decorators accumulate in declaration order (top-to-bottom).
+ *
+ * Can be applied at class level (all methods) or method level.
+ */
+declare function ProtectedBy(name: string): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
+/**
+ * Marks a method as public, opting out of the default guard.
+ */
+declare function Public(): MethodDecorator;
+
+declare function UseLayer(...layers: (Type<CelerityLayer> | CelerityLayer)[]): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
+declare function UseLayers(layers: (Type<CelerityLayer> | CelerityLayer)[]): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
+
+declare function SetMetadata(key: string, value: unknown): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
+declare function Action(value: unknown): (target: object, propertyKey?: string | symbol, _descriptor?: PropertyDescriptor) => void;
+
+declare function Injectable(): ClassDecorator;
+declare function Inject(token: InjectionToken): ParameterDecorator;
+
+declare function Module(metadata: ModuleMetadata): ClassDecorator;
+
+type ValidationSchemas = {
+    body?: Schema;
+    params?: Schema;
+    query?: Schema;
+    headers?: Schema;
+};
+declare function validate(schemas: ValidationSchemas): CelerityLayer;
+
+declare function runLayerPipeline(layers: (CelerityLayer | Type<CelerityLayer>)[], context: HandlerContext, handler: () => Promise<HandlerResponse>): Promise<HandlerResponse>;
+
+declare function createDefaultSystemLayers(): Promise<CelerityLayer[]>;
+
+/**
+ * Disposes an array of layers in reverse order.
+ * Skips class references (Type<CelerityLayer>) — only instances with a
+ * `dispose` method are called. Errors are non-fatal; disposal continues
+ * for remaining layers.
+ */
+declare function disposeLayers(layers: (CelerityLayer | Type<CelerityLayer>)[]): Promise<void>;
+
+declare class HandlerMetadataStore implements HandlerMetadata {
+    private readonly decoratorData;
+    private readonly requestData;
+    constructor(decoratorMetadata: Record<string, unknown>);
+    get<T = unknown>(key: string): T | undefined;
+    set(key: string, value: unknown): void;
+    has(key: string): boolean;
+}
+
+declare function tokenToString(token: InjectionToken): string;
+type AnyProvider = Provider<any>;
+declare class Container implements ServiceContainer {
+    private providers;
+    private instances;
+    private resolving;
+    private edges;
+    private closeStack;
+    private trackedTokens;
+    register<T>(token: InjectionToken, provider: Provider<T>): void;
+    registerClass<T>(target: Type<T>): void;
+    registerValue<T>(token: InjectionToken, value: T): void;
+    resolve<T>(token: InjectionToken): Promise<T>;
+    resolveClass<T>(target: Type<T>): Promise<T>;
+    has(token: InjectionToken): boolean;
+    getDependencies(token: InjectionToken): ReadonlySet<InjectionToken>;
+    closeAll(): Promise<void>;
+    /**
+     * Validates that all registered providers have resolvable dependencies.
+     * Call after all module providers are registered but before resolution.
+     * Throws a descriptive error listing ALL missing dependencies at once.
+     */
+    validateDependencies(): void;
+    getClassDependencyTokens(target: Type): InjectionToken[];
+    getProviderDependencyTokens(provider: AnyProvider): InjectionToken[];
+    /**
+     * Constructs a class by resolving constructor dependencies via design:paramtypes.
+     * Does NOT manage the resolving set — callers (resolve/resolveClass) own cycle detection.
+     */
+    private constructClass;
+    private recordEdges;
+    private trackCloseable;
+    private createFromProvider;
+}
+
+/**
+ * Reads reflect-metadata to determine the constructor dependency tokens for a class.
+ * Applies @Inject() overrides where present.
+ *
+ * Pure function — reads metadata only, no container side effects.
+ */
+declare function getClassDependencyTokens(target: Type): InjectionToken[];
+/**
+ * Determines the dependency tokens for a provider (class, factory, or value).
+ *
+ * Pure function — reads metadata only, no container side effects.
+ */
+declare function getProviderDependencyTokens(provider: Provider<any>): InjectionToken[];
+
+declare const APP_CONFIG: unique symbol;
+declare const RUNTIME_APP: unique symbol;
+
+type ResolvedHandler = {
+    path?: string;
+    method?: string;
+    protectedBy: string[];
+    layers: (CelerityLayer | Type<CelerityLayer>)[];
+    isPublic: boolean;
+    paramMetadata: ParamMetadata[];
+    customMetadata: Record<string, unknown>;
+    handlerFn: (...args: unknown[]) => unknown;
+    handlerInstance?: object;
+    isFunctionHandler?: boolean;
+    injectTokens?: InjectionToken[];
+};
+type PipelineOptions = {
+    container: ServiceContainer;
+    systemLayers?: (CelerityLayer | Type<CelerityLayer>)[];
+    appLayers?: (CelerityLayer | Type<CelerityLayer>)[];
+};
+declare function executeHandlerPipeline(handler: ResolvedHandler, request: HttpRequest, options: PipelineOptions): Promise<HttpResponse>;
+
+type ModuleNode = {
+    moduleClass: Type;
+    ownTokens: Set<InjectionToken>;
+    exports: Set<InjectionToken>;
+    imports: Type[];
+    controllers: Type[];
+    functionHandlers: FunctionHandlerDefinition[];
+    providers: (Type | (Provider & {
+        provide: InjectionToken;
+    }))[];
+};
+type ModuleGraph = Map<Type, ModuleNode>;
+/**
+ * Builds a module graph by walking the module tree depth-first, collecting
+ * all metadata into a graph structure without any side effects.
+ *
+ * Detects circular module imports and deduplicates visited modules.
+ */
+declare function buildModuleGraph(rootModule: Type): ModuleGraph;
+/**
+ * Registers all providers and controllers from the module graph into the
+ * DI container.
+ */
+declare function registerModuleGraph(graph: ModuleGraph, container: Container): void;
+
+declare class HandlerRegistry {
+    private handlers;
+    getHandler(path: string, method: string): ResolvedHandler | undefined;
+    getAllHandlers(): ResolvedHandler[];
+    populateFromGraph(graph: ModuleGraph, container: Container): Promise<void>;
+    scanModule(moduleClass: Type, container: Container): Promise<void>;
+    private registerClassHandler;
+    private registerFunctionHandler;
+}
+
+declare class CelerityApplication {
+    private registry;
+    private container;
+    private systemLayers;
+    private appLayers;
+    private runtimeApp?;
+    constructor(registry: HandlerRegistry, container: Container, systemLayers?: (CelerityLayer | Type<CelerityLayer>)[], appLayers?: (CelerityLayer | Type<CelerityLayer>)[], runtimeApp?: unknown | undefined);
+    start(): Promise<void>;
+    close(): Promise<void>;
+    getContainer(): Container;
+    getRegistry(): HandlerRegistry;
+    getSystemLayers(): (CelerityLayer | Type<CelerityLayer>)[];
+    getAppLayers(): (CelerityLayer | Type<CelerityLayer>)[];
+}
+
+type ServerlessHandler = (event: unknown, context: unknown) => Promise<unknown>;
+interface ServerlessAdapter {
+    createHandler(registry: HandlerRegistry, options: PipelineOptions): ServerlessHandler;
+}
+
+declare class ServerlessApplication {
+    private registry;
+    private container;
+    private adapter;
+    private systemLayers;
+    private appLayers;
+    private handler;
+    constructor(registry: HandlerRegistry, container: Container, adapter: ServerlessAdapter, systemLayers?: (CelerityLayer | Type<CelerityLayer>)[], appLayers?: (CelerityLayer | Type<CelerityLayer>)[]);
+    start(): Promise<ServerlessHandler>;
+    close(): Promise<void>;
+    getHandler(): ServerlessHandler;
+    getContainer(): Container;
+    getRegistry(): HandlerRegistry;
+}
+
+declare class TestingApplication {
+    private registry;
+    private container;
+    private systemLayers;
+    private appLayers;
+    constructor(registry: HandlerRegistry, container: Container, systemLayers?: (CelerityLayer | Type<CelerityLayer>)[], appLayers?: (CelerityLayer | Type<CelerityLayer>)[]);
+    inject(request: HttpRequest): Promise<HttpResponse>;
+    getContainer(): Container;
+    getRegistry(): HandlerRegistry;
+}
+type MockRequestOptions = {
+    pathParams?: Record<string, string>;
+    query?: Record<string, string | string[]>;
+    headers?: Record<string, string | string[]>;
+    cookies?: Record<string, string>;
+    body?: unknown;
+    auth?: Record<string, unknown>;
+    requestId?: string;
+    clientIp?: string;
+};
+declare function mockRequest(method: HttpMethod, path: string, options?: MockRequestOptions): HttpRequest;
+
+type CreateOptions = {
+    adapter?: ServerlessAdapter;
+    /** App-wide layers that run after system layers but before handler layers. */
+    layers?: (CelerityLayer | Type<CelerityLayer>)[];
+    /**
+     * Override the default system layer stack.
+     * @internal Used by TestingApplication and runtime orchestrator.
+     */
+    systemLayers?: (CelerityLayer | Type<CelerityLayer>)[];
+};
+declare class CelerityFactory {
+    static create(rootModule: Type, options?: CreateOptions): Promise<CelerityApplication | ServerlessApplication>;
+    static createTestingApp(rootModule: Type, options?: CreateOptions): Promise<TestingApplication>;
+}
+
+type HttpHandlerRequest<TBody = unknown> = {
+    method: HttpMethod;
+    path: string;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    body: TBody;
+    headers: Record<string, string | string[]>;
+    cookies: Record<string, string>;
+    auth: Record<string, unknown> | null;
+    clientIp: string | null;
+    userAgent: string | null;
+    contentType: string | null;
+};
+type HttpHandlerContext = {
+    requestId: string;
+    requestTime: string;
+    metadata: HandlerMetadata;
+    container: ServiceContainer;
+    /** Request-scoped logger set by TelemetryLayer. */
+    logger?: CelerityLogger;
+    raw: HttpRequest;
+};
+
+type HttpHandlerConfig<TBody = unknown> = {
+    path?: string;
+    method?: HttpMethod;
+    schema?: {
+        body?: Schema<TBody>;
+        query?: Schema;
+        params?: Schema;
+        headers?: Schema;
+    };
+    layers?: (CelerityLayer | Type<CelerityLayer>)[];
+    inject?: InjectionToken[];
+    metadata?: Record<string, unknown>;
+};
+type HttpHandlerOptions<TBody = unknown> = Omit<HttpHandlerConfig<TBody>, "path" | "method">;
+type HttpHandlerFn<TBody = unknown> = (req: HttpHandlerRequest<TBody>, ctx: HttpHandlerContext, ...deps: unknown[]) => unknown;
+declare function createHttpHandler<TBody = unknown>(config: HttpHandlerConfig<TBody>, handler: HttpHandlerFn<TBody>): FunctionHandlerDefinition;
+declare function httpGet(path: string, handler: HttpHandlerFn): FunctionHandlerDefinition;
+declare function httpGet(path: string, options: HttpHandlerOptions, handler: HttpHandlerFn): FunctionHandlerDefinition;
+declare function httpPost(path: string, handler: HttpHandlerFn): FunctionHandlerDefinition;
+declare function httpPost<TBody = unknown>(path: string, options: HttpHandlerOptions<TBody>, handler: HttpHandlerFn<TBody>): FunctionHandlerDefinition;
+declare function httpPut(path: string, handler: HttpHandlerFn): FunctionHandlerDefinition;
+declare function httpPut<TBody = unknown>(path: string, options: HttpHandlerOptions<TBody>, handler: HttpHandlerFn<TBody>): FunctionHandlerDefinition;
+declare function httpPatch(path: string, handler: HttpHandlerFn): FunctionHandlerDefinition;
+declare function httpPatch<TBody = unknown>(path: string, options: HttpHandlerOptions<TBody>, handler: HttpHandlerFn<TBody>): FunctionHandlerDefinition;
+declare function httpDelete(path: string, handler: HttpHandlerFn): FunctionHandlerDefinition;
+declare function httpDelete(path: string, options: HttpHandlerOptions, handler: HttpHandlerFn): FunctionHandlerDefinition;
+
+declare class HttpException extends Error {
+    readonly statusCode: number;
+    readonly details?: unknown | undefined;
+    constructor(statusCode: number, message: string, details?: unknown | undefined);
+}
+declare class BadRequestException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class UnauthorizedException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class ForbiddenException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class NotFoundException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class MethodNotAllowedException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class NotAcceptableException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class ConflictException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class GoneException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class UnprocessableEntityException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class TooManyRequestsException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class InternalServerErrorException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class NotImplementedException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class BadGatewayException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class ServiceUnavailableException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+declare class GatewayTimeoutException extends HttpException {
+    constructor(message?: string, details?: unknown);
+}
+
+declare const CONTROLLER_METADATA: unique symbol;
+declare const HTTP_METHOD_METADATA: unique symbol;
+declare const ROUTE_PATH_METADATA: unique symbol;
+declare const GUARD_PROTECTEDBY_METADATA: unique symbol;
+declare const GUARD_CUSTOM_METADATA: unique symbol;
+declare const LAYER_METADATA: unique symbol;
+declare const MODULE_METADATA: unique symbol;
+declare const INJECT_METADATA: unique symbol;
+declare const PUBLIC_METADATA: unique symbol;
+declare const CUSTOM_METADATA: unique symbol;
+
+type BootstrapResult = {
+    container: Container;
+    registry: HandlerRegistry;
+};
+/** Bootstrap DI container + handler registry from a root module class. */
+declare function bootstrap(rootModule: Type): Promise<BootstrapResult>;
+
+/** Discover and dynamically import the user's root module. */
+declare function discoverModule(modulePath?: string): Promise<Type>;
+
+/** Flatten multi-value records: single-element arrays become plain strings. */
+declare function flattenMultiValueRecord(record: Record<string, string[]>): Record<string, string | string[]>;
+/** Convert NAPI runtime Request → SDK HttpRequest. */
+declare function mapRuntimeRequest(request: Request): HttpRequest;
+/** Convert SDK HttpResponse → NAPI runtime Response. */
+declare function mapToRuntimeResponse(response: HttpResponse): Response;
+
+type RuntimeBootstrapResult = {
+    registry: HandlerRegistry;
+    container: Container;
+    /** Create a runtime-compatible handler callback for a specific route. */
+    createRouteCallback(path: string, method: string): ((err: Error | null, request: Request) => Promise<Response>) | null;
+};
+/**
+ * Bootstrap the user's module and return an object with per-route callback creation.
+ * Used by the runtime host to get handler callbacks for each blueprint route.
+ */
+declare function bootstrapForRuntime(modulePath?: string, systemLayers?: (CelerityLayer | Type<CelerityLayer>)[]): Promise<RuntimeBootstrapResult>;
+
+type StartRuntimeOptions = {
+    block?: boolean;
+};
+/**
+ * Full runtime lifecycle orchestrator.
+ * Dynamically imports @celerity-sdk/runtime, loads config from CELERITY_* environment
+ * variables, bootstraps the user's module, registers handler callbacks, and starts the server.
+ */
+declare function startRuntime(options?: StartRuntimeOptions): Promise<void>;
+
+export { APP_CONFIG, Action, Auth, BadGatewayException, BadRequestException, Body, type BootstrapResult, CONTROLLER_METADATA, CUSTOM_METADATA, CelerityApplication, CelerityFactory, ConflictException, Container, Controller, type ControllerMetadata, Cookies, type CreateOptions, Delete, ForbiddenException, GUARD_CUSTOM_METADATA, GUARD_PROTECTEDBY_METADATA, GatewayTimeoutException, Get, GoneException, Guard, HTTP_METHOD_METADATA, HandlerMetadataStore, HandlerRegistry, Head, Headers, HttpException, type HttpHandlerConfig, type HttpHandlerContext, type HttpHandlerRequest, INJECT_METADATA, Inject, Injectable, InternalServerErrorException, LAYER_METADATA, MODULE_METADATA, MethodNotAllowedException, type MockRequestOptions, Module, type ModuleGraph, type ModuleNode, NotAcceptableException, NotFoundException, NotImplementedException, Options, PUBLIC_METADATA, Param, type ParamMetadata, type ParamType, Patch, type PipelineOptions, Post, ProtectedBy, Public, Put, Query, ROUTE_PATH_METADATA, RUNTIME_APP, Req, RequestId, type ResolvedHandler, type RuntimeBootstrapResult, type ServerlessAdapter, ServerlessApplication, type ServerlessHandler, ServiceUnavailableException, SetMetadata, type StartRuntimeOptions, TestingApplication, TooManyRequestsException, UnauthorizedException, UnprocessableEntityException, UseLayer, UseLayers, type ValidationSchemas, bootstrap, bootstrapForRuntime, buildModuleGraph, createDefaultSystemLayers, createHttpHandler, discoverModule, disposeLayers, executeHandlerPipeline, flattenMultiValueRecord, getClassDependencyTokens, getProviderDependencyTokens, httpDelete, httpGet, httpPatch, httpPost, httpPut, mapRuntimeRequest, mapToRuntimeResponse, mockRequest, registerModuleGraph, runLayerPipeline, startRuntime, tokenToString, validate };