@webpieces/http-server 0.2.12 → 0.2.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webpieces/http-server",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "WebPieces server with filter chain and dependency injection",
   "type": "commonjs",
   "main": "./src/index.js",
@@ -22,8 +22,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@webpieces/core-meta": "0.2.12",
-    "@webpieces/http-routing": "0.2.12",
-    "@webpieces/http-filters": "0.2.12"
+    "@webpieces/core-meta": "0.2.14",
+    "@webpieces/core-util": "0.2.14",
+    "@webpieces/http-routing": "0.2.14",
+    "@webpieces/http-filters": "0.2.14"
   }
 }

package/src/FilterMatcher.d.ts

@@ -1,5 +1,10 @@
-import { Filter } from '@webpieces/http-filters';
+import { Filter, WpResponse } from '@webpieces/http-filters';
+import { MethodMeta } from './MethodMeta';
 import { FilterDefinition } from '@webpieces/core-meta';
+/**
+ * Type alias for HTTP filters that work with MethodMeta and ResponseWrapper.
+ */
+export type HttpFilter = Filter<MethodMeta, WpResponse<unknown>>;
 /**
  * FilterMatcher - Matches filters to routes based on filepath patterns.
  * Similar to Java SharedMatchUtil.findMatchingFilters().
@@ -21,10 +26,7 @@ export declare class FilterMatcher {
      * @param allFilters - All registered filters with their definitions
      * @returns Array of matching filters, sorted by priority (highest first)
      */
