@celerity-sdk/core 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -153,6 +153,7 @@ declare const APP_CONFIG: unique symbol;
 declare const RUNTIME_APP: unique symbol;
 
 type ResolvedHandler = {
+    id?: string;
     path?: string;
     method?: string;
     protectedBy: string[];
@@ -200,6 +201,7 @@ declare function registerModuleGraph(graph: ModuleGraph, container: Container):
 declare class HandlerRegistry {
     private handlers;
     getHandler(path: string, method: string): ResolvedHandler | undefined;
+    getHandlerById(id: string): ResolvedHandler | undefined;
     getAllHandlers(): ResolvedHandler[];
     populateFromGraph(graph: ModuleGraph, container: Container): Promise<void>;
     scanModule(moduleClass: Type, container: Container): Promise<void>;
@@ -380,6 +382,25 @@ declare class GatewayTimeoutException extends HttpException {
     constructor(message?: string, details?: unknown);
 }
 
+/**
+ * Resolve a handler ID as a module reference by dynamically importing
+ * the module and matching the exported function against the registry.
+ *
+ * Resolution strategy:
+ * 1. If the ID contains a dot, try splitting at the last dot into
+ *    `moduleName.exportName` (named export).
+ * 2. Fallback: treat the full ID as a module name with a default export.
+ *    This handles no-dot refs (e.g. "myModule") and dotted module names
+ *    (e.g. "app.module" from app.module.js) where the named export split failed.
+ *
+ * Supported formats:
+ * - `"handlers.hello"` — named export `hello` from module `handlers`
+ * - `"handlers"` — default export from module `handlers`
+ * - `"app.module"` — dotted module name: tries named export split first,
+ *   falls back to default export from module `app.module`
+ */
+declare function resolveHandlerByModuleRef(handlerId: string, registry: HandlerRegistry, baseDir: string): Promise<ResolvedHandler | null>;
+
 declare const CONTROLLER_METADATA: unique symbol;
 declare const HTTP_METHOD_METADATA: unique symbol;
 declare const ROUTE_PATH_METADATA: unique symbol;
@@ -408,11 +429,25 @@ declare function mapRuntimeRequest(request: Request): HttpRequest;
 /** Convert SDK HttpResponse → NAPI runtime Response. */
 declare function mapToRuntimeResponse(response: HttpResponse): Response;
 
+type RuntimeCallback = (err: Error | null, request: Request) => Promise<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;
+    createRouteCallback(path: string, method: string): RuntimeCallback | null;
+    /**
+     * Create a runtime-compatible handler callback by handler ID.
+     * First tries a direct registry lookup. If that fails, resolves the handler ID
+     * as a module reference by dynamically importing the module and matching the
+     * exported function against the registry.
+     *
+     * Supported formats:
+     * - `"handlers.hello"` — named export `hello` from module `handlers`
+     * - `"handlers"` — default export from module `handlers`
+     * - `"app.module"` — dotted module name: tries named export split first,
+     *   falls back to default export from module `app.module`
+     */
+    createRouteCallbackById(handlerId: string, codeLocation?: string): Promise<RuntimeCallback | null>;
 };
 /**
  * Bootstrap the user's module and return an object with per-route callback creation.
@@ -430,4 +465,4 @@ type StartRuntimeOptions = {
  */
 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 };
+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, resolveHandlerByModuleRef, runLayerPipeline, startRuntime, tokenToString, validate };

package/dist/index.d.ts

