@stacksjs/bun-router 0.0.15 → 0.0.17

package/dist/chunk-g3ybefhg.js

@@ -0,0 +1,1923 @@
+// @bun
+// src/errors/exceptions.ts
+class RouterException extends Error {
+  code;
+  statusCode;
+  context;
+  retryable;
+  severity;
+  category;
+  timestamp;
+  cause;
+  constructor(details) {
+    super(details.message);
+    this.name = this.constructor.name;
+    this.code = details.code;
+    this.statusCode = details.statusCode || 500;
+    this.context = details.context || {};
+    this.retryable = details.retryable || false;
+    this.severity = details.severity || "medium";
+    this.category = details.category || "system";
+    this.timestamp = new Date;
+    this.cause = details.cause;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      statusCode: this.statusCode,
+      context: this.context,
+      retryable: this.retryable,
+      severity: this.severity,
+      category: this.category,
+      timestamp: this.timestamp.toISOString(),
+      stack: this.stack,
+      cause: this.cause ? {
+        name: this.cause.name,
+        message: this.cause.message,
+        stack: this.cause.stack
+      } : undefined
+    };
+  }
+  toResponse() {
+    const body = {
+      error: {
+        code: this.code,
+        message: this.message,
+        statusCode: this.statusCode,
+        timestamp: this.timestamp.toISOString(),
+        requestId: this.context.requestId
+      }
+    };
+    return new Response(JSON.stringify(body), {
+      status: this.statusCode,
+      headers: {
+        "Content-Type": "application/json",
+        "X-Error-Code": this.code,
+        "X-Request-ID": this.context.requestId || ""
+      }
+    });
+  }
+}
+
+class ValidationException extends RouterException {
+  fields;
+  constructor(message, fields = {}, context) {
+    super({
+      code: "VALIDATION_ERROR",
+      message,
+      statusCode: 400,
+      context,
+      retryable: false,
+      severity: "low",
+      category: "validation"
+    });
+    this.fields = fields;
+  }
+  toResponse() {
+    const body = {
+      error: {
+        code: this.code,
+        message: this.message,
+        statusCode: this.statusCode,
+        timestamp: this.timestamp.toISOString(),
+        requestId: this.context.requestId,
+        fields: this.fields
+      }
+    };
+    return new Response(JSON.stringify(body), {
+      status: this.statusCode,
+      headers: {
+        "Content-Type": "application/json",
+        "X-Error-Code": this.code,
+        "X-Request-ID": this.context.requestId || ""
+      }
+    });
+  }
+}
+
+class AuthenticationException extends RouterException {
+  constructor(message = "Authentication required", context) {
+    super({
+      code: "AUTHENTICATION_ERROR",
+      message,
+      statusCode: 401,
+      context,
+      retryable: false,
+      severity: "medium",
+      category: "authentication"
+    });
+  }
+}
+
+class AuthorizationException extends RouterException {
+  requiredPermissions;
+  constructor(message = "Access denied", requiredPermissions, context) {
+    super({
+      code: "AUTHORIZATION_ERROR",
+      message,
+      statusCode: 403,
+      context,
+      retryable: false,
+      severity: "medium",
+      category: "authorization"
+    });
+    this.requiredPermissions = requiredPermissions;
+  }
+}
+
+class NotFoundException extends RouterException {
+  resource;
+  resourceId;
+  constructor(message = "Resource not found", resource, resourceId, context) {
+    super({
+      code: "NOT_FOUND",
+      message,
+      statusCode: 404,
+      context,
+      retryable: false,
+      severity: "low",
+      category: "business"
+    });
+    this.resource = resource;
+    this.resourceId = resourceId;
+  }
+}
+
+class MethodNotAllowedException extends RouterException {
+  allowedMethods;
+  constructor(method, allowedMethods, context) {
+    super({
+      code: "METHOD_NOT_ALLOWED",
+      message: `Method ${method} not allowed. Allowed methods: ${allowedMethods.join(", ")}`,
+      statusCode: 405,
+      context,
+      retryable: false,
+      severity: "low",
+      category: "business"
+    });
+    this.allowedMethods = allowedMethods;
+  }
+  toResponse() {
+    const response = super.toResponse();
+    response.headers.set("Allow", this.allowedMethods.join(", "));
+    return response;
+  }
+}
+
+class TimeoutException extends RouterException {
+  timeoutMs;
+  constructor(message = "Request timeout", timeoutMs, context) {
+    super({
+      code: "REQUEST_TIMEOUT",
+      message,
+      statusCode: 408,
+      context,
+      retryable: true,
+      severity: "medium",
+      category: "network"
+    });
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+class RateLimitException extends RouterException {
+  retryAfter;
+  limit;
+  remaining;
+  constructor(message = "Rate limit exceeded", retryAfter, limit, remaining = 0, context) {
+    super({
+      code: "RATE_LIMIT_EXCEEDED",
+      message,
+      statusCode: 429,
+      context,
+      retryable: true,
+      severity: "medium",
+      category: "network"
+    });
+    this.retryAfter = retryAfter;
+    this.limit = limit;
+    this.remaining = remaining;
+  }
+  toResponse() {
+    const response = super.toResponse();
+    response.headers.set("Retry-After", this.retryAfter.toString());
+    response.headers.set("X-RateLimit-Limit", this.limit.toString());
+    response.headers.set("X-RateLimit-Remaining", this.remaining.toString());
+    return response;
+  }
+}
+
+class InternalServerException extends RouterException {
+  constructor(message = "Internal server error", cause, context) {
+    super({
+      code: "INTERNAL_SERVER_ERROR",
+      message,
+      statusCode: 500,
+      context,
+      cause,
+      retryable: true,
+      severity: "high",
+      category: "system"
+    });
+  }
+}
+
+class ServiceUnavailableException extends RouterException {
+  retryAfter;
+  constructor(message = "Service unavailable", retryAfter, context) {
+    super({
+      code: "SERVICE_UNAVAILABLE",
+      message,
+      statusCode: 503,
+      context,
+      retryable: true,
+      severity: "high",
+      category: "system"
+    });
+    this.retryAfter = retryAfter;
+  }
+  toResponse() {
+    const response = super.toResponse();
+    if (this.retryAfter) {
+      response.headers.set("Retry-After", this.retryAfter.toString());
+    }
+    return response;
+  }
+}
+
+class DatabaseException extends RouterException {
+  query;
+  operation;
+  constructor(message, operation, query, cause, context) {
+    super({
+      code: "DATABASE_ERROR",
+      message,
+      statusCode: 500,
+      context,
+      cause,
+      retryable: true,
+      severity: "high",
+      category: "database"
+    });
+    this.operation = operation;
+    this.query = query;
+  }
+}
+
+class ExternalServiceException extends RouterException {
+  service;
+  endpoint;
+  constructor(message, service, endpoint, statusCode = 502, cause, context) {
+    super({
+      code: "EXTERNAL_SERVICE_ERROR",
+      message,
+      statusCode,
+      context,
+      cause,
+      retryable: true,
+      severity: "medium",
+      category: "external"
+    });
+    this.service = service;
+    this.endpoint = endpoint;
+  }
+}
+
+class CircuitBreakerOpenException extends RouterException {
+  service;
+  nextAttemptAt;
+  constructor(service, nextAttemptAt, context) {
+    super({
+      code: "CIRCUIT_BREAKER_OPEN",
+      message: `Circuit breaker is open for service: ${service}. Next attempt at: ${nextAttemptAt.toISOString()}`,
+      statusCode: 503,
+      context,
+      retryable: true,
+      severity: "medium",
+      category: "external"
+    });
+    this.service = service;
+    this.nextAttemptAt = nextAttemptAt;
+  }
+}
+
+class BusinessLogicException extends RouterException {
+  businessRule;
+  constructor(message, businessRule, context) {
+    super({
+      code: "BUSINESS_LOGIC_ERROR",
+      message,
+      statusCode: 422,
+      context,
+      retryable: false,
+      severity: "low",
+      category: "business"
+    });
+    this.businessRule = businessRule;
+  }
+}
+
+class ConfigurationException extends RouterException {
+  configKey;
+  constructor(message, configKey, context) {
+    super({
+      code: "CONFIGURATION_ERROR",
+      message,
+      statusCode: 500,
+      context,
+      retryable: false,
+      severity: "critical",
+      category: "system"
+    });
+    this.configKey = configKey;
+  }
+}
+
+class FileSystemException extends RouterException {
+  path;
+  operation;
+  constructor(message, path, operation, cause, context) {
+    super({
+      code: "FILESYSTEM_ERROR",
+      message,
+      statusCode: 500,
+      context,
+      cause,
+      retryable: false,
+      severity: "medium",
+      category: "system"
+    });
+    this.path = path;
+    this.operation = operation;
+  }
+}
+var ErrorFactory = {
+  validation: (message, fields, context) => new ValidationException(message, fields, context),
+  authentication: (message, context) => new AuthenticationException(message, context),
+  authorization: (message, requiredPermissions, context) => new AuthorizationException(message, requiredPermissions, context),
+  notFound: (resource, resourceId, context) => new NotFoundException(undefined, resource, resourceId, context),
+  methodNotAllowed: (method, allowedMethods, context) => new MethodNotAllowedException(method, allowedMethods, context),
+  timeout: (timeoutMs, message, context) => new TimeoutException(message, timeoutMs, context),
+  rateLimit: (retryAfter, limit, remaining, context) => new RateLimitException(undefined, retryAfter, limit, remaining, context),
+  internalServer: (message, cause, context) => new InternalServerException(message, cause, context),
+  serviceUnavailable: (message, retryAfter, context) => new ServiceUnavailableException(message, retryAfter, context),
+  database: (message, operation, query, cause, context) => new DatabaseException(message, operation, query, cause, context),
+  externalService: (message, service, endpoint, statusCode, cause, context) => new ExternalServiceException(message, service, endpoint, statusCode, cause, context),
+  circuitBreakerOpen: (service, nextAttemptAt, context) => new CircuitBreakerOpenException(service, nextAttemptAt, context),
+  businessLogic: (message, businessRule, context) => new BusinessLogicException(message, businessRule, context),
+  configuration: (message, configKey, context) => new ConfigurationException(message, configKey, context),
+  fileSystem: (message, path, operation, cause, context) => new FileSystemException(message, path, operation, cause, context)
+};
+
+// src/errors/router-errors.ts
+class RouteConflictException extends RouterException {
+  conflictingRoutes;
+  suggestion;
+  constructor(conflictingRoutes, context) {
+    const message = RouteConflictException.buildMessage(conflictingRoutes);
+    const suggestion = RouteConflictException.buildSuggestion(conflictingRoutes);
+    super({
+      code: "ROUTE_CONFLICT",
+      message,
+      statusCode: 500,
+      context,
+      retryable: false,
+      severity: "critical",
+      category: "system"
+    });
+    this.conflictingRoutes = conflictingRoutes;
+    this.suggestion = suggestion;
+  }
+  static buildMessage(routes) {
+    const lines = [
+      "Route conflict detected! Multiple routes match the same path pattern.",
+      "",
+      "Conflicting routes:"
+    ];
+    for (const route of routes) {
+      lines.push(`  \u2022 ${route.method} ${route.path}`);
+      if (route.name) {
+        lines.push(`    Name: "${route.name}"`);
+      }
+      if (route.definedAt) {
+        lines.push(`    Defined at: ${route.definedAt}`);
+      }
+    }
+    return lines.join(`
+`);
+  }
+  static buildSuggestion(routes) {
+    const suggestions = [];
+    const hasStatic = routes.some((r) => !r.path.includes("{"));
+    const hasDynamic = routes.some((r) => r.path.includes("{"));
+    if (hasStatic && hasDynamic) {
+      suggestions.push("\u2022 Static routes should be defined before dynamic routes", "\u2022 Consider using route constraints (whereNumber, whereUuid) to differentiate");
+    }
+    const dynamicRoutes = routes.filter((r) => r.path.includes("{"));
+    if (dynamicRoutes.length > 1) {
+      suggestions.push("\u2022 Use different parameter names or add constraints:", '  router.get("/users/{id}").whereNumber("id")', '  router.get("/users/{slug}").whereAlpha("slug")');
+    }
+    const hasWildcard = routes.some((r) => r.path.includes("*"));
+    if (hasWildcard) {
+      suggestions.push("\u2022 Wildcard routes should be defined last", "\u2022 Consider using more specific path prefixes");
+    }
+    if (suggestions.length === 0) {
+      suggestions.push("\u2022 Rename one of the conflicting routes", "\u2022 Use route groups with different prefixes", "\u2022 Add parameter constraints to differentiate routes");
+    }
+    return `How to fix:
+${suggestions.join(`
+`)}`;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      conflictingRoutes: this.conflictingRoutes,
+      suggestion: this.suggestion
+    };
+  }
+}
+
+class CircularDependencyException extends RouterException {
+  dependencyChain;
+  suggestion;
+  constructor(dependencyChain, context) {
+    const message = CircularDependencyException.buildMessage(dependencyChain);
+    const suggestion = CircularDependencyException.buildSuggestion(dependencyChain);
+    super({
+      code: "CIRCULAR_DEPENDENCY",
+      message,
+      statusCode: 500,
+      context,
+      retryable: false,
+      severity: "critical",
+      category: "system"
+    });
+    this.dependencyChain = dependencyChain;
+    this.suggestion = suggestion;
+  }
+  static buildMessage(chain) {
+    const lines = [
+      "Circular dependency detected in the dependency injection container!",
+      "",
+      "Dependency chain:",
+      ""
+    ];
+    for (let i = 0;i < chain.length; i++) {
+      const isLast = i === chain.length - 1;
+      const prefix = i === 0 ? "\u250C\u2500\u25BA" : isLast ? "\u2514\u2500\u25BA" : "\u251C\u2500\u25BA";
+      lines.push(`  ${prefix} ${chain[i]}`);
+      if (!isLast) {
+        lines.push("  \u2502");
+      }
+    }
+    lines.push("  \u2502");
+    lines.push(`  \u2514\u2500\u2500 cycles back to: ${chain[0]}`);
+    return lines.join(`
+`);
+  }
+  static buildSuggestion(chain) {
+    return `How to fix:
+
+1. Break the cycle by introducing an interface:
+  \u2022 Create an interface for one of the dependencies
+  \u2022 Use lazy injection: container.bind('${chain[0]}').lazy()
+
+2. Restructure your dependencies:
+  \u2022 Extract shared logic into a separate service
+  \u2022 Use events/callbacks instead of direct dependencies
+
+3. Use setter injection instead of constructor injection:
+  \u2022 Remove the dependency from the constructor
+  \u2022 Set it after instantiation using a setter method
+
+4. Check if the dependency is actually needed:
+  \u2022 Sometimes circular dependencies indicate a design issue
+  \u2022 Consider if the classes have too many responsibilities
+
+Dependency chain involved:
+${chain.map((dep, i) => `  ${i + 1}. ${dep}`).join(`
+`)}`;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      dependencyChain: this.dependencyChain,
+      suggestion: this.suggestion
+    };
+  }
+}
+
+class MiddlewareConfigurationException extends RouterException {
+  middlewareName;
+  configErrors;
+  suggestion;
+  constructor(middlewareName, configErrors, context) {
+    const message = `Middleware "${middlewareName}" configuration error:
+${configErrors.map((e) => `  \u2022 ${e}`).join(`
+`)}`;
+    super({
+      code: "MIDDLEWARE_CONFIGURATION_ERROR",
+      message,
+      statusCode: 500,
+      context,
+      retryable: false,
+      severity: "high",
+      category: "system"
+    });
+    this.middlewareName = middlewareName;
+    this.configErrors = configErrors;
+    this.suggestion = this.buildSuggestion();
+  }
+  buildSuggestion() {
+    return `How to fix:
+\u2022 Check the middleware documentation for required options
+\u2022 Ensure all required configuration values are provided
+\u2022 Verify configuration value types match expected types
+
+Example configuration:
+  router.use(new ${this.middlewareName}({
+    // Add required options here
+  }))`;
+  }
+}
+
+class RouteNotFoundException extends RouterException {
+  requestedPath;
+  requestedMethod;
+  similarRoutes;
+  suggestion;
+  constructor(requestedMethod, requestedPath, similarRoutes = [], context) {
+    const message = RouteNotFoundException.buildMessage(requestedMethod, requestedPath, similarRoutes);
+    super({
+      code: "ROUTE_NOT_FOUND",
+      message,
+      statusCode: 404,
+      context,
+      retryable: false,
+      severity: "low",
+      category: "business"
+    });
+    this.requestedPath = requestedPath;
+    this.requestedMethod = requestedMethod;
+    this.similarRoutes = similarRoutes;
+    this.suggestion = this.buildSuggestion();
+  }
+  static buildMessage(method, path, similarRoutes) {
+    const lines = [
+      `Route not found: ${method} ${path}`
+    ];
+    if (similarRoutes.length > 0) {
+      lines.push("");
+      lines.push("Did you mean one of these routes?");
+      for (const route of similarRoutes.slice(0, 5)) {
+        lines.push(`  \u2022 ${route.method} ${route.path}`);
+        if (route.similarity) {
+          lines.push(`    (${Math.round(route.similarity * 100)}% match)`);
+        }
+      }
+    }
+    return lines.join(`
+`);
+  }
+  buildSuggestion() {
+    const suggestions = [
+      `\u2022 Verify the HTTP method is correct (you used ${this.requestedMethod})`,
+      "\u2022 Check for typos in the URL path",
+      "\u2022 Ensure the route is registered before the server starts",
+      "\u2022 Check if the route requires specific middleware (e.g., auth)"
+    ];
+    if (this.requestedPath.includes("//")) {
+      suggestions.push("\u2022 Remove duplicate slashes from the URL");
+    }
+    if (!this.requestedPath.startsWith("/")) {
+      suggestions.push("\u2022 Ensure the path starts with a forward slash (/)");
+    }
+    return `How to fix:
+${suggestions.join(`
+`)}`;
+  }
+}
+
+class HandlerResolutionException extends RouterException {
+  handlerRef;
+  suggestion;
+  constructor(handlerRef, reason, context) {
+    const message = `Failed to resolve handler "${handlerRef}": ${reason}`;
+    super({
+      code: "HANDLER_RESOLUTION_ERROR",
+      message,
+      statusCode: 500,
+      context,
+      retryable: false,
+      severity: "high",
+      category: "system"
+    });
+    this.handlerRef = handlerRef;
+    this.suggestion = this.buildSuggestion(handlerRef);
+  }
+  buildSuggestion(handlerRef) {
+    const isControllerMethod = handlerRef.includes("@");
+    const isActionPath = handlerRef.includes("/");
+    if (isControllerMethod) {
+      const [controller, method] = handlerRef.split("@");
+      return `How to fix:
+\u2022 Ensure the controller "${controller}" is registered in the container
+\u2022 Verify the method "${method}" exists and is public
+\u2022 Check the controller file is imported
+
+Example:
+  // Register the controller
+  container.singleton('${controller}', ${controller})
+
+  // Define the route
+  router.get('/path', '${handlerRef}')`;
+    }
+    if (isActionPath) {
+      return `How to fix:
+\u2022 Ensure the action class exists at the specified path
+\u2022 Verify the action has a "handle" method
+\u2022 Check the action file is properly exported
+
+Example:
+  // Action class at ${handlerRef}.ts
+  export default class ${handlerRef.split("/").pop()} {
+    handle(req: Request): Response {
+      return new Response('OK')
+    }
+  }`;
+    }
+    return `How to fix:
+\u2022 Verify the handler reference is correct
+\u2022 Ensure the handler function/class is exported
+\u2022 Check for circular dependencies in the handler module`;
+  }
+}
+
+class ModelBindingException extends RouterException {
+  modelName;
+  paramName;
+  paramValue;
+  suggestion;
+  constructor(modelName, paramName, paramValue, reason, context) {
+    const message = `Failed to bind model "${modelName}" for parameter "${paramName}" with value "${paramValue}": ${reason}`;
+    super({
+      code: "MODEL_BINDING_ERROR",
+      message,
+      statusCode: 404,
+      context,
+      retryable: false,
+      severity: "low",
+      category: "business"
+    });
+    this.modelName = modelName;
+    this.paramName = paramName;
+    this.paramValue = paramValue;
+    this.suggestion = this.buildSuggestion();
+  }
+  buildSuggestion() {
+    return `How to fix:
+\u2022 Verify the ${this.paramName} "${this.paramValue}" exists in your data source
+\u2022 Check if the model resolver is correctly configured
+\u2022 Ensure the route parameter matches the model's identifier field
+
+Example model binding:
+  router.model('${this.paramName}', async (value) => {
+    const ${this.modelName.toLowerCase()} = await db.${this.modelName.toLowerCase()}s.findUnique({
+      where: { id: value }
+    })
+    if (!${this.modelName.toLowerCase()}) {
+      throw new Error('${this.modelName} not found')
+    }
+    return ${this.modelName.toLowerCase()}
+  })`;
+  }
+}
+function findSimilarRoutes(requestedPath, availableRoutes, maxResults = 5) {
+  const results = [];
+  for (const route of availableRoutes) {
+    const similarity = calculateSimilarity(requestedPath, route.path);
+    if (similarity > 0.3) {
+      results.push({
+        method: route.method,
+        path: route.path,
+        similarity
+      });
+    }
+  }
+  return results.sort((a, b) => (b.similarity || 0) - (a.similarity || 0)).slice(0, maxResults);
+}
+function calculateSimilarity(str1, str2) {
+  const len1 = str1.length;
+  const len2 = str2.length;
+  if (len1 === 0)
+    return len2 === 0 ? 1 : 0;
+  if (len2 === 0)
+    return 0;
+  const matrix = [];
+  for (let i = 0;i <= len1; i++) {
+    matrix[i] = [i];
+  }
+  for (let j = 0;j <= len2; j++) {
+    matrix[0][j] = j;
+  }
+  for (let i = 1;i <= len1; i++) {
+    for (let j = 1;j <= len2; j++) {
+      const cost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(matrix[i - 1][j] + 1, matrix[i][j - 1] + 1, matrix[i - 1][j - 1] + cost);
+    }
+  }
+  const distance = matrix[len1][len2];
+  const maxLen = Math.max(len1, len2);
+  return 1 - distance / maxLen;
+}
+function detectRouteConflicts(routes) {
+  const conflicts = [];
+  const checked = new Set;
+  for (let i = 0;i < routes.length; i++) {
+    const route1 = routes[i];
+    const key1 = `${route1.method}:${route1.path}`;
+    if (checked.has(key1))
+      continue;
+    const conflicting = [];
+    for (let j = i + 1;j < routes.length; j++) {
+      const route2 = routes[j];
+      if (route1.method === route2.method && routesConflict(route1.path, route2.path)) {
+        if (conflicting.length === 0) {
+          conflicting.push({
+            method: route1.method,
+            path: route1.path,
+            name: route1.name
+          });
+        }
+        conflicting.push({
+          method: route2.method,
+          path: route2.path,
+          name: route2.name
+        });
+        checked.add(`${route2.method}:${route2.path}`);
+      }
+    }
+    if (conflicting.length > 0) {
+      conflicts.push(conflicting);
+    }
+    checked.add(key1);
+  }
+  return conflicts;
+}
+function routesConflict(path1, path2) {
+  if (path1 === path2)
+    return true;
+  const segments1 = path1.split("/").filter(Boolean);
+  const segments2 = path2.split("/").filter(Boolean);
+  if (segments1.length !== segments2.length) {
+    const hasWildcard1 = path1.includes("*");
+    const hasWildcard2 = path2.includes("*");
+    if (!hasWildcard1 && !hasWildcard2)
+      return false;
+  }
+  const maxLen = Math.max(segments1.length, segments2.length);
+  for (let i = 0;i < maxLen; i++) {
+    const seg1 = segments1[i] || "";
+    const seg2 = segments2[i] || "";
+    if (seg1 === "*" || seg2 === "*")
+      return true;
+    const isDynamic1 = seg1.startsWith("{") && seg1.endsWith("}");
+    const isDynamic2 = seg2.startsWith("{") && seg2.endsWith("}");
+    if (!isDynamic1 && !isDynamic2) {
+      if (seg1 !== seg2)
+        return false;
+    }
+  }
+  return true;
+}
+var RouterErrorFactory = {
+  routeConflict: (routes, context) => new RouteConflictException(routes, context),
+  circularDependency: (chain, context) => new CircularDependencyException(chain, context),
+  middlewareConfig: (name, errors, context) => new MiddlewareConfigurationException(name, errors, context),
+  routeNotFound: (method, path, similarRoutes, context) => new RouteNotFoundException(method, path, similarRoutes, context),
+  handlerResolution: (ref, reason, context) => new HandlerResolutionException(ref, reason, context),
+  modelBinding: (model, param, value, reason, context) => new ModelBindingException(model, param, value, reason, context)
+};
+
+// src/container/container.ts
+var INJECTABLE_METADATA_KEY = Symbol("injectable");
+var INJECT_METADATA_KEY = Symbol("inject");
+var OPTIONAL_METADATA_KEY = Symbol("optional");
+var TAGGED_METADATA_KEY = Symbol("tagged");
+
+class Container {
+  bindings = new Map;
+  tagIndex = new Map;
+  instances = new Map;
+  scopedInstances = new Map;
+  interceptors = new Map;
+  parent;
+  children = new Set;
+  options;
+  constructor(options = {}) {
+    this.options = {
+      autoRegister: options.autoRegister ?? true,
+      strictMode: options.strictMode ?? false,
+      maxDepth: options.maxDepth ?? 50,
+      enableDecorators: options.enableDecorators ?? true,
+      enableInterception: options.enableInterception ?? false,
+      defaultScope: options.defaultScope ?? "transient"
+    };
+  }
+  bind(token) {
+    return new BindingBuilder(this, token);
+  }
+  register(binding) {
+    const existing = this.bindings.get(binding.token);
+    if (existing?.metadata?.tags) {
+      for (const tag of existing.metadata.tags) {
+        this.tagIndex.get(tag)?.delete(binding.token);
+      }
+    }
+    this.bindings.set(binding.token, binding);
+    if (binding.metadata?.tags) {
+      for (const tag of binding.metadata.tags) {
+        let tokens = this.tagIndex.get(tag);
+        if (!tokens) {
+          tokens = new Set;
+          this.tagIndex.set(tag, tokens);
+        }
+        tokens.add(binding.token);
+      }
+    }
+    return this;
+  }
+  singleton(token, implementation) {
+    return this.bind(token).to(implementation).inSingletonScope().build();
+  }
+  transient(token, implementation) {
+    return this.bind(token).to(implementation).inTransientScope().build();
+  }
+  value(token, value) {
+    return this.bind(token).toValue(value).build();
+  }
+  factory(token, factory) {
+    return this.bind(token).toFactory(factory).build();
+  }
+  resolve(token, context) {
+    const resolutionContext = {
+      container: this,
+      token,
+      environment: context?.environment || "development",
+      requestId: context?.requestId || this.generateRequestId(),
+      depth: context?.depth || 0,
+      resolving: context?.resolving || new Set,
+      parent: context?.parent
+    };
+    return this.resolveInternal(token, resolutionContext);
+  }
+  resolveAll(token) {
+    const tokens = new Set;
+    if (this.bindings.has(token)) {
+      tokens.add(token);
+    }
+    if (typeof token === "string") {
+      for (const tagged of this.tagIndex.get(token) ?? []) {
+        tokens.add(tagged);
+      }
+    }
+    return Array.from(tokens, (t) => this.resolve(t));
+  }
+  resolveTagged(tag) {
+    const tokens = this.tagIndex.get(tag);
+    if (!tokens || tokens.size === 0) {
+      return [];
+    }
+    return Array.from(tokens, (token) => this.resolve(token));
+  }
+  getTaggedBindings(tag) {
+    const tokens = this.tagIndex.get(tag);
+    if (!tokens || tokens.size === 0) {
+      return [];
+    }
+    const bindings = [];
+    for (const token of tokens) {
+      const binding = this.bindings.get(token);
+      if (binding) {
+        bindings.push(binding);
+      }
+    }
+    return bindings;
+  }
+  addInterceptor(token, interceptor) {
+    const key = this.tokenToString(token);
+    if (!this.interceptors.has(key)) {
+      this.interceptors.set(key, []);
+    }
+    this.interceptors.get(key).push(interceptor);
+  }
+  registerController(controller) {
+    this.singleton(controller, controller);
+  }
+  getController(controller) {
+    return this.resolve(controller);
+  }
+  isBound(token) {
+    return this.bindings.has(token) || (this.parent?.isBound(token) ?? false);
+  }
+  unbind(token) {
+    const binding = this.bindings.get(token);
+    if (binding?.metadata?.tags) {
+      for (const tag of binding.metadata.tags) {
+        this.tagIndex.get(tag)?.delete(token);
+      }
+    }
+    this.bindings.delete(token);
+    this.instances.delete(token);
+    return this;
+  }
+  createChild(options) {
+    const child = new Container({ ...this.options, ...options });
+    child.parent = this;
+    this.children.add(child);
+    return child;
+  }
+  createScope(scopeId) {
+    const scope = this.createChild();
+    scope.scopedInstances.set(scopeId, new Map);
+    return scope;
+  }
+  getBindings() {
+    return new Map(this.bindings);
+  }
+  clear() {
+    this.bindings.clear();
+    this.tagIndex.clear();
+    this.instances.clear();
+    this.scopedInstances.clear();
+    return this;
+  }
+  intercept(token, interceptor) {
+    if (!this.interceptors.has(token)) {
+      this.interceptors.set(token, []);
+    }
+    this.interceptors.get(token).push(interceptor);
+    return this;
+  }
+  resolveInternal(token, context) {
+    if (context.resolving.has(token)) {
+      const chain = Array.from(context.resolving).map((t) => this.tokenToString(t));
+      chain.push(this.tokenToString(token));
+      throw new CircularDependencyException(chain);
+    }
+    if (context.depth > this.options.maxDepth) {
+      const chain = Array.from(context.resolving).map((t) => this.tokenToString(t));
+      throw new Error(`Maximum resolution depth exceeded (${this.options.maxDepth}).
+` + `This usually indicates a circular or very deep dependency chain.
+` + `Current resolution chain:
+${chain.map((t, i) => `  ${i + 1}. ${t}`).join(`
+`)}`);
+    }
+    context.resolving.add(token);
+    context.depth++;
+    try {
+      const binding = this.bindings.get(token);
+      if (binding) {
+        if (binding.metadata.when && !binding.metadata.when(context)) {
+          throw new Error(`Contextual binding condition not met for: ${this.tokenToString(token)}`);
+        }
+        return this.createInstance(binding, context);
+      }
+      if (this.parent) {
+        const parentContext = {
+          resolving: new Set,
+          depth: 0,
+          container: this.parent,
+          token
+        };
+        return this.parent.resolveInternal(token, parentContext);
+      }
+      if (this.options.autoRegister && typeof token === "function") {
+        return this.autoRegisterAndResolve(token, context);
+      }
+      if (this.options.strictMode) {
+        throw new Error(`No binding found for: ${this.tokenToString(token)}`);
+      }
+      if (typeof token === "function") {
+        return this.createInstanceFromConstructor(token, context);
+      }
+      throw new Error(`Cannot resolve: ${this.tokenToString(token)}`);
+    } finally {
+      context.resolving.delete(token);
+      context.depth--;
+    }
+  }
+  createInstance(binding, context) {
+    let instance;
+    if (binding.metadata.scope === "singleton" && this.instances.has(binding.token)) {
+      instance = this.instances.get(binding.token);
+    } else if (binding.metadata.scope === "scoped" && context.requestId) {
+      const scopedMap = this.scopedInstances.get(context.requestId);
+      if (scopedMap?.has(binding.token)) {
+        instance = scopedMap.get(binding.token);
+      } else {
+        instance = this.createNewInstance(binding, context);
+        if (!scopedMap) {
+          this.scopedInstances.set(context.requestId, new Map);
+        }
+        this.scopedInstances.get(context.requestId).set(binding.token, instance);
+      }
+    } else {
+      instance = this.createNewInstance(binding, context);
+      if (binding.metadata.scope === "singleton") {
+        this.instances.set(binding.token, instance);
+      }
+    }
+    const tokenKey = this.tokenToString(binding.token);
+    if (this.interceptors.has(tokenKey)) {
+      const interceptors = this.interceptors.get(tokenKey);
+      for (const interceptor of interceptors) {
+        instance = interceptor(instance);
+      }
+    }
+    return instance;
+  }
+  createNewInstance(binding, context) {
+    if (binding.value !== undefined) {
+      return binding.value;
+    }
+    if (binding.factory) {
+      const dependencies = this.resolveDependencies(binding.metadata.dependencies || [], context);
+      return binding.factory(...dependencies);
+    }
+    if (binding.instance) {
+      return binding.instance;
+    }
+    if (binding.implementation) {
+      return this.createInstanceFromConstructor(binding.implementation, context);
+    }
+    throw new Error(`Invalid binding configuration for: ${this.tokenToString(binding.token)}`);
+  }
+  createInstanceFromConstructor(constructor, context) {
+    const dependencies = this.getConstructorDependencies(constructor);
+    const resolvedDependencies = this.resolveDependencies(dependencies, context);
+    const instance = new constructor(...resolvedDependencies);
+    if (this.options.enableDecorators) {
+      this.applyDecorators(instance, constructor);
+    }
+    return instance;
+  }
+  getConstructorDependencies(constructor) {
+    let injectMetadata = Reflect.getMetadata?.(INJECT_METADATA_KEY, constructor) || constructor[INJECT_METADATA_KEY];
+    if (!injectMetadata && constructor.constructor) {
+      injectMetadata = constructor.constructor[INJECT_METADATA_KEY];
+    }
+    if (!injectMetadata && typeof constructor === "function" && constructor.prototype) {
+      const classMetadata = constructor[INJECT_METADATA_KEY];
+      if (classMetadata) {
+        injectMetadata = classMetadata;
+      }
+    }
+    if (!injectMetadata && typeof constructor === "function") {
+      const directMetadata = constructor[INJECT_METADATA_KEY];
+      if (directMetadata) {
+        injectMetadata = directMetadata;
+      }
+    }
+    if (injectMetadata) {
+      return injectMetadata.map((meta) => meta.token);
+    }
+    const paramTypes = Reflect.getMetadata?.("design:paramtypes", constructor);
+    if (paramTypes) {
+      return paramTypes;
+    }
+    return this.parseConstructorDependencies(constructor);
+  }
+  parseConstructorDependencies(constructor) {
+    const constructorString = constructor.toString();
+    const match = constructorString.match(/constructor\s*\(([^)]*)\)/);
+    if (!match || !match[1]) {
+      return [];
+    }
+    return match[1].split(",").map((param) => param.trim().split(":")[0].trim()).filter((param) => param.length > 0);
+  }
+  resolveDependencies(dependencies, context) {
+    return dependencies.map((dep) => this.resolveInternal(dep, context));
+  }
+  autoRegisterAndResolve(constructor, context) {
+    const metadata = Reflect.getMetadata?.(INJECTABLE_METADATA_KEY, constructor);
+    const binding = {
+      token: constructor,
+      implementation: constructor,
+      metadata: {
+        scope: metadata?.scope || this.options.defaultScope,
+        tags: metadata?.tags
+      }
+    };
+    this.register(binding);
+    return this.resolveInternal(constructor, context);
+  }
+  applyDecorators(instance, constructor) {
+    const decorators = Reflect.getMetadata?.("decorators", constructor);
+    if (decorators) {
+      for (const decorator of decorators) {
+        decorator(instance);
+      }
+    }
+  }
+  hasTag(binding, tag) {
+    return binding.metadata.tags?.includes(tag) ?? false;
+  }
+  tokenToString(token) {
+    if (typeof token === "string")
+      return token;
+    if (typeof token === "symbol")
+      return token.toString();
+    if (typeof token === "function")
+      return token.name || "anonymous";
+    return "unknown";
+  }
+  generateRequestId() {
+    return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+}
+
+class BindingBuilder {
+  container;
+  binding;
+  constructor(container, token) {
+    this.container = container;
+    this.binding = {
+      token,
+      metadata: {
+        scope: "transient"
+      }
+    };
+  }
+  to(implementation) {
+    this.binding.implementation = implementation;
+    return this;
+  }
+  toValue(value) {
+    this.binding.value = value;
+    this.binding.metadata.scope = "singleton";
+    return this;
+  }
+  toFactory(factory) {
+    this.binding.factory = factory;
+    return this;
+  }
+  toInstance(instance) {
+    this.binding.instance = instance;
+    this.binding.metadata.scope = "singleton";
+    return this;
+  }
+  inSingletonScope() {
+    this.binding.metadata.scope = "singleton";
+    return this;
+  }
+  inTransientScope() {
+    this.binding.metadata.scope = "transient";
+    return this;
+  }
+  inScopedScope() {
+    this.binding.metadata.scope = "scoped";
+    return this;
+  }
+  inRequestScope() {
+    this.binding.metadata.scope = "request";
+    return this;
+  }
+  withTags(...tags) {
+    this.binding.metadata.tags = [...this.binding.metadata.tags || [], ...tags];
+    return this;
+  }
+  when(condition) {
+    this.binding.metadata.when = condition;
+    return this;
+  }
+  lazy() {
+    this.binding.metadata.lazy = true;
+    return this;
+  }
+  build() {
+    this.container.register(this.binding);
+    return this.container;
+  }
+}
+var globalContainer = null;
+function getContainer() {
+  if (!globalContainer) {
+    globalContainer = new Container;
+  }
+  return globalContainer;
+}
+function setContainer(container) {
+  globalContainer = container;
+}
+function createContainer(options) {
+  return new Container(options);
+}
+
+// src/container/contextual-binding.ts
+class EnvironmentManager {
+  environments = new Map;
+  currentEnvironment;
+  variables = new Map;
+  constructor(defaultEnvironment = "development") {
+    this.currentEnvironment = defaultEnvironment;
+    this.loadEnvironmentVariables();
+  }
+  register(config) {
+    this.environments.set(config.name, config);
+    return this;
+  }
+  setEnvironment(name) {
+    if (!this.environments.has(name)) {
+      throw new Error(`Environment ${name} is not registered`);
+    }
+    this.currentEnvironment = name;
+    this.loadEnvironmentVariables();
+    return this;
+  }
+  getCurrentEnvironment() {
+    return this.currentEnvironment;
+  }
+  getEnvironment(name) {
+    return this.environments.get(name || this.currentEnvironment);
+  }
+  is(...environments) {
+    return environments.includes(this.currentEnvironment);
+  }
+  get(key, defaultValue) {
+    return this.variables.get(key) ?? defaultValue;
+  }
+  set(key, value) {
+    this.variables.set(key, value);
+    return this;
+  }
+  hasFeature(feature) {
+    const env = this.getEnvironment();
+    return env?.features.includes(feature) ?? false;
+  }
+  loadEnvironmentVariables() {
+    const env = this.getEnvironment();
+    if (env) {
+      for (const [key, value] of Object.entries(env.variables)) {
+        this.variables.set(key, value);
+      }
+    }
+  }
+}
+
+class DefaultContextualBindingBuilder {
+  container;
+  binding;
+  constructor(container, token) {
+    this.container = container;
+    this.binding = {
+      token,
+      conditions: [],
+      priority: 0,
+      metadata: {
+        scope: "transient"
+      }
+    };
+  }
+  when(condition) {
+    this.binding.conditions.push(condition);
+    return this;
+  }
+  whenEnvironment(...environments) {
+    const condition = {
+      type: "environment",
+      predicate: (context) => environments.includes(context.environment || "development"),
+      description: `Environment is one of: ${environments.join(", ")}`
+    };
+    return this.when(condition);
+  }
+  whenTag(tag) {
+    const condition = {
+      type: "tag",
+      predicate: (context) => {
+        return context.parent?.token?.toString().includes(tag) ?? false;
+      },
+      description: `Parent has tag: ${tag}`
+    };
+    return this.when(condition);
+  }
+  whenParent(parentToken) {
+    const condition = {
+      type: "parent",
+      predicate: (context) => context.parent?.token === parentToken,
+      description: `Parent token is: ${parentToken.toString()}`
+    };
+    return this.when(condition);
+  }
+  whenRequest(predicate) {
+    const condition = {
+      type: "request",
+      predicate,
+      description: "Custom request condition"
+    };
+    return this.when(condition);
+  }
+  withPriority(priority) {
+    this.binding.priority = priority;
+    return this;
+  }
+  withFallback(fallback) {
+    this.binding.fallback = fallback;
+    return this;
+  }
+  to(implementation) {
+    this.binding.implementation = implementation;
+    return this;
+  }
+  toValue(value) {
+    this.binding.value = value;
+    this.binding.metadata.scope = "singleton";
+    return this;
+  }
+  toFactory(factory) {
+    this.binding.factory = factory;
+    return this;
+  }
+  inSingletonScope() {
+    this.binding.metadata.scope = "singleton";
+    return this;
+  }
+  inTransientScope() {
+    this.binding.metadata.scope = "transient";
+    return this;
+  }
+  build() {
+    this.container.registerContextualBinding(this.binding);
+    return this.container;
+  }
+}
+
+class ContextualContainer extends Container {
+  contextualBindings = new Map;
+  environmentManager;
+  constructor(options) {
+    super(options);
+    this.environmentManager = new EnvironmentManager;
+  }
+  bindContextual(token) {
+    return new DefaultContextualBindingBuilder(this, token);
+  }
+  registerContextualBinding(binding) {
+    if (!this.contextualBindings.has(binding.token)) {
+      this.contextualBindings.set(binding.token, []);
+    }
+    const bindings = this.contextualBindings.get(binding.token);
+    bindings.push(binding);
+    bindings.sort((a, b) => b.priority - a.priority);
+    return this;
+  }
+  getEnvironmentManager() {
+    return this.environmentManager;
+  }
+  forDevelopment(token) {
+    return this.bindContextual(token).whenEnvironment("development");
+  }
+  forProduction(token) {
+    return this.bindContextual(token).whenEnvironment("production");
+  }
+  forTesting(token) {
+    return this.bindContextual(token).whenEnvironment("test", "testing");
+  }
+  forStaging(token) {
+    return this.bindContextual(token).whenEnvironment("staging");
+  }
+  resolve(token, context) {
+    const resolutionContext = {
+      container: this,
+      token,
+      environment: context?.environment || this.environmentManager.getCurrentEnvironment(),
+      requestId: context?.requestId || this.generateContextualRequestId(),
+      depth: context?.depth || 0,
+      resolving: context?.resolving || new Set,
+      parent: context?.parent
+    };
+    const contextualBinding = this.findContextualBinding(token, resolutionContext);
+    if (contextualBinding) {
+      return this.createInstanceFromContextualBinding(contextualBinding, resolutionContext);
+    }
+    return super.resolve(token, resolutionContext);
+  }
+  findContextualBinding(token, context) {
+    const bindings = this.contextualBindings.get(token);
+    if (!bindings)
+      return;
+    for (const binding of bindings) {
+      if (this.evaluateConditions(binding.conditions, context)) {
+        return binding;
+      }
+    }
+    return;
+  }
+  evaluateConditions(conditions, context) {
+    return conditions.every((condition) => {
+      try {
+        return condition.predicate(context);
+      } catch (error) {
+        console.warn(`Error evaluating binding condition: ${condition.description}`, error);
+        return false;
+      }
+    });
+  }
+  createInstanceFromContextualBinding(binding, context) {
+    try {
+      return this.createInstance(binding, context);
+    } catch (error) {
+      if (binding.fallback) {
+        console.warn(`Contextual binding failed, using fallback for ${binding.token.toString()}`);
+        return this.createInstance(binding.fallback, context);
+      }
+      throw error;
+    }
+  }
+  generateContextualRequestId() {
+    return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+}
+
+class EnvironmentPresets {
+  static development() {
+    return {
+      name: "development",
+      variables: {
+        DEBUG: true,
+        LOG_LEVEL: "debug",
+        CACHE_TTL: 60,
+        DB_POOL_SIZE: 5
+      },
+      services: {
+        logger: "ConsoleLogger",
+        cache: "MemoryCache",
+        database: "SQLiteDatabase"
+      },
+      features: ["hot-reload", "debug-toolbar", "detailed-errors"]
+    };
+  }
+  static production() {
+    return {
+      name: "production",
+      variables: {
+        DEBUG: false,
+        LOG_LEVEL: "error",
+        CACHE_TTL: 3600,
+        DB_POOL_SIZE: 20
+      },
+      services: {
+        logger: "FileLogger",
+        cache: "RedisCache",
+        database: "PostgreSQLDatabase"
+      },
+      features: ["performance-monitoring", "error-tracking"]
+    };
+  }
+  static testing() {
+    return {
+      name: "test",
+      variables: {
+        DEBUG: false,
+        LOG_LEVEL: "warn",
+        CACHE_TTL: 1,
+        DB_POOL_SIZE: 1
+      },
+      services: {
+        logger: "NullLogger",
+        cache: "MemoryCache",
+        database: "InMemoryDatabase"
+      },
+      features: ["test-doubles", "fast-teardown"]
+    };
+  }
+  static staging() {
+    return {
+      name: "staging",
+      variables: {
+        DEBUG: true,
+        LOG_LEVEL: "info",
+        CACHE_TTL: 1800,
+        DB_POOL_SIZE: 10
+      },
+      services: {
+        logger: "FileLogger",
+        cache: "RedisCache",
+        database: "PostgreSQLDatabase"
+      },
+      features: ["performance-monitoring", "debug-toolbar"]
+    };
+  }
+}
+
+class BindingConditions {
+  static environment(...environments) {
+    return {
+      type: "environment",
+      predicate: (context) => environments.includes(context.environment || "development"),
+      description: `Environment is one of: ${environments.join(", ")}`
+    };
+  }
+  static feature(featureName) {
+    return {
+      type: "custom",
+      predicate: (context) => {
+        const container = context.container;
+        return container.getEnvironmentManager().hasFeature(featureName);
+      },
+      description: `Feature ${featureName} is enabled`
+    };
+  }
+  static envVar(key, value) {
+    return {
+      type: "custom",
+      predicate: (context) => {
+        const container = context.container;
+        return container.getEnvironmentManager().get(key) === value;
+      },
+      description: `Environment variable ${key} equals ${value}`
+    };
+  }
+  static requestPattern(pattern) {
+    return {
+      type: "request",
+      predicate: (context) => pattern.test(context.requestId || ""),
+      description: `Request ID matches pattern: ${pattern.toString()}`
+    };
+  }
+  static timeRange(startHour, endHour) {
+    return {
+      type: "custom",
+      predicate: () => {
+        const hour = new Date().getHours();
+        return hour >= startHour && hour <= endHour;
+      },
+      description: `Time is between ${startHour}:00 and ${endHour}:00`
+    };
+  }
+  static custom(predicate, description) {
+    return {
+      type: "custom",
+      predicate,
+      description: description || "Custom condition"
+    };
+  }
+}
+
+// src/container/service-provider.ts
+class BaseServiceProvider {
+  version;
+  dependencies;
+  environment;
+  priority = 0;
+  boot(_container) {}
+  shutdown(_container) {}
+  singleton(container, token, implementation) {
+    container.singleton(token, implementation);
+  }
+  transient(container, token, implementation) {
+    container.transient(token, implementation);
+  }
+  value(container, token, value) {
+    container.value(token, value);
+  }
+  factory(container, token, factory) {
+    container.factory(token, factory);
+  }
+  when(container, condition) {
+    return {
+      bind: (token) => {
+        return container.bind(token).when(condition);
+      }
+    };
+  }
+  forEnvironment(container, ...environments) {
+    return this.when(container, (context) => environments.includes(context.environment || "development"));
+  }
+}
+
+class BaseDeferredServiceProvider extends BaseServiceProvider {
+  isDeferred() {
+    return true;
+  }
+}
+
+class DefaultServiceProviderManager {
+  providers = new Map;
+  deferredProviders = new Map;
+  loadedProviders = new Set;
+  bootedProviders = new Set;
+  container;
+  constructor(container) {
+    this.container = container;
+  }
+  register(provider) {
+    if (this.isConditionalProvider(provider)) {
+      const shouldLoad = provider.shouldLoad(this.container);
+      if (shouldLoad instanceof Promise) {
+        shouldLoad.then((load) => {
+          if (load) {
+            this.doRegister(provider);
+          }
+        });
+      } else if (!shouldLoad) {
+        return this;
+      }
+    }
+    this.doRegister(provider);
+    return this;
+  }
+  async boot() {
+    const providers = Array.from(this.providers.values()).sort((a, b) => (b.priority || 0) - (a.priority || 0));
+    this.validateDependencies(providers);
+    for (const provider of providers) {
+      if (!this.loadedProviders.has(provider.name)) {
+        await this.loadProvider(provider);
+      }
+    }
+    for (const provider of providers) {
+      if (!this.bootedProviders.has(provider.name)) {
+        await this.bootProvider(provider);
+      }
+    }
+  }
+  async shutdown() {
+    const providers = Array.from(this.providers.values()).reverse();
+    for (const provider of providers) {
+      if (provider.shutdown) {
+        try {
+          await provider.shutdown(this.container);
+        } catch (error) {
+          console.error(`Error shutting down provider ${provider.name}:`, error);
+        }
+      }
+    }
+    this.providers.clear();
+    this.deferredProviders.clear();
+    this.loadedProviders.clear();
+    this.bootedProviders.clear();
+  }
+  getProvider(name) {
+    return this.providers.get(name);
+  }
+  getProviders() {
+    return Array.from(this.providers.values());
+  }
+  async loadDeferredProvider(token) {
+    for (const [name, provider] of this.deferredProviders) {
+      if (provider.provides().includes(token) && !this.loadedProviders.has(name)) {
+        await this.loadProvider(provider);
+        await this.bootProvider(provider);
+        this.deferredProviders.delete(name);
+      }
+    }
+  }
+  doRegister(provider) {
+    if (this.providers.has(provider.name)) {
+      throw new Error(`Provider ${provider.name} is already registered`);
+    }
+    this.providers.set(provider.name, provider);
+    if (this.isDeferredProvider(provider)) {
+      this.deferredProviders.set(provider.name, provider);
+    }
+  }
+  async loadProvider(provider) {
+    try {
+      await provider.register(this.container);
+      this.loadedProviders.add(provider.name);
+    } catch (error) {
+      throw new Error(`Failed to load provider ${provider.name}: ${error}`);
+    }
+  }
+  async bootProvider(provider) {
+    if (provider.boot) {
+      try {
+        await provider.boot(this.container);
+        this.bootedProviders.add(provider.name);
+      } catch (error) {
+        throw new Error(`Failed to boot provider ${provider.name}: ${error}`);
+      }
+    } else {
+      this.bootedProviders.add(provider.name);
+    }
+  }
+  validateDependencies(providers) {
+    const providerNames = new Set(providers.map((p) => p.name));
+    for (const provider of providers) {
+      if (provider.dependencies) {
+        for (const dependency of provider.dependencies) {
+          if (!providerNames.has(dependency)) {
+            throw new Error(`Provider ${provider.name} depends on ${dependency}, but it's not registered`);
+          }
+        }
+      }
+    }
+  }
+  isDeferredProvider(provider) {
+    return "provides" in provider && "isDeferred" in provider;
+  }
+  isConditionalProvider(provider) {
+    return "shouldLoad" in provider;
+  }
+}
+
+class ConfigServiceProvider extends BaseServiceProvider {
+  name = "config";
+  priority = 100;
+  register(container) {
+    container.singleton("config", ConfigService);
+    this.forEnvironment(container, "development").bind("config.debug").toValue(true);
+    this.forEnvironment(container, "production").bind("config.debug").toValue(false);
+    this.forEnvironment(container, "test").bind("config.debug").toValue(false);
+  }
+}
+
+class LoggingServiceProvider extends BaseServiceProvider {
+  name = "logging";
+  priority = 90;
+  register(container) {
+    container.factory("logger", (config) => {
+      return new Logger(config.get("logging", {}));
+    });
+    this.forEnvironment(container, "development").bind("logger").toFactory(() => new ConsoleLogger);
+    this.forEnvironment(container, "production").bind("logger").toFactory((config) => new FileLogger(config.get("logging.file", "./app.log")));
+  }
+}
+
+class DatabaseServiceProvider extends BaseServiceProvider {
+  name = "database";
+  dependencies = ["config", "logging"];
+  register(container) {
+    container.singleton("database", DatabaseConnection);
+    container.transient("userRepository", UserRepository);
+    container.transient("postRepository", PostRepository);
+  }
+  async boot(container) {
+    const db = container.resolve("database");
+    await db.connect();
+  }
+  async shutdown(container) {
+    const db = container.resolve("database");
+    await db.disconnect();
+  }
+}
+
+class CacheServiceProvider extends BaseServiceProvider {
+  name = "cache";
+  dependencies = ["config"];
+  register(container) {
+    container.singleton("cache", CacheManager);
+    this.forEnvironment(container, "development").bind("cache.store").toFactory(() => new MemoryCache);
+    this.forEnvironment(container, "production").bind("cache.store").toFactory((config) => new RedisCache(config.get("cache.redis")));
+  }
+}
+
+class AuthServiceProvider extends BaseServiceProvider {
+  name = "auth";
+  dependencies = ["config", "database"];
+  register(container) {
+    container.singleton("authService", AuthService);
+    container.singleton("jwtService", JwtService);
+    container.transient("authGuard", AuthGuard);
+  }
+}
+
+class ValidationServiceProvider extends BaseServiceProvider {
+  name = "validation";
+  register(container) {
+    container.singleton("validator", Validator);
+    container.factory("validationPipe", (validator) => new ValidationPipe(validator));
+  }
+}
+
+class EventServiceProvider extends BaseDeferredServiceProvider {
+  name = "events";
+  provides() {
+    return ["eventBus", "eventDispatcher", EventBus, EventDispatcher];
+  }
+  register(container) {
+    container.singleton("eventBus", EventBus);
+    container.singleton("eventDispatcher", EventDispatcher);
+  }
+}
+
+class ConfigService {
+  get(key, defaultValue) {
+    return defaultValue;
+  }
+}
+
+class Logger {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+  log(message) {
+    console.log(message);
+  }
+}
+
+class ConsoleLogger extends Logger {
+  constructor() {
+    super({});
+  }
+}
+
+class FileLogger extends Logger {
+  filePath;
+  constructor(filePath) {
+    super({});
+    this.filePath = filePath;
+  }
+}
+
+class DatabaseConnection {
+  async connect() {}
+  async disconnect() {}
+}
+
+class UserRepository {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+}
+
+class PostRepository {
+  db;
+  constructor(db) {
+    this.db = db;
+  }
+}
+
+class CacheManager {
+  store;
+  constructor(store) {
+    this.store = store;
+  }
+}
+
+class MemoryCache {
+  cache = new Map;
+}
+
+class RedisCache {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+}
+
+class AuthService {
+  jwt;
+  userRepo;
+  constructor(jwt, userRepo) {
+    this.jwt = jwt;
+    this.userRepo = userRepo;
+  }
+}
+
+class JwtService {
+  config;
+  constructor(config) {
+    this.config = config;
+  }
+}
+
+class AuthGuard {
+  auth;
+  constructor(auth) {
+    this.auth = auth;
+  }
+}
+
+class Validator {
+  validate(_data, _rules) {
+    return true;
+  }
+}
+
+class ValidationPipe {
+  validator;
+  constructor(validator) {
+    this.validator = validator;
+  }
+}
+
+class EventBus {
+  emit(_event, _data) {}
+}
+
+class EventDispatcher {
+  bus;
+  constructor(bus) {
+    this.bus = bus;
+  }
+}
+
+export { RouterException, ValidationException, AuthenticationException, AuthorizationException, NotFoundException, MethodNotAllowedException, TimeoutException, RateLimitException, InternalServerException, ServiceUnavailableException, DatabaseException, ExternalServiceException, CircuitBreakerOpenException, BusinessLogicException, ConfigurationException, FileSystemException, ErrorFactory, RouteConflictException, CircularDependencyException, MiddlewareConfigurationException, RouteNotFoundException, HandlerResolutionException, ModelBindingException, findSimilarRoutes, detectRouteConflicts, RouterErrorFactory, INJECTABLE_METADATA_KEY, INJECT_METADATA_KEY, OPTIONAL_METADATA_KEY, TAGGED_METADATA_KEY, Container, BindingBuilder, getContainer, setContainer, createContainer, EnvironmentManager, DefaultContextualBindingBuilder, ContextualContainer, EnvironmentPresets, BindingConditions, BaseServiceProvider, BaseDeferredServiceProvider, DefaultServiceProviderManager, ConfigServiceProvider, LoggingServiceProvider, DatabaseServiceProvider, CacheServiceProvider, AuthServiceProvider, ValidationServiceProvider, EventServiceProvider, ConfigService, Logger, ConsoleLogger, FileLogger, DatabaseConnection, UserRepository, PostRepository, CacheManager, MemoryCache, RedisCache, AuthService, JwtService, AuthGuard, Validator, ValidationPipe, EventBus, EventDispatcher };