-    static findMatchingFilters(controllerFilepath: string | undefined, allFilters: Array<{
-        filter: Filter;
-        definition: FilterDefinition;
-    }>): Filter[];
+    static findMatchingFilters(controllerFilepath: string | undefined, allFilters: Array<FilterDefinition>): HttpFilter[];
     /**
      * Normalize a controller filepath for consistent matching.
      * - Converts backslashes to forward slashes (Windows compatibility)

package/src/FilterMatcher.js

@@ -25,17 +25,18 @@ class FilterMatcher {
      */
     static findMatchingFilters(controllerFilepath, allFilters) {
         const matchingFilters = [];
-        for (const { filter, definition } of allFilters) {
+        for (const definition of allFilters) {
             const pattern = definition.filepathPattern;
+            const filter = definition.filter;
             // Special case: '*' matches all controllers (global filter)
             if (pattern === '*') {
-                matchingFilters.push({ filter, priority: filter.priority });
+                matchingFilters.push({ filter, priority: definition.priority });
                 continue;
             }
             // If no filepath available, only match wildcard patterns
             if (!controllerFilepath) {
                 if (pattern === '**/*') {
-                    matchingFilters.push({ filter, priority: filter.priority });
+                    matchingFilters.push({ filter, priority: definition.priority });
                 }
                 continue;
             }
@@ -43,7 +44,7 @@ class FilterMatcher {
             const normalizedPath = FilterMatcher.normalizeFilepath(controllerFilepath);
             // Match using minimatch
             if ((0, minimatch_1.minimatch)(normalizedPath, pattern)) {
-                matchingFilters.push({ filter, priority: filter.priority });
+                matchingFilters.push({ filter, priority: definition.priority });
             }
         }
         // Sort by priority (highest first)

package/src/FilterMatcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"FilterMatcher.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/FilterMatcher.ts"],"names":[],"mappings":";;;AAEA,yCAAsC;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAa,aAAa;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CACxB,kBAAsC,EACtC,UAAmE;QAEnE,MAAM,eAAe,GAAgD,EAAE,CAAC;QAExE,KAAK,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,UAAU,EAAE,CAAC;YAChD,MAAM,OAAO,GAAG,UAAU,CAAC,eAAe,CAAC;YAE3C,4DAA4D;YAC5D,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;gBACpB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;gBAC5D,SAAS;YACX,CAAC;YAED,yDAAyD;YACzD,IAAI,CAAC,kBAAkB,EAAE,CAAC;gBACxB,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;oBACvB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;gBAC9D,CAAC;gBACD,SAAS;YACX,CAAC;YAED,6CAA6C;YAC7C,MAAM,cAAc,GAAG,aAAa,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;YAE3E,wBAAwB;YACxB,IAAI,IAAA,qBAAS,EAAC,cAAc,EAAE,OAAO,CAAC,EAAE,CAAC;gBACvC,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;YAC9D,CAAC;QACH,CAAC;QAED,mCAAmC;QACnC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QAExD,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpD,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,iBAAiB,CAAC,QAAgB;QACvC,OAAO,QAAQ;aACZ,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,yCAAyC;aAC7D,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,sBAAsB;IACjD,CAAC;CACF;AA3DD,sCA2DC","sourcesContent":["import { Filter } from '@webpieces/http-filters';\nimport { FilterDefinition } from '@webpieces/core-meta';\nimport { minimatch } from 'minimatch';\n\n/**\n * FilterMatcher - Matches filters to routes based on filepath patterns.\n * Similar to Java SharedMatchUtil.findMatchingFilters().\n *\n * Responsibilities:\n * 1. Filter based on filepath glob pattern matching\n * 2. Sort matching filters by priority (higher first)\n *\n * Differences from Java:\n * - Uses glob patterns instead of regex\n * - Only matches filepaths (no URL path or HTTPS filtering yet)\n * - Simpler API focused on one responsibility\n */\nexport class FilterMatcher {\n  /**\n   * Find filters that match the given controller filepath.\n   *\n   * @param controllerFilepath - The filepath of the controller source file\n   * @param allFilters - All registered filters with their definitions\n   * @returns Array of matching filters, sorted by priority (highest first)\n   */\n  static findMatchingFilters(\n    controllerFilepath: string | undefined,\n    allFilters: Array<{ filter: Filter; definition: FilterDefinition }>\n  ): Filter[] {\n    const matchingFilters: Array<{ filter: Filter; priority: number }> = [];\n\n    for (const { filter, definition } of allFilters) {\n      const pattern = definition.filepathPattern;\n\n      // Special case: '*' matches all controllers (global filter)\n      if (pattern === '*') {\n        matchingFilters.push({ filter, priority: filter.priority });\n        continue;\n      }\n\n      // If no filepath available, only match wildcard patterns\n      if (!controllerFilepath) {\n        if (pattern === '**/*') {\n          matchingFilters.push({ filter, priority: filter.priority });\n        }\n        continue;\n      }\n\n      // Normalize filepath for consistent matching\n      const normalizedPath = FilterMatcher.normalizeFilepath(controllerFilepath);\n\n      // Match using minimatch\n      if (minimatch(normalizedPath, pattern)) {\n        matchingFilters.push({ filter, priority: filter.priority });\n      }\n    }\n\n    // Sort by priority (highest first)\n    matchingFilters.sort((a, b) => b.priority - a.priority);\n\n    return matchingFilters.map((item) => item.filter);\n  }\n\n  /**\n   * Normalize a controller filepath for consistent matching.\n   * - Converts backslashes to forward slashes (Windows compatibility)\n   * - Removes leading './'\n   *\n   * @param filepath - Raw filepath\n   * @returns Normalized filepath\n   */\n  static normalizeFilepath(filepath: string): string {\n    return filepath\n      .replace(/\\\\/g, '/') // Windows backslashes to forward slashes\n      .replace(/^\\.\\//, ''); // Remove leading './'\n  }\n}\n"]}
+{"version":3,"file":"FilterMatcher.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/FilterMatcher.ts"],"names":[],"mappings":";;;AAGA,yCAAsC;AAOtC;;;;;;;;;;;;GAYG;AACH,MAAa,aAAa;IACxB;;;;;;OAMG;IACH,MAAM,CAAC,mBAAmB,CACxB,kBAAsC,EACtC,UAAmC;QAEnC,MAAM,eAAe,GAAoD,EAAE,CAAC;QAE5E,KAAK,MAAM,UAAU,IAAI,UAAU,EAAE,CAAC;YACpC,MAAM,OAAO,GAAG,UAAU,CAAC,eAAe,CAAC;YAC3C,MAAM,MAAM,GAAG,UAAU,CAAC,MAAoB,CAAC;YAE/C,4DAA4D;YAC5D,IAAI,OAAO,KAAK,GAAG,EAAE,CAAC;gBACpB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;gBAChE,SAAS;YACX,CAAC;YAED,yDAAyD;YACzD,IAAI,CAAC,kBAAkB,EAAE,CAAC;gBACxB,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;oBACvB,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;gBAClE,CAAC;gBACD,SAAS;YACX,CAAC;YAED,6CAA6C;YAC7C,MAAM,cAAc,GAAG,aAAa,CAAC,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;YAE3E,wBAAwB;YACxB,IAAI,IAAA,qBAAS,EAAC,cAAc,EAAE,OAAO,CAAC,EAAE,CAAC;gBACvC,eAAe,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC;YAClE,CAAC;QACH,CAAC;QAED,mCAAmC;QACnC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;QAExD,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACpD,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,iBAAiB,CAAC,QAAgB;QACvC,OAAO,QAAQ;aACZ,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,yCAAyC;aAC7D,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,sBAAsB;IACjD,CAAC;CACF;AA5DD,sCA4DC","sourcesContent":["import { Filter, WpResponse } from '@webpieces/http-filters';\nimport { MethodMeta } from './MethodMeta';\nimport { FilterDefinition } from '@webpieces/core-meta';\nimport { minimatch } from 'minimatch';\n\n/**\n * Type alias for HTTP filters that work with MethodMeta and ResponseWrapper.\n */\nexport type HttpFilter = Filter<MethodMeta, WpResponse<unknown>>;\n\n/**\n * FilterMatcher - Matches filters to routes based on filepath patterns.\n * Similar to Java SharedMatchUtil.findMatchingFilters().\n *\n * Responsibilities:\n * 1. Filter based on filepath glob pattern matching\n * 2. Sort matching filters by priority (higher first)\n *\n * Differences from Java:\n * - Uses glob patterns instead of regex\n * - Only matches filepaths (no URL path or HTTPS filtering yet)\n * - Simpler API focused on one responsibility\n */\nexport class FilterMatcher {\n  /**\n   * Find filters that match the given controller filepath.\n   *\n   * @param controllerFilepath - The filepath of the controller source file\n   * @param allFilters - All registered filters with their definitions\n   * @returns Array of matching filters, sorted by priority (highest first)\n   */\n  static findMatchingFilters(\n    controllerFilepath: string | undefined,\n    allFilters: Array<FilterDefinition>\n  ): HttpFilter[] {\n    const matchingFilters: Array<{ filter: HttpFilter; priority: number }> = [];\n\n    for (const definition of allFilters) {\n      const pattern = definition.filepathPattern;\n      const filter = definition.filter as HttpFilter;\n\n      // Special case: '*' matches all controllers (global filter)\n      if (pattern === '*') {\n        matchingFilters.push({ filter, priority: definition.priority });\n        continue;\n      }\n\n      // If no filepath available, only match wildcard patterns\n      if (!controllerFilepath) {\n        if (pattern === '**/*') {\n          matchingFilters.push({ filter, priority: definition.priority });\n        }\n        continue;\n      }\n\n      // Normalize filepath for consistent matching\n      const normalizedPath = FilterMatcher.normalizeFilepath(controllerFilepath);\n\n      // Match using minimatch\n      if (minimatch(normalizedPath, pattern)) {\n        matchingFilters.push({ filter, priority: definition.priority });\n      }\n    }\n\n    // Sort by priority (highest first)\n    matchingFilters.sort((a, b) => b.priority - a.priority);\n\n    return matchingFilters.map((item) => item.filter);\n  }\n\n  /**\n   * Normalize a controller filepath for consistent matching.\n   * - Converts backslashes to forward slashes (Windows compatibility)\n   * - Removes leading './'\n   *\n   * @param filepath - Raw filepath\n   * @returns Normalized filepath\n   */\n  static normalizeFilepath(filepath: string): string {\n    return filepath\n      .replace(/\\\\/g, '/') // Windows backslashes to forward slashes\n      .replace(/^\\.\\//, ''); // Remove leading './'\n  }\n}\n"]}