@@ -153,6 +153,7 @@ declare const APP_CONFIG: unique symbol;
 declare const RUNTIME_APP: unique symbol;
 
 type ResolvedHandler = {
+    id?: string;
     path?: string;
     method?: string;
     protectedBy: string[];
@@ -200,6 +201,7 @@ declare function registerModuleGraph(graph: ModuleGraph, container: Container):
 declare class HandlerRegistry {
     private handlers;
     getHandler(path: string, method: string): ResolvedHandler | undefined;
+    getHandlerById(id: string): ResolvedHandler | undefined;
     getAllHandlers(): ResolvedHandler[];
     populateFromGraph(graph: ModuleGraph, container: Container): Promise<void>;
     scanModule(moduleClass: Type, container: Container): Promise<void>;
@@ -380,6 +382,25 @@ declare class GatewayTimeoutException extends HttpException {
     constructor(message?: string, details?: unknown);
 }
 
+/**
+ * Resolve a handler ID as a module reference by dynamically importing
+ * the module and matching the exported function against the registry.
+ *
+ * Resolution strategy:
+ * 1. If the ID contains a dot, try splitting at the last dot into
+ *    `moduleName.exportName` (named export).
+ * 2. Fallback: treat the full ID as a module name with a default export.
+ *    This handles no-dot refs (e.g. "myModule") and dotted module names
+ *    (e.g. "app.module" from app.module.js) where the named export split failed.
+ *
+ * Supported formats:
+ * - `"handlers.hello"` — named export `hello` from module `handlers`
+ * - `"handlers"` — default export from module `handlers`
+ * - `"app.module"` — dotted module name: tries named export split first,
+ *   falls back to default export from module `app.module`
+ */
+declare function resolveHandlerByModuleRef(handlerId: string, registry: HandlerRegistry, baseDir: string): Promise<ResolvedHandler | null>;
+
 declare const CONTROLLER_METADATA: unique symbol;
 declare const HTTP_METHOD_METADATA: unique symbol;
 declare const ROUTE_PATH_METADATA: unique symbol;
@@ -408,11 +429,25 @@ declare function mapRuntimeRequest(request: Request): HttpRequest;
 /** Convert SDK HttpResponse → NAPI runtime Response. */
 declare function mapToRuntimeResponse(response: HttpResponse): Response;
 
+type RuntimeCallback = (err: Error | null, request: Request) => Promise<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;
+    createRouteCallback(path: string, method: string): RuntimeCallback | null;
+    /**
+     * Create a runtime-compatible handler callback by handler ID.
+     * First tries a direct registry lookup. If that fails, resolves the handler ID
+     * as a module reference by dynamically importing the module and matching the
+     * exported function against the registry.
+     *
+     * Supported formats:
+     * - `"handlers.hello"` — named export `hello` from module `handlers`
+     * - `"handlers"` — default export from module `handlers`
+     * - `"app.module"` — dotted module name: tries named export split first,
+     *   falls back to default export from module `app.module`
+     */
+    createRouteCallbackById(handlerId: string, codeLocation?: string): Promise<RuntimeCallback | null>;
 };
 /**
  * Bootstrap the user's module and return an object with per-route callback creation.
@@ -430,4 +465,4 @@ type StartRuntimeOptions = {
  */
 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 };
+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, resolveHandlerByModuleRef, runLayerPipeline, startRuntime, tokenToString, validate };

package/dist/index.js

@@ -1055,6 +1055,11 @@ var HandlerRegistry = class {
     debug4("getHandler %s %s \u2192 %s", method, path, found ? "matched" : "not found");
     return found;
   }
