@theokit/http 0.5.4 → 0.6.0

package/dist/chunk-RC4V75DI.js

@@ -0,0 +1,257 @@
+import {
+  HttpDecoratorsConfigError
+} from "./chunk-QGB5YC4T.js";
+import {
+  resolveOrNew
+} from "./chunk-MQAJWR3K.js";
+import {
+  __name
+} from "./chunk-7QVYU63E.js";
+
+// src/bridge/middleware-consumer.ts
+var MiddlewareConsumerImpl = class {
+  static {
+    __name(this, "MiddlewareConsumerImpl");
+  }
+  entries = [];
+  container;
+  constructor(container) {
+    this.container = container;
+  }
+  apply(...middleware) {
+    const resolved = middleware.map((m) => this.resolveMiddleware(m));
+    const excludePatterns = [];
+    const proxy = {
+      exclude: /* @__PURE__ */ __name((...routes) => {
+        for (const r of routes) excludePatterns.push(typeof r === "string" ? r : r.path);
+        return proxy;
+      }, "exclude"),
+      forRoutes: /* @__PURE__ */ __name((...routes) => {
+        const routePatterns = routes.map((r) => typeof r === "string" ? r : r.path);
+        for (const handler of resolved) {
+          this.entries.push({
+            handler,
+            routePatterns: [
+              ...routePatterns
+            ],
+            excludePatterns: [
+              ...excludePatterns
+            ]
+          });
+        }
+        return this;
+      }, "forRoutes")
+    };
+    return proxy;
+  }
+  getEntries() {
+    return this.entries;
+  }
+  resolveMiddleware(m) {
+    if (typeof m === "function" && !m.prototype?.use) {
+      return m;
+    }
+    const instance = resolveOrNew(m, this.container);
+    return (request, next) => instance.use(request, next);
+  }
+};
+function middlewareMatchesPath(entry, requestPath) {
+  for (const pattern of entry.excludePatterns) {
+    if (pathMatches(requestPath, pattern)) return false;
+  }
+  for (const pattern of entry.routePatterns) {
+    if (pathMatches(requestPath, pattern)) return true;
+  }
+  return false;
+}
+__name(middlewareMatchesPath, "middlewareMatchesPath");
+function pathMatches(requestPath, pattern) {
+  if (pattern === "*") return true;
+  const normPath = ("/" + requestPath).replace(/\/+/g, "/").replace(/\/$/, "");
+  const normPattern = ("/" + pattern).replace(/\/+/g, "/").replace(/\/$/, "");
+  return normPath === normPattern || normPath.startsWith(normPattern + "/");
+}
+__name(pathMatches, "pathMatches");
+async function runMiddleware(entries, request, requestPath) {
+  for (const entry of entries) {
+    if (!middlewareMatchesPath(entry, requestPath)) continue;
+    const response = await entry.handler(request, () => Promise.resolve(null));
+    if (response) return response;
+  }
+  return null;
+}
+__name(runMiddleware, "runMiddleware");
+
+// src/bridge/swc-loader.ts
+import "reflect-metadata";
+import { readFileSync, writeFileSync, unlinkSync, readdirSync } from "fs";
+import { createRequire } from "module";
+import { resolve, dirname, join, relative } from "path";
+import { pathToFileURL, fileURLToPath } from "url";
+function getSwcrcTarget(swcrc) {
+  if (!swcrc) return "es2022";
+  const jsc = swcrc.jsc;
+  if (typeof jsc !== "object" || jsc === null) return "es2022";
+  const target = jsc.target;
+  return typeof target === "string" ? target : "es2022";
+}
+__name(getSwcrcTarget, "getSwcrcTarget");
+var consumerSwcrcCache;
+function readConsumerSwcrc(startDir) {
+  if (consumerSwcrcCache !== void 0) return consumerSwcrcCache;
+  let dir = startDir;
+  const root = dirname(dir);
+  while (dir !== root) {
+    const candidate = join(dir, ".swcrc");
+    try {
+      const raw = readFileSync(candidate, "utf-8");
+      const parsed = JSON.parse(raw);
+      delete parsed.$schema;
+      consumerSwcrcCache = parsed;
+      return parsed;
+    } catch {
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  consumerSwcrcCache = null;
+  return null;
+}
+__name(readConsumerSwcrc, "readConsumerSwcrc");
+var swcCoreCache;
+async function loadSwcCore() {
+  if (swcCoreCache !== void 0) return swcCoreCache;
+  try {
+    swcCoreCache = await import("@swc/core");
+  } catch {
+    try {
+      const thisDir = dirname(fileURLToPath(import.meta.url));
+      const req = createRequire(resolve(thisDir, "index.js"));
+      const resolved = req.resolve("@swc/core");
+      swcCoreCache = await import(pathToFileURL(resolved).href);
+    } catch {
+      swcCoreCache = null;
+    }
+  }
+  return swcCoreCache;
+}
+__name(loadSwcCore, "loadSwcCore");
+async function transformControllerSource(source, filename, loadSwc = loadSwcCore) {
+  const swc = await loadSwc();
+  if (!swc) {
+    throw new HttpDecoratorsConfigError(`@swc/core is required for parameter decorators (@Body, @Param, @Query). Install it:
+
+  pnpm add -D @swc/core
+
+esbuild (used by tsx/Vite) cannot parse parameter decorators. SWC handles them correctly with full metadata emission.`);
+  }
+  const consumerSwcrc = readConsumerSwcrc(dirname(filename));
+  const consumerJsc = consumerSwcrc?.jsc && typeof consumerSwcrc.jsc === "object" ? consumerSwcrc.jsc : null;
+  const { code } = swc.transformSync(source, {
+    filename,
+    jsc: {
+      parser: {
+        syntax: "typescript",
+        decorators: true,
+        ...consumerJsc?.parser
+      },
+      transform: {
+        ...consumerJsc?.transform,
+        // NON-NEGOTIABLE — always enforce decorator metadata emission
+        // regardless of consumer .swcrc overrides
+        legacyDecorator: true,
+        decoratorMetadata: true
+      },
+      target: getSwcrcTarget(consumerSwcrc)
+    },
+    module: {
+      type: "es6"
+    },
+    sourceMaps: false
+  });
+  return code;
+}
+__name(transformControllerSource, "transformControllerSource");
+async function loadControllerWithSwc(absoluteFilePath) {
+  const source = readFileSync(absoluteFilePath, "utf-8");
+  const code = await transformControllerSource(source, absoluteFilePath);
+  const tmpPath = absoluteFilePath.replace(/\.ts$/, ".__decorated__.mjs");
+  writeFileSync(tmpPath, code, "utf-8");
+  try {
+    const url = pathToFileURL(tmpPath).href + `?t=${Date.now()}`;
+    return await import(url);
+  } finally {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+    }
+  }
+}
+__name(loadControllerWithSwc, "loadControllerWithSwc");
+async function loadControllersFromGlob(rootDir, pattern) {
+  const files = scanControllerFiles(rootDir, pattern);
+  if (files.length === 0) {
+    console.warn(`[@theokit/http] No controller files found matching "${pattern}" in ${rootDir}. Ensure files match the pattern and export @Controller classes.`);
+    return [];
+  }
+  const controllers = [];
+  for (const file of files) {
+    const absPath = resolve(rootDir, file);
+    const mod = await loadControllerWithSwc(absPath);
+    for (const exported of Object.values(mod)) {
+      if (typeof exported === "function" && isControllerClass(exported)) {
+        controllers.push(exported);
+      }
+    }
+  }
+  return controllers;
+}
+__name(loadControllersFromGlob, "loadControllersFromGlob");
+function isControllerClass(fn) {
+  try {
+    return Reflect.hasMetadata(/* @__PURE__ */ Symbol.for("theokit:http-decorators:controller-prefix"), fn);
+  } catch {
+    return false;
+  }
+}
+__name(isControllerClass, "isControllerClass");
+function scanControllerFiles(rootDir, pattern) {
+  const parts = pattern.split("/");
+  const dirParts = [];
+  for (const part of parts) {
+    if (part.includes("*")) break;
+    dirParts.push(part);
+  }
+  const baseDir = join(rootDir, ...dirParts);
+  const lastPart = parts[parts.length - 1];
+  const suffix = lastPart.replace(/\*/g, "");
+  const files = [];
+  function walk(dir) {
+    try {
+      for (const entry of readdirSync(dir, {
+        withFileTypes: true
+      })) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) walk(full);
+        else if (entry.name.endsWith(suffix)) files.push(relative(rootDir, full));
+      }
+    } catch {
+    }
+  }
+  __name(walk, "walk");
+  walk(baseDir);
+  return files;
+}
+__name(scanControllerFiles, "scanControllerFiles");
+
+export {
+  MiddlewareConsumerImpl,
+  middlewareMatchesPath,
+  runMiddleware,
+  transformControllerSource,
+  loadControllerWithSwc,
+  loadControllersFromGlob,
+  isControllerClass
+};
+//# sourceMappingURL=chunk-RC4V75DI.js.map