package/src/MethodMeta.d.ts

@@ -0,0 +1,42 @@
+import { RouteMetadata2, RouteRequest } from '@webpieces/core-meta';
+/**
+ * Metadata about the method being invoked.
+ * Passed to filters and contains request information.
+ *
+ * MethodMeta is created by WebpiecesServerImpl when handling a request:
+ * - routeMeta: Static route information (httpMethod, path, methodName)
+ * - routeRequest: Express Request/Response objects
+ * - requestDto: Set by JsonFilter after deserializing the request body
+ */
+export declare class MethodMeta {
+    /**
+     * Route metadata (httpMethod, path, methodName, parameterTypes)
+     */
+    routeMeta: RouteMetadata2;
+    /**
+     * Express Request and Response objects
+     */
+    routeRequest: RouteRequest;
+    /**
+     * The deserialized request DTO.
+     * Set by JsonFilter after deserializing the request body.
+     */
+    requestDto?: unknown;
+    /**
+     * Additional metadata for storing request-scoped data.
+     */
+    metadata: Map<string, unknown>;
+    constructor(routeMeta: RouteMetadata2, routeRequest: RouteRequest, requestDto?: unknown, metadata?: Map<string, unknown>);
+    /**
+     * Get the HTTP method (convenience accessor).
+     */
+    get httpMethod(): string;
+    /**
+     * Get the request path (convenience accessor).
+     */
+    get path(): string;
+    /**
+     * Get the method name (convenience accessor).
+     */
+    get methodName(): string;
+}

package/src/MethodMeta.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MethodMeta = void 0;
+/**
+ * Metadata about the method being invoked.
+ * Passed to filters and contains request information.
+ *
+ * MethodMeta is created by WebpiecesServerImpl when handling a request:
+ * - routeMeta: Static route information (httpMethod, path, methodName)
+ * - routeRequest: Express Request/Response objects
+ * - requestDto: Set by JsonFilter after deserializing the request body
+ */
+class MethodMeta {
+    constructor(routeMeta, routeRequest, requestDto, metadata) {
+        this.routeMeta = routeMeta;
+        this.routeRequest = routeRequest;
+        this.requestDto = requestDto;
+        this.metadata = metadata ?? new Map();
+    }
+    /**
+     * Get the HTTP method (convenience accessor).
+     */
+    get httpMethod() {
+        return this.routeMeta.httpMethod;
+    }
+    /**
+     * Get the request path (convenience accessor).
+     */
+    get path() {
+        return this.routeMeta.path;
+    }
+    /**
+     * Get the method name (convenience accessor).
+     */
+    get methodName() {
+        return this.routeMeta.methodName;
+    }
+}
+exports.MethodMeta = MethodMeta;
+//# sourceMappingURL=MethodMeta.js.map

package/src/MethodMeta.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MethodMeta.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/MethodMeta.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;GAQG;AACH,MAAa,UAAU;IAsBrB,YACE,SAAyB,EACzB,YAA0B,EAC1B,UAAoB,EACpB,QAA+B;QAE/B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,QAAQ,GAAG,QAAQ,IAAI,IAAI,GAAG,EAAE,CAAC;IACxC,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACnC,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC;IACnC,CAAC;CACF;AAtDD,gCAsDC","sourcesContent":["import { RouteMetadata2, RouteRequest } from '@webpieces/core-meta';\n\n/**\n * Metadata about the method being invoked.\n * Passed to filters and contains request information.\n *\n * MethodMeta is created by WebpiecesServerImpl when handling a request:\n * - routeMeta: Static route information (httpMethod, path, methodName)\n * - routeRequest: Express Request/Response objects\n * - requestDto: Set by JsonFilter after deserializing the request body\n */\nexport class MethodMeta {\n  /**\n   * Route metadata (httpMethod, path, methodName, parameterTypes)\n   */\n  routeMeta: RouteMetadata2;\n\n  /**\n   * Express Request and Response objects\n   */\n  routeRequest: RouteRequest;\n\n  /**\n   * The deserialized request DTO.\n   * Set by JsonFilter after deserializing the request body.\n   */\n  requestDto?: unknown;\n\n  /**\n   * Additional metadata for storing request-scoped data.\n   */\n  metadata: Map<string, unknown>;\n\n  constructor(\n    routeMeta: RouteMetadata2,\n    routeRequest: RouteRequest,\n    requestDto?: unknown,\n    metadata?: Map<string, unknown>\n  ) {\n    this.routeMeta = routeMeta;\n    this.routeRequest = routeRequest;\n    this.requestDto = requestDto;\n    this.metadata = metadata ?? new Map();\n  }\n\n  /**\n   * Get the HTTP method (convenience accessor).\n   */\n  get httpMethod(): string {\n    return this.routeMeta.httpMethod;\n  }\n\n  /**\n   * Get the request path (convenience accessor).\n   */\n  get path(): string {\n    return this.routeMeta.path;\n  }\n\n  /**\n   * Get the method name (convenience accessor).\n   */\n  get methodName(): string {\n    return this.routeMeta.methodName;\n  }\n}\n"]}