+  getHandlerById(id) {
+    const found = this.handlers.find((h) => h.id !== void 0 && h.id === id);
+    debug4("getHandlerById %s \u2192 %s", id, found ? "matched" : "not found");
+    return found;
+  }
   getAllHandlers() {
     return [
       ...this.handlers
@@ -1140,8 +1145,9 @@ var HandlerRegistry = class {
         layers.unshift(validate(schemas));
       }
     }
-    debug4("registerFunctionHandler: %s", meta.method && meta.path ? `${meta.method} ${meta.path}` : "(no route)");
+    debug4("registerFunctionHandler: %s", definition.id ?? (meta.method && meta.path ? `${meta.method} ${meta.path}` : "(no route)"));
     this.handlers.push({
+      id: definition.id,
       path: meta.path,
       method: meta.method,
       protectedBy: [],
@@ -1683,23 +1689,96 @@ function httpDelete(path, handlerOrOptions, maybeHandler) {
 }
 __name(httpDelete, "httpDelete");
 
-// src/bootstrap/discovery.ts
+// src/handlers/module-resolver.ts
 import { resolve } from "path";
 import createDebug9 from "debug";
-var debug9 = createDebug9("celerity:core:bootstrap");
+var debug9 = createDebug9("celerity:core:module-resolver");
+async function resolveHandlerByModuleRef(handlerId, registry, baseDir) {
+  const lastDot = handlerId.lastIndexOf(".");
+  if (lastDot > 0) {
+    const moduleName = handlerId.slice(0, lastDot);
+    const exportName = handlerId.slice(lastDot + 1);
+    const result = await tryResolveExport(baseDir, moduleName, exportName, handlerId, registry);
+    if (result) return result;
+  }
+  return tryResolveExport(baseDir, handlerId, "default", handlerId, registry);
+}
+__name(resolveHandlerByModuleRef, "resolveHandlerByModuleRef");
+async function tryResolveExport(baseDir, moduleName, exportName, handlerId, registry) {
+  const handlerModulePath = resolve(baseDir, moduleName);
+  let mod;
+  try {
+    mod = await import(handlerModulePath);
+  } catch {
+    try {
+      mod = await import(`${handlerModulePath}.js`);
+    } catch {
+      return null;
+    }
+  }
+  const exported = mod[exportName];
+  if (!exported) return null;
+  const isFnDef = typeof exported === "object" && exported !== null && exported.__celerity_handler;
+  const handlerFn = isFnDef ? exported.handler : exported;
+  if (typeof handlerFn !== "function") return null;
+  const match = registry.getAllHandlers().find((h) => h.handlerFn === handlerFn);
+  if (match) {
+    match.id = handlerId;
+    debug9("matched '%s' to registry handler", handlerId);
+    return match;
+  }
+  debug9("'%s' not in registry, wrapping directly", handlerId);
+  return buildResolvedFromExport(handlerId, handlerFn, isFnDef ? exported : null);
+}
+__name(tryResolveExport, "tryResolveExport");
+function buildResolvedFromExport(handlerId, handlerFn, fnDef) {
+  if (fnDef) {
+    const meta = fnDef.metadata;
+    return {
+      id: handlerId,
+      protectedBy: [],
+      layers: [
+        ...meta.layers ?? []
+      ],
+      isPublic: false,
+      paramMetadata: [],
+      customMetadata: meta.customMetadata ?? {},
+      handlerFn,
+      isFunctionHandler: true,
+      injectTokens: meta.inject ?? []
+    };
+  }
+  return {
+    id: handlerId,
+    protectedBy: [],
+    layers: [],
+    isPublic: false,
+    paramMetadata: [],
+    customMetadata: {},
+    handlerFn,
+    isFunctionHandler: true,
+    injectTokens: []
+  };
+}
+__name(buildResolvedFromExport, "buildResolvedFromExport");
+
+// src/bootstrap/discovery.ts
+import { resolve as resolve2 } from "path";
+import createDebug10 from "debug";
+var debug10 = createDebug10("celerity:core:bootstrap");
 async function discoverModule(modulePath) {
   const resolved = modulePath ?? process.env.CELERITY_MODULE_PATH;
   if (!resolved) {
     throw new Error("Cannot discover module: set CELERITY_MODULE_PATH environment variable or pass modulePath");
   }
-  const absolutePath = resolve(resolved);
-  debug9("discoverModule: importing %s", absolutePath);
+  const absolutePath = resolve2(resolved);
+  debug10("discoverModule: importing %s", absolutePath);
   const imported = await import(absolutePath);
   const rootModule = imported.default ?? findModuleExport(imported);
   if (!rootModule || typeof rootModule !== "function") {
     throw new Error(`No module class found in "${resolved}"`);
   }
-  debug9("discoverModule: found %s", rootModule.name);
+  debug10("discoverModule: found %s", rootModule.name);
   return rootModule;
 }
 __name(discoverModule, "discoverModule");
@@ -1755,24 +1834,37 @@ function mapToRuntimeResponse(response) {
 __name(mapToRuntimeResponse, "mapToRuntimeResponse");
 
 // src/bootstrap/runtime-entry.ts
+import { resolve as resolve3, dirname } from "path";
 async function bootstrapForRuntime(modulePath, systemLayers) {
   const layers = systemLayers ?? await createDefaultSystemLayers();
+  const resolvedModulePath = modulePath ?? process.env.CELERITY_MODULE_PATH;
+  const moduleDir = resolvedModulePath ? dirname(resolve3(resolvedModulePath)) : process.cwd();
   const rootModule = await discoverModule(modulePath);
   const { container, registry } = await bootstrap(rootModule);
+  function buildCallback(handler) {
+    if (!handler) return null;
+    return async (_err, request) => {
+      const httpRequest = mapRuntimeRequest(request);
+      const httpResponse = await executeHandlerPipeline(handler, httpRequest, {
+        container,
+        systemLayers: layers
+      });
+      return mapToRuntimeResponse(httpResponse);
+    };
+  }
+  __name(buildCallback, "buildCallback");
   return {
     registry,
     container,
     createRouteCallback(path, method) {
-      const handler = registry.getHandler(path, method);
-      if (!handler) return null;
-      return async (_err, request) => {
-        const httpRequest = mapRuntimeRequest(request);
-        const httpResponse = await executeHandlerPipeline(handler, httpRequest, {
-          container,
-          systemLayers: layers
-        });
-        return mapToRuntimeResponse(httpResponse);
-      };
+      return buildCallback(registry.getHandler(path, method));
+    },
+    async createRouteCallbackById(handlerId, codeLocation) {
+      const fromRegistry = registry.getHandlerById(handlerId);
+      if (fromRegistry) return buildCallback(fromRegistry);
+      const baseDir = codeLocation ? resolve3(codeLocation) : moduleDir;
+      const resolved = await resolveHandlerByModuleRef(handlerId, registry, baseDir);
+      return resolved ? buildCallback(resolved) : null;
     }
   };
 }
@@ -1787,7 +1879,7 @@ async function startRuntime(options) {
   const appConfig = app.setup();
   const result = await bootstrapForRuntime();
   for (const def of appConfig.api?.http?.handlers ?? []) {
-    const callback = result.createRouteCallback(def.path, def.method);
+    const callback = result.createRouteCallback(def.path, def.method) ?? await result.createRouteCallbackById(def.handler, def.location);
     if (callback) {
       app.registerHttpHandler(def.path, def.method, def.timeout, callback);
     }
@@ -1877,6 +1969,7 @@ export {
   mapToRuntimeResponse,
   mockRequest,
   registerModuleGraph,
+  resolveHandlerByModuleRef,
   runLayerPipeline,
   startRuntime,
   tokenToString,