@coherent.js/api 1.0.0-beta.2

package/dist/index.cjs

@@ -0,0 +1,1776 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var index_exports = {};
+__export(index_exports, {
+  ApiError: () => ApiError,
+  AuthenticationError: () => AuthenticationError,
+  AuthorizationError: () => AuthorizationError,
+  ConflictError: () => ConflictError,
+  NotFoundError: () => NotFoundError,
+  ValidationError: () => ValidationError,
+  createErrorHandler: () => createErrorHandler,
+  createRouter: () => createRouter,
+  default: () => index_default,
+  deserializeDate: () => deserializeDate,
+  deserializeMap: () => deserializeMap,
+  deserializeSet: () => deserializeSet,
+  generateToken: () => generateToken,
+  hashPassword: () => hashPassword,
+  serializeDate: () => serializeDate,
+  serializeForJSON: () => serializeForJSON,
+  serializeMap: () => serializeMap,
+  serializeSet: () => serializeSet,
+  validateAgainstSchema: () => validateAgainstSchema,
+  validateField: () => validateField,
+  verifyPassword: () => verifyPassword,
+  withAuth: () => withAuth,
+  withErrorHandling: () => withErrorHandling,
+  withInputValidation: () => withInputValidation,
+  withParamsValidation: () => withParamsValidation,
+  withQueryValidation: () => withQueryValidation,
+  withRole: () => withRole,
+  withSerialization: () => withSerialization,
+  withValidation: () => withValidation
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/router.js
+var import_node_crypto = require("node:crypto");
+
+// src/errors.js
+var ApiError = class _ApiError extends Error {
+  /**
+   * Create an API _error
+   * @param {string} message - Error message
+   * @param {number} statusCode - HTTP status code
+   * @param {Object} details - Additional _error details
+   */
+  constructor(message, statusCode = 500, details = {}) {
+    super(message);
+    this.name = "ApiError";
+    this.statusCode = statusCode;
+    this.details = details;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _ApiError);
+    }
+  }
+  /**
+   * Convert _error to JSON-serializable object
+   * @returns {Object} Error object
+   */
+  toJSON() {
+    return {
+      _error: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      details: this.details
+    };
+  }
+};
+var ValidationError = class extends ApiError {
+  /**
+   * Create a validation _error
+   * @param {Object} errors - Validation errors
+   * @param {string} message - Error message
+   */
+  constructor(errors, message = "Validation failed") {
+    super(message, 400, { errors });
+    this.name = "ValidationError";
+  }
+};
+var AuthenticationError = class extends ApiError {
+  /**
+   * Create an authentication _error
+   * @param {string} message - Error message
+   */
+  constructor(message = "Authentication required") {
+    super(message, 401);
+    this.name = "AuthenticationError";
+  }
+};
+var AuthorizationError = class extends ApiError {
+  /**
+   * Create an authorization _error
+   * @param {string} message - Error message
+   */
+  constructor(message = "Access denied") {
+    super(message, 403);
+    this.name = "AuthorizationError";
+  }
+};
+var NotFoundError = class extends ApiError {
+  /**
+   * Create a not found _error
+   * @param {string} message - Error message
+   */
+  constructor(message = "Resource not found") {
+    super(message, 404);
+    this.name = "NotFoundError";
+  }
+};
+var ConflictError = class extends ApiError {
+  /**
+   * Create a conflict _error
+   * @param {string} message - Error message
+   */
+  constructor(message = "Resource conflict") {
+    super(message, 409);
+    this.name = "ConflictError";
+  }
+};
+function withErrorHandling(handler) {
+  return async (req, res, next) => {
+    try {
+      return await handler(req, res, next);
+    } catch (_error) {
+      if (_error instanceof ApiError) {
+        throw _error;
+      }
+      throw new ApiError(_error.message || "Internal server _error", 500);
+    }
+  };
+}
+function createErrorHandler() {
+  return (_error, req, res, next) => {
+    console.error("API Error:", _error);
+    if (res.headersSent) {
+      return next(_error);
+    }
+    const response = {
+      _error: _error.name || "Error",
+      message: _error.message || "An _error occurred",
+      statusCode: _error.statusCode || 500
+    };
+    if (_error.details) {
+      response.details = _error.details;
+    }
+    if (true) {
+      response.stack = _error.stack;
+    }
+    res.status(response.statusCode).json(response);
+  };
+}
+
+// src/validation.js
+function validateAgainstSchema(schema, data) {
+  const errors = [];
+  if (schema.type === "object") {
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+      errors.push({
+        field: "",
+        message: `Expected object, got ${typeof data}`
+      });
+      return { valid: false, errors };
+    }
+    if (schema.required && Array.isArray(schema.required)) {
+      for (const field of schema.required) {
+        if (!(field in data)) {
+          errors.push({
+            field,
+            message: `Required field '${field}' is missing`
+          });
+        }
+      }
+    }
+    if (schema.properties) {
+      for (const [field, fieldSchema] of Object.entries(schema.properties)) {
+        if (field in data) {
+          const fieldValue = data[field];
+          const fieldErrors = validateField(fieldSchema, fieldValue, field);
+          errors.push(...fieldErrors);
+        }
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+function validateField(schema, value, fieldName) {
+  const errors = [];
+  if (schema.type) {
+    if (schema.type === "string" && typeof value !== "string") {
+      errors.push({
+        field: fieldName,
+        message: `Expected string, got ${typeof value}`
+      });
+    } else if (schema.type === "number" && typeof value !== "number") {
+      errors.push({
+        field: fieldName,
+        message: `Expected number, got ${typeof value}`
+      });
+    } else if (schema.type === "boolean" && typeof value !== "boolean") {
+      errors.push({
+        field: fieldName,
+        message: `Expected boolean, got ${typeof value}`
+      });
+    } else if (schema.type === "array" && !Array.isArray(value)) {
+      errors.push({
+        field: fieldName,
+        message: `Expected array, got ${typeof value}`
+      });
+    }
+  }
+  if (schema.type === "string") {
+    if (schema.minLength && value.length < schema.minLength) {
+      errors.push({
+        field: fieldName,
+        message: `String must be at least ${schema.minLength} characters`
+      });
+    }
+    if (schema.maxLength && value.length > schema.maxLength) {
+      errors.push({
+        field: fieldName,
+        message: `String must be at most ${schema.maxLength} characters`
+      });
+    }
+    if (schema.format === "email" && !/^[^@]+@[^@]+\.[^@]+$/.test(value)) {
+      errors.push({
+        field: fieldName,
+        message: "Invalid email format"
+      });
+    }
+  }
+  if (schema.type === "number") {
+    if (schema.minimum !== void 0 && value < schema.minimum) {
+      errors.push({
+        field: fieldName,
+        message: `Number must be at least ${schema.minimum}`
+      });
+    }
+    if (schema.maximum !== void 0 && value > schema.maximum) {
+      errors.push({
+        field: fieldName,
+        message: `Number must be at most ${schema.maximum}`
+      });
+    }
+  }
+  return errors;
+}
+function withValidation(schema) {
+  return (req, res, next) => {
+    const data = req.body || {};
+    const result = validateAgainstSchema(schema, data);
+    if (!result.valid) {
+      throw new ValidationError(result.errors);
+    }
+    next();
+  };
+}
+function withQueryValidation(schema) {
+  return (req, res, next) => {
+    const data = req.query || {};
+    const result = validateAgainstSchema(schema, data);
+    if (!result.valid) {
+      throw new ValidationError(result.errors);
+    }
+    next();
+  };
+}
+function withParamsValidation(schema) {
+  return (req, res, next) => {
+    const data = req.params || {};
+    const result = validateAgainstSchema(schema, data);
+    if (!result.valid) {
+      throw new ValidationError(result.errors);
+    }
+    next();
+  };
+}
+
+// src/router.js
+var import_node_http = require("node:http");
+var import_node_url = require("node:url");
+var HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH"];
+function parseBody(req, maxSize = 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    if (req.method === "GET" || req.method === "DELETE") {
+      resolve({});
+      return;
+    }
+    let body = "";
+    let size = 0;
+    req.on("data", (chunk) => {
+      size += chunk.length;
+      if (size > maxSize) {
+        reject(new Error("Request body too large"));
+        return;
+      }
+      body += chunk.toString();
+    });
+    req.on("end", () => {
+      try {
+        const contentType = req.headers["content-type"] || "";
+        if (contentType.includes("application/json")) {
+          const parsed = body ? JSON.parse(body) : {};
+          resolve(sanitizeInput(parsed));
+        } else {
+          resolve({});
+        }
+      } catch {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+    req.on("_error", reject);
+  });
+}
+function sanitizeInput(obj) {
+  if (typeof obj !== "object" || obj === null) return obj;
+  const sanitized = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (key.startsWith("__") || key.includes("prototype")) continue;
+    if (typeof value === "string") {
+      sanitized[key] = value.replace(/<script[^>]*>.*?<\/script>/gi, "").replace(/javascript:/gi, "").replace(/on\w+=/gi, "");
+    } else if (typeof value === "object") {
+      sanitized[key] = sanitizeInput(value);
+    } else {
+      sanitized[key] = value;
+    }
+  }
+  return sanitized;
+}
+var rateLimitStore = /* @__PURE__ */ new Map();
+function checkRateLimit(ip, windowMs = 6e4, maxRequests = 100) {
+  const now = Date.now();
+  const key = ip;
+  if (!rateLimitStore.has(key)) {
+    rateLimitStore.set(key, { count: 1, resetTime: now + windowMs });
+    return true;
+  }
+  const record = rateLimitStore.get(key);
+  if (now > record.resetTime) {
+    record.count = 1;
+    record.resetTime = now + windowMs;
+    return true;
+  }
+  if (record.count >= maxRequests) {
+    return false;
+  }
+  record.count++;
+  return true;
+}
+function addSecurityHeaders(res, corsOrigin = null) {
+  const origin = corsOrigin || "http://localhost:3000";
+  res.setHeader("Access-Control-Allow-Origin", origin);
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, PATCH, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+  res.setHeader("Access-Control-Allow-Credentials", "true");
+  res.setHeader("X-Content-Type-Options", "nosniff");
+  res.setHeader("X-Frame-Options", "DENY");
+  res.setHeader("X-XSS-Protection", "1; mode=block");
+  res.setHeader("Strict-Transport-Security", "max-age=31536000; includeSubDomains");
+  res.setHeader("Content-Security-Policy", "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'");
+  res.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
+}
+function extractParams(pattern, path) {
+  const patternParts = pattern.split("/");
+  const pathParts = path.split("/");
+  const params = {};
+  const hasMultiWildcard = patternParts.includes("**");
+  const hasSingleWildcard = patternParts.includes("*");
+  if (!hasMultiWildcard && !hasSingleWildcard && patternParts.length !== pathParts.length) {
+    return null;
+  }
+  for (let i = 0; i < patternParts.length; i++) {
+    const patternPart = patternParts[i];
+    const pathPart = pathParts[i];
+    if (patternPart.startsWith(":")) {
+      const match = patternPart.match(/^:([^(]+)(\(([^)]+)\))?(\?)?$/);
+      if (match) {
+        const [, paramName, , constraint, optional] = match;
+        if (optional && !pathPart) {
+          continue;
+        }
+        if (constraint) {
+          const regex = new RegExp(`^${constraint}$`);
+          if (!regex.test(pathPart)) {
+            return null;
+          }
+        }
+        params[paramName] = pathPart;
+      } else {
+        params[patternPart.slice(1)] = pathPart;
+      }
+    } else if (patternPart === "*") {
+      params.splat = pathPart;
+    } else if (patternPart === "**") {
+      params.splat = pathParts.slice(i).join("/");
+      return params;
+    } else if (patternPart !== pathPart) {
+      return null;
+    }
+  }
+  return params;
+}
+function processRoutes(routeObj, router, basePath = "") {
+  if (!routeObj || typeof routeObj !== "object") return;
+  Object.entries(routeObj).forEach(([key, config]) => {
+    if (!config || typeof config !== "object") return;
+    if (config.ws && typeof config.ws === "function") {
+      const cleanKey = key.startsWith("/") ? key.slice(1) : key;
+      const wsPath = basePath ? `${basePath}/${cleanKey}` : `/${cleanKey}`;
+      router.addWebSocketRoute(wsPath, config.ws);
+      return;
+    }
+    if (HTTP_METHODS.includes(key.toUpperCase())) {
+      registerRoute(key.toUpperCase(), config, router, basePath);
+    } else {
+      const cleanKey = key.startsWith("/") ? key.slice(1) : key;
+      const path = basePath ? `${basePath}/${cleanKey}` : `/${cleanKey}`;
+      processRoutes(config, router, path);
+    }
+  });
+}
+function registerRoute(method, config, router, path) {
+  const {
+    handler,
+    handlers,
+    validation,
+    middleware,
+    errorHandling = true,
+    path: customPath,
+    name
+  } = config;
+  const routePath = customPath || path || "/";
+  const chain = [];
+  if (middleware) {
+    chain.push(...Array.isArray(middleware) ? middleware : [middleware]);
+  }
+  if (validation) {
+    chain.push(withValidation(validation));
+  }
+  if (handlers) {
+    chain.push(...handlers);
+  } else if (handler) {
+    chain.push(handler);
+  } else {
+    console.warn(`No handler for ${method} ${routePath}`);
+    return;
+  }
+  if (errorHandling) {
+    chain.forEach((fn, i) => {
+      chain[i] = withErrorHandling(fn);
+    });
+  }
+  router.addRoute(method, routePath, async (req, res) => {
+    try {
+      let result = null;
+      for (const fn of chain) {
+        result = await fn(req, res);
+        if (result && typeof result === "object") {
+          break;
+        }
+      }
+      if (result && typeof result === "object") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(result));
+      } else {
+        res.writeHead(204);
+        res.end();
+      }
+    } catch (_error) {
+      const statusCode = _error.statusCode || 500;
+      res.writeHead(statusCode, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ _error: _error.message }));
+    }
+  }, { name });
+}
+var SimpleRouter = class {
+  constructor(options = {}) {
+    this.routes = [];
+    this.routeCache = /* @__PURE__ */ new Map();
+    this.namedRoutes = /* @__PURE__ */ new Map();
+    this.maxCacheSize = options.maxCacheSize || 1e3;
+    this.routeGroups = [];
+    this.globalMiddleware = [];
+    this.enableCompilation = options.enableCompilation !== false;
+    this.compiledRoutes = /* @__PURE__ */ new Map();
+    this.routeCompilationCache = /* @__PURE__ */ new Map();
+    this.enableVersioning = options.enableVersioning || false;
+    this.defaultVersion = options.defaultVersion || "v1";
+    this.versionHeader = options.versionHeader || "api-version";
+    this.versionedRoutes = /* @__PURE__ */ new Map();
+    this.enableContentNegotiation = options.enableContentNegotiation !== false;
+    this.defaultContentType = options.defaultContentType || "application/json";
+    this.enableWebSockets = options.enableWebSockets || false;
+    this.wsRoutes = [];
+    this.wsConnections = /* @__PURE__ */ new Map();
+    this.enableMetrics = options.enableMetrics || false;
+    if (this.enableMetrics) {
+      this.metrics = {
+        requests: 0,
+        cacheHits: 0,
+        compilationHits: 0,
+        routeMatches: /* @__PURE__ */ new Map(),
+        responseTime: [],
+        errors: 0,
+        versionRequests: /* @__PURE__ */ new Map(),
+        // Track requests per version
+        contentTypeRequests: /* @__PURE__ */ new Map(),
+        // Track requests per content type
+        wsConnections: 0,
+        // Track WebSocket connections
+        wsMessages: 0
+        // Track WebSocket messages
+      };
+    }
+  }
+  /**
+   * Add an HTTP route to the router
+   * 
+   * @param {string} method - HTTP method (GET, POST, PUT, DELETE, PATCH)
+   * @param {string} path - Route path pattern (supports :param and wildcards)
+   * @param {Function} handler - Route handler function
+   * @param {Object} [options={}] - Route options
+   * @param {Array} [options.middleware] - Route-specific middleware
+   * @param {string} [options.name] - Named route for URL generation
+   * @param {string} [options.version] - API version for this route
+   * 
+   * @example
+   * router.addRoute('GET', '/users/:id', (req, res) => {
+   *   return { user: { id: req.params.id } };
+   * }, { name: 'getUser', version: 'v2' });
+   */
+  addRoute(method, path, handler, options = {}) {
+    const prefix = this.getCurrentPrefix();
+    const fullPath = prefix + (path.startsWith("/") ? path : `/${path}`);
+    const groupMiddleware = this.getCurrentGroupMiddleware();
+    const routeMiddleware = options.middleware || [];
+    const allMiddleware = [...this.globalMiddleware, ...groupMiddleware, ...routeMiddleware];
+    const route = {
+      method: method.toUpperCase(),
+      path: fullPath,
+      handler,
+      middleware: allMiddleware,
+      name: options.name,
+      version: options.version || this.defaultVersion
+    };
+    if (this.enableCompilation) {
+      route.compiled = this.compileRoute(fullPath);
+    }
+    this.routes.push(route);
+    if (this.enableVersioning) {
+      if (!this.versionedRoutes.has(route.version)) {
+        this.versionedRoutes.set(route.version, []);
+      }
+      this.versionedRoutes.get(route.version).push(route);
+    }
+    if (options.name) {
+      this.namedRoutes.set(options.name, { method: route.method, path: fullPath, version: route.version });
+    }
+  }
+  /**
+   * Add a versioned route
+   * @param {string} version - API version (e.g., 'v1', 'v2')
+   * @param {string} method - HTTP method
+   * @param {string} path - Route path
+   * @param {Function} handler - Route handler
+   * @param {Object} options - Route options
+   */
+  addVersionedRoute(version, method, path, handler, options = {}) {
+    this.addRoute(method, path, handler, { ...options, version });
+  }
+  /**
+   * Add route with content negotiation support
+   * @param {string} method - HTTP method
+   * @param {string} path - Route path
+   * @param {Object} handlers - Content type handlers { 'application/json': handler, 'text/xml': handler }
+   * @param {Object} options - Route options
+   */
+  addContentNegotiatedRoute(method, path, handlers, options = {}) {
+    const negotiationHandler = async (req, res) => {
+      const acceptedType = this.negotiateContentType(req, Object.keys(handlers));
+      if (this.enableMetrics) {
+        this.metrics.contentTypeRequests.set(acceptedType, (this.metrics.contentTypeRequests.get(acceptedType) || 0) + 1);
+      }
+      const handler = handlers[acceptedType];
+      if (!handler) {
+        res.writeHead(406, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({
+          _error: "Not Acceptable",
+          supportedTypes: Object.keys(handlers)
+        }));
+        return;
+      }
+      const result = await handler(req, res);
+      if (result && typeof result === "object") {
+        res.writeHead(200, { "Content-Type": acceptedType });
+        if (acceptedType === "application/json") {
+          res.end(JSON.stringify(result));
+        } else if (acceptedType === "text/xml" || acceptedType === "application/xml") {
+          res.end(this.objectToXml(result));
+        } else if (acceptedType === "text/html") {
+          res.end(typeof result === "string" ? result : `<pre>${JSON.stringify(result, null, 2)}</pre>`);
+        } else if (acceptedType === "text/plain") {
+          res.end(typeof result === "string" ? result : JSON.stringify(result));
+        } else {
+          res.end(JSON.stringify(result));
+        }
+      }
+    };
+    this.addRoute(method, path, negotiationHandler, options);
+  }
+  /**
+   * Negotiate content type based on Accept header
+   * @param {Object} req - Request object
+   * @param {Array} supportedTypes - Array of supported content types
+   * @returns {string} Best matching content type
+   * @private
+   */
+  negotiateContentType(req, supportedTypes) {
+    const acceptHeader = req.headers.accept || this.defaultContentType;
+    const acceptedTypes = acceptHeader.split(",").map((type) => {
+      const [mediaType, ...params] = type.trim().split(";");
+      const qValue = params.find((p) => p.trim().startsWith("q="));
+      const quality = qValue ? parseFloat(qValue.split("=")[1]) : 1;
+      return { type: mediaType.trim(), quality };
+    }).sort((a, b) => b.quality - a.quality);
+    for (const accepted of acceptedTypes) {
+      if (accepted.type === "*/*") {
+        return supportedTypes[0] || this.defaultContentType;
+      }
+      const [mainType, subType] = accepted.type.split("/");
+      for (const supported of supportedTypes) {
+        const [supportedMain, supportedSub] = supported.split("/");
+        if (accepted.type === supported || mainType === supportedMain && subType === "*" || mainType === "*" && subType === supportedSub) {
+          return supported;
+        }
+      }
+    }
+    return supportedTypes[0] || this.defaultContentType;
+  }
+  /**
+   * Convert object to XML string
+   * @param {Object} obj - Object to convert
+   * @param {string} rootName - Root element name
+   * @returns {string} XML string
+   * @private
+   */
+  objectToXml(obj, rootName = "root") {
+    const xmlEscape = (str) => String(str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+    const toXml = (obj2, name) => {
+      if (obj2 === null || obj2 === void 0) {
+        return `<${name}/>`;
+      }
+      if (typeof obj2 !== "object") {
+        return `<${name}>${xmlEscape(obj2)}</${name}>`;
+      }
+      if (Array.isArray(obj2)) {
+        return obj2.map((item) => toXml(item, "item")).join("");
+      }
+      const content = Object.entries(obj2).map(([key, value]) => toXml(value, key)).join("");
+      return `<${name}>${content}</${name}>`;
+    };
+    return `<?xml version="1.0" encoding="UTF-8"?>${toXml(obj, rootName)}`;
+  }
+  /**
+   * Add WebSocket route
+   * @param {string} path - WebSocket path
+   * @param {Function} handler - WebSocket handler function
+   * @param {Object} options - Route options
+   */
+  addWebSocketRoute(path, handler, options = {}) {
+    if (!this.enableWebSockets) {
+      throw new Error("WebSocket routing is disabled. Enable with { enableWebSockets: true }");
+    }
+    const prefix = this.getCurrentPrefix();
+    const fullPath = prefix + (path.startsWith("/") ? path : `/${path}`);
+    const wsRoute = {
+      path: fullPath,
+      handler,
+      name: options.name,
+      version: options.version || this.defaultVersion,
+      compiled: this.enableCompilation ? this.compileRoute(fullPath) : null
+    };
+    this.wsRoutes.push(wsRoute);
+    if (options.name) {
+      this.namedRoutes.set(options.name, { method: "WS", path: fullPath, version: wsRoute.version });
+    }
+  }
+  /**
+   * Handle WebSocket upgrade request
+   * @param {Object} request - HTTP request object
+   * @param {Object} socket - Socket object
+   * @param {Buffer} head - First packet of the upgraded stream
+   */
+  handleWebSocketUpgrade(request, socket, head) {
+    if (!this.enableWebSockets) {
+      socket.end("HTTP/1.1 501 Not Implemented\r\n\r\n");
+      return;
+    }
+    const url = new URL(request.url, `http://${request.headers.host}`);
+    const pathname = url.pathname;
+    let matchedRoute = null;
+    for (const wsRoute of this.wsRoutes) {
+      let params = null;
+      if (this.enableCompilation && wsRoute.compiled) {
+        params = this.matchCompiledRoute(wsRoute.compiled, pathname);
+      } else {
+        params = extractParams(wsRoute.path, pathname);
+      }
+      if (params !== null) {
+        matchedRoute = { route: wsRoute, params };
+        break;
+      }
+    }
+    if (!matchedRoute) {
+      socket.end("HTTP/1.1 404 Not Found\r\n\r\n");
+      return;
+    }
+    this.createWebSocketConnection(request, socket, head, matchedRoute);
+  }
+  /**
+   * Create WebSocket connection
+   * @param {Object} request - HTTP request object
+   * @param {Object} socket - Socket object
+   * @param {Buffer} head - First packet of the upgraded stream
+   * @param {Object} matchedRoute - Matched WebSocket route
+   * @private
+   */
+  createWebSocketConnection(request, socket, head, matchedRoute) {
+    const key = request.headers["sec-websocket-key"];
+    if (!key) {
+      socket.end("HTTP/1.1 400 Bad Request\r\n\r\n");
+      return;
+    }
+    const acceptKey = (0, import_node_crypto.createHash)("sha1").update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`).digest("base64");
+    const responseHeaders = [
+      "HTTP/1.1 101 Switching Protocols",
+      "Upgrade: websocket",
+      "Connection: Upgrade",
+      `Sec-WebSocket-Accept: ${acceptKey}`,
+      "",
+      ""
+    ].join("\r\n");
+    socket.write(responseHeaders);
+    const ws = this.createWebSocketWrapper(socket, matchedRoute);
+    const connectionId = (0, import_node_crypto.randomBytes)(16).toString("hex");
+    this.wsConnections.set(connectionId, ws);
+    if (this.enableMetrics) {
+      this.metrics.wsConnections++;
+    }
+    ws.id = connectionId;
+    ws.params = matchedRoute.params;
+    ws.path = matchedRoute.route.path;
+    socket.on("close", () => {
+      if (matchedRoute.route.handler.onClose) {
+        matchedRoute.route.handler.onClose(ws);
+      }
+      if (ws.onclose) {
+        try {
+          ws.onclose();
+        } catch (_error) {
+          console.error("WebSocket onclose handler _error:", _error);
+        }
+      }
+      this.wsConnections.delete(connectionId);
+      if (this.enableMetrics) {
+        this.metrics.wsConnections--;
+      }
+    });
+    try {
+      matchedRoute.route.handler(ws, request);
+    } catch (err) {
+      console.error("WebSocket upgrade _error:", err);
+      socket.end("HTTP/1.1 500 Internal Server Error\r\n\r\n");
+    }
+  }
+  /**
+   * Create WebSocket wrapper with message handling
+   * @param {Object} socket - Raw socket
+   * @param {Object} matchedRoute - Matched route info
+   * @returns {Object} WebSocket wrapper
+   * @private
+   */
+  createWebSocketWrapper(socket) {
+    const ws = {
+      socket,
+      readyState: 1,
+      // OPEN
+      send(data) {
+        if (this.readyState !== 1) return;
+        const message = typeof data === "string" ? data : JSON.stringify(data);
+        const frame = this.createFrame(message);
+        socket.write(frame);
+        if (ws.router && ws.router.enableMetrics) {
+          ws.router.metrics.wsMessages++;
+        }
+      },
+      close(code = 1e3, reason = "") {
+        if (this.readyState !== 1) return;
+        this.readyState = 3;
+        const frame = this.createCloseFrame(code, reason);
+        socket.write(frame);
+        socket.destroy();
+      },
+      ping(data = Buffer.alloc(0)) {
+        if (this.readyState !== 1) return;
+        const frame = this.createPingFrame(data);
+        socket.write(frame);
+      },
+      createFrame(data) {
+        const payload = Buffer.from(data, "utf8");
+        const payloadLength = payload.length;
+        let frame;
+        if (payloadLength < 126) {
+          frame = Buffer.allocUnsafe(2 + payloadLength);
+          frame[0] = 129;
+          frame[1] = payloadLength;
+          payload.copy(frame, 2);
+        } else if (payloadLength < 65536) {
+          frame = Buffer.allocUnsafe(4 + payloadLength);
+          frame[0] = 129;
+          frame[1] = 126;
+          frame.writeUInt16BE(payloadLength, 2);
+          payload.copy(frame, 4);
+        } else {
+          frame = Buffer.allocUnsafe(10 + payloadLength);
+          frame[0] = 129;
+          frame[1] = 127;
+          frame.writeUInt32BE(0, 2);
+          frame.writeUInt32BE(payloadLength, 6);
+          payload.copy(frame, 10);
+        }
+        return frame;
+      },
+      createCloseFrame(code, reason) {
+        const reasonBuffer = Buffer.from(reason, "utf8");
+        const frame = Buffer.allocUnsafe(4 + reasonBuffer.length);
+        frame[0] = 136;
+        frame[1] = 2 + reasonBuffer.length;
+        frame.writeUInt16BE(code, 2);
+        reasonBuffer.copy(frame, 4);
+        return frame;
+      },
+      createPingFrame(data) {
+        const frame = Buffer.allocUnsafe(2 + data.length);
+        frame[0] = 137;
+        frame[1] = data.length;
+        data.copy(frame, 2);
+        return frame;
+      }
+    };
+    ws.router = this;
+    socket.on("data", (buffer) => {
+      try {
+        const message = this.parseWebSocketFrame(buffer);
+        if (message && ws.onmessage) {
+          ws.onmessage({ data: message });
+        }
+      } catch {
+      }
+    });
+    socket.on("_error", (err) => {
+      console.log("WebSocket socket _error (connection likely closed):", err.code);
+    });
+    return ws;
+  }
+  /**
+   * Parse WebSocket frame
+   * @param {Buffer} buffer - Raw frame data
+   * @returns {string|null} Parsed message
+   * @private
+   */
+  parseWebSocketFrame(buffer) {
+    if (buffer.length < 2) return null;
+    const firstByte = buffer[0];
+    const secondByte = buffer[1];
+    const opcode = firstByte & 15;
+    const masked = (secondByte & 128) === 128;
+    let payloadLength = secondByte & 127;
+    if (opcode === 8) {
+      return null;
+    }
+    if (opcode !== 1) {
+      return null;
+    }
+    let offset = 2;
+    if (payloadLength === 126) {
+      if (buffer.length < offset + 2) return null;
+      payloadLength = buffer.readUInt16BE(offset);
+      offset += 2;
+    } else if (payloadLength === 127) {
+      if (buffer.length < offset + 8) return null;
+      payloadLength = buffer.readUInt32BE(offset + 4);
+      offset += 8;
+    }
+    if (masked) {
+      if (buffer.length < offset + 4 + payloadLength) return null;
+      const maskKey = buffer.slice(offset, offset + 4);
+      offset += 4;
+      const payload = buffer.slice(offset, offset + payloadLength);
+      for (let i = 0; i < payload.length; i++) {
+        payload[i] ^= maskKey[i % 4];
+      }
+      return payload.toString("utf8");
+    }
+    if (buffer.length < offset + payloadLength) return null;
+    return buffer.slice(offset, offset + payloadLength).toString("utf8");
+  }
+  /**
+   * Broadcast message to all WebSocket connections on a path
+   * @param {string} path - WebSocket path pattern
+   * @param {*} message - Message to broadcast
+   * @param {string} [excludeId=null] - Connection ID to exclude from broadcast
+   */
+  broadcast(path, message, excludeId = null) {
+    for (const [id, ws] of this.wsConnections) {
+      if (id === excludeId) continue;
+      if (ws.path === path || path === "*" && ws.path) {
+        try {
+          ws.send(message);
+        } catch {
+          console.log("Failed to send message to connection:", id);
+        }
+      }
+    }
+  }
+  /**
+   * Get active WebSocket connections
+   * @returns {Array} Array of connection info
+   */
+  getWebSocketConnections() {
+    return Array.from(this.wsConnections.entries()).map(([id, ws]) => ({
+      id,
+      path: ws.path,
+      params: ws.params,
+      readyState: ws.readyState
+    }));
+  }
+  /**
+   * Get version from request
+   * @param {Object} req - Request object
+   * @returns {string} API version
+   * @private
+   */
+  getRequestVersion(req) {
+    if (req.headers[this.versionHeader]) {
+      return req.headers[this.versionHeader];
+    }
+    const pathMatch = req.url.match(/^\/v(\d+)/);
+    if (pathMatch) {
+      return `v${pathMatch[1]}`;
+    }
+    if (req.query && req.query.version) {
+      return req.query.version;
+    }
+    return this.defaultVersion;
+  }
+  /**
+   * Generate URL for named route with parameter substitution
+   * 
+   * @param {string} name - Route name (set during route registration)
+   * @param {Object} [params={}] - Parameters to substitute in the URL pattern
+   * @returns {string} Generated URL with parameters substituted
+   * @throws {Error} If named route is not found
+   * 
+   * @example
+   * // Route registered as: router.addRoute('GET', '/users/:id', handler, { name: 'getUser' })
+   * const url = router.url('getUser', { id: 123 }); // '/users/123'
+   * 
+   * // With constrained parameters
+   * const url = router.url('getUserPosts', { userId: 123, postId: 456 }); // '/users/123/posts/456'
+   */
+  generateUrl(name, params = {}) {
+    const route = this.namedRoutes.get(name);
+    if (!route) {
+      throw new Error(`Named route '${name}' not found`);
+    }
+    let url = route.path;
+    for (const [key, value] of Object.entries(params)) {
+      const paramPattern = new RegExp(`:${key}(\\([^)]+\\))?`, "g");
+      url = url.replace(paramPattern, encodeURIComponent(value));
+    }
+    return url;
+  }
+  /**
+   * Add routes from configuration object
+   * 
+   * @param {Object} routeConfig - Route configuration object with nested structure
+   * @description Processes nested route objects and registers HTTP and WebSocket routes.
+   * Supports declarative route definition with automatic method detection.
+   * 
+   * @example
+   * router.addRoutes({
+   *   'api': {
+   *     'users': {
+   *       GET: (req, res) => ({ users: [] }),
+   *       POST: (req, res) => ({ created: true })
+   *     }
+   *   }
+   * });
+   */
+  addRoutes(routeConfig) {
+    processRoutes(routeConfig, this);
+  }
+  /**
+   * Add global middleware to the router
+   * 
+   * @param {Function|Object} middleware - Middleware function or conditional middleware object
+   * @description Adds middleware that runs before all route handlers. Supports both
+   * simple functions and conditional middleware objects.
+   * 
+   * @example
+   * // Simple middleware
+   * router.use((req, res) => {
+   *   console.log(`${req.method} ${req.url}`);
+   * });
+   * 
+   * // Conditional middleware
+   * router.use({
+   *   condition: (req) => req.url.startsWith('/api'),
+   *   middleware: authMiddleware,
+   *   name: 'apiAuth'
+   * });
+   */
+  use(middleware) {
+    if (typeof middleware === "function") {
+      this.globalMiddleware.push(middleware);
+    } else if (middleware && typeof middleware === "object") {
+      this.globalMiddleware.push(this.createConditionalMiddleware(middleware));
+    }
+  }
+  /**
+   * Create conditional middleware wrapper
+   * @param {Object} config - Conditional middleware configuration
+   * @returns {Function} Wrapped middleware function
+   * @private
+   */
+  createConditionalMiddleware(config) {
+    const { condition, middleware } = config;
+    return async (req, res) => {
+      let shouldExecute = false;
+      if (typeof condition === "function") {
+        shouldExecute = await condition(req, res);
+      } else if (typeof condition === "object") {
+        shouldExecute = this.evaluateConditionObject(condition, req);
+      } else {
+        shouldExecute = !!condition;
+      }
+      if (shouldExecute) {
+        return await middleware(req, res);
+      }
+      return null;
+    };
+  }
+  /**
+   * Evaluate condition object
+   * @param {Object} condition - Condition object
+   * @param {Object} req - Request object
+   * @param {Object} res - Response object
+   * @returns {boolean} Whether condition is met
+   * @private
+   */
+  evaluateConditionObject(condition, req) {
+    const { method, path, header, query, body, user } = condition;
+    if (method && !this.matchCondition(req.method, method)) return false;
+    if (path && !this.matchCondition(req.url, path)) return false;
+    if (header) {
+      for (const [key, value] of Object.entries(header)) {
+        if (!this.matchCondition(req.headers[key.toLowerCase()], value)) return false;
+      }
+    }
+    if (query && req.query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (!this.matchCondition(req.query[key], value)) return false;
+      }
+    }
+    if (body && req.body) {
+      for (const [key, value] of Object.entries(body)) {
+        if (!this.matchCondition(req.body[key], value)) return false;
+      }
+    }
+    if (user && req.user) {
+      for (const [key, value] of Object.entries(user)) {
+        if (!this.matchCondition(req.user[key], value)) return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Match condition value
+   * @param {*} actual - Actual value
+   * @param {*} expected - Expected value or condition
+   * @returns {boolean} Whether condition matches
+   * @private
+   */
+  matchCondition(actual, expected) {
+    if (expected instanceof RegExp) {
+      return expected.test(String(actual || ""));
+    }
+    if (Array.isArray(expected)) {
+      return expected.includes(actual);
+    }
+    if (typeof expected === "function") {
+      return expected(actual);
+    }
+    return actual === expected;
+  }
+  /**
+   * Create a route group with shared middleware and prefix
+   * @param {string} prefix - Path prefix for the group
+   * @param {Function|Array} middleware - Shared middleware
+   * @param {Function} callback - Function to define routes in the group
+   */
+  group(prefix, middleware, callback) {
+    const group = {
+      prefix: prefix.startsWith("/") ? prefix : `/${prefix}`,
+      middleware: Array.isArray(middleware) ? middleware : [middleware]
+    };
+    this.routeGroups.push(group);
+    callback(this);
+    this.routeGroups.pop();
+    return this;
+  }
+  /**
+   * Get current route prefix from active groups
+   * @private
+   */
+  getCurrentPrefix() {
+    return this.routeGroups.map((g) => g.prefix).join("");
+  }
+  /**
+   * Get current group middleware
+   * @private
+   */
+  getCurrentGroupMiddleware() {
+    return this.routeGroups.flatMap((g) => g.middleware);
+  }
+  /**
+   * Compile route pattern into optimized regex
+   * @param {string} pattern - Route pattern to compile
+   * @returns {Object} Compiled route object with regex and parameter names
+   * @private
+   */
+  compileRoute(pattern) {
+    if (this.routeCompilationCache.has(pattern)) {
+      if (this.enableMetrics) this.metrics.compilationHits++;
+      return this.routeCompilationCache.get(pattern);
+    }
+    const paramNames = [];
+    let regexPattern = pattern;
+    if (pattern.includes("**")) {
+      regexPattern = regexPattern.replace(/\/\*\*/g, "/(.*)");
+      paramNames.push("splat");
+    } else if (pattern.includes("*")) {
+      regexPattern = regexPattern.replace(/\/\*/g, "/([^/]+)");
+      paramNames.push("splat");
+    }
+    regexPattern = regexPattern.replace(/:([^(/]+)(\([^)]+\))?(\?)?/g, (match, paramName, constraint, optional) => {
+      paramNames.push(paramName);
+      if (constraint) {
+        const constraintPattern = constraint.slice(1, -1);
+        return optional ? `(?:/(?:${constraintPattern}))?` : `/(${constraintPattern})`;
+      } else {
+        return optional ? "(?:/([^/]+))?" : "/([^/]+)";
+      }
+    });
+    regexPattern = regexPattern.replace(/[.+?^${}|[\]\\]/g, "\\$&").replace(/\\\(/g, "(").replace(/\\\)/g, ")").replace(/\\\?/g, "?");
+    regexPattern = `^${regexPattern}$`;
+    const compiled = {
+      regex: new RegExp(regexPattern),
+      paramNames,
+      pattern
+    };
+    if (this.routeCompilationCache.size < 1e3) {
+      this.routeCompilationCache.set(pattern, compiled);
+    }
+    return compiled;
+  }
+  /**
+   * Match path using compiled route
+   * @param {Object} compiledRoute - Compiled route object
+   * @param {string} path - Path to match
+   * @returns {Object|null} Parameters object or null if no match
+   * @private
+   */
+  matchCompiledRoute(compiledRoute, path) {
+    const match = compiledRoute.regex.exec(path);
+    if (!match) return null;
+    const params = {};
+    for (let i = 0; i < compiledRoute.paramNames.length; i++) {
+      const paramName = compiledRoute.paramNames[i];
+      const value = match[i + 1];
+      if (value !== void 0) {
+        params[paramName] = value;
+      }
+    }
+    return params;
+  }
+  /**
+   * Get performance metrics
+   * @returns {Object} Performance metrics object
+   */
+  getMetrics() {
+    if (!this.enableMetrics) {
+      throw new Error("Metrics collection is disabled. Enable with { enableMetrics: true }");
+    }
+    const avgResponseTime = this.metrics.responseTime.length > 0 ? this.metrics.responseTime.reduce((a, b) => a + b, 0) / this.metrics.responseTime.length : 0;
+    return {
+      ...this.metrics,
+      averageResponseTime: Math.round(avgResponseTime * 100) / 100,
+      cacheHitRate: this.metrics.requests > 0 ? `${(this.metrics.cacheHits / this.metrics.requests * 100).toFixed(2)}%` : "0%",
+      compilationHitRate: this.metrics.requests > 0 ? `${(this.metrics.compilationHits / this.metrics.requests * 100).toFixed(2)}%` : "0%"
+    };
+  }
+  /**
+   * Get compilation statistics
+   * @returns {Object} Compilation statistics
+   */
+  getCompilationStats() {
+    const totalRoutes = this.routes.length;
+    const compiledRoutes = this.routes.filter((r) => r.compiled).length;
+    const compilationCacheSize = this.routeCompilationCache.size;
+    return {
+      totalRoutes,
+      compiledRoutes,
+      compilationEnabled: this.enableCompilation,
+      compilationCacheSize,
+      compilationCacheHits: this.enableMetrics ? this.metrics.compilationHits : "N/A (metrics disabled)"
+    };
+  }
+  /**
+   * Clear route cache (useful for development)
+   */
+  clearCache() {
+    this.routeCache.clear();
+  }
+  /**
+   * Clear compilation cache
+   */
+  clearCompilationCache() {
+    this.routeCompilationCache.clear();
+  }
+  /**
+   * Get all registered routes with detailed information
+   * @returns {Array} Array of route information objects
+   */
+  getRoutes() {
+    return this.routes.map((route) => ({
+      method: route.method,
+      path: route.path,
+      name: route.name || null,
+      hasMiddleware: route.middleware && route.middleware.length > 0,
+      middlewareCount: route.middleware ? route.middleware.length : 0,
+      compiled: !!route.compiled,
+      compiledPattern: route.compiled ? route.compiled.regex.source : null,
+      paramNames: route.compiled ? route.compiled.paramNames : null
+    }));
+  }
+  /**
+   * Find routes matching a pattern or method
+   * @param {Object} criteria - Search criteria
+   * @returns {Array} Matching routes
+   */
+  findRoutes(criteria = {}) {
+    const { method, path, name, hasMiddleware } = criteria;
+    return this.routes.filter((route) => {
+      if (method && route.method !== method.toUpperCase()) return false;
+      if (path && !route.path.includes(path)) return false;
+      if (name && route.name !== name) return false;
+      if (hasMiddleware !== void 0 && !!route.middleware?.length !== hasMiddleware) return false;
+      return true;
+    }).map((route) => ({
+      method: route.method,
+      path: route.path,
+      name: route.name || null,
+      middlewareCount: route.middleware ? route.middleware.length : 0
+    }));
+  }
+  /**
+   * Test route matching without executing handlers
+   * @param {string} method - HTTP method
+   * @param {string} path - Path to test
+   * @returns {Object} Match result with route info and extracted parameters
+   */
+  testRoute(method, path) {
+    const upperMethod = method.toUpperCase();
+    for (const route of this.routes) {
+      if (route.method === upperMethod) {
+        let params = null;
+        if (this.enableCompilation && route.compiled) {
+          params = this.matchCompiledRoute(route.compiled, path);
+        } else {
+          params = extractParams(route.path, path);
+        }
+        if (params !== null) {
+          return {
+            matched: true,
+            route: {
+              method: route.method,
+              path: route.path,
+              name: route.name || null,
+              middlewareCount: route.middleware ? route.middleware.length : 0
+            },
+            params,
+            compiledUsed: this.enableCompilation && !!route.compiled
+          };
+        }
+      }
+    }
+    return { matched: false, route: null, params: null };
+  }
+  /**
+   * Get router debug information
+   * @returns {Object} Comprehensive debug information
+   */
+  getDebugInfo() {
+    const routesByMethod = {};
+    const namedRoutes = {};
+    this.routes.forEach((route) => {
+      if (!routesByMethod[route.method]) {
+        routesByMethod[route.method] = [];
+      }
+      routesByMethod[route.method].push({
+        path: route.path,
+        name: route.name,
+        middlewareCount: route.middleware ? route.middleware.length : 0,
+        compiled: !!route.compiled
+      });
+    });
+    this.namedRoutes.forEach((routeInfo, name) => {
+      namedRoutes[name] = routeInfo;
+    });
+    return {
+      totalRoutes: this.routes.length,
+      routesByMethod,
+      namedRoutes,
+      globalMiddleware: this.globalMiddleware.length,
+      activeGroups: this.routeGroups.length,
+      cacheSize: this.routeCache.size,
+      maxCacheSize: this.maxCacheSize,
+      compilationEnabled: this.enableCompilation,
+      compilationCacheSize: this.routeCompilationCache.size,
+      metricsEnabled: this.enableMetrics
+    };
+  }
+  async handle(req, res, options = {}) {
+    const startTime = Date.now();
+    if (this.enableMetrics) {
+      this.metrics.requests++;
+    }
+    const { corsOrigin, rateLimit = { windowMs: 6e4, maxRequests: 100 } } = options;
+    addSecurityHeaders(res, corsOrigin);
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    const clientIP = req.headers["x-forwarded-for"] || req.connection.remoteAddress || "unknown";
+    if (!checkRateLimit(clientIP, rateLimit.windowMs, rateLimit.maxRequests)) {
+      res.writeHead(429, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ _error: "Too Many Requests" }));
+      return;
+    }
+    const parsedUrl = (0, import_node_url.parse)(req.url, true);
+    const pathname = parsedUrl.pathname;
+    req.query = parsedUrl.query || {};
+    try {
+      req.body = await parseBody(req, options.maxBodySize);
+    } catch (_error) {
+      if (this.enableMetrics) this.metrics.errors++;
+      const statusCode = _error.message.includes("too large") ? 413 : 400;
+      res.writeHead(statusCode, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ _error: _error.message }));
+      return;
+    }
+    const cacheKey = `${req.method}:${pathname}`;
+    let matchedRoute = this.routeCache.get(cacheKey);
+    if (matchedRoute && this.enableMetrics) {
+      this.metrics.cacheHits++;
+    }
+    if (!matchedRoute) {
+      const requestVersion = this.enableVersioning ? this.getRequestVersion(req) : null;
+      if (this.enableMetrics && requestVersion) {
+        this.metrics.versionRequests.set(requestVersion, (this.metrics.versionRequests.get(requestVersion) || 0) + 1);
+      }
+      const routesToSearch = this.enableVersioning && this.versionedRoutes.has(requestVersion) ? this.versionedRoutes.get(requestVersion) : this.routes;
+      for (const route of routesToSearch) {
+        if (route.method === req.method) {
+          if (this.enableVersioning && route.version !== requestVersion) {
+            continue;
+          }
+          let params = null;
+          if (this.enableCompilation && route.compiled) {
+            params = this.matchCompiledRoute(route.compiled, pathname);
+          } else {
+            params = extractParams(route.path, pathname);
+          }
+          if (params !== null) {
+            matchedRoute = { route, params };
+            if (this.routeCache.size < this.maxCacheSize) {
+              this.routeCache.set(cacheKey, matchedRoute);
+            }
+            break;
+          }
+        }
+      }
+    }
+    if (matchedRoute) {
+      req.params = matchedRoute.params;
+      if (this.enableMetrics) {
+        const routeKey = `${req.method}:${matchedRoute.route.path}`;
+        this.metrics.routeMatches.set(routeKey, (this.metrics.routeMatches.get(routeKey) || 0) + 1);
+      }
+      console.log(`${(/* @__PURE__ */ new Date()).toISOString()} ${req.method} ${pathname}`);
+      try {
+        if (matchedRoute.route.middleware && matchedRoute.route.middleware.length > 0) {
+          for (const middleware of matchedRoute.route.middleware) {
+            const result2 = await middleware(req, res);
+            if (result2) break;
+          }
+        }
+        const { route } = matchedRoute;
+        const result = await route.handler(req, res);
+        if (result && typeof result === "object" && !res.headersSent) {
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify(result));
+        }
+        if (this.enableMetrics) {
+          const responseTime = Date.now() - startTime;
+          this.metrics.responseTime.push(responseTime);
+          if (this.metrics.responseTime.length > 1e3) {
+            this.metrics.responseTime = this.metrics.responseTime.slice(-1e3);
+          }
+        }
+        return;
+      } catch (_error) {
+        if (this.enableMetrics) this.metrics.errors++;
+        if (!res.headersSent) {
+          res.writeHead(500, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ _error: _error.message }));
+        }
+        return;
+      }
+    }
+    if (this.enableMetrics) this.metrics.errors++;
+    if (!res.headersSent) {
+      res.writeHead(404, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ _error: "Not Found" }));
+    }
+  }
+  createServer(options = {}) {
+    const mergedOptions = { ...this.defaultOptions, ...options };
+    return (0, import_node_http.createServer)((req, res) => this.handle(req, res, mergedOptions));
+  }
+  // HTTP convenience methods
+  get(path, handler, options = {}) {
+    return this.addRoute("GET", path, handler, options);
+  }
+  post(path, handler, options = {}) {
+    return this.addRoute("POST", path, handler, options);
+  }
+  put(path, handler, options = {}) {
+    return this.addRoute("PUT", path, handler, options);
+  }
+  patch(path, handler, options = {}) {
+    return this.addRoute("PATCH", path, handler, options);
+  }
+  delete(path, handler, options = {}) {
+    return this.addRoute("DELETE", path, handler, options);
+  }
+  options(path, handler, options = {}) {
+    return this.addRoute("OPTIONS", path, handler, options);
+  }
+  head(path, handler, options = {}) {
+    return this.addRoute("HEAD", path, handler, options);
+  }
+};
+function createRouter(routeConfig, options = {}) {
+  const router = new SimpleRouter(options);
+  router.defaultOptions = options;
+  if (routeConfig) {
+    router.addRoutes(routeConfig);
+  }
+  return router;
+}
+
+// src/serialization.js
+function serializeDate(date) {
+  if (!(date instanceof Date)) {
+    throw new Error("Expected Date object");
+  }
+  return date.toISOString();
+}
+function deserializeDate(dateString) {
+  const date = new Date(dateString);
+  if (isNaN(date.getTime())) {
+    throw new Error("Invalid date string");
+  }
+  return date;
+}
+function serializeMap(map) {
+  if (!(map instanceof Map)) {
+    throw new Error("Expected Map object");
+  }
+  const obj = {};
+  for (const [key, value] of map) {
+    obj[key] = value;
+  }
+  return obj;
+}
+function deserializeMap(obj) {
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
+    throw new Error("Expected plain object");
+  }
+  return new Map(Object.entries(obj));
+}
+function serializeSet(set) {
+  if (!(set instanceof Set)) {
+    throw new Error("Expected Set object");
+  }
+  return Array.from(set);
+}
+function deserializeSet(arr) {
+  if (!Array.isArray(arr)) {
+    throw new Error("Expected array");
+  }
+  return new Set(arr);
+}
+function withSerialization(options = {}) {
+  const {
+    enableDate = true,
+    enableMap = true,
+    enableSet = true,
+    custom = {}
+  } = options;
+  return (req, res, next) => {
+    res.serialize = {};
+    req.deserialize = {};
+    if (enableDate) {
+      res.serialize.date = custom.serializeDate || serializeDate;
+      req.deserialize.date = custom.deserializeDate || deserializeDate;
+    }
+    if (enableMap) {
+      res.serialize.map = custom.serializeMap || serializeMap;
+      req.deserialize.map = custom.deserializeMap || deserializeMap;
+    }
+    if (enableSet) {
+      res.serialize.set = custom.serializeSet || serializeSet;
+      req.deserialize.set = custom.deserializeSet || deserializeSet;
+    }
+    next();
+  };
+}
+function serializeForJSON(data) {
+  if (data instanceof Date) {
+    return serializeDate(data);
+  }
+  if (data instanceof Map) {
+    return serializeMap(data);
+  }
+  if (data instanceof Set) {
+    return serializeSet(data);
+  }
+  if (Array.isArray(data)) {
+    return data.map((item) => serializeForJSON(item));
+  }
+  if (typeof data === "object" && data !== null) {
+    const serialized = {};
+    for (const [key, value] of Object.entries(data)) {
+      serialized[key] = serializeForJSON(value);
+    }
+    return serialized;
+  }
+  return data;
+}
+
+// src/security.js
+var import_crypto = require("crypto");
+var import_buffer = require("buffer");
+function base64UrlDecode(str) {
+  str += "=".repeat((4 - str.length % 4) % 4);
+  return import_buffer.Buffer.from(str.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString();
+}
+function createSignature(data, secret) {
+  return (0, import_crypto.createHmac)("sha256", secret).update(data).digest("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function verifyToken(token, secret = "your-secret-key") {
+  try {
+    let jwtToken = token;
+    if (token && token.startsWith("Bearer ")) {
+      jwtToken = token.slice(7);
+    }
+    if (!jwtToken) {
+      return null;
+    }
+    const parts = jwtToken.split(".");
+    if (parts.length !== 3) {
+      return null;
+    }
+    const [encodedHeader, encodedPayload, signature] = parts;
+    const data = `${encodedHeader}.${encodedPayload}`;
+    const expectedSignature = createSignature(data, secret);
+    if (signature !== expectedSignature) {
+      return null;
+    }
+    const payload = JSON.parse(base64UrlDecode(encodedPayload));
+    const now = Math.floor(Date.now() / 1e3);
+    if (payload.exp && payload.exp < now) {
+      return null;
+    }
+    return payload;
+  } catch {
+    return null;
+  }
+}
+function withAuth(options = {}) {
+  const { secret, required = true } = options;
+  return (req, res) => {
+    const authHeader = req.headers.authorization;
+    const user = verifyToken(authHeader, secret);
+    if (required && !user) {
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ _error: "Unauthorized" }));
+      return;
+    }
+    req.user = user;
+    return null;
+  };
+}
+function withRole(roles) {
+  const requiredRoles = Array.isArray(roles) ? roles : [roles];
+  return (req, res) => {
+    if (!req.user) {
+      res.writeHead(401, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ _error: "Unauthorized" }));
+      return;
+    }
+    if (!requiredRoles.includes(req.user.role)) {
+      res.writeHead(403, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ _error: "Forbidden" }));
+      return;
+    }
+    return null;
+  };
+}
+function hashPassword(password) {
+  const salt = (0, import_crypto.randomBytes)(16).toString("hex");
+  const hash = (0, import_crypto.pbkdf2Sync)(password, salt, 1e4, 64, "sha512").toString("hex");
+  return `${salt}:${hash}`;
+}
+function verifyPassword(password, hashedPassword) {
+  try {
+    const [salt, hash] = hashedPassword.split(":");
+    const verifyHash = (0, import_crypto.pbkdf2Sync)(password, salt, 1e4, 64, "sha512").toString("hex");
+    return hash === verifyHash;
+  } catch {
+    return false;
+  }
+}
+function generateToken(length = 32) {
+  return (0, import_crypto.randomBytes)(length).toString("hex");
+}
+function withInputValidation(rules) {
+  return (req, res) => {
+    const errors = [];
+    for (const [field, rule] of Object.entries(rules)) {
+      const value = req.body[field];
+      if (rule.required && (value === void 0 || value === null || value === "")) {
+        errors.push(`${field} is required`);
+        continue;
+      }
+      if (value !== void 0 && rule.type && typeof value !== rule.type) {
+        errors.push(`${field} must be of type ${rule.type}`);
+      }
+      if (value && rule.minLength && value.length < rule.minLength) {
+        errors.push(`${field} must be at least ${rule.minLength} characters`);
+      }
+      if (value && rule.maxLength && value.length > rule.maxLength) {
+        errors.push(`${field} must be at most ${rule.maxLength} characters`);
+      }
+      if (value && rule.pattern && !rule.pattern.test(value)) {
+        errors.push(`${field} format is invalid`);
+      }
+    }
+    if (errors.length > 0) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ _error: "Validation failed", details: errors }));
+      return;
+    }
+    return null;
+  };
+}
+
+// src/index.js
+var index_default = {
+  createRouter,
+  ApiError,
+  ValidationError,
+  AuthenticationError,
+  AuthorizationError,
+  NotFoundError,
+  ConflictError,
+  withErrorHandling,
+  createErrorHandler,
+  validateAgainstSchema,
+  validateField,
+  withValidation,
+  withQueryValidation,
+  withParamsValidation,
+  serializeDate,
+  deserializeDate,
+  serializeMap,
+  deserializeMap,
+  serializeSet,
+  deserializeSet,
+  withSerialization,
+  serializeForJSON,
+  withAuth,
+  withRole,
+  hashPassword,
+  verifyPassword,
+  generateToken,
+  withInputValidation
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiError,
+  AuthenticationError,
+  AuthorizationError,
+  ConflictError,
+  NotFoundError,
+  ValidationError,
+  createErrorHandler,
+  createRouter,
+  deserializeDate,
+  deserializeMap,
+  deserializeSet,
+  generateToken,
+  hashPassword,
+  serializeDate,
+  serializeForJSON,
+  serializeMap,
+  serializeSet,
+  validateAgainstSchema,
+  validateField,
+  verifyPassword,
+  withAuth,
+  withErrorHandling,
+  withInputValidation,
+  withParamsValidation,
+  withQueryValidation,
+  withRole,
+  withSerialization,
+  withValidation
+});
+//# sourceMappingURL=index.cjs.map