package/src/RouteBuilderImpl.d.ts

@@ -1,21 +1,32 @@
 import { Container } from 'inversify';
-import { RouteBuilder, RouteDefinition, FilterDefinition, RouteHandler } from '@webpieces/core-meta';
-import { Filter } from '@webpieces/http-filters';
-import { RouteMetadata } from '@webpieces/http-api';
+import { RouteBuilder, RouteDefinition, FilterDefinition } from '@webpieces/core-meta';
+import { Filter, WpResponse } from '@webpieces/http-filters';
+import { RouteHandler } from './RouteHandler';
+import { MethodMeta } from './MethodMeta';
 /**
- * Registered route entry in the route registry.
- *
- * We use unknown instead of any for better type safety:
- * - unknown forces type checking at usage points
- * - any allows unsafe operations without checks
+ * Type alias for HTTP filters that work with MethodMeta and ResponseWrapper.
+ */
+export type HttpFilter = Filter<MethodMeta, WpResponse<unknown>>;
+/**
+ * FilterWithMeta - Pairs a resolved filter instance with its definition.
+ * Stores both the DI-resolved filter and the metadata needed for matching.
+ */
+export declare class FilterWithMeta {
+    filter: HttpFilter;
+    definition: FilterDefinition;
+    constructor(filter: HttpFilter, definition: FilterDefinition);
+}
+/**
+ * RouteHandlerWithMeta - Pairs a route handler with its definition.
+ * Stores both the handler (which wraps the DI-resolved controller) and the route metadata.
  *
- * Each route has its own TResult type, but we can't store different
- * generic types in the same Map, so we use unknown as a type-safe escape hatch.
+ * We use unknown for the generic type since we store different TResult types in the same Map.
+ * Type safety is maintained through the generic on RouteDefinition at registration time.
  */