package/dist/chunk-RC4V75DI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bridge/middleware-consumer.ts","../src/bridge/swc-loader.ts"],"sourcesContent":["/**\n * NestJS-style Middleware support — Web Standard Request/Response.\n *\n * Middleware runs BEFORE guards: middleware → guards → interceptors → handler\n *\n * Supports class middleware (NestMiddleware) and functional middleware.\n * Returns a Response to short-circuit, or null to continue.\n */\nimport { resolveOrNew, type DiContainer } from './di-resolve.js'\n\n/** NestJS-compatible middleware interface — Web Standard. */\nexport interface NestMiddleware {\n  use(\n    request: Request,\n    next: () => Promise<Response | null>,\n  ): Response | null | Promise<Response | null>\n}\n\n/** Functional middleware. */\nexport type MiddlewareFn = (\n  request: Request,\n  next: () => Promise<Response | null>,\n) => Response | null | Promise<Response | null>\n\nexport interface ResolvedMiddleware {\n  handler: MiddlewareFn\n  routePatterns: string[]\n  excludePatterns: string[]\n}\n\nexport type RouteInfo = string | { path: string; method?: string }\n\nexport interface MiddlewareConfigProxy {\n  forRoutes(...routes: RouteInfo[]): MiddlewareConsumerImpl\n  exclude(...routes: RouteInfo[]): MiddlewareConfigProxy\n}\n\nexport class MiddlewareConsumerImpl {\n  private entries: ResolvedMiddleware[] = []\n  private container?: DiContainer\n\n  constructor(container?: DiContainer) {\n    this.container = container\n  }\n\n  apply(...middleware: (Function | MiddlewareFn)[]): MiddlewareConfigProxy {\n    const resolved = middleware.map((m) => this.resolveMiddleware(m))\n    const excludePatterns: string[] = []\n\n    const proxy: MiddlewareConfigProxy = {\n      exclude: (...routes: RouteInfo[]) => {\n        for (const r of routes) excludePatterns.push(typeof r === 'string' ? r : r.path)\n        return proxy\n      },\n      forRoutes: (...routes: RouteInfo[]) => {\n        const routePatterns = routes.map((r) => (typeof r === 'string' ? r : r.path))\n        for (const handler of resolved) {\n          this.entries.push({ handler, routePatterns: [...routePatterns], excludePatterns: [...excludePatterns] })\n        }\n        return this\n      },\n    }\n    return proxy\n  }\n\n  getEntries(): ResolvedMiddleware[] {\n    return this.entries\n  }\n\n  private resolveMiddleware(m: Function | MiddlewareFn): MiddlewareFn {\n    if (typeof m === 'function' && !m.prototype?.use) {\n      return m as MiddlewareFn\n    }\n    const instance = resolveOrNew(m, this.container) as NestMiddleware\n    return (request, next) => instance.use(request, next)\n  }\n}\n\nexport function middlewareMatchesPath(entry: ResolvedMiddleware, requestPath: string): boolean {\n  for (const pattern of entry.excludePatterns) {\n    if (pathMatches(requestPath, pattern)) return false\n  }\n  for (const pattern of entry.routePatterns) {\n    if (pathMatches(requestPath, pattern)) return true\n  }\n  return false\n}\n\nfunction pathMatches(requestPath: string, pattern: string): boolean {\n  if (pattern === '*') return true\n  const normPath = ('/' + requestPath).replace(/\\/+/g, '/').replace(/\\/$/, '')\n  const normPattern = ('/' + pattern).replace(/\\/+/g, '/').replace(/\\/$/, '')\n  return normPath === normPattern || normPath.startsWith(normPattern + '/')\n}\n\n/**\n * Run all matching middleware. Returns a Response if any short-circuited, null otherwise.\n */\nexport async function runMiddleware(\n  entries: ResolvedMiddleware[],\n  request: Request,\n  requestPath: string,\n): Promise<Response | null> {\n  for (const entry of entries) {\n    if (!middlewareMatchesPath(entry, requestPath)) continue\n    const response = await entry.handler(request, () => Promise.resolve(null))\n    if (response) return response // short-circuit\n  }\n  return null\n}\n","/* eslint-disable security/detect-non-literal-fs-filename --\n * The SWC loader reads/writes controller files by absolute path derived\n * from developer-authored glob patterns in theo.config.ts, not from HTTP\n * input. The file paths come from scanControllerFiles() which walks the\n * project's own source tree. No injection vector.\n */\n/**\n * SWC-powered module loader for controller files with parameter decorators.\n *\n * esbuild (used by tsx/Vite SSR) fundamentally cannot parse TypeScript\n * parameter decorators (`@Body()`, `@Param()`, `@Query()`). This loader\n * uses @swc/core to transform controller files with full decorator support\n * (legacyDecorator + decoratorMetadata), then imports them via a temp .mjs\n * file written in the SAME directory (preserving relative import resolution).\n *\n * Pattern: follows Next.js's approach (read tsconfig → configure SWC)\n * but scoped to the http-decorators package, not the framework core.\n *\n * @see references/next.js/packages/next/src/build/swc/options.ts\n */\nimport 'reflect-metadata'\nimport { readFileSync, writeFileSync, unlinkSync, readdirSync } from 'node:fs'\nimport { createRequire } from 'node:module'\nimport { resolve, dirname, join, relative } from 'node:path'\nimport { pathToFileURL, fileURLToPath } from 'node:url'\n\nimport { HttpDecoratorsConfigError } from './errors.js'\n\n/** Extract jsc.target from parsed .swcrc or fall back to es2022. */\nfunction getSwcrcTarget(swcrc: Record<string, unknown> | null): string {\n  if (!swcrc) return 'es2022'\n  const jsc = swcrc.jsc\n  if (typeof jsc !== 'object' || jsc === null) return 'es2022'\n  const target = (jsc as Record<string, unknown>).target\n  return typeof target === 'string' ? target : 'es2022'\n}\n\n/** Cached consumer .swcrc — read once per process. */\nlet consumerSwcrcCache: Record<string, unknown> | null | undefined\n\n/**\n * Walk up from the controller file's directory to find a .swcrc.\n * Returns the parsed JSON or null if none found.\n * Caches the result — .swcrc doesn't change at runtime.\n */\nfunction readConsumerSwcrc(startDir: string): Record<string, unknown> | null {\n  if (consumerSwcrcCache !== undefined) return consumerSwcrcCache\n\n  let dir = startDir\n  const root = dirname(dir) // stop at filesystem root\n  while (dir !== root) {\n    const candidate = join(dir, '.swcrc')\n    try {\n      const raw = readFileSync(candidate, 'utf-8')\n      const parsed = JSON.parse(raw) as Record<string, unknown>\n      // Strip $schema — not an SWC transform option\n      delete parsed.$schema\n      consumerSwcrcCache = parsed\n      return parsed\n    } catch {\n      // File doesn't exist or invalid JSON — walk up\n    }\n    const parent = dirname(dir)\n    if (parent === dir) break\n    dir = parent\n  }\n\n  consumerSwcrcCache = null\n  return null\n}\n\nexport interface SwcCore {\n  transformSync: (src: string, opts: unknown) => { code: string }\n}\n\n/** Cached @swc/core instance — loaded once, reused across all controller files. */\nlet swcCoreCache: SwcCore | null | undefined\n\n/**\n * Dynamically load @swc/core with singleton cache.\n *\n * Handles pnpm strict node_modules: @swc/core is only directly importable\n * from the package that declares it as a dependency. We use createRequire\n * rooted at THIS package's directory to resolve correctly.\n *\n * The cache ensures the ~50ms dynamic import() cost is paid ONCE,\n * not per-controller-file.\n */\nasync function loadSwcCore(): Promise<SwcCore | null> {\n  if (swcCoreCache !== undefined) return swcCoreCache\n\n  try {\n    swcCoreCache = (await import('@swc/core')) as SwcCore\n  } catch {\n    try {\n      const thisDir = dirname(fileURLToPath(import.meta.url))\n      const req = createRequire(resolve(thisDir, 'index.js'))\n      const resolved = req.resolve('@swc/core')\n      swcCoreCache = (await import(pathToFileURL(resolved).href)) as SwcCore\n    } catch {\n      swcCoreCache = null\n    }\n  }\n  return swcCoreCache\n}\n\n/**\n * Transform TypeScript controller SOURCE (with parameter decorators) into\n * ESM code, emitting the `design:paramtypes` / decorator metadata that esbuild\n * cannot produce. Pure code→code — no file I/O, no module load — so it is\n * reusable both by {@link loadControllerWithSwc} (which then temp-writes +\n * imports) and by a build-tool transform hook that returns `{ code }` directly.\n *\n * The `@swc/core` loader is injectable (`loadSwc`) for testability; it defaults\n * to the cached singleton.\n *\n * @throws HttpDecoratorsConfigError when @swc/core is unavailable.\n */\nexport async function transformControllerSource(\n  source: string,\n  filename: string,\n  loadSwc: () => Promise<SwcCore | null> = loadSwcCore,\n): Promise<string> {\n  const swc = await loadSwc()\n  if (!swc) {\n    throw new HttpDecoratorsConfigError(\n      `@swc/core is required for parameter decorators (@Body, @Param, @Query). ` +\n        `Install it:\\n\\n  pnpm add -D @swc/core\\n\\n` +\n        `esbuild (used by tsx/Vite) cannot parse parameter decorators. ` +\n        `SWC handles them correctly with full metadata emission.`,\n    )\n  }\n\n  const consumerSwcrc = readConsumerSwcrc(dirname(filename))\n  const consumerJsc =\n    consumerSwcrc?.jsc && typeof consumerSwcrc.jsc === 'object'\n      ? (consumerSwcrc.jsc as Record<string, unknown>)\n      : null\n  const { code } = swc.transformSync(source, {\n    filename,\n    jsc: {\n      parser: {\n        syntax: 'typescript',\n        decorators: true,\n        ...(consumerJsc?.parser as Record<string, unknown> | undefined),\n      },\n      transform: {\n        ...(consumerJsc?.transform as Record<string, unknown> | undefined),\n        // NON-NEGOTIABLE — always enforce decorator metadata emission\n        // regardless of consumer .swcrc overrides\n        legacyDecorator: true,\n        decoratorMetadata: true,\n      },\n      target: getSwcrcTarget(consumerSwcrc),\n    },\n    module: { type: 'es6' },\n    sourceMaps: false,\n  })\n  return code\n}\n\n/**\n * Load a TypeScript controller file using @swc/core for decorator support.\n *\n * Strategy:\n *   1. Read source .ts file\n *   2. Transform via {@link transformControllerSource} (legacyDecorator + metadata)\n *   3. Write temp .mjs in SAME directory (relative imports resolve correctly)\n *   4. Dynamic import() the .mjs — transitive .ts imports go through\n *      tsx/Vite's global hook (they don't have parameter decorators)\n *   5. Cleanup temp file\n */\nexport async function loadControllerWithSwc(\n  absoluteFilePath: string,\n): Promise<Record<string, unknown>> {\n  const source = readFileSync(absoluteFilePath, 'utf-8')\n  const code = await transformControllerSource(source, absoluteFilePath)\n\n  // Write temp .mjs in SAME directory so relative imports resolve identically.\n  // .mjs = Node treats as ESM regardless of package.json type field.\n  // Transitive .ts imports go through tsx's global hook (no param decorators there).\n  const tmpPath = absoluteFilePath.replace(/\\.ts$/, '.__decorated__.mjs')\n  writeFileSync(tmpPath, code, 'utf-8')\n  try {\n    const url = pathToFileURL(tmpPath).href + `?t=${Date.now()}`\n    return (await import(url)) as Record<string, unknown>\n  } finally {\n    try {\n      unlinkSync(tmpPath)\n    } catch {\n      // Best-effort cleanup\n    }\n  }\n}\n\n/**\n * Scan a glob pattern for controller files and load them all via SWC.\n * Returns an array of controller class constructors found.\n */\nexport async function loadControllersFromGlob(\n  rootDir: string,\n  pattern: string,\n): Promise<Function[]> {\n  const files = scanControllerFiles(rootDir, pattern)\n  if (files.length === 0) {\n    console.warn(\n      `[@theokit/http] No controller files found matching \"${pattern}\" ` +\n        `in ${rootDir}. Ensure files match the pattern and export @Controller classes.`,\n    )\n    return []\n  }\n\n  const controllers: Function[] = []\n  for (const file of files) {\n    const absPath = resolve(rootDir, file)\n    const mod = await loadControllerWithSwc(absPath)\n    for (const exported of Object.values(mod)) {\n      if (typeof exported === 'function' && isControllerClass(exported)) {\n        controllers.push(exported)\n      }\n    }\n  }\n\n  return controllers\n}\n\n/**\n * Check if a function has @Controller metadata.\n * Uses Symbol.for() global registry key — same Symbol instance across\n * module boundaries (SWC-loaded controllers share the global registry).\n */\nexport function isControllerClass(fn: Function): boolean {\n  try {\n    return Reflect.hasMetadata(Symbol.for('theokit:http-decorators:controller-prefix'), fn)\n  } catch {\n    return false\n  }\n}\n\n/**\n * Scan for files matching a controller glob pattern.\n * Extracts the static directory prefix and file suffix from the pattern,\n * then recursively walks the directory.\n */\nfunction scanControllerFiles(rootDir: string, pattern: string): string[] {\n  const parts = pattern.split('/')\n  const dirParts: string[] = []\n  for (const part of parts) {\n    if (part.includes('*')) break\n    dirParts.push(part)\n  }\n  const baseDir = join(rootDir, ...dirParts)\n\n  // Extract file suffix (e.g., '*.controller.ts' → '.controller.ts')\n  const lastPart = parts[parts.length - 1]\n  const suffix = lastPart.replace(/\\*/g, '')\n\n  const files: string[] = []\n  function walk(dir: string) {\n    try {\n      for (const entry of readdirSync(dir, { withFileTypes: true })) {\n        const full = join(dir, entry.name)\n        if (entry.isDirectory()) walk(full)\n        else if (entry.name.endsWith(suffix)) files.push(relative(rootDir, full))\n      }\n    } catch {\n      // Directory doesn't exist\n    }\n  }\n  walk(baseDir)\n  return files\n}\n"],"mappings":"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","names":["MiddlewareConsumerImpl","entries","container","apply","middleware","resolved","map","m","resolveMiddleware","excludePatterns","proxy","exclude","routes","r","push","path","forRoutes","routePatterns","handler","getEntries","prototype","use","instance","resolveOrNew","request","next","middlewareMatchesPath","entry","requestPath","pattern","pathMatches","normPath","replace","normPattern","startsWith","runMiddleware","response","Promise","resolve","readFileSync","writeFileSync","unlinkSync","readdirSync","createRequire","resolve","dirname","join","relative","pathToFileURL","fileURLToPath","getSwcrcTarget","swcrc","jsc","target","consumerSwcrcCache","readConsumerSwcrc","startDir","undefined","dir","root","dirname","candidate","join","raw","readFileSync","parsed","JSON","parse","$schema","parent","swcCoreCache","loadSwcCore","thisDir","fileURLToPath","url","req","createRequire","resolve","resolved","pathToFileURL","href","transformControllerSource","source","filename","loadSwc","swc","HttpDecoratorsConfigError","consumerSwcrc","consumerJsc","code","transformSync","parser","syntax","decorators","transform","legacyDecorator","decoratorMetadata","module","type","sourceMaps","loadControllerWithSwc","absoluteFilePath","tmpPath","replace","writeFileSync","Date","now","unlinkSync","loadControllersFromGlob","rootDir","pattern","files","scanControllerFiles","length","console","warn","controllers","file","absPath","mod","exported","Object","values","isControllerClass","push","fn","Reflect","hasMetadata","Symbol","for","parts","split","dirParts","part","includes","baseDir","lastPart","suffix","walk","entry","readdirSync","withFileTypes","full","name","isDirectory","endsWith","relative"]}

package/dist/{exception-filter-chain-BCSQ3MZ2.js → exception-filter-chain-O45FXGEB.js}

@@ -1,10 +1,10 @@
 import {
   runExceptionFilters
-} from "./chunk-34KOKJ5M.js";
+} from "./chunk-6W4T4DPJ.js";
 import "./chunk-3PGQVQWG.js";
-import "./chunk-LKNI6QEP.js";
+import "./chunk-MQAJWR3K.js";
 import "./chunk-7QVYU63E.js";
 export {
   runExceptionFilters
 };
-//# sourceMappingURL=exception-filter-chain-BCSQ3MZ2.js.map
+//# sourceMappingURL=exception-filter-chain-O45FXGEB.js.map

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { z } from 'zod';
-import { D as DiContainer, M as MiddlewareConsumerImpl } from './middleware-consumer-ljxK1fU_.js';
-export { a as MiddlewareConfigProxy, b as MiddlewareFn, N as NestMiddleware, R as ResolvedMiddleware, m as middlewareMatchesPath, r as resolveOrNew, c as runMiddleware } from './middleware-consumer-ljxK1fU_.js';
+import { D as DiContainer, M as MiddlewareConsumerImpl } from './middleware-consumer-DcaksawH.js';
+export { a as MiddlewareConfigProxy, b as MiddlewareFn, N as NestMiddleware, R as ResolvedMiddleware, m as middlewareMatchesPath, r as resolveOrNew, c as runMiddleware } from './middleware-consumer-DcaksawH.js';
 import { S as ServerHandle } from './types-CGthbcon.js';
 export { ReadinessCheck, TheoApp, TheoAppOptions } from './app.js';
+import * as ReactTypes from 'react';
 
 interface ControllerOptions {
     host?: string;
@@ -354,6 +355,63 @@ declare function joinPath(prefix: string, path: string): string;
  */
 declare function walkControllerMetadata(ControllerClass: Function): WalkResult[];
 
+/**
+ * SWC-powered module loader for controller files with parameter decorators.
+ *
+ * esbuild (used by tsx/Vite SSR) fundamentally cannot parse TypeScript
+ * parameter decorators (`@Body()`, `@Param()`, `@Query()`). This loader
+ * uses @swc/core to transform controller files with full decorator support
+ * (legacyDecorator + decoratorMetadata), then imports them via a temp .mjs
+ * file written in the SAME directory (preserving relative import resolution).
+ *
+ * Pattern: follows Next.js's approach (read tsconfig → configure SWC)
+ * but scoped to the http-decorators package, not the framework core.
+ *
+ * @see references/next.js/packages/next/src/build/swc/options.ts
+ */
+
+interface SwcCore {
+    transformSync: (src: string, opts: unknown) => {
+        code: string;
+    };
+}
+/**
+ * Transform TypeScript controller SOURCE (with parameter decorators) into
+ * ESM code, emitting the `design:paramtypes` / decorator metadata that esbuild
+ * cannot produce. Pure code→code — no file I/O, no module load — so it is
+ * reusable both by {@link loadControllerWithSwc} (which then temp-writes +
+ * imports) and by a build-tool transform hook that returns `{ code }` directly.
+ *
+ * The `@swc/core` loader is injectable (`loadSwc`) for testability; it defaults
+ * to the cached singleton.
+ *
+ * @throws HttpDecoratorsConfigError when @swc/core is unavailable.
+ */
+declare function transformControllerSource(source: string, filename: string, loadSwc?: () => Promise<SwcCore | null>): Promise<string>;
+/**
+ * Load a TypeScript controller file using @swc/core for decorator support.
+ *
+ * Strategy:
+ *   1. Read source .ts file
+ *   2. Transform via {@link transformControllerSource} (legacyDecorator + metadata)
+ *   3. Write temp .mjs in SAME directory (relative imports resolve correctly)
+ *   4. Dynamic import() the .mjs — transitive .ts imports go through
+ *      tsx/Vite's global hook (they don't have parameter decorators)
+ *   5. Cleanup temp file
+ */
+declare function loadControllerWithSwc(absoluteFilePath: string): Promise<Record<string, unknown>>;
+/**
+ * Scan a glob pattern for controller files and load them all via SWC.
+ * Returns an array of controller class constructors found.
+ */
+declare function loadControllersFromGlob(rootDir: string, pattern: string): Promise<Function[]>;
+/**
+ * Check if a function has @Controller metadata.
+ * Uses Symbol.for() global registry key — same Symbol instance across
+ * module boundaries (SWC-loaded controllers share the global registry).
+ */
+declare function isControllerClass(fn: Function): boolean;
+
 interface RouteRegistration {
     verb: HttpVerb;
     fullPath: string;
@@ -377,6 +435,25 @@ interface CreateDecoratorServerOptions {
     container?: DiContainer;
     configure?: (consumer: MiddlewareConsumerImpl) => void;
 }
+/**
+ * A pure Web-Standard controller handler: callable as `(request) => Response | null`
+ * plus a non-executing `matches(method, pathname)` route probe (so a host can gate
+ * — e.g. CSRF — before dispatch runs a handler).
+ */
+interface DecoratorHandler {
+    (request: Request): Promise<Response | null>;
+    /** True when a controller route owns `method` + `pathname` (no handler executed). */
+    matches(method: string, pathname: string): boolean;
+}
+/**
+ * Build a pure Web-Standard request handler from decorated controller classes,
+ * WITHOUT binding a network listener. Returns a {@link DecoratorHandler} whose
+ * call returns `null` when no controller route matched — the caller decides the
+ * miss (a standalone server answers 404; a host middleware falls through to its
+ * own routing). This is the reusable dispatch seam consumed by the framework's
+ * controller dispatch (#122) so it never re-implements match/bind/validate.
+ */
+declare function createDecoratorHandler(controllersOrOpts: Function[] | CreateDecoratorServerOptions): DecoratorHandler;
 declare function createDecoratorServer(controllersOrOpts: Function[] | CreateDecoratorServerOptions): ServerHandle;
 
 /**
@@ -998,10 +1075,10 @@ type InferResponse<D> = D extends {
     response: infer R;
 } ? R : unknown;
 interface TypedClient<M extends RouteMap> {
-    get<P extends string & keyof M>(path: P, opts?: {
+    get<P extends string>(path: P, opts?: {
         query?: Record<string, string>;
         headers?: Record<string, string>;
-    }): Promise<InferResponse<M[`GET ${P}`] extends never ? M[P] : M[`GET ${P}`]>>;
+    }): Promise<InferResponse<M[`GET ${P}`]>>;
     post<P extends string>(path: P, body?: InferBody<M[`POST ${P}`]>, opts?: {
         headers?: Record<string, string>;
     }): Promise<InferResponse<M[`POST ${P}`]>>;
@@ -1091,4 +1168,202 @@ declare function isSafePath(pathname: string): boolean;
  */
 declare function createStaticHandler(options?: StaticOptions): (request: Request) => Promise<Response | null>;
 
-export { All, type ArgumentsHost, BadGatewayException, BadRequestException, Body, CATCH_EXCEPTIONS, CONTROLLER_PREFIX, type CanActivate, Catch, ConflictException, Controller, type ControllerMeta, type ControllerOptions, Delete, DiContainer, type ExceptionFilter, type ExecutionContext, ForbiddenException, GatewayTimeoutException, Get, GoneException, Head, Header, Headers, HostParam, HttpCode, HttpDecoratorsConfigError, HttpException, type HttpExceptionOptions, HttpStatus, type HttpStatusCode, type HttpVerb, HttpVersionNotSupportedException, ImATeapotException, type Interceptor, InternalServerErrorException, Ip, type MetadataKey, MethodNotAllowedException, MiddlewareConsumerImpl, NotAcceptableException, NotFoundException, NotImplementedException, Options, Param, type ParamEntry, type ParamSource, Patch, PayloadTooLargeException, Post, PreconditionFailedException, Put, Query, ROUTE_HEADERS, ROUTE_METHODS, ROUTE_PARAMS, ROUTE_REDIRECT, ROUTE_STATUS, Redirect, type RedirectMeta, Reflector, Req, RequestTimeoutException, Res, type RouteDefinition, type RouteMap, type RouteMethodEntry, type RouteRegistration, ServiceUnavailableException, Session, SetMetadata, SkipThrottle, type StaticOptions, Throttle, type ThrottleOptions, TooManyRequestsException, type TypedClient, TypedClientError, USE_FILTERS, USE_GUARDS, USE_INTERCEPTORS, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, UseFilters, UseGuards, UseInterceptors, type WalkResult, contract, createDecorator, createDecoratorServer, createExecutionContext, createStaticHandler, createTypedClient, getMeta, getMimeType, getThrottleOptions, isSafePath, isThrottleSkipped, joinPath, registerControllers, resolveDtoSchema, runExceptionFilters, runInterceptors, setMeta, walkControllerMetadata };
+interface TheoRequestContext {
+    /** The raw Web Standard Request object. */
+    request: Request;
+    /** URL pathname (e.g., '/api/tasks'). */
+    pathname: string;
+    /** HTTP method (e.g., 'GET', 'POST'). */
+    method: string;
+    /** Route params extracted from URL (e.g., { id: '42' }). */
+    params: Record<string, string>;
+    /** Matched controller or agent class name (if resolved). */
+    handler?: string;
+    /** Request start time (ms). */
+    startedAt: number;
+}
+/**
+ * Get the current request context.
+ *
+ * @throws Error if called outside a request (e.g., at module load time).
+ *
+ * @example
+ * ```typescript
+ * import { getRequestContext } from '@theokit/http'
+ *
+ * class AuthGuard {
+ *   canActivate() {
+ *     const { request } = getRequestContext()
+ *     return request.headers.get('authorization') !== null
+ *   }
+ * }
+ * ```
+ */
+declare function getRequestContext(): TheoRequestContext;
+/**
+ * Try to get the current request context, or null if not in a request.
+ * Useful for code that may run both inside and outside requests.
+ */
+declare function tryGetRequestContext(): TheoRequestContext | null;
+
+/**
+ * Error digestion — converts any thrown value into a stable hash + context.
+ *
+ * Inspired by Next.js `create-error-handler.tsx`. Produces a deterministic
+ * digest ID suitable for logging and client-safe error references without
+ * leaking stack traces in production.
+ *
+ * Uses djb2 hash (sync, no crypto dependency) per ADR D3.
+ */
+interface ErrorContext {
+    route?: string;
+    phase?: 'guard' | 'interceptor' | 'handler' | 'filter' | 'agent';
+    source?: string;
+}
+interface DigestedError {
+    digest: string;
+    message: string;
+    status: number;
+    context: ErrorContext;
+    stack?: string;
+}
+/**
+ * Converts any thrown value into a structured {@link DigestedError}.
+ *
+ * - Sync (never async) — safe to call inside catch blocks.
+ * - Stack trace stripped when `process.env.NODE_ENV === 'production'`.
+ * - Preserves {@link HttpException} status codes.
+ * - Handles non-Error throws (string, number, object).
+ */
+declare function digestError(err: unknown, context?: ErrorContext): DigestedError;
+
+/**
+ * Component tree composition — recursive wrapping of file-convention
+ * components (layout, page, loading, error, not-found) into a React
+ * element tree with Suspense and error boundaries.
+ *
+ * Inspired by Next.js `create-component-tree.tsx`.
+ *
+ * React is loaded via dynamic `import('react')` because it is an
+ * optional peerDep of @theokit/http (EC-2).
+ */
+
+interface RouteTree {
+    layout?: ReactTypes.ComponentType<{
+        children: ReactTypes.ReactNode;
+    }>;
+    page?: ReactTypes.ComponentType;
+    loading?: ReactTypes.ComponentType;
+    error?: ReactTypes.ComponentType;
+    notFound?: ReactTypes.ComponentType;
+    children?: Record<string, RouteTree>;
+}
+/**
+ * Composes a {@link RouteTree} into a nested React element tree.
+ *
+ * Wrapping order (outermost → innermost):
+ *   layout → ErrorBoundary(error) → Suspense(loading) → page
+ *
+ * Returns `null` when no `page` component is found in the tree.
+ *
+ * @param tree - The route tree describing file conventions found.
+ * @returns A React element or `null`.
+ */
+declare function composeComponentTree(tree: RouteTree): Promise<ReactTypes.ReactElement | null>;
+
+/**
+ * Streaming SSR — renders a React element tree to a `ReadableStream<Uint8Array>`.
+ *
+ * Inspired by Next.js `stream-ops.ts`. Uses Web Standard `renderToReadableStream`
+ * (works on Node 18+, Bun, Deno). Falls back to `renderToString` wrapped in a
+ * ReadableStream when `renderToReadableStream` is not available (React 17 — EC-4).
+ *
+ * React is loaded via dynamic `import('react-dom/server')` because react-dom
+ * is an optional peerDep of @theokit/http (ADR D2).
+ */
+
+interface StreamRenderOptions {
+    /** React element to render */
+    root: ReactTypes.ReactElement;
+    /** Whether to wait for all Suspense to resolve (default: false — stream immediately) */
+    waitForAll?: boolean;
+}
+interface StreamRenderResult {
+    /** The HTML stream */
+    stream: ReadableStream<Uint8Array>;
+    /** Promise that resolves when all content has been flushed */
+    allReady: Promise<void>;
+}
+/**
+ * Renders a React element to a `ReadableStream<Uint8Array>` (Web Standard).
+ *
+ * 1. Tries `renderToReadableStream` first (React 18+ — Web Standard API).
+ * 2. Falls back to `renderToString` wrapped in a ReadableStream when
+ *    `renderToReadableStream` is not available (React 17 compat — EC-4).
+ * 3. Prepends `<!DOCTYPE html>` to the stream.
+ *
+ * **EC-7 — Streaming error handling:** In streaming mode, errors thrown inside
+ * Suspense boundaries are caught by React's streaming error handler and result
+ * in a client-side error boundary activation (the shell is already sent). In
+ * string mode (`renderToString`), errors throw synchronously before any bytes
+ * are sent, allowing a full 500 error page. Choose streaming when you want
+ * progressive rendering; choose string mode when you want atomic error handling.
+ */
+declare function renderToStream(options: StreamRenderOptions): Promise<StreamRenderResult>;
+/**
+ * Converts a {@link StreamRenderResult} into a Web Standard `Response`.
+ *
+ * Convenience wrapper for use in request handlers:
+ * ```ts
+ * const result = await renderToStream({ root: <App /> })
+ * return streamToResponse(result)
+ * ```
+ */
+declare function streamToResponse(result: StreamRenderResult): Response;
+
+interface RevalidationSignal {
+    kind: 'tag' | 'path';
+    value: string;
+    timestamp: number;
+}
+/**
+ * Signal that a cache tag should be revalidated.
+ *
+ * Safe to call from any request handler (controller, agent, action).
+ * Signals are accumulated per-request and consumed by the cache engine.
+ *
+ * @example
+ * ```typescript
+ * import { revalidateTag } from '@theokit/http'
+ *
+ * @Post()
+ * async createTask(@Body(schema) body) {
+ *   const task = await db.tasks.create(body)
+ *   revalidateTag('tasks')  // invalidate cached task lists
+ *   return task
+ * }
+ * ```
+ */
+declare function revalidateTag(tag: string): void;
+/**
+ * Signal that a cached path should be revalidated.
+ *
+ * @example
+ * ```typescript
+ * import { revalidatePath } from '@theokit/http'
+ *
+ * @Delete(':id')
+ * async removeTask(@Param('id') id: string) {
+ *   await db.tasks.delete(id)
+ *   revalidatePath('/api/tasks')
+ * }
+ * ```
+ */
+declare function revalidatePath(path: string): void;
+/**
+ * Get all revalidation signals collected during the current request.
+ * Called by the cache engine after the handler completes.
+ */
+declare function getRevalidationSignals(): RevalidationSignal[];
+
+export { All, type ArgumentsHost, BadGatewayException, BadRequestException, Body, CATCH_EXCEPTIONS, CONTROLLER_PREFIX, type CanActivate, Catch, ConflictException, Controller, type ControllerMeta, type ControllerOptions, type DecoratorHandler, Delete, DiContainer, type DigestedError, type ErrorContext, type ExceptionFilter, type ExecutionContext, ForbiddenException, GatewayTimeoutException, Get, GoneException, Head, Header, Headers, HostParam, HttpCode, HttpDecoratorsConfigError, HttpException, type HttpExceptionOptions, HttpStatus, type HttpStatusCode, type HttpVerb, HttpVersionNotSupportedException, ImATeapotException, type Interceptor, InternalServerErrorException, Ip, type MetadataKey, MethodNotAllowedException, MiddlewareConsumerImpl, NotAcceptableException, NotFoundException, NotImplementedException, Options, Param, type ParamEntry, type ParamSource, Patch, PayloadTooLargeException, Post, PreconditionFailedException, Put, Query, ROUTE_HEADERS, ROUTE_METHODS, ROUTE_PARAMS, ROUTE_REDIRECT, ROUTE_STATUS, Redirect, type RedirectMeta, Reflector, Req, RequestTimeoutException, Res, type RevalidationSignal, type RouteDefinition, type RouteMap, type RouteMethodEntry, type RouteRegistration, type RouteTree, ServiceUnavailableException, Session, SetMetadata, SkipThrottle, type StaticOptions, type StreamRenderOptions, type StreamRenderResult, type SwcCore, type TheoRequestContext, Throttle, type ThrottleOptions, TooManyRequestsException, type TypedClient, TypedClientError, USE_FILTERS, USE_GUARDS, USE_INTERCEPTORS, UnauthorizedException, UnprocessableEntityException, UnsupportedMediaTypeException, UseFilters, UseGuards, UseInterceptors, type WalkResult, composeComponentTree, contract, createDecorator, createDecoratorHandler, createDecoratorServer, createExecutionContext, createStaticHandler, createTypedClient, digestError, getMeta, getMimeType, getRequestContext, getRevalidationSignals, getThrottleOptions, isControllerClass, isSafePath, isThrottleSkipped, joinPath, loadControllerWithSwc, loadControllersFromGlob, registerControllers, renderToStream, resolveDtoSchema, revalidatePath, revalidateTag, runExceptionFilters, runInterceptors, setMeta, streamToResponse, transformControllerSource, tryGetRequestContext, walkControllerMetadata };