@gravito/core 1.0.0 → 1.2.0

package/dist/index.cjs

@@ -54,6 +54,7 @@ __export(index_exports, {
   PhotonRequestWrapper: () => PhotonRequestWrapper,
   PlanetCore: () => PlanetCore,
   Route: () => Route,
+  RouteGroup: () => RouteGroup,
   Router: () => Router,
   ServiceProvider: () => ServiceProvider,
   Str: () => Str,
@@ -82,6 +83,7 @@ __export(index_exports, {
   dd: () => dd,
   defineConfig: () => defineConfig,
   dump: () => dump,
+  engine: () => engine_exports,
   env: () => env,
   errors: () => errors,
   fail: () => fail,
@@ -112,7 +114,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@gravito/core",
-  version: "1.0.0",
+  version: "1.2.0",
   description: "",
   module: "./dist/index.js",
   main: "./dist/index.cjs",
@@ -128,6 +130,11 @@ var package_default = {
       types: "./dist/compat.d.ts",
       import: "./dist/compat.js",
       require: "./dist/compat.cjs"
+    },
+    "./engine": {
+      types: "./dist/engine/index.d.ts",
+      import: "./dist/engine/index.js",
+      require: "./dist/engine/index.cjs"
     }
   },
   files: [
@@ -179,11 +186,45 @@ var package_default = {
 };
 
 // src/adapters/PhotonAdapter.ts
-var PhotonRequestWrapper = class {
+var PhotonRequestWrapper = class _PhotonRequestWrapper {
   constructor(photonCtx) {
     this.photonCtx = photonCtx;
   }
-  _cachedJson = null;
+  /**
+   * Create a proxied instance to delegate to Photon's request
+   */
+  static create(photonCtx) {
+    const instance = new _PhotonRequestWrapper(photonCtx);
+    return new Proxy(instance, {
+      get(target, prop, receiver) {
+        if (prop in target) {
+          const value2 = Reflect.get(target, prop, receiver);
+          if (typeof value2 === "function") {
+            return value2.bind(target);
+          }
+          return value2;
+        }
+        const nativeReq = target.photonCtx.req;
+        if (prop in nativeReq) {
+          const value2 = nativeReq[prop];
+          if (typeof value2 === "function") {
+            return value2.bind(nativeReq);
+          }
+          return value2;
+        }
+        return void 0;
+      },
+      // Allow setting properties (for addValidated etc.)
+      set(target, prop, value2) {
+        if (prop in target) {
+          return Reflect.set(target, prop, value2);
+        }
+        ;
+        target.photonCtx.req[prop] = value2;
+        return true;
+      }
+    });
+  }
   get url() {
     return this.photonCtx.req.url;
   }
@@ -242,7 +283,7 @@ var PhotonRequestWrapper = class {
 var PhotonContextWrapper = class _PhotonContextWrapper {
   constructor(photonCtx) {
     this.photonCtx = photonCtx;
-    this._req = new PhotonRequestWrapper(photonCtx);
+    this._req = PhotonRequestWrapper.create(photonCtx);
   }
   _req;
   /**
@@ -354,7 +395,7 @@ function toPhotonMiddleware(middleware) {
   return async (c, next) => {
     const ctx = PhotonContextWrapper.create(c);
     const gravitoNext = async () => {
-      await next();
+      return await next();
     };
     return middleware(ctx, gravitoNext);
   };
@@ -2818,20 +2859,20 @@ var RouteGroup = class _RouteGroup {
   group(callback) {
     callback(this);
   }
-  get(path2, requestOrHandler, handler) {
-    return this.router.req("get", path2, requestOrHandler, handler, this.options);
+  get(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.router.req("get", path2, requestOrHandlerOrMiddleware, handler, this.options);
   }
-  post(path2, requestOrHandler, handler) {
-    return this.router.req("post", path2, requestOrHandler, handler, this.options);
+  post(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.router.req("post", path2, requestOrHandlerOrMiddleware, handler, this.options);
   }
-  put(path2, requestOrHandler, handler) {
-    return this.router.req("put", path2, requestOrHandler, handler, this.options);
+  put(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.router.req("put", path2, requestOrHandlerOrMiddleware, handler, this.options);
   }
-  delete(path2, requestOrHandler, handler) {
-    return this.router.req("delete", path2, requestOrHandler, handler, this.options);
+  delete(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.router.req("delete", path2, requestOrHandlerOrMiddleware, handler, this.options);
   }
-  patch(path2, requestOrHandler, handler) {
-    return this.router.req("patch", path2, requestOrHandler, handler, this.options);
+  patch(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.router.req("patch", path2, requestOrHandlerOrMiddleware, handler, this.options);
   }
   resource(name, controller, options = {}) {
     const actions = [
@@ -3007,20 +3048,20 @@ var Router = class {
   middleware(...handlers) {
     return new RouteGroup(this, { middleware: handlers.flat() });
   }
-  get(path2, requestOrHandler, handler) {
-    return this.req("get", path2, requestOrHandler, handler);
+  get(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.req("get", path2, requestOrHandlerOrMiddleware, handler);
   }
-  post(path2, requestOrHandler, handler) {
-    return this.req("post", path2, requestOrHandler, handler);
+  post(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.req("post", path2, requestOrHandlerOrMiddleware, handler);
   }
-  put(path2, requestOrHandler, handler) {
-    return this.req("put", path2, requestOrHandler, handler);
+  put(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.req("put", path2, requestOrHandlerOrMiddleware, handler);
   }
-  delete(path2, requestOrHandler, handler) {
-    return this.req("delete", path2, requestOrHandler, handler);
+  delete(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.req("delete", path2, requestOrHandlerOrMiddleware, handler);
   }
-  patch(path2, requestOrHandler, handler) {
-    return this.req("patch", path2, requestOrHandler, handler);
+  patch(path2, requestOrHandlerOrMiddleware, handler) {
+    return this.req("patch", path2, requestOrHandlerOrMiddleware, handler);
   }
   /**
    * Register a resource route (Laravel-style).
@@ -3066,17 +3107,25 @@ var Router = class {
   /**
    * Internal Request Registration
    */
-  req(method, path2, requestOrHandler, handler, options = {}) {
+  req(method, path2, requestOrHandlerOrMiddleware, handler, options = {}) {
     const fullPath = (options.prefix || "") + path2;
     let formRequestMiddleware = null;
+    let routeMiddleware = [];
     let finalRouteHandler;
     if (handler !== void 0) {
-      if (isFormRequestClass(requestOrHandler)) {
-        formRequestMiddleware = formRequestToMiddleware(requestOrHandler);
+      if (isFormRequestClass(requestOrHandlerOrMiddleware)) {
+        formRequestMiddleware = formRequestToMiddleware(requestOrHandlerOrMiddleware);
+      } else {
+        const middleware = requestOrHandlerOrMiddleware;
+        if (Array.isArray(middleware)) {
+          routeMiddleware = middleware;
+        } else {
+          routeMiddleware = [middleware];
+        }
       }
       finalRouteHandler = handler;
     } else {
-      finalRouteHandler = requestOrHandler;
+      finalRouteHandler = requestOrHandlerOrMiddleware;
     }
     let resolvedHandler;
     if (Array.isArray(finalRouteHandler)) {
@@ -3092,6 +3141,9 @@ var Router = class {
     if (formRequestMiddleware) {
       handlers.push(formRequestMiddleware);
     }
+    if (routeMiddleware.length > 0) {
+      handlers.push(...routeMiddleware);
+    }
     handlers.push(resolvedHandler);
     if (options.domain) {
       const domainCheck = async (c, next) => {
@@ -3366,8 +3418,7 @@ var PlanetCore = class _PlanetCore {
       const cookieJar = new CookieJar(this.encrypter);
       c.set("cookieJar", cookieJar);
       c.route = (name, params, query) => this.router.url(name, params, query);
-      await next();
-      return void 0;
+      return await next();
     });
     this.router = new Router(this);
     this.adapter.onError(async (err, c) => {
@@ -4709,6 +4760,947 @@ function createHttpTester(core) {
   return new HttpTester(core);
 }
 
+// src/engine/index.ts
+var engine_exports = {};
+__export(engine_exports, {
+  AOTRouter: () => AOTRouter,
+  FastContextImpl: () => FastContext,
+  Gravito: () => Gravito,
+  MinimalContext: () => MinimalContext,
+  ObjectPool: () => ObjectPool,
+  extractPath: () => extractPath
+});
+
+// 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, path2, handler, middleware = []) {
+    const normalizedMethod = method.toLowerCase();
+    if (this.isStaticPath(path2)) {
+      const key = `${normalizedMethod}:${path2}`;
+      this.staticRoutes.set(key, { handler, middleware });
+    } else {
+      const wrappedHandler = handler;
+      this.dynamicRouter.add(normalizedMethod, path2, [wrappedHandler]);
+      if (middleware.length > 0) {
+        this.pathMiddleware.set(`${normalizedMethod}:${path2}`, 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, path2) {
+    const normalizedMethod = method.toLowerCase();
+    const staticKey = `${normalizedMethod}:${path2}`;
+    const staticRoute = this.staticRoutes.get(staticKey);
+    if (staticRoute) {
+      return {
+        handler: staticRoute.handler,
+        params: {},
+        middleware: this.collectMiddleware(path2, staticRoute.middleware)
+      };
+    }
+    const match = this.dynamicRouter.match(normalizedMethod, path2);
+    if (match && match.handlers.length > 0) {
+      const handler = match.handlers[0];
+      const routeKey = this.findDynamicRouteKey(normalizedMethod, path2);
+      const routeMiddleware = routeKey ? this.pathMiddleware.get(routeKey) ?? [] : [];
+      return {
+        handler,
+        params: match.params,
+        middleware: this.collectMiddleware(path2, routeMiddleware)
+      };
+    }
+    return {
+      handler: null,
+      params: {},
+      middleware: []
+    };
+  }
+  /**
+   * Public wrapper for collectMiddleware (used by Gravito for optimization)
+   */
+  collectMiddlewarePublic(path2, routeMiddleware) {
+    return this.collectMiddleware(path2, 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(path2, 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, path2)) {
+          middleware.push(...mw);
+        }
+      }
+    }
+    if (routeMiddleware.length > 0) {
+      middleware.push(...routeMiddleware);
+    }
+    return middleware;
+  }
+  /**
+   * Check if a path is static (no parameters or wildcards)
+   */
+  isStaticPath(path2) {
+    return !path2.includes(":") && !path2.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, path2) {
+    if (pattern === "*") return true;
+    if (pattern === path2) return true;
+    if (pattern.endsWith("/*")) {
+      const prefix = pattern.slice(0, -2);
+      return path2.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, path2] = key.split(":");
+      routes.push({ method, path: path2, 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, value2] of this._query.entries()) {
+      const existing = result[key];
+      if (existing === void 0) {
+        result[key] = value2;
+      } else if (Array.isArray(existing)) {
+        existing.push(value2);
+      } else {
+        result[key] = [existing, value2];
+      }
+    }
+    return result;
+  }
+  header(name) {
+    return this._request.headers.get(name) ?? void 0;
+  }
+  headers() {
+    if (!this._headers) {
+      this._headers = {};
+      for (const [key, value2] of this._request.headers.entries()) {
+        this._headers[key] = value2;
+      }
+    }
+    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();
+  // private _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._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, value2) {
+    this._headers.set(name, value2);
+  }
+  status(_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, value2] of url.searchParams.entries()) {
+      const existing = result[key];
+      if (existing === void 0) {
+        result[key] = value2;
+      } else if (Array.isArray(existing)) {
+        existing.push(value2);
+      } else {
+        result[key] = [existing, value2];
+      }
+    }
+    return result;
+  }
+  header(name) {
+    return this._request.headers.get(name) ?? void 0;
+  }
+  headers() {
+    const result = {};
+    for (const [key, value2] of this._request.headers.entries()) {
+      result[key] = value2;
+    }
+    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, path2) {
+    this._req = new MinimalRequest(request, params, path2);
+  }
+  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(path2, ...handlers) {
+    return this.addRoute("get", path2, handlers);
+  }
+  /**
+   * Register a POST route
+   */
+  post(path2, ...handlers) {
+    return this.addRoute("post", path2, handlers);
+  }
+  /**
+   * Register a PUT route
+   */
+  put(path2, ...handlers) {
+    return this.addRoute("put", path2, handlers);
+  }
+  /**
+   * Register a DELETE route
+   */
+  delete(path2, ...handlers) {
+    return this.addRoute("delete", path2, handlers);
+  }
+  /**
+   * Register a PATCH route
+   */
+  patch(path2, ...handlers) {
+    return this.addRoute("patch", path2, handlers);
+  }
+  /**
+   * Register an OPTIONS route
+   */
+  options(path2, ...handlers) {
+    return this.addRoute("options", path2, handlers);
+  }
+  /**
+   * Register a HEAD route
+   */
+  head(path2, ...handlers) {
+    return this.addRoute("head", path2, handlers);
+  }
+  /**
+   * Register a route for all HTTP methods
+   */
+  all(path2, ...handlers) {
+    const methods = ["get", "post", "put", "delete", "patch", "options", "head"];
+    for (const method of methods) {
+      this.addRoute(method, path2, 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 path2 = extractPath(request.url);
+    const method = request.method.toLowerCase();
+    const staticKey = `${method}:${path2}`;
+    const staticRoute = this.staticRoutes.get(staticKey);
+    if (staticRoute) {
+      if (staticRoute.useMinimal) {
+        const ctx = new MinimalContext(request, {}, path2);
+        try {
+          const result = staticRoute.handler(ctx);
+          if (result instanceof Response) {
+            return result;
+          }
+          return result;
+        } catch (error) {
+          return this.handleErrorSync(error, request, path2);
+        }
+      }
+      return this.handleWithMiddleware(request, path2, staticRoute);
+    }
+    return this.handleDynamicRoute(request, method, path2);
+  };
+  /**
+   * Handle routes with middleware (async path)
+   */
+  async handleWithMiddleware(request, path2, route) {
+    const ctx = this.contextPool.acquire();
+    try {
+      ctx.reset(request, {});
+      const middleware = this.collectMiddlewareForPath(path2, 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, path2) {
+    const match = this.router.match(method.toUpperCase(), path2);
+    if (!match.handler) {
+      return this.handleNotFoundSync(request, path2);
+    }
+    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, path2) {
+    if (this.errorHandler) {
+      const ctx = new MinimalContext(request, {}, path2);
+      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, path2) {
+    if (this.notFoundHandler) {
+      const ctx = new MinimalContext(request, {}, path2);
+      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(path2, routeMiddleware) {
+    if (this.router.globalMiddleware.length === 0 && this.router.pathMiddleware.size === 0) {
+      return routeMiddleware;
+    }
+    return this.router.collectMiddlewarePublic(path2, 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, path2, handlers) {
+    if (handlers.length === 0) {
+      throw new Error(`No handler provided for ${method.toUpperCase()} ${path2}`);
+    }
+    const handler = handlers[handlers.length - 1];
+    const middleware = handlers.slice(0, -1);
+    this.router.add(method, path2, 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++];
+        return await mw(ctx, next);
+      }
+      return void 0;
+    };
+    const result = await next();
+    if (result instanceof Response) {
+      return result;
+    }
+    return await handler(ctx);
+  }
+  /*
+   * Handle 404 Not Found (Async version for dynamic/middleware paths)
+   * Note: Currently unused as we handle 404s via handleNotFoundSync or inline
+   */
+  // private async handleNotFound(ctx: FastContext): Promise<Response> {
+  //   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
+    );
+  }
+};
+
 // src/index.ts
 var VERSION = package_default.version;
 function defineConfig(config2) {
@@ -4740,6 +5732,7 @@ function defineConfig(config2) {
   PhotonRequestWrapper,
   PlanetCore,
   Route,
+  RouteGroup,
   Router,
   ServiceProvider,
   Str,
@@ -4768,6 +5761,7 @@ function defineConfig(config2) {
   dd,
   defineConfig,
   dump,
+  engine,
   env,
   errors,
   fail,