@gravito/core 1.0.0-beta.6 → 1.1.0

package/dist/engine/index.cjs

@@ -0,0 +1,1173 @@
+"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/engine/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AOTRouter: () => AOTRouter,
+  FastContextImpl: () => FastContext,
+  Gravito: () => Gravito,
+  MinimalContext: () => MinimalContext,
+  ObjectPool: () => ObjectPool,
+  extractPath: () => extractPath
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/adapters/bun/RadixNode.ts
+var RadixNode = class _RadixNode {
+  // Path segment for this node (e.g., "users", ":id")
+  segment;
+  // Node type (Static, Param, Wildcard)
+  type;
+  // Children nodes (mapped by segment for fast lookup)
+  children = /* @__PURE__ */ new Map();
+  // Specialized child for parameter node (only one per level allowed usually to avoid ambiguity, though some routers support multiple)
+  paramChild = null;
+  // Specialized child for wildcard node
+  wildcardChild = null;
+  // Handlers registered at this node (keyed by HTTP method)
+  handlers = /* @__PURE__ */ new Map();
+  // Parameter name if this is a PARAM node (e.g., "id" for ":id")
+  paramName = null;
+  // Parameter constraints (regex) - only applicable if this is a PARAM node
+  // If we support per-route constraints, they might need to be stored differently,
+  // but for now assume constraints are defined at node level (uncommon) or checked at match time.
+  // Laravel allows global pattern constraints or per-route.
+  // Ideally, constraints should be stored with the handler or part of matching logic.
+  // For a Radix tree, if we have constraints, we might need to backtrack if constraint fails?
+  // Or simply store constraint with the param node.
+  regex = null;
+  constructor(segment = "", type = 0 /* STATIC */) {
+    this.segment = segment;
+    this.type = type;
+  }
+  toJSON() {
+    return {
+      segment: this.segment,
+      type: this.type,
+      children: Array.from(this.children.entries()).map(([k, v]) => [k, v.toJSON()]),
+      paramChild: this.paramChild?.toJSON() || null,
+      wildcardChild: this.wildcardChild?.toJSON() || null,
+      paramName: this.paramName,
+      regex: this.regex ? this.regex.source : null
+    };
+  }
+  static fromJSON(json) {
+    const node = new _RadixNode(json.segment, json.type);
+    node.paramName = json.paramName;
+    if (json.regex) {
+      node.regex = new RegExp(json.regex);
+    }
+    if (json.children) {
+      for (const [key, childJson] of json.children) {
+        node.children.set(key, _RadixNode.fromJSON(childJson));
+      }
+    }
+    if (json.paramChild) {
+      node.paramChild = _RadixNode.fromJSON(json.paramChild);
+    }
+    if (json.wildcardChild) {
+      node.wildcardChild = _RadixNode.fromJSON(json.wildcardChild);
+    }
+    return node;
+  }
+};
+
+// src/adapters/bun/RadixRouter.ts
+var RadixRouter = class _RadixRouter {
+  root = new RadixNode();
+  // Global parameter constraints (e.g., id => /^\d+$/)
+  globalConstraints = /* @__PURE__ */ new Map();
+  /**
+   * Add a generic parameter constraint
+   */
+  where(param, regex) {
+    this.globalConstraints.set(param, regex);
+  }
+  /**
+   * Register a route
+   */
+  add(method, path, handlers) {
+    let node = this.root;
+    const segments = this.splitPath(path);
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      if (segment === "*") {
+        if (!node.wildcardChild) {
+          node.wildcardChild = new RadixNode("*", 2 /* WILDCARD */);
+        }
+        node = node.wildcardChild;
+        break;
+      } else if (segment.startsWith(":")) {
+        const paramName = segment.slice(1);
+        if (!node.paramChild) {
+          const child = new RadixNode(segment, 1 /* PARAM */);
+          child.paramName = paramName;
+          const constraint = this.globalConstraints.get(paramName);
+          if (constraint) {
+            child.regex = constraint;
+          }
+          node.paramChild = child;
+        }
+        node = node.paramChild;
+      } else {
+        if (!node.children.has(segment)) {
+          node.children.set(segment, new RadixNode(segment, 0 /* STATIC */));
+        }
+        node = node.children.get(segment);
+      }
+    }
+    node.handlers.set(method.toLowerCase(), handlers);
+  }
+  /**
+   * Match a request
+   */
+  match(method, path) {
+    const normalizedMethod = method.toLowerCase();
+    if (path === "/" || path === "") {
+      const handlers = this.root.handlers.get(normalizedMethod);
+      if (handlers) {
+        return { handlers, params: {} };
+      }
+      return null;
+    }
+    const searchPath = path.startsWith("/") ? path.slice(1) : path;
+    const segments = searchPath.split("/");
+    return this.matchRecursive(this.root, segments, 0, {}, normalizedMethod);
+  }
+  matchRecursive(node, segments, depth, params, method) {
+    if (depth >= segments.length) {
+      let handlers = node.handlers.get(method);
+      if (!handlers) {
+        handlers = node.handlers.get("all");
+      }
+      if (handlers) {
+        return { handlers, params };
+      }
+      return null;
+    }
+    const segment = segments[depth];
+    const staticChild = node.children.get(segment);
+    if (staticChild) {
+      const match = this.matchRecursive(staticChild, segments, depth + 1, params, method);
+      if (match) {
+        return match;
+      }
+    }
+    const paramChild = node.paramChild;
+    if (paramChild) {
+      if (paramChild.regex && !paramChild.regex.test(segment)) {
+      } else {
+        if (paramChild.paramName) {
+          params[paramChild.paramName] = decodeURIComponent(segment);
+          const match = this.matchRecursive(paramChild, segments, depth + 1, params, method);
+          if (match) {
+            return match;
+          }
+          delete params[paramChild.paramName];
+        }
+      }
+    }
+    if (node.wildcardChild) {
+      let handlers = node.wildcardChild.handlers.get(method);
+      if (!handlers) {
+        handlers = node.wildcardChild.handlers.get("all");
+      }
+      if (handlers) {
+        return { handlers, params };
+      }
+    }
+    return null;
+  }
+  splitPath(path) {
+    if (path === "/" || path === "") {
+      return [];
+    }
+    let p = path;
+    if (p.startsWith("/")) {
+      p = p.slice(1);
+    }
+    if (p.endsWith("/")) {
+      p = p.slice(0, -1);
+    }
+    return p.split("/");
+  }
+  /**
+   * Serialize the router to a JSON string
+   */
+  serialize() {
+    return JSON.stringify({
+      root: this.root.toJSON(),
+      globalConstraints: Array.from(this.globalConstraints.entries()).map(([k, v]) => [
+        k,
+        v.source
+      ])
+    });
+  }
+  /**
+   * Restore a router from a serialized JSON string
+   */
+  static fromSerialized(json) {
+    const data = JSON.parse(json);
+    const router = new _RadixRouter();
+    router.root = RadixNode.fromJSON(data.root);
+    if (data.globalConstraints) {
+      for (const [key, source] of data.globalConstraints) {
+        router.globalConstraints.set(key, new RegExp(source));
+      }
+    }
+    return router;
+  }
+};
+
+// src/engine/AOTRouter.ts
+var AOTRouter = class {
+  // Static route cache: "METHOD:PATH" -> RouteMetadata
+  staticRoutes = /* @__PURE__ */ new Map();
+  // Dynamic route handler (Radix Tree)
+  dynamicRouter = new RadixRouter();
+  // Global middleware (applies to all routes)
+  globalMiddleware = [];
+  // Path-based middleware: pattern -> middleware[]
+  pathMiddleware = /* @__PURE__ */ new Map();
+  /**
+   * Register a route
+   *
+   * Automatically determines if route is static or dynamic.
+   * Static routes are stored in a Map for O(1) lookup.
+   * Dynamic routes use the Radix Tree.
+   *
+   * @param method - HTTP method
+   * @param path - Route path
+   * @param handler - Route handler
+   * @param middleware - Route-specific middleware
+   */
+  add(method, path, handler, middleware = []) {
+    const normalizedMethod = method.toLowerCase();
+    if (this.isStaticPath(path)) {
+      const key = `${normalizedMethod}:${path}`;
+      this.staticRoutes.set(key, { handler, middleware });
+    } else {
+      const wrappedHandler = handler;
+      this.dynamicRouter.add(normalizedMethod, path, [wrappedHandler]);
+      if (middleware.length > 0) {
+        this.pathMiddleware.set(`${normalizedMethod}:${path}`, middleware);
+      }
+    }
+  }
+  /**
+   * Add global middleware
+   *
+   * These run for every request, before route-specific middleware.
+   *
+   * @param middleware - Middleware functions
+   */
+  use(...middleware) {
+    this.globalMiddleware.push(...middleware);
+  }
+  /**
+   * Add path-based middleware
+   *
+   * Supports wildcard patterns like '/api/*'
+   *
+   * @param pattern - Path pattern
+   * @param middleware - Middleware functions
+   */
+  usePattern(pattern, ...middleware) {
+    const existing = this.pathMiddleware.get(pattern) ?? [];
+    this.pathMiddleware.set(pattern, [...existing, ...middleware]);
+  }
+  /**
+   * Match a request to a route
+   *
+   * Returns the handler, params, and all applicable middleware.
+   *
+   * @param method - HTTP method
+   * @param path - Request path
+   * @returns Route match or null if not found
+   */
+  match(method, path) {
+    const normalizedMethod = method.toLowerCase();
+    const staticKey = `${normalizedMethod}:${path}`;
+    const staticRoute = this.staticRoutes.get(staticKey);
+    if (staticRoute) {
+      return {
+        handler: staticRoute.handler,
+        params: {},
+        middleware: this.collectMiddleware(path, staticRoute.middleware)
+      };
+    }
+    const match = this.dynamicRouter.match(normalizedMethod, path);
+    if (match && match.handlers.length > 0) {
+      const handler = match.handlers[0];
+      const routeKey = this.findDynamicRouteKey(normalizedMethod, path);
+      const routeMiddleware = routeKey ? this.pathMiddleware.get(routeKey) ?? [] : [];
+      return {
+        handler,
+        params: match.params,
+        middleware: this.collectMiddleware(path, routeMiddleware)
+      };
+    }
+    return {
+      handler: null,
+      params: {},
+      middleware: []
+    };
+  }
+  /**
+   * Public wrapper for collectMiddleware (used by Gravito for optimization)
+   */
+  collectMiddlewarePublic(path, routeMiddleware) {
+    return this.collectMiddleware(path, routeMiddleware);
+  }
+  /**
+   * Collect all applicable middleware for a path
+   *
+   * Order: global -> pattern-based -> route-specific
+   *
+   * @param path - Request path
+   * @param routeMiddleware - Route-specific middleware
+   * @returns Combined middleware array
+   */
+  collectMiddleware(path, routeMiddleware) {
+    if (this.globalMiddleware.length === 0 && this.pathMiddleware.size === 0 && routeMiddleware.length === 0) {
+      return [];
+    }
+    const middleware = [];
+    if (this.globalMiddleware.length > 0) {
+      middleware.push(...this.globalMiddleware);
+    }
+    if (this.pathMiddleware.size > 0) {
+      for (const [pattern, mw] of this.pathMiddleware) {
+        if (pattern.includes(":")) continue;
+        if (this.matchPattern(pattern, path)) {
+          middleware.push(...mw);
+        }
+      }
+    }
+    if (routeMiddleware.length > 0) {
+      middleware.push(...routeMiddleware);
+    }
+    return middleware;
+  }
+  /**
+   * Check if a path is static (no parameters or wildcards)
+   */
+  isStaticPath(path) {
+    return !path.includes(":") && !path.includes("*");
+  }
+  /**
+   * Match a pattern against a path
+   *
+   * Supports:
+   * - Exact match: '/api/users'
+   * - Wildcard suffix: '/api/*'
+   *
+   * @param pattern - Pattern to match
+   * @param path - Path to test
+   * @returns True if pattern matches
+   */
+  matchPattern(pattern, path) {
+    if (pattern === "*") return true;
+    if (pattern === path) return true;
+    if (pattern.endsWith("/*")) {
+      const prefix = pattern.slice(0, -2);
+      return path.startsWith(prefix);
+    }
+    return false;
+  }
+  /**
+   * Find the original route key for a matched dynamic route
+   *
+   * This is needed to look up route-specific middleware.
+   * It's a bit of a hack, but avoids storing duplicate data.
+   *
+   * @param method - HTTP method
+   * @param path - Matched path
+   * @returns Route key or null
+   */
+  findDynamicRouteKey(method, path) {
+    for (const key of this.pathMiddleware.keys()) {
+      if (key.startsWith(`${method}:`)) {
+        return key;
+      }
+    }
+    return null;
+  }
+  /**
+   * Get all registered routes (for debugging)
+   */
+  getRoutes() {
+    const routes = [];
+    for (const key of this.staticRoutes.keys()) {
+      const [method, path] = key.split(":");
+      routes.push({ method, path, type: "static" });
+    }
+    return routes;
+  }
+};
+
+// src/engine/analyzer.ts
+function analyzeHandler(handler) {
+  const source = handler.toString();
+  return {
+    usesHeaders: source.includes(".header(") || source.includes(".header)") || source.includes(".headers(") || source.includes(".headers)"),
+    usesQuery: source.includes(".query(") || source.includes(".query)") || source.includes(".queries(") || source.includes(".queries)"),
+    usesBody: source.includes(".json()") || source.includes(".text()") || source.includes(".formData()") || source.includes(".body"),
+    usesParams: source.includes(".param(") || source.includes(".param)") || source.includes(".params(") || source.includes(".params)"),
+    isAsync: source.includes("async") || source.includes("await")
+  };
+}
+function getOptimalContextType(analysis) {
+  if (analysis.usesHeaders) {
+    return "fast";
+  }
+  if (!analysis.usesQuery && !analysis.usesBody && !analysis.usesParams) {
+    return "minimal";
+  }
+  if (!analysis.usesQuery && !analysis.usesBody && analysis.usesParams) {
+    return "minimal";
+  }
+  if (analysis.usesBody) {
+    return "full";
+  }
+  return "fast";
+}
+
+// src/engine/FastContext.ts
+var FastRequestImpl = class {
+  _request;
+  _params;
+  _url = new URL("http://localhost");
+  // Reuse this object
+  _query = null;
+  _headers = null;
+  /**
+   * Reset for pooling
+   */
+  reset(request, params = {}) {
+    this._request = request;
+    this._params = params;
+    this._url.href = request.url;
+    this._query = null;
+    this._headers = null;
+  }
+  get url() {
+    return this._request.url;
+  }
+  get method() {
+    return this._request.method;
+  }
+  get path() {
+    return this._url.pathname;
+  }
+  param(name) {
+    return this._params[name];
+  }
+  params() {
+    return { ...this._params };
+  }
+  query(name) {
+    if (!this._query) {
+      this._query = this._url.searchParams;
+    }
+    return this._query.get(name) ?? void 0;
+  }
+  queries() {
+    if (!this._query) {
+      this._query = this._url.searchParams;
+    }
+    const result = {};
+    for (const [key, value] of this._query.entries()) {
+      const existing = result[key];
+      if (existing === void 0) {
+        result[key] = value;
+      } else if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        result[key] = [existing, value];
+      }
+    }
+    return result;
+  }
+  header(name) {
+    return this._request.headers.get(name) ?? void 0;
+  }
+  headers() {
+    if (!this._headers) {
+      this._headers = {};
+      for (const [key, value] of this._request.headers.entries()) {
+        this._headers[key] = value;
+      }
+    }
+    return { ...this._headers };
+  }
+  async json() {
+    return this._request.json();
+  }
+  async text() {
+    return this._request.text();
+  }
+  async formData() {
+    return this._request.formData();
+  }
+  get raw() {
+    return this._request;
+  }
+};
+var FastContext = class {
+  _req = new FastRequestImpl();
+  _statusCode = 200;
+  _headers = new Headers();
+  // Reuse this object
+  /**
+   * Reset context for pooling
+   *
+   * This is called when acquiring from the pool.
+   * Must clear all state from previous request.
+   */
+  reset(request, params = {}) {
+    this._req.reset(request, params);
+    this._statusCode = 200;
+    this._headers = new Headers();
+    return this;
+  }
+  get req() {
+    return this._req;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Response Helpers
+  // ─────────────────────────────────────────────────────────────────────────
+  json(data, status = 200) {
+    this._headers.set("Content-Type", "application/json; charset=utf-8");
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: this._headers
+    });
+  }
+  text(text, status = 200) {
+    this._headers.set("Content-Type", "text/plain; charset=utf-8");
+    return new Response(text, {
+      status,
+      headers: this._headers
+    });
+  }
+  html(html, status = 200) {
+    this._headers.set("Content-Type", "text/html; charset=utf-8");
+    return new Response(html, {
+      status,
+      headers: this._headers
+    });
+  }
+  redirect(url, status = 302) {
+    this._headers.set("Location", url);
+    return new Response(null, {
+      status,
+      headers: this._headers
+    });
+  }
+  body(data, status = 200) {
+    return new Response(data, {
+      status,
+      headers: this._headers
+    });
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Header Management
+  // ─────────────────────────────────────────────────────────────────────────
+  header(name, value) {
+    this._headers.set(name, value);
+  }
+  status(code) {
+    this._statusCode = code;
+  }
+};
+
+// src/engine/MinimalContext.ts
+var MinimalRequest = class {
+  constructor(_request, _params, _path) {
+    this._request = _request;
+    this._params = _params;
+    this._path = _path;
+  }
+  get url() {
+    return this._request.url;
+  }
+  get method() {
+    return this._request.method;
+  }
+  get path() {
+    return this._path;
+  }
+  param(name) {
+    return this._params[name];
+  }
+  params() {
+    return { ...this._params };
+  }
+  query(name) {
+    const url = new URL(this._request.url);
+    return url.searchParams.get(name) ?? void 0;
+  }
+  queries() {
+    const url = new URL(this._request.url);
+    const result = {};
+    for (const [key, value] of url.searchParams.entries()) {
+      const existing = result[key];
+      if (existing === void 0) {
+        result[key] = value;
+      } else if (Array.isArray(existing)) {
+        existing.push(value);
+      } else {
+        result[key] = [existing, value];
+      }
+    }
+    return result;
+  }
+  header(name) {
+    return this._request.headers.get(name) ?? void 0;
+  }
+  headers() {
+    const result = {};
+    for (const [key, value] of this._request.headers.entries()) {
+      result[key] = value;
+    }
+    return result;
+  }
+  async json() {
+    return this._request.json();
+  }
+  async text() {
+    return this._request.text();
+  }
+  async formData() {
+    return this._request.formData();
+  }
+  get raw() {
+    return this._request;
+  }
+};
+var MinimalContext = class {
+  _req;
+  constructor(request, params, path) {
+    this._req = new MinimalRequest(request, params, path);
+  }
+  get req() {
+    return this._req;
+  }
+  // Response helpers - create headers inline (no reuse overhead)
+  json(data, status = 200) {
+    return new Response(JSON.stringify(data), {
+      status,
+      headers: { "Content-Type": "application/json; charset=utf-8" }
+    });
+  }
+  text(text, status = 200) {
+    return new Response(text, {
+      status,
+      headers: { "Content-Type": "text/plain; charset=utf-8" }
+    });
+  }
+  html(html, status = 200) {
+    return new Response(html, {
+      status,
+      headers: { "Content-Type": "text/html; charset=utf-8" }
+    });
+  }
+  redirect(url, status = 302) {
+    return new Response(null, {
+      status,
+      headers: { Location: url }
+    });
+  }
+  body(data, status = 200) {
+    return new Response(data, { status });
+  }
+  header(_name, _value) {
+    console.warn("MinimalContext.header() is a no-op. Use FastContext for custom headers.");
+  }
+  status(_code) {
+  }
+  // Required for interface compatibility
+  reset(_request, _params) {
+    throw new Error("MinimalContext does not support reset. Create a new instance instead.");
+  }
+};
+
+// src/engine/path.ts
+function extractPath(url) {
+  const protocolEnd = url.indexOf("://");
+  const searchStart = protocolEnd === -1 ? 0 : protocolEnd + 3;
+  const pathStart = url.indexOf("/", searchStart);
+  if (pathStart === -1) {
+    return "/";
+  }
+  const queryStart = url.indexOf("?", pathStart);
+  if (queryStart === -1) {
+    return url.slice(pathStart);
+  }
+  return url.slice(pathStart, queryStart);
+}
+
+// src/engine/pool.ts
+var ObjectPool = class {
+  pool = [];
+  factory;
+  reset;
+  maxSize;
+  /**
+   * Create a new object pool
+   *
+   * @param factory - Function to create new objects
+   * @param reset - Function to reset objects before reuse
+   * @param maxSize - Maximum pool size (default: 256)
+   */
+  constructor(factory, reset, maxSize = 256) {
+    this.factory = factory;
+    this.reset = reset;
+    this.maxSize = maxSize;
+  }
+  /**
+   * Acquire an object from the pool
+   *
+   * If the pool is empty, creates a new object (overflow strategy).
+   * This ensures the pool never blocks under high load.
+   *
+   * @returns Object from pool or newly created
+   */
+  acquire() {
+    const obj = this.pool.pop();
+    if (obj !== void 0) {
+      return obj;
+    }
+    return this.factory();
+  }
+  /**
+   * Release an object back to the pool
+   *
+   * If the pool is full, the object is discarded (will be GC'd).
+   * This prevents unbounded memory growth.
+   *
+   * @param obj - Object to release
+   */
+  release(obj) {
+    if (this.pool.length < this.maxSize) {
+      this.reset(obj);
+      this.pool.push(obj);
+    }
+  }
+  /**
+   * Clear all objects from the pool
+   *
+   * Useful for testing or when you need to force a clean slate.
+   */
+  clear() {
+    this.pool = [];
+  }
+  /**
+   * Get current pool size
+   */
+  get size() {
+    return this.pool.length;
+  }
+  /**
+   * Get maximum pool size
+   */
+  get capacity() {
+    return this.maxSize;
+  }
+  /**
+   * Pre-warm the pool by creating objects in advance
+   *
+   * This can reduce latency for the first N requests.
+   *
+   * @param count - Number of objects to pre-create
+   */
+  prewarm(count) {
+    const targetSize = Math.min(count, this.maxSize);
+    while (this.pool.length < targetSize) {
+      const obj = this.factory();
+      this.reset(obj);
+      this.pool.push(obj);
+    }
+  }
+};
+
+// src/engine/Gravito.ts
+var Gravito = class {
+  router = new AOTRouter();
+  contextPool;
+  errorHandler;
+  notFoundHandler;
+  // Direct reference to static routes Map (O(1) access)
+  // Optimization: Bypass getter/setter overhead
+  staticRoutes;
+  // Flag: pure static app (no middleware at all) allows ultra-fast path
+  isPureStaticApp = true;
+  /**
+   * Create a new Gravito instance
+   *
+   * @param options - Engine configuration options
+   */
+  constructor(options = {}) {
+    const poolSize = options.poolSize ?? 256;
+    this.contextPool = new ObjectPool(
+      () => new FastContext(),
+      (ctx) => ctx.reset(new Request("http://localhost")),
+      poolSize
+    );
+    this.contextPool.prewarm(Math.min(32, poolSize));
+    if (options.onError) {
+      this.errorHandler = options.onError;
+    }
+    if (options.onNotFound) {
+      this.notFoundHandler = options.onNotFound;
+    }
+    this.compileRoutes();
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // HTTP Method Registration
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Register a GET route
+   *
+   * @param path - Route path (e.g., '/users/:id')
+   * @param handlers - Handler and optional middleware
+   * @returns This instance for chaining
+   */
+  get(path, ...handlers) {
+    return this.addRoute("get", path, handlers);
+  }
+  /**
+   * Register a POST route
+   */
+  post(path, ...handlers) {
+    return this.addRoute("post", path, handlers);
+  }
+  /**
+   * Register a PUT route
+   */
+  put(path, ...handlers) {
+    return this.addRoute("put", path, handlers);
+  }
+  /**
+   * Register a DELETE route
+   */
+  delete(path, ...handlers) {
+    return this.addRoute("delete", path, handlers);
+  }
+  /**
+   * Register a PATCH route
+   */
+  patch(path, ...handlers) {
+    return this.addRoute("patch", path, handlers);
+  }
+  /**
+   * Register an OPTIONS route
+   */
+  options(path, ...handlers) {
+    return this.addRoute("options", path, handlers);
+  }
+  /**
+   * Register a HEAD route
+   */
+  head(path, ...handlers) {
+    return this.addRoute("head", path, handlers);
+  }
+  /**
+   * Register a route for all HTTP methods
+   */
+  all(path, ...handlers) {
+    const methods = ["get", "post", "put", "delete", "patch", "options", "head"];
+    for (const method of methods) {
+      this.addRoute(method, path, handlers);
+    }
+    return this;
+  }
+  use(pathOrMiddleware, ...middleware) {
+    this.isPureStaticApp = false;
+    if (typeof pathOrMiddleware === "string") {
+      this.router.usePattern(pathOrMiddleware, ...middleware);
+    } else {
+      this.router.use(pathOrMiddleware, ...middleware);
+    }
+    return this;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Route Grouping
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Mount a sub-application at a path prefix
+   *
+   * @example
+   * ```typescript
+   * const api = new Gravito()
+   * api.get('/users', (c) => c.json({ users: [] }))
+   *
+   * const app = new Gravito()
+   * app.route('/api', api)
+   * // Now accessible at /api/users
+   * ```
+   */
+  route(path, app) {
+    console.warn("route() method is not yet fully implemented");
+    return this;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Error Handling
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Set custom error handler
+   *
+   * @example
+   * ```typescript
+   * app.onError((err, c) => {
+   *   console.error(err)
+   *   return c.json({ error: err.message }, 500)
+   * })
+   * ```
+   */
+  onError(handler) {
+    this.errorHandler = handler;
+    return this;
+  }
+  /**
+   * Set custom 404 handler
+   *
+   * @example
+   * ```typescript
+   * app.notFound((c) => {
+   *   return c.json({ error: 'Not Found' }, 404)
+   * })
+   * ```
+   */
+  notFound(handler) {
+    this.notFoundHandler = handler;
+    return this;
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Request Handling (Bun.serve integration)
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Handle an incoming request
+   *
+   * Optimized for minimal allocations and maximum throughput.
+   * Uses sync/async dual-path strategy inspired by Hono.
+   *
+   * @param request - Incoming Request object
+   * @returns Response object (sync or async)
+   */
+  fetch = (request) => {
+    const path = extractPath(request.url);
+    const method = request.method.toLowerCase();
+    const staticKey = `${method}:${path}`;
+    const staticRoute = this.staticRoutes.get(staticKey);
+    if (staticRoute) {
+      if (staticRoute.useMinimal) {
+        const ctx = new MinimalContext(request, {}, path);
+        try {
+          const result = staticRoute.handler(ctx);
+          if (result instanceof Response) {
+            return result;
+          }
+          return result;
+        } catch (error) {
+          return this.handleErrorSync(error, request, path);
+        }
+      }
+      return this.handleWithMiddleware(request, path, staticRoute);
+    }
+    return this.handleDynamicRoute(request, method, path);
+  };
+  /**
+   * Handle routes with middleware (async path)
+   */
+  async handleWithMiddleware(request, path, route) {
+    const ctx = this.contextPool.acquire();
+    try {
+      ctx.reset(request, {});
+      const middleware = this.collectMiddlewareForPath(path, route.middleware);
+      if (middleware.length === 0) {
+        return await route.handler(ctx);
+      }
+      return await this.executeMiddleware(ctx, middleware, route.handler);
+    } catch (error) {
+      return await this.handleError(error, ctx);
+    } finally {
+      this.contextPool.release(ctx);
+    }
+  }
+  /**
+   * Handle dynamic routes (Radix Tree lookup)
+   */
+  handleDynamicRoute(request, method, path) {
+    const match = this.router.match(method.toUpperCase(), path);
+    if (!match.handler) {
+      return this.handleNotFoundSync(request, path);
+    }
+    const ctx = this.contextPool.acquire();
+    const execute = async () => {
+      try {
+        ctx.reset(request, match.params);
+        if (match.middleware.length === 0) {
+          return await match.handler(ctx);
+        }
+        return await this.executeMiddleware(ctx, match.middleware, match.handler);
+      } catch (error) {
+        return await this.handleError(error, ctx);
+      } finally {
+        this.contextPool.release(ctx);
+      }
+    };
+    return execute();
+  }
+  /**
+   * Sync error handler (for ultra-fast path)
+   */
+  handleErrorSync(error, request, path) {
+    if (this.errorHandler) {
+      const ctx = new MinimalContext(request, {}, path);
+      const result = this.errorHandler(error, ctx);
+      if (result instanceof Response) {
+        return result;
+      }
+      return result;
+    }
+    console.error("Unhandled error:", error);
+    return new Response(
+      JSON.stringify({
+        error: "Internal Server Error",
+        message: error.message
+      }),
+      {
+        status: 500,
+        headers: { "Content-Type": "application/json" }
+      }
+    );
+  }
+  /**
+   * Sync 404 handler (for ultra-fast path)
+   */
+  handleNotFoundSync(request, path) {
+    if (this.notFoundHandler) {
+      const ctx = new MinimalContext(request, {}, path);
+      const result = this.notFoundHandler(ctx);
+      if (result instanceof Response) {
+        return result;
+      }
+      return result;
+    }
+    return new Response(JSON.stringify({ error: "Not Found" }), {
+      status: 404,
+      headers: { "Content-Type": "application/json" }
+    });
+  }
+  /**
+   * Collect middleware for a specific path
+   * (Simplified version - assumes we've already checked for pure static)
+   */
+  collectMiddlewareForPath(path, routeMiddleware) {
+    if (this.router.globalMiddleware.length === 0 && this.router.pathMiddleware.size === 0) {
+      return routeMiddleware;
+    }
+    return this.router.collectMiddlewarePublic(path, routeMiddleware);
+  }
+  /**
+   * Compile routes for optimization
+   * Called once during initialization and when routes change
+   */
+  compileRoutes() {
+    this.staticRoutes = this.router.staticRoutes;
+    const hasGlobalMiddleware = this.router.globalMiddleware.length > 0;
+    const hasPathMiddleware = this.router.pathMiddleware.size > 0;
+    this.isPureStaticApp = !hasGlobalMiddleware && !hasPathMiddleware;
+    for (const [_key, route] of this.staticRoutes) {
+      const analysis = analyzeHandler(route.handler);
+      const optimalType = getOptimalContextType(analysis);
+      route.useMinimal = this.isPureStaticApp && route.middleware.length === 0 && optimalType === "minimal";
+    }
+  }
+  // ─────────────────────────────────────────────────────────────────────────
+  // Internal Methods
+  // ─────────────────────────────────────────────────────────────────────────
+  /**
+   * Add a route to the router
+   */
+  addRoute(method, path, handlers) {
+    if (handlers.length === 0) {
+      throw new Error(`No handler provided for ${method.toUpperCase()} ${path}`);
+    }
+    const handler = handlers[handlers.length - 1];
+    const middleware = handlers.slice(0, -1);
+    this.router.add(method, path, handler, middleware);
+    this.compileRoutes();
+    return this;
+  }
+  /**
+   * Execute middleware chain followed by handler
+   *
+   * Implements the standard middleware pattern:
+   * Each middleware can call next() to continue the chain.
+   */
+  async executeMiddleware(ctx, middleware, handler) {
+    let index = 0;
+    const next = async () => {
+      if (index < middleware.length) {
+        const mw = middleware[index++];
+        await mw(ctx, next);
+      }
+    };
+    await next();
+    return await handler(ctx);
+  }
+  /**
+   * Handle 404 Not Found (Async version for dynamic/middleware paths)
+   */
+  async handleNotFound(ctx) {
+    if (this.notFoundHandler) {
+      return await this.notFoundHandler(ctx);
+    }
+    return ctx.json({ error: "Not Found" }, 404);
+  }
+  /**
+   * Handle errors (Async version for dynamic/middleware paths)
+   */
+  async handleError(error, ctx) {
+    if (this.errorHandler) {
+      return await this.errorHandler(error, ctx);
+    }
+    console.error("Unhandled error:", error);
+    return ctx.json(
+      {
+        error: "Internal Server Error",
+        message: error.message
+      },
+      500
+    );
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AOTRouter,
+  FastContextImpl,
+  Gravito,
+  MinimalContext,
+  ObjectPool,
+  extractPath
+});