-export declare class RegisteredRoute<TResult = unknown> extends RouteDefinition<TResult> {
-    routeMetadata?: RouteMetadata;
-    controllerClass?: any;
-    constructor(method: string, path: string, handler: RouteHandler<TResult>, controllerFilepath?: string, routeMetadata?: RouteMetadata, controllerClass?: any);
+export declare class RouteHandlerWithMeta {
+    handler: RouteHandler<unknown>;
+    definition: RouteDefinition<unknown>;
+    constructor(handler: RouteHandler<unknown>, definition: RouteDefinition<unknown>);
 }
 /**
  * RouteBuilderImpl - Concrete implementation of RouteBuilder interface.
@@ -28,39 +39,52 @@ export declare class RegisteredRoute<TResult = unknown> extends RouteDefinition<
  * - Improve traceability and debugging
  * - Make the code easier to understand
  * - Enable better IDE navigation (Cmd+Click on addRoute works!)
+ *
+ * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()
+ * but needs appContainer to resolve filters/controllers. The container is set via
+ * setContainer() after appContainer is created (late binding pattern).
  */
 export declare class RouteBuilderImpl implements RouteBuilder {
     private routes;
     private filterRegistry;
-    private container;
+    private container?;
     /**
-     * Create a new RouteBuilder.
+     * Set the DI container used for resolving filters and controllers.
+     * Called by WebpiecesCoreServer after appContainer is created.
      *
-     * @param routes - Map to store registered routes (keyed by "METHOD:path")
-     * @param filterRegistry - Array to store registered filters with their definitions
-     * @param container - DI container for resolving filter instances
+     * @param container - The application DI container (appContainer)
      */
-    constructor(routes: Map<string, RegisteredRoute<unknown>>, filterRegistry: Array<{
-        filter: Filter;
-        definition: FilterDefinition;
-    }>, container: Container);
+    setContainer(container: Container): void;
     /**
      * Register a route with the router.
      *
+     * Resolves the controller from DI container ONCE and creates a handler that uses
+     * the resolved controller instance. This is more efficient than resolving on every request.
+     *
      * The route is stored with a key of "METHOD:path" (e.g., "POST:/search/item").
-     * The TResult generic ensures type safety for the route's return type.
      *
-     * @param route - Route definition with method, path, and handler
+     * @param route - Route definition with controller class and method name
      */
     addRoute<TResult = unknown>(route: RouteDefinition<TResult>): void;
     /**
      * Register a filter with the filter chain.
      *
-     * Filters are resolved from the DI container and stored with their definitions.
+     * Resolves the filter from DI container and pairs it with the filter definition.
      * The definition includes pattern information used for route-specific filtering.
-     * Filters will be matched and executed in priority order (higher priority first).
      *
      * @param filterDef - Filter definition with priority, filter class, and optional filepath pattern
      */
     addFilter(filterDef: FilterDefinition): void;
+    /**
+     * Get all registered routes.
+     *
+     * @returns Map of routes with handlers and definitions, keyed by "METHOD:path"
+     */
+    getRoutes(): Map<string, RouteHandlerWithMeta>;
+    /**
+     * Get all filters sorted by priority (highest priority first).
+     *
+     * @returns Array of FilterWithMeta sorted by priority
+     */
+    getSortedFilters(): Array<FilterWithMeta>;
 }

package/src/RouteBuilderImpl.js

@@ -1,25 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RouteBuilderImpl = exports.RegisteredRoute = void 0;
-const core_meta_1 = require("@webpieces/core-meta");
+exports.RouteBuilderImpl = exports.RouteHandlerWithMeta = exports.FilterWithMeta = void 0;
+const tslib_1 = require("tslib");
+const inversify_1 = require("inversify");
+const http_routing_1 = require("@webpieces/http-routing");
+const RouteHandler_1 = require("./RouteHandler");
 /**
- * Registered route entry in the route registry.
- *
- * We use unknown instead of any for better type safety:
- * - unknown forces type checking at usage points
- * - any allows unsafe operations without checks
+ * FilterWithMeta - Pairs a resolved filter instance with its definition.
+ * Stores both the DI-resolved filter and the metadata needed for matching.
+ */
+class FilterWithMeta {
+    constructor(filter, definition) {
+        this.filter = filter;
+        this.definition = definition;
+    }
+}
+exports.FilterWithMeta = FilterWithMeta;
+/**
+ * RouteHandlerWithMeta - Pairs a route handler with its definition.
+ * Stores both the handler (which wraps the DI-resolved controller) and the route metadata.
  *
- * Each route has its own TResult type, but we can't store different
- * generic types in the same Map, so we use unknown as a type-safe escape hatch.
+ * We use unknown for the generic type since we store different TResult types in the same Map.
+ * Type safety is maintained through the generic on RouteDefinition at registration time.
  */
-class RegisteredRoute extends core_meta_1.RouteDefinition {
-    constructor(method, path, handler, controllerFilepath, routeMetadata, controllerClass) {
-        super(method, path, handler, controllerFilepath);
-        this.routeMetadata = routeMetadata;
-        this.controllerClass = controllerClass;
+class RouteHandlerWithMeta {
+    constructor(handler, definition) {
+        this.handler = handler;
+        this.definition = definition;
     }
 }
-exports.RegisteredRoute = RegisteredRoute;
+exports.RouteHandlerWithMeta = RouteHandlerWithMeta;
 /**
  * RouteBuilderImpl - Concrete implementation of RouteBuilder interface.
  *
@@ -31,51 +41,101 @@ exports.RegisteredRoute = RegisteredRoute;
  * - Improve traceability and debugging
  * - Make the code easier to understand
  * - Enable better IDE navigation (Cmd+Click on addRoute works!)
+ *
+ * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()
+ * but needs appContainer to resolve filters/controllers. The container is set via
+ * setContainer() after appContainer is created (late binding pattern).
  */
-class RouteBuilderImpl {
+let RouteBuilderImpl = class RouteBuilderImpl {
+    constructor() {
+        this.routes = new Map();
+        this.filterRegistry = [];
+    }
     /**
-     * Create a new RouteBuilder.
+     * Set the DI container used for resolving filters and controllers.
+     * Called by WebpiecesCoreServer after appContainer is created.
      *
-     * @param routes - Map to store registered routes (keyed by "METHOD:path")
-     * @param filterRegistry - Array to store registered filters with their definitions
-     * @param container - DI container for resolving filter instances
+     * @param container - The application DI container (appContainer)
      */
-    constructor(routes, filterRegistry, container) {
-        this.routes = routes;
-        this.filterRegistry = filterRegistry;
+    setContainer(container) {
         this.container = container;
     }
     /**
      * Register a route with the router.
      *
+     * Resolves the controller from DI container ONCE and creates a handler that uses
+     * the resolved controller instance. This is more efficient than resolving on every request.
+     *
      * The route is stored with a key of "METHOD:path" (e.g., "POST:/search/item").
-     * The TResult generic ensures type safety for the route's return type.
      *
-     * @param route - Route definition with method, path, and handler
+     * @param route - Route definition with controller class and method name
      */
     addRoute(route) {
-        const key = `${route.method}:${route.path}`;
-        // Store as RegisteredRoute<unknown> in the map
-        // Type safety is maintained through the generic on RouteDefinition
-        this.routes.set(key, route);
+        if (!this.container) {
+            throw new Error('Container not set. Call setContainer() before registering routes.');
+        }
+        const routeMeta = route.routeMeta;
+        const key = `${routeMeta.httpMethod}:${routeMeta.path}`;
+        // Resolve controller instance from DI container ONCE (not on every request!)
+        const controller = this.container.get(route.controllerClass);
+        // Get the controller method
+        const method = controller[routeMeta.methodName];
+        if (typeof method !== 'function') {
+            const controllerName = route.controllerClass.name || 'Unknown';
+            throw new Error(`Method ${routeMeta.methodName} not found on controller ${controllerName}`);
+        }
+        // Create handler that uses the resolved controller instance
+        const handler = new class extends RouteHandler_1.RouteHandler {
+            async execute(meta) {
+                // Invoke the method with requestDto from meta
+                // The controller is already resolved - no DI lookup on every request!
+                // Pass requestDto as the single argument to the controller method
+                const result = await method.call(controller, meta.requestDto);
+                return result;
+            }
+        };
+        // Store handler with route definition
+        const routeWithMeta = new RouteHandlerWithMeta(handler, route);
+        this.routes.set(key, routeWithMeta);
     }
     /**
      * Register a filter with the filter chain.
      *
-     * Filters are resolved from the DI container and stored with their definitions.
+     * Resolves the filter from DI container and pairs it with the filter definition.
      * The definition includes pattern information used for route-specific filtering.
-     * Filters will be matched and executed in priority order (higher priority first).
      *
      * @param filterDef - Filter definition with priority, filter class, and optional filepath pattern
      */
     addFilter(filterDef) {
+        if (!this.container) {
+            throw new Error('Container not set. Call setContainer() before registering filters.');
+        }
         // Resolve filter instance from DI container
         const filter = this.container.get(filterDef.filterClass);
-        // Set priority on the filter instance
-        filter.priority = filterDef.priority;
-        // Store both filter instance and definition for pattern matching
-        this.filterRegistry.push({ filter, definition: filterDef });
+        // Store filter with its definition
+        const filterWithMeta = new FilterWithMeta(filter, filterDef);
+        this.filterRegistry.push(filterWithMeta);
     }
-}
+    /**
+     * Get all registered routes.
+     *
+     * @returns Map of routes with handlers and definitions, keyed by "METHOD:path"
+     */
+    getRoutes() {
+        return this.routes;
+    }
+    /**
+     * Get all filters sorted by priority (highest priority first).
+     *
+     * @returns Array of FilterWithMeta sorted by priority
+     */
+    getSortedFilters() {
+        return [...this.filterRegistry].sort((a, b) => b.definition.priority - a.definition.priority);
+    }
+};
 exports.RouteBuilderImpl = RouteBuilderImpl;
+exports.RouteBuilderImpl = RouteBuilderImpl = tslib_1.__decorate([
+    (0, http_routing_1.provideSingleton)(),
+    (0, inversify_1.injectable)()
+], RouteBuilderImpl);
 //# sourceMappingURL=RouteBuilderImpl.js.map

package/src/RouteBuilderImpl.js.map

@@ -1 +1 @@
-{"version":3,"file":"RouteBuilderImpl.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/RouteBuilderImpl.ts"],"names":[],"mappings":";;;AACA,oDAAqG;AAIrG;;;;;;;;;GASG;AACH,MAAa,eAAmC,SAAQ,2BAAwB;IAI9E,YACE,MAAc,EACd,IAAY,EACZ,OAA8B,EAC9B,kBAA2B,EAC3B,aAA6B,EAC7B,eAAqB;QAErB,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,kBAAkB,CAAC,CAAC;QACjD,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;IACzC,CAAC;CACF;AAhBD,0CAgBC;AAED;;;;;;;;;;;GAWG;AACH,MAAa,gBAAgB;IAK3B;;;;;;OAMG;IACH,YACE,MAA6C,EAC7C,cAAuE,EACvE,SAAoB;QAEpB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;QACrC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;IAED;;;;;;;OAOG;IACH,QAAQ,CAAoB,KAA+B;QACzD,MAAM,GAAG,GAAG,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAE5C,+CAA+C;QAC/C,mEAAmE;QACnE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAiC,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;;;OAQG;IACH,SAAS,CAAC,SAA2B;QACnC,4CAA4C;QAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAS,SAAS,CAAC,WAAW,CAAC,CAAC;QAEjE,sCAAsC;QACtC,MAAM,CAAC,QAAQ,GAAG,SAAS,CAAC,QAAQ,CAAC;QAErC,iEAAiE;QACjE,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IAC9D,CAAC;CACF;AAzDD,4CAyDC","sourcesContent":["import { Container } from 'inversify';\nimport { RouteBuilder, RouteDefinition, FilterDefinition, RouteHandler } from '@webpieces/core-meta';\nimport { Filter } from '@webpieces/http-filters';\nimport { RouteMetadata } from '@webpieces/http-api';\n\n/**\n * Registered route entry in the route registry.\n *\n * We use unknown instead of any for better type safety:\n * - unknown forces type checking at usage points\n * - any allows unsafe operations without checks\n *\n * Each route has its own TResult type, but we can't store different\n * generic types in the same Map, so we use unknown as a type-safe escape hatch.\n */\nexport class RegisteredRoute<TResult = unknown> extends RouteDefinition<TResult> {\n  routeMetadata?: RouteMetadata;\n  controllerClass?: any;\n\n  constructor(\n    method: string,\n    path: string,\n    handler: RouteHandler<TResult>,\n    controllerFilepath?: string,\n    routeMetadata?: RouteMetadata,\n    controllerClass?: any\n  ) {\n    super(method, path, handler, controllerFilepath);\n    this.routeMetadata = routeMetadata;\n    this.controllerClass = controllerClass;\n  }\n}\n\n/**\n * RouteBuilderImpl - Concrete implementation of RouteBuilder interface.\n *\n * Similar to Java WebPieces RouteBuilder, this class is responsible for:\n * 1. Registering routes with their handlers\n * 2. Registering filters with priority\n *\n * This class is explicit (not anonymous) to:\n * - Improve traceability and debugging\n * - Make the code easier to understand\n * - Enable better IDE navigation (Cmd+Click on addRoute works!)\n */\nexport class RouteBuilderImpl implements RouteBuilder {\n  private routes: Map<string, RegisteredRoute<unknown>>;\n  private filterRegistry: Array<{ filter: Filter; definition: FilterDefinition }>;\n  private container: Container;\n\n  /**\n   * Create a new RouteBuilder.\n   *\n   * @param routes - Map to store registered routes (keyed by \"METHOD:path\")\n   * @param filterRegistry - Array to store registered filters with their definitions\n   * @param container - DI container for resolving filter instances\n   */\n  constructor(\n    routes: Map<string, RegisteredRoute<unknown>>,\n    filterRegistry: Array<{ filter: Filter; definition: FilterDefinition }>,\n    container: Container\n  ) {\n    this.routes = routes;\n    this.filterRegistry = filterRegistry;\n    this.container = container;\n  }\n\n  /**\n   * Register a route with the router.\n   *\n   * The route is stored with a key of \"METHOD:path\" (e.g., \"POST:/search/item\").\n   * The TResult generic ensures type safety for the route's return type.\n   *\n   * @param route - Route definition with method, path, and handler\n   */\n  addRoute<TResult = unknown>(route: RouteDefinition<TResult>): void {\n    const key = `${route.method}:${route.path}`;\n\n    // Store as RegisteredRoute<unknown> in the map\n    // Type safety is maintained through the generic on RouteDefinition\n    this.routes.set(key, route as RegisteredRoute<unknown>);\n  }\n\n  /**\n   * Register a filter with the filter chain.\n   *\n   * Filters are resolved from the DI container and stored with their definitions.\n   * The definition includes pattern information used for route-specific filtering.\n   * Filters will be matched and executed in priority order (higher priority first).\n   *\n   * @param filterDef - Filter definition with priority, filter class, and optional filepath pattern\n   */\n  addFilter(filterDef: FilterDefinition): void {\n    // Resolve filter instance from DI container\n    const filter = this.container.get<Filter>(filterDef.filterClass);\n\n    // Set priority on the filter instance\n    filter.priority = filterDef.priority;\n\n    // Store both filter instance and definition for pattern matching\n    this.filterRegistry.push({ filter, definition: filterDef });\n  }\n}\n"]}
+{"version":3,"file":"RouteBuilderImpl.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/RouteBuilderImpl.ts"],"names":[],"mappings":"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","sourcesContent":["import { Container, injectable } from 'inversify';\nimport { RouteBuilder, RouteDefinition, FilterDefinition } from '@webpieces/core-meta';\nimport { Filter, WpResponse } from '@webpieces/http-filters';\nimport { provideSingleton } from '@webpieces/http-routing';\nimport { RouteHandler } from './RouteHandler';\nimport { MethodMeta } from './MethodMeta';\n\n/**\n * Type alias for HTTP filters that work with MethodMeta and ResponseWrapper.\n */\nexport type HttpFilter = Filter<MethodMeta, WpResponse<unknown>>;\n\n/**\n * FilterWithMeta - Pairs a resolved filter instance with its definition.\n * Stores both the DI-resolved filter and the metadata needed for matching.\n */\nexport class FilterWithMeta {\n  constructor(\n    public filter: HttpFilter,\n    public definition: FilterDefinition\n  ) {}\n}\n\n/**\n * RouteHandlerWithMeta - Pairs a route handler with its definition.\n * Stores both the handler (which wraps the DI-resolved controller) and the route metadata.\n *\n * We use unknown for the generic type since we store different TResult types in the same Map.\n * Type safety is maintained through the generic on RouteDefinition at registration time.\n */\nexport class RouteHandlerWithMeta {\n  constructor(\n    public handler: RouteHandler<unknown>,\n    public definition: RouteDefinition<unknown>\n  ) {}\n}\n\n/**\n * RouteBuilderImpl - Concrete implementation of RouteBuilder interface.\n *\n * Similar to Java WebPieces RouteBuilder, this class is responsible for:\n * 1. Registering routes with their handlers\n * 2. Registering filters with priority\n *\n * This class is explicit (not anonymous) to:\n * - Improve traceability and debugging\n * - Make the code easier to understand\n * - Enable better IDE navigation (Cmd+Click on addRoute works!)\n *\n * DI Pattern: This class is registered in webpiecesContainer via @provideSingleton()\n * but needs appContainer to resolve filters/controllers. The container is set via\n * setContainer() after appContainer is created (late binding pattern).\n */\n@provideSingleton()\n@injectable()\nexport class RouteBuilderImpl implements RouteBuilder {\n  private routes: Map<string, RouteHandlerWithMeta> = new Map();\n  private filterRegistry: Array<FilterWithMeta> = [];\n  private container?: Container;\n\n  /**\n   * Set the DI container used for resolving filters and controllers.\n   * Called by WebpiecesCoreServer after appContainer is created.\n   *\n   * @param container - The application DI container (appContainer)\n   */\n  setContainer(container: Container): void {\n    this.container = container;\n  }\n\n  /**\n   * Register a route with the router.\n   *\n   * Resolves the controller from DI container ONCE and creates a handler that uses\n   * the resolved controller instance. This is more efficient than resolving on every request.\n   *\n   * The route is stored with a key of \"METHOD:path\" (e.g., \"POST:/search/item\").\n   *\n   * @param route - Route definition with controller class and method name\n   */\n  addRoute<TResult = unknown>(route: RouteDefinition<TResult>): void {\n    if (!this.container) {\n      throw new Error('Container not set. Call setContainer() before registering routes.');\n    }\n\n    const routeMeta = route.routeMeta;\n\n    const key = `${routeMeta.httpMethod}:${routeMeta.path}`;\n\n    // Resolve controller instance from DI container ONCE (not on every request!)\n    const controller = this.container.get(route.controllerClass);\n\n    // Get the controller method\n    const method = (controller as Record<string, unknown>)[routeMeta.methodName];\n    if (typeof method !== 'function') {\n      const controllerName = (route.controllerClass as { name?: string }).name || 'Unknown';\n      throw new Error(\n        `Method ${routeMeta.methodName} not found on controller ${controllerName}`\n      );\n    }\n\n    // Create handler that uses the resolved controller instance\n    const handler = new class extends RouteHandler<TResult> {\n      async execute(meta: MethodMeta): Promise<TResult> {\n        // Invoke the method with requestDto from meta\n        // The controller is already resolved - no DI lookup on every request!\n        // Pass requestDto as the single argument to the controller method\n        const result: TResult = await method.call(controller, meta.requestDto);\n        return result;\n      }\n    };\n\n    // Store handler with route definition\n    const routeWithMeta = new RouteHandlerWithMeta(\n      handler as RouteHandler<unknown>,\n      route as RouteDefinition<unknown>\n    );\n\n    this.routes.set(key, routeWithMeta);\n  }\n\n  /**\n   * Register a filter with the filter chain.\n   *\n   * Resolves the filter from DI container and pairs it with the filter definition.\n   * The definition includes pattern information used for route-specific filtering.\n   *\n   * @param filterDef - Filter definition with priority, filter class, and optional filepath pattern\n   */\n  addFilter(filterDef: FilterDefinition): void {\n    if (!this.container) {\n      throw new Error('Container not set. Call setContainer() before registering filters.');\n    }\n\n    // Resolve filter instance from DI container\n    const filter = this.container.get<HttpFilter>(filterDef.filterClass);\n\n    // Store filter with its definition\n    const filterWithMeta = new FilterWithMeta(filter, filterDef);\n    this.filterRegistry.push(filterWithMeta);\n  }\n\n  /**\n   * Get all registered routes.\n   *\n   * @returns Map of routes with handlers and definitions, keyed by \"METHOD:path\"\n   */\n  getRoutes(): Map<string, RouteHandlerWithMeta> {\n    return this.routes;\n  }\n\n  /**\n   * Get all filters sorted by priority (highest priority first).\n   *\n   * @returns Array of FilterWithMeta sorted by priority\n   */\n  getSortedFilters(): Array<FilterWithMeta> {\n    return [...this.filterRegistry].sort((a, b) => b.definition.priority - a.definition.priority);\n  }\n}\n"]}

package/src/RouteHandler.d.ts

@@ -0,0 +1,22 @@
+import { MethodMeta } from './MethodMeta';
+/**
+ * Handler class for routes.
+ * Takes a MethodMeta and returns the controller method result.
+ *
+ * Generic type parameter TResult represents the return type of the controller method.
+ * Example: RouteHandler<SaveResponse> for a method that returns Promise<SaveResponse>
+ *
+ * Using unknown as default instead of any forces type safety - consumers must
+ * handle the result appropriately rather than assuming any type.
+ *
+ * This is a class instead of a function type to make it easier to trace
+ * who is calling what in the debugger/IDE.
+ */
+export declare abstract class RouteHandler<TResult = unknown> {
+    /**
+     * Execute the route handler.
+     * @param meta - The method metadata containing request info and params
+     * @returns Promise of the controller method result
+     */
+    abstract execute(meta: MethodMeta): Promise<TResult>;
+}

package/src/RouteHandler.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RouteHandler = void 0;
+/**
+ * Handler class for routes.
+ * Takes a MethodMeta and returns the controller method result.
+ *
+ * Generic type parameter TResult represents the return type of the controller method.
+ * Example: RouteHandler<SaveResponse> for a method that returns Promise<SaveResponse>
+ *
+ * Using unknown as default instead of any forces type safety - consumers must
+ * handle the result appropriately rather than assuming any type.
+ *
+ * This is a class instead of a function type to make it easier to trace
+ * who is calling what in the debugger/IDE.
+ */
+class RouteHandler {
+}
+exports.RouteHandler = RouteHandler;
+//# sourceMappingURL=RouteHandler.js.map

package/src/RouteHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteHandler.js","sourceRoot":"","sources":["../../../../../packages/http/http-server/src/RouteHandler.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;GAYG;AACH,MAAsB,YAAY;CAOjC;AAPD,oCAOC","sourcesContent":["import { MethodMeta } from './MethodMeta';\n\n/**\n * Handler class for routes.\n * Takes a MethodMeta and returns the controller method result.\n *\n * Generic type parameter TResult represents the return type of the controller method.\n * Example: RouteHandler<SaveResponse> for a method that returns Promise<SaveResponse>\n *\n * Using unknown as default instead of any forces type safety - consumers must\n * handle the result appropriately rather than assuming any type.\n *\n * This is a class instead of a function type to make it easier to trace\n * who is calling what in the debugger/IDE.\n */\nexport abstract class RouteHandler<TResult = unknown> {\n  /**\n   * Execute the route handler.\n   * @param meta - The method metadata containing request info and params\n   * @returns Promise of the controller method result\n   */\n  abstract execute(meta: MethodMeta): Promise<TResult>;\n}\n"]}

package/src/WebpiecesFactory.d.ts

@@ -0,0 +1,44 @@
+import { WebAppMeta } from '@webpieces/core-meta';
+import { WebpiecesServer } from './WebpiecesServer';
+/**
+ * WebpiecesFactory - Factory for creating WebPieces server instances.
+ *
+ * This factory encapsulates the server creation and initialization logic:
+ * 1. Creates the WebPieces DI container
+ * 2. Loads the provider module for @provideSingleton decorators
+ * 3. Resolves WebpiecesServerImpl from DI
+ * 4. Calls initialize() with the container and meta
+ * 5. Returns the server as the WebpiecesServer interface
+ *
+ * The returned WebpiecesServer interface only exposes start() and stop(),
+ * hiding the internal initialize() method from consumers.
+ *
+ * Usage:
+ * ```typescript
+ * const server = WebpiecesFactory.create(new ProdServerMeta());
+ * server.start(8080);
+ * // ... later
+ * server.stop();
+ * ```
+ *
+ * This pattern:
+ * - Enforces proper initialization order
+ * - Hides implementation details from consumers
+ * - Makes the API simpler and harder to misuse
+ * - Follows the principle of least privilege
+ */
+export declare class WebpiecesFactory {
+    /**
+     * Create a new WebPieces server instance.
+     *
+     * This method:
+     * 1. Creates the WebPieces framework DI container
+     * 2. Loads framework bindings via buildProviderModule()
+     * 3. Resolves the server implementation from DI
+     * 4. Initializes the server with the container and meta
+     *
+     * @param meta - User-provided WebAppMeta with DI modules and routes
+     * @returns A fully initialized WebpiecesServer ready to start()
+     */
+    static create(meta: WebAppMeta): WebpiecesServer;
+}