@forinda/kickjs 8.0.0 → 8.1.0

package/dist/{bootstrap-BG86IC_L.mjs.map → bootstrap-CJkXHDeQ.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"bootstrap-BG86IC_L.mjs","names":["log"],"sources":["../src/http/cluster.ts","../src/http/bootstrap.ts"],"sourcesContent":["import cluster from 'node:cluster'\nimport os from 'node:os'\nimport { createLogger } from '../core'\nimport { reactive, ref } from '../core/reactivity'\n\nconst log = createLogger('Cluster')\n\nexport interface ClusterOptions {\n  /** Number of worker processes (default: os.cpus().length) */\n  workers?: number\n  /** Delay before forcefully killing a worker during shutdown (ms), default: 5000 */\n  gracefulShutdownTimeout?: number\n  /** Delay between worker restarts (ms), default: 1000 */\n  restartDelay?: number\n  /** Max failures in restartWindow before refusing to restart, default: 5 */\n  maxFailures?: number\n  /** Time window for counting failures (ms), default: 30000 */\n  restartWindow?: number\n}\n\n/** Returns true if the current process is the cluster primary */\nexport function isClusterPrimary(): boolean {\n  return cluster.isPrimary\n}\n\n/**\n * Fork worker processes and manage the cluster lifecycle.\n *\n * The primary process forks `workers` child processes. Each worker\n * shares the same port via Node's built-in `cluster` module (OS\n * round-robin load balancing).\n *\n * Features:\n * - Graceful shutdown with timeout fallback to forceful kill\n * - Auto-restart dead workers (respects voluntary disconnects)\n * - Startup timeout detection (stuck workers)\n * - Crash loop prevention (backoff on rapid failures)\n * - Comprehensive lifecycle logging\n */\nexport function setupClusterPrimary(opts: ClusterOptions): void {\n  const numWorkers = opts.workers ?? os.cpus().length\n  const gracefulTimeout = opts.gracefulShutdownTimeout ?? 5000\n  const restartDelay = opts.restartDelay ?? 1000\n  const maxFailures = opts.maxFailures ?? 5\n  const restartWindow = opts.restartWindow ?? 30000\n\n  const startupTimeouts = new Map<number, NodeJS.Timeout>()\n  const state = reactive({\n    failureTimestamps: [] as number[],\n    shuttingDown: false,\n  })\n  const activeWorkers = ref(0)\n\n  log.info(`Primary ${process.pid} starting ${numWorkers} worker(s)`)\n\n  // Initial fork\n  for (let i = 0; i < numWorkers; i++) {\n    cluster.fork()\n  }\n\n  // Detect stuck workers (no 'listening' event within timeout)\n  cluster.on('fork', (worker) => {\n    const timeout = setTimeout(() => {\n      log.error(`Worker ${worker.process.pid} did not respond within 10s, killing...`)\n      worker.kill()\n    }, 10000)\n\n    startupTimeouts.set(worker.id, timeout)\n    activeWorkers.value++\n    log.debug(`Worker ${worker.process.pid} forked (id=${worker.id})`)\n  })\n\n  // Clear startup timeout when worker is ready\n  cluster.on('listening', (worker, address) => {\n    const timeout = startupTimeouts.get(worker.id)\n    if (timeout) {\n      clearTimeout(timeout)\n      startupTimeouts.delete(worker.id)\n    }\n    log.info(`Worker ${worker.process.pid} listening on ${address.address}:${address.port}`)\n  })\n\n  // Log when worker comes online\n  cluster.on('online', (worker) => {\n    log.debug(`Worker ${worker.process.pid} online (id=${worker.id})`)\n  })\n\n  // Auto-restart dead workers (unless intentionally disconnected)\n  cluster.on('exit', (worker, code, signal) => {\n    // Clear startup timeout if still pending\n    const timeout = startupTimeouts.get(worker.id)\n    if (timeout) {\n      clearTimeout(timeout)\n      startupTimeouts.delete(worker.id)\n    }\n\n    // Don't restart if worker was intentionally disconnected\n    activeWorkers.value--\n\n    if (worker.exitedAfterDisconnect) {\n      log.info(`Worker ${worker.process.pid} exited gracefully (id=${worker.id})`)\n      return\n    }\n\n    // Track crash history globally (worker IDs change on restart)\n    const now = Date.now()\n    // Remove timestamps outside the window, then add the current failure\n    while (\n      state.failureTimestamps.length > 0 &&\n      now - state.failureTimestamps[0] >= restartWindow\n    ) {\n      state.failureTimestamps.shift()\n    }\n    state.failureTimestamps.push(now)\n\n    // Prevent restart loops\n    if (state.failureTimestamps.length > maxFailures) {\n      log.error(\n        `${state.failureTimestamps.length} worker failures in ${restartWindow}ms, giving up`,\n      )\n      // Optionally exit the primary if too many workers are crashing\n      if (activeWorkers.value === 0) {\n        log.error('All workers have crashed, exiting primary')\n        process.exit(1)\n      }\n      return\n    }\n\n    log.warn(\n      `Worker ${worker.process.pid} died (code=${code}, signal=${signal}), restarting in ${restartDelay}ms... (failures: ${state.failureTimestamps.length}/${maxFailures})`,\n    )\n\n    setTimeout(() => {\n      // Only restart if we still need more workers\n      if (activeWorkers.value < numWorkers) {\n        cluster.fork()\n      }\n    }, restartDelay)\n  })\n\n  // Log when worker disconnects (can happen before exit)\n  cluster.on('disconnect', (worker) => {\n    log.debug(`Worker ${worker.process.pid} disconnected (id=${worker.id})`)\n  })\n\n  // Forward shutdown signals to workers (disconnect so exitedAfterDisconnect is set)\n  for (const signal of ['SIGTERM', 'SIGINT'] as const) {\n    process.on(signal, () => {\n      if (state.shuttingDown) return\n      state.shuttingDown = true\n      log.info(`Primary received ${signal}, disconnecting workers...`)\n      cluster.disconnect(() => {\n        log.info('All workers disconnected, exiting primary')\n        process.exit(0)\n      })\n      // Force kill after graceful timeout\n      setTimeout(() => {\n        log.warn('Graceful shutdown timed out, forcing exit')\n        process.exit(1)\n      }, gracefulTimeout).unref()\n    })\n  }\n}\n","import cluster from 'node:cluster'\nimport { createLogger, Container } from '../core'\nimport { reloadEnv } from '../config/env'\nimport { Application, type ApplicationOptions } from './application'\nimport { setupClusterPrimary, type ClusterOptions } from './cluster'\n\n/** Reload env from .env file (HMR rebuild) — config now lives in-tree. */\nfunction tryReloadEnv(): void {\n  try {\n    reloadEnv()\n  } catch {\n    // Best-effort: never crash bootstrap because env reload failed.\n  }\n}\n\nconst log = createLogger('Process')\n\n/**\n * Bootstrap a KickJS application.\n *\n * Creates the Express app, registers modules and adapters, and starts\n * the HTTP server. In dev mode (`kick dev`), the Vite plugin manages\n * the server and HMR — source changes are picked up instantly without\n * losing database connections or WebSocket state.\n *\n * @returns The {@link Application} instance.\n *\n * @example\n * ```ts\n * // src/index.ts\n * import 'reflect-metadata'\n * import { bootstrap } from '@forinda/kickjs'\n * import { modules } from './modules'\n *\n * export const app = await bootstrap({ modules })\n * ```\n */\nexport async function bootstrap(options: ApplicationOptions): Promise<Application> {\n  // ── Cluster mode ─────────────────────────────────────────────────────\n  // In cluster mode the primary process forks workers and never runs the\n  // Express application itself.  Only workers proceed past this block.\n  // Cluster is disabled in Vite dev mode — Vite owns the HTTP server and\n  // forked workers would each create their own Vite instance on separate ports.\n  const isViteDev = !!(globalThis as any).__kickjs_httpServer\n  if (options.cluster && isViteDev) {\n    log.warn(\n      'Cluster mode is ignored in dev — Vite owns the server. Cluster applies in production (kick start).',\n    )\n  }\n  if (options.cluster && cluster.isPrimary && !isViteDev) {\n    const clusterOpts: ClusterOptions = typeof options.cluster === 'object' ? options.cluster : {}\n    setupClusterPrimary(clusterOpts)\n\n    // Return a placeholder — the primary never serves HTTP traffic.\n    // The Application is created only so callers get a valid reference.\n    return new Application(options)\n  }\n\n  // Internal: globalThis stores the app instance and Vite's HTTP server\n  // reference across HMR rebuilds. When __kickjs_httpServer is set, the\n  // Vite plugin owns the port and bootstrap() skips server creation.\n  // On subsequent calls (HMR), the Express handler is swapped without\n  // restarting the server — preserving DB connections and port bindings.\n  const g = globalThis as any\n\n  // ── Global error handlers + signal hooks ─────────────────────────────\n  // `processHooks` controls whether KickJS registers its own\n  // process-level handlers. Defaults to `'auto'` — register everything.\n  // Adopters that bring their own observability stack (OpenTelemetry SDK,\n  // Sentry, custom shutdown choreographer) often register their own\n  // SIGINT/SIGTERM handlers and need to opt out of ours so the two don't\n  // race to call `process.exit(0)`. Three modes:\n  //   - 'auto' (default): register uncaughtException/unhandledRejection\n  //     loggers + SIGINT/SIGTERM → `app.shutdown()` → `process.exit(0)`.\n  //   - 'errors-only': register the error loggers; skip signal handlers.\n  //     Use this when you have your own shutdown choreographer that calls\n  //     `app.shutdown()` itself.\n  //   - 'manual': skip everything. Adopter is responsible for both error\n  //     logging and signal-driven shutdown.\n  const processHooks = options.processHooks ?? 'auto'\n\n  if (!g.__kickBootstrapped) {\n    if (processHooks !== 'manual') {\n      process.on('uncaughtException', (err) => {\n        log.error(err, 'Uncaught exception')\n      })\n\n      process.on('unhandledRejection', (reason) => {\n        log.error(reason as any, 'Unhandled rejection')\n      })\n    }\n\n    if (processHooks === 'auto' && !g.__kickjs_httpServer) {\n      for (const signal of ['SIGINT', 'SIGTERM'] as const) {\n        process.on(signal, async () => {\n          log.info(`Received ${signal}, shutting down...`)\n          if (g.__app) await g.__app.shutdown()\n          process.exit(0)\n        })\n      }\n    }\n\n    g.__kickBootstrapped = true\n  }\n\n  // ── HMR rebuild ──────────────────────────────────────────────────────\n  if (g.__app) {\n    log.debug('HMR rebuild triggered')\n\n    // Tear the PREVIOUS app down before replacing it. Without this the old\n    // Application was dropped on the floor still running: its adapters kept\n    // their sockets and consumers open, so every save added another set.\n    //\n    // Observed in the wild as one process holding several consumer-group\n    // members — on a single-partition topic only one can hold the assignment,\n    // and it was a leaked consumer no longer wired to anything, so jobs\n    // stopped being processed. A second socket.io server on the same HTTP\n    // server crashed `handleUpgrade()` the same way.\n    //\n    // `closeServer: false` is load-bearing: the dev HTTP server is shared\n    // across rebuilds, so a full shutdown would close the listening socket and\n    // kill HMR on the first save.\n    //\n    // Failures are logged, not thrown — one broken adapter must not leave the\n    // dev server wedged with no app at all.\n    try {\n      await g.__app.shutdown({ closeServer: false })\n    } catch (err) {\n      log.error(err as Error, 'HMR teardown of the previous app failed')\n    }\n\n    tryReloadEnv()\n    Container.reset()\n\n    const freshApp = new Application(options)\n    g.__app = freshApp\n    g.__kickjs_container = freshApp.getContainer()\n\n    await freshApp.start()\n    log.debug('HMR rebuild complete')\n    return freshApp\n  }\n\n  // ── First boot ───────────────────────────────────────────────────────\n  const app = new Application(options)\n  g.__app = app\n  g.__kickjs_container = app.getContainer()\n\n  if (process.env.KICK_TINKER) {\n    await app.registerOnly()\n    return app\n  }\n\n  await app.start()\n\n  return app\n}\n"],"mappings":"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"}
+{"version":3,"file":"bootstrap-CJkXHDeQ.mjs","names":["log"],"sources":["../src/http/cluster.ts","../src/http/bootstrap.ts"],"sourcesContent":["import cluster from 'node:cluster'\nimport os from 'node:os'\nimport { createLogger } from '../core'\nimport { reactive, ref } from '../core/reactivity'\n\nconst log = createLogger('Cluster')\n\nexport interface ClusterOptions {\n  /** Number of worker processes (default: os.cpus().length) */\n  workers?: number\n  /** Delay before forcefully killing a worker during shutdown (ms), default: 5000 */\n  gracefulShutdownTimeout?: number\n  /** Delay between worker restarts (ms), default: 1000 */\n  restartDelay?: number\n  /** Max failures in restartWindow before refusing to restart, default: 5 */\n  maxFailures?: number\n  /** Time window for counting failures (ms), default: 30000 */\n  restartWindow?: number\n}\n\n/** Returns true if the current process is the cluster primary */\nexport function isClusterPrimary(): boolean {\n  return cluster.isPrimary\n}\n\n/**\n * Fork worker processes and manage the cluster lifecycle.\n *\n * The primary process forks `workers` child processes. Each worker\n * shares the same port via Node's built-in `cluster` module (OS\n * round-robin load balancing).\n *\n * Features:\n * - Graceful shutdown with timeout fallback to forceful kill\n * - Auto-restart dead workers (respects voluntary disconnects)\n * - Startup timeout detection (stuck workers)\n * - Crash loop prevention (backoff on rapid failures)\n * - Comprehensive lifecycle logging\n */\nexport function setupClusterPrimary(opts: ClusterOptions): void {\n  const numWorkers = opts.workers ?? os.cpus().length\n  const gracefulTimeout = opts.gracefulShutdownTimeout ?? 5000\n  const restartDelay = opts.restartDelay ?? 1000\n  const maxFailures = opts.maxFailures ?? 5\n  const restartWindow = opts.restartWindow ?? 30000\n\n  const startupTimeouts = new Map<number, NodeJS.Timeout>()\n  const state = reactive({\n    failureTimestamps: [] as number[],\n    shuttingDown: false,\n  })\n  const activeWorkers = ref(0)\n\n  log.info(`Primary ${process.pid} starting ${numWorkers} worker(s)`)\n\n  // Initial fork\n  for (let i = 0; i < numWorkers; i++) {\n    cluster.fork()\n  }\n\n  // Detect stuck workers (no 'listening' event within timeout)\n  cluster.on('fork', (worker) => {\n    const timeout = setTimeout(() => {\n      log.error(`Worker ${worker.process.pid} did not respond within 10s, killing...`)\n      worker.kill()\n    }, 10000)\n\n    startupTimeouts.set(worker.id, timeout)\n    activeWorkers.value++\n    log.debug(`Worker ${worker.process.pid} forked (id=${worker.id})`)\n  })\n\n  // Clear startup timeout when worker is ready\n  cluster.on('listening', (worker, address) => {\n    const timeout = startupTimeouts.get(worker.id)\n    if (timeout) {\n      clearTimeout(timeout)\n      startupTimeouts.delete(worker.id)\n    }\n    log.info(`Worker ${worker.process.pid} listening on ${address.address}:${address.port}`)\n  })\n\n  // Log when worker comes online\n  cluster.on('online', (worker) => {\n    log.debug(`Worker ${worker.process.pid} online (id=${worker.id})`)\n  })\n\n  // Auto-restart dead workers (unless intentionally disconnected)\n  cluster.on('exit', (worker, code, signal) => {\n    // Clear startup timeout if still pending\n    const timeout = startupTimeouts.get(worker.id)\n    if (timeout) {\n      clearTimeout(timeout)\n      startupTimeouts.delete(worker.id)\n    }\n\n    // Don't restart if worker was intentionally disconnected\n    activeWorkers.value--\n\n    if (worker.exitedAfterDisconnect) {\n      log.info(`Worker ${worker.process.pid} exited gracefully (id=${worker.id})`)\n      return\n    }\n\n    // Track crash history globally (worker IDs change on restart)\n    const now = Date.now()\n    // Remove timestamps outside the window, then add the current failure\n    while (\n      state.failureTimestamps.length > 0 &&\n      now - state.failureTimestamps[0] >= restartWindow\n    ) {\n      state.failureTimestamps.shift()\n    }\n    state.failureTimestamps.push(now)\n\n    // Prevent restart loops\n    if (state.failureTimestamps.length > maxFailures) {\n      log.error(\n        `${state.failureTimestamps.length} worker failures in ${restartWindow}ms, giving up`,\n      )\n      // Optionally exit the primary if too many workers are crashing\n      if (activeWorkers.value === 0) {\n        log.error('All workers have crashed, exiting primary')\n        process.exit(1)\n      }\n      return\n    }\n\n    log.warn(\n      `Worker ${worker.process.pid} died (code=${code}, signal=${signal}), restarting in ${restartDelay}ms... (failures: ${state.failureTimestamps.length}/${maxFailures})`,\n    )\n\n    setTimeout(() => {\n      // Only restart if we still need more workers\n      if (activeWorkers.value < numWorkers) {\n        cluster.fork()\n      }\n    }, restartDelay)\n  })\n\n  // Log when worker disconnects (can happen before exit)\n  cluster.on('disconnect', (worker) => {\n    log.debug(`Worker ${worker.process.pid} disconnected (id=${worker.id})`)\n  })\n\n  // Forward shutdown signals to workers (disconnect so exitedAfterDisconnect is set)\n  for (const signal of ['SIGTERM', 'SIGINT'] as const) {\n    process.on(signal, () => {\n      if (state.shuttingDown) return\n      state.shuttingDown = true\n      log.info(`Primary received ${signal}, disconnecting workers...`)\n      cluster.disconnect(() => {\n        log.info('All workers disconnected, exiting primary')\n        process.exit(0)\n      })\n      // Force kill after graceful timeout\n      setTimeout(() => {\n        log.warn('Graceful shutdown timed out, forcing exit')\n        process.exit(1)\n      }, gracefulTimeout).unref()\n    })\n  }\n}\n","import cluster from 'node:cluster'\nimport { createLogger, Container } from '../core'\nimport { reloadEnv } from '../config/env'\nimport { Application, type ApplicationOptions } from './application'\nimport { setupClusterPrimary, type ClusterOptions } from './cluster'\n\n/** Reload env from .env file (HMR rebuild) — config now lives in-tree. */\nfunction tryReloadEnv(): void {\n  try {\n    reloadEnv()\n  } catch {\n    // Best-effort: never crash bootstrap because env reload failed.\n  }\n}\n\nconst log = createLogger('Process')\n\n/**\n * Bootstrap a KickJS application.\n *\n * Creates the Express app, registers modules and adapters, and starts\n * the HTTP server. In dev mode (`kick dev`), the Vite plugin manages\n * the server and HMR — source changes are picked up instantly without\n * losing database connections or WebSocket state.\n *\n * @returns The {@link Application} instance.\n *\n * @example\n * ```ts\n * // src/index.ts\n * import 'reflect-metadata'\n * import { bootstrap } from '@forinda/kickjs'\n * import { modules } from './modules'\n *\n * export const app = await bootstrap({ modules })\n * ```\n */\nexport async function bootstrap(options: ApplicationOptions): Promise<Application> {\n  // ── Cluster mode ─────────────────────────────────────────────────────\n  // In cluster mode the primary process forks workers and never runs the\n  // Express application itself.  Only workers proceed past this block.\n  // Cluster is disabled in Vite dev mode — Vite owns the HTTP server and\n  // forked workers would each create their own Vite instance on separate ports.\n  const isViteDev = !!(globalThis as any).__kickjs_httpServer\n  if (options.cluster && isViteDev) {\n    log.warn(\n      'Cluster mode is ignored in dev — Vite owns the server. Cluster applies in production (kick start).',\n    )\n  }\n  if (options.cluster && cluster.isPrimary && !isViteDev) {\n    const clusterOpts: ClusterOptions = typeof options.cluster === 'object' ? options.cluster : {}\n    setupClusterPrimary(clusterOpts)\n\n    // Return a placeholder — the primary never serves HTTP traffic.\n    // The Application is created only so callers get a valid reference.\n    return new Application(options)\n  }\n\n  // Internal: globalThis stores the app instance and Vite's HTTP server\n  // reference across HMR rebuilds. When __kickjs_httpServer is set, the\n  // Vite plugin owns the port and bootstrap() skips server creation.\n  // On subsequent calls (HMR), the Express handler is swapped without\n  // restarting the server — preserving DB connections and port bindings.\n  const g = globalThis as any\n\n  // ── Global error handlers + signal hooks ─────────────────────────────\n  // `processHooks` controls whether KickJS registers its own\n  // process-level handlers. Defaults to `'auto'` — register everything.\n  // Adopters that bring their own observability stack (OpenTelemetry SDK,\n  // Sentry, custom shutdown choreographer) often register their own\n  // SIGINT/SIGTERM handlers and need to opt out of ours so the two don't\n  // race to call `process.exit(0)`. Three modes:\n  //   - 'auto' (default): register uncaughtException/unhandledRejection\n  //     loggers + SIGINT/SIGTERM → `app.shutdown()` → `process.exit(0)`.\n  //   - 'errors-only': register the error loggers; skip signal handlers.\n  //     Use this when you have your own shutdown choreographer that calls\n  //     `app.shutdown()` itself.\n  //   - 'manual': skip everything. Adopter is responsible for both error\n  //     logging and signal-driven shutdown.\n  const processHooks = options.processHooks ?? 'auto'\n\n  if (!g.__kickBootstrapped) {\n    if (processHooks !== 'manual') {\n      process.on('uncaughtException', (err) => {\n        log.error(err, 'Uncaught exception')\n      })\n\n      process.on('unhandledRejection', (reason) => {\n        log.error(reason as any, 'Unhandled rejection')\n      })\n    }\n\n    if (processHooks === 'auto' && !g.__kickjs_httpServer) {\n      for (const signal of ['SIGINT', 'SIGTERM'] as const) {\n        process.on(signal, async () => {\n          log.info(`Received ${signal}, shutting down...`)\n          if (g.__app) await g.__app.shutdown()\n          process.exit(0)\n        })\n      }\n    }\n\n    g.__kickBootstrapped = true\n  }\n\n  // ── HMR rebuild ──────────────────────────────────────────────────────\n  if (g.__app) {\n    log.debug('HMR rebuild triggered')\n\n    // Tear the PREVIOUS app down before replacing it. Without this the old\n    // Application was dropped on the floor still running: its adapters kept\n    // their sockets and consumers open, so every save added another set.\n    //\n    // Observed in the wild as one process holding several consumer-group\n    // members — on a single-partition topic only one can hold the assignment,\n    // and it was a leaked consumer no longer wired to anything, so jobs\n    // stopped being processed. A second socket.io server on the same HTTP\n    // server crashed `handleUpgrade()` the same way.\n    //\n    // `closeServer: false` is load-bearing: the dev HTTP server is shared\n    // across rebuilds, so a full shutdown would close the listening socket and\n    // kill HMR on the first save.\n    //\n    // Failures are logged, not thrown — one broken adapter must not leave the\n    // dev server wedged with no app at all.\n    try {\n      await g.__app.shutdown({ closeServer: false })\n    } catch (err) {\n      log.error(err as Error, 'HMR teardown of the previous app failed')\n    }\n\n    tryReloadEnv()\n    Container.reset()\n\n    const freshApp = new Application(options)\n    g.__app = freshApp\n    g.__kickjs_container = freshApp.getContainer()\n\n    await freshApp.start()\n    log.debug('HMR rebuild complete')\n    return freshApp\n  }\n\n  // ── First boot ───────────────────────────────────────────────────────\n  const app = new Application(options)\n  g.__app = app\n  g.__kickjs_container = app.getContainer()\n\n  if (process.env.KICK_TINKER) {\n    await app.registerOnly()\n    return app\n  }\n\n  await app.start()\n\n  return app\n}\n"],"mappings":";;;;;;;;;;+UAKA,MAAMA,MAAM,aAAa,SAAS,EAgBlC,SAAgB,kBAA4B,CAC1C,OAAO,QAAQ,SACjB,CAgBA,SAAgB,oBAAoB,KAA4B,CAC9D,IAAM,WAAa,KAAK,SAAW,GAAG,KAAK,CAAC,CAAC,OACvC,gBAAkB,KAAK,yBAA2B,IAClD,aAAe,KAAK,cAAgB,IACpC,YAAc,KAAK,aAAe,EAClC,cAAgB,KAAK,eAAiB,IAEtC,gBAAkB,IAAI,IACtB,MAAQ,SAAS,CACrB,kBAAmB,CAAC,EACpB,aAAc,EAChB,CAAC,EACK,cAAgB,IAAI,CAAC,EAE3B,MAAI,KAAK,WAAW,QAAQ,IAAI,YAAY,WAAW,WAAW,EAGlE,IAAK,IAAI,EAAI,EAAG,EAAI,WAAY,IAC9B,QAAQ,KAAK,EAIf,QAAQ,GAAG,OAAS,QAAW,CAC7B,IAAM,QAAU,eAAiB,CAC/B,MAAI,MAAM,UAAU,OAAO,QAAQ,IAAI,wCAAwC,EAC/E,OAAO,KAAK,CACd,EAAG,GAAK,EAER,gBAAgB,IAAI,OAAO,GAAI,OAAO,EACtC,cAAc,QACd,MAAI,MAAM,UAAU,OAAO,QAAQ,IAAI,cAAc,OAAO,GAAG,EAAE,CACnE,CAAC,EAGD,QAAQ,GAAG,aAAc,OAAQ,UAAY,CAC3C,IAAM,QAAU,gBAAgB,IAAI,OAAO,EAAE,EACzC,UACF,aAAa,OAAO,EACpB,gBAAgB,OAAO,OAAO,EAAE,GAElC,MAAI,KAAK,UAAU,OAAO,QAAQ,IAAI,gBAAgB,QAAQ,QAAQ,GAAG,QAAQ,MAAM,CACzF,CAAC,EAGD,QAAQ,GAAG,SAAW,QAAW,CAC/B,MAAI,MAAM,UAAU,OAAO,QAAQ,IAAI,cAAc,OAAO,GAAG,EAAE,CACnE,CAAC,EAGD,QAAQ,GAAG,QAAS,OAAQ,KAAM,SAAW,CAE3C,IAAM,QAAU,gBAAgB,IAAI,OAAO,EAAE,EAS7C,GARI,UACF,aAAa,OAAO,EACpB,gBAAgB,OAAO,OAAO,EAAE,GAIlC,cAAc,QAEV,OAAO,sBAAuB,CAChC,MAAI,KAAK,UAAU,OAAO,QAAQ,IAAI,yBAAyB,OAAO,GAAG,EAAE,EAC3E,MACF,CAGA,IAAM,IAAM,KAAK,IAAI,EAErB,KACE,MAAM,kBAAkB,OAAS,GACjC,IAAM,MAAM,kBAAkB,IAAM,eAEpC,MAAM,kBAAkB,MAAM,EAKhC,GAHA,MAAM,kBAAkB,KAAK,GAAG,EAG5B,MAAM,kBAAkB,OAAS,YAAa,CAChD,MAAI,MACF,GAAG,MAAM,kBAAkB,OAAO,sBAAsB,cAAc,cACxE,EAEI,cAAc,QAAU,IAC1B,MAAI,MAAM,2CAA2C,EACrD,QAAQ,KAAK,CAAC,GAEhB,MACF,CAEA,MAAI,KACF,UAAU,OAAO,QAAQ,IAAI,cAAc,KAAK,WAAW,OAAO,mBAAmB,aAAa,mBAAmB,MAAM,kBAAkB,OAAO,GAAG,YAAY,EACrK,EAEA,eAAiB,CAEX,cAAc,MAAQ,YACxB,QAAQ,KAAK,CAEjB,EAAG,YAAY,CACjB,CAAC,EAGD,QAAQ,GAAG,aAAe,QAAW,CACnC,MAAI,MAAM,UAAU,OAAO,QAAQ,IAAI,oBAAoB,OAAO,GAAG,EAAE,CACzE,CAAC,EAGD,IAAK,IAAM,SAAU,CAAC,UAAW,QAAQ,EACvC,QAAQ,GAAG,WAAc,CACnB,MAAM,eACV,MAAM,aAAe,GACrB,MAAI,KAAK,oBAAoB,OAAO,2BAA2B,EAC/D,QAAQ,eAAiB,CACvB,MAAI,KAAK,2CAA2C,EACpD,QAAQ,KAAK,CAAC,CAChB,CAAC,EAED,eAAiB,CACf,MAAI,KAAK,2CAA2C,EACpD,QAAQ,KAAK,CAAC,CAChB,EAAG,eAAe,CAAC,CAAC,MAAM,EAC5B,CAAC,CAEL,CC3JA,SAAS,cAAqB,CAC5B,GAAI,CACF,UAAU,CACZ,MAAQ,CAER,CACF,CAEA,MAAM,IAAM,aAAa,SAAS,EAsBlC,eAAsB,UAAU,QAAmD,CAMjF,IAAM,UAAY,CAAC,CAAE,WAAmB,oBAMxC,GALI,QAAQ,SAAW,WACrB,IAAI,KACF,oGACF,EAEE,QAAQ,SAAW,QAAQ,WAAa,CAAC,UAM3C,OAJA,oBADoC,OAAO,QAAQ,SAAY,SAAW,QAAQ,QAAU,CAAC,CAC9D,EAIxB,IAAI,YAAY,OAAO,EAQhC,IAAM,EAAI,WAgBJ,aAAe,QAAQ,cAAgB,OAE7C,GAAI,CAAC,EAAE,mBAAoB,CAWzB,GAVI,eAAiB,WACnB,QAAQ,GAAG,oBAAsB,KAAQ,CACvC,IAAI,MAAM,IAAK,oBAAoB,CACrC,CAAC,EAED,QAAQ,GAAG,qBAAuB,QAAW,CAC3C,IAAI,MAAM,OAAe,qBAAqB,CAChD,CAAC,GAGC,eAAiB,QAAU,CAAC,EAAE,oBAChC,IAAK,IAAM,SAAU,CAAC,SAAU,SAAS,EACvC,QAAQ,GAAG,OAAQ,SAAY,CAC7B,IAAI,KAAK,YAAY,OAAO,mBAAmB,EAC3C,EAAE,OAAO,MAAM,EAAE,MAAM,SAAS,EACpC,QAAQ,KAAK,CAAC,CAChB,CAAC,EAIL,EAAE,mBAAqB,EACzB,CAGA,GAAI,EAAE,MAAO,CACX,IAAI,MAAM,uBAAuB,EAkBjC,GAAI,CACF,MAAM,EAAE,MAAM,SAAS,CAAE,YAAa,EAAM,CAAC,CAC/C,OAAS,IAAK,CACZ,IAAI,MAAM,IAAc,yCAAyC,CACnE,CAEA,aAAa,EACb,UAAU,MAAM,EAEhB,IAAM,SAAW,IAAI,YAAY,OAAO,EAMxC,MALA,GAAE,MAAQ,SACV,EAAE,mBAAqB,SAAS,aAAa,EAE7C,MAAM,SAAS,MAAM,EACrB,IAAI,MAAM,sBAAsB,EACzB,QACT,CAGA,IAAM,IAAM,IAAI,YAAY,OAAO,EAWnC,MAVA,GAAE,MAAQ,IACV,EAAE,mBAAqB,IAAI,aAAa,EAEpC,QAAQ,IAAI,aACd,MAAM,IAAI,aAAa,EAChB,MAGT,MAAM,IAAI,MAAM,EAET,IACT"}

package/dist/{client-ip-C909xeVL.mjs → client-ip-D_XUCo45.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v8.0.0
+ * @forinda/kickjs v8.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -9,4 +9,4 @@
  * @license MIT
  */
 function firstHop(value){return typeof value==`string`&&value.length>0?value.split(`,`)[0].trim():void 0}function headerValue(headers,name){if(headers)return typeof headers.get==`function`?headers.get(name):headers[name]}function resolveClientIp(req){if(typeof req.ip==`string`&&req.ip.length>0)return req.ip;let socketAddress=req.socket?.remoteAddress;if(socketAddress)return socketAddress;let h=req.headers;return firstHop(headerValue(h,`cf-connecting-ip`))??firstHop(headerValue(h,`x-forwarded-for`))??firstHop(headerValue(h,`x-real-ip`))}function resolvePathname(req){if(typeof req.path==`string`&&req.path.length>0)return req.path;let url=req.url;if(!url)return`/`;if(/^[a-z][a-z0-9+.-]*:\/\//i.test(url))try{return new URL(url).pathname||`/`}catch{return`/`}let q=url.indexOf(`?`);return(q===-1?url:url.slice(0,q))||`/`}export{resolvePathname as n,resolveClientIp as t};
-//# sourceMappingURL=client-ip-C909xeVL.mjs.map
+//# sourceMappingURL=client-ip-D_XUCo45.mjs.map

package/dist/{client-ip-C909xeVL.mjs.map → client-ip-D_XUCo45.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"client-ip-C909xeVL.mjs","names":[],"sources":["../src/http/client-ip.ts"],"sourcesContent":["/**\n * Client address + pathname resolution shared by everything that runs as\n * connect-style middleware.\n *\n * Fastify and h3 hand middleware the RAW node request, so the Express\n * conveniences (`req.ip`, `req.path`, `req.originalUrl`) are `undefined`\n * there. Reading them directly produced two live bugs:\n *\n *   rate-limit → every caller keyed as the `'127.0.0.1'` fallback, i.e. ONE\n *                shared bucket, so a single client could exhaust the limit\n *                for everyone\n *   csrf       → `ignorePaths` never matched, so configured exemptions were\n *                silently dead\n *\n * Edge-safe: no node imports.\n */\n\n/** The request members these helpers read, from node's shape rather than Express's. */\nexport interface ClientRequestLike {\n  url?: string\n  /** Express-only convenience. */\n  path?: string\n  /** Express-only; the full path before router mounting rewrote `url`. */\n  originalUrl?: string\n  /** Express and Fastify compute this from their trust-proxy settings. */\n  ip?: unknown\n  /**\n   * A plain object on every path the framework currently takes — `WebRequestShim`\n   * normalizes a WHATWG `Headers` before the context is built. A `Headers`\n   * instance is accepted defensively: it is not index-accessible, so if one ever\n   * did arrive, every lookup would return `undefined` SILENTLY and drop each\n   * caller into one shared rate-limit bucket.\n   */\n  headers?: Record<string, string | string[] | undefined> | Headers\n  socket?: { remoteAddress?: string }\n}\n\n/** First entry of a possibly comma-separated header value. */\nfunction firstHop(value: unknown): string | undefined {\n  return typeof value === 'string' && value.length > 0 ? value.split(',')[0]!.trim() : undefined\n}\n\n/** Read one header from either a plain object or a WHATWG `Headers`. */\nfunction headerValue(\n  headers: Record<string, string | string[] | undefined> | Headers | undefined,\n  name: string,\n): unknown {\n  if (!headers) return undefined\n  // `Headers` has no index access, so `headers[name]` silently yields\n  // `undefined` rather than the value.\n  if (typeof (headers as Headers).get === 'function') return (headers as Headers).get(name)\n  return (headers as Record<string, string | string[] | undefined>)[name]\n}\n\n/**\n * The client's IP address, or `undefined` when it cannot be determined.\n *\n * Prefers the address the runtime computed — Express derives `req.ip` from\n * `trust proxy`, Fastify from `trustProxy` — because raw forwarded headers are\n * client-SPOOFABLE wherever nothing normalizes them. h3 takes the same stance:\n * its `getRequestIP` only consults `x-forwarded-for` when explicitly opted in.\n *\n * Order is `req.ip` → `socket.remoteAddress` → forwarded headers. The socket\n * comes BEFORE the headers deliberately: it cannot be spoofed, whereas a direct\n * client can vary `x-forwarded-for` per request to get a fresh rate-limit\n * bucket each time. Headers are consulted only where there is no socket — the\n * web/edge entry, where the platform terminates the connection.\n */\nexport function resolveClientIp(req: ClientRequestLike): string | undefined {\n  // 1. What the runtime computed. Express derives `req.ip` from `trust proxy`,\n  //    Fastify from `trustProxy` — a value vetted against a CONFIGURED proxy,\n  //    which is the only reason to believe a forwarded header at all.\n  if (typeof req.ip === 'string' && req.ip.length > 0) return req.ip\n\n  // 2. The socket. Unspoofable, and present on every node runtime.\n  //\n  //    This MUST precede the headers. A raw Fastify / h3 request has no\n  //    `req.ip`, so consulting `x-forwarded-for` first let a DIRECT client send\n  //    a different value per request and land in a fresh rate-limit bucket each\n  //    time — evading the limit entirely. Behind a real proxy the socket is the\n  //    proxy's address, which buckets clients together; the fix for that is to\n  //    configure the runtime's trust-proxy setting so step 1 answers, not to\n  //    trust an unverified header here.\n  const socketAddress = req.socket?.remoteAddress\n  if (socketAddress) return socketAddress\n\n  // 3. Headers, only where there is no socket at all — the web/edge entry,\n  //    where the platform terminates the connection and these are the only\n  //    signal available.\n  const h = req.headers\n  return (\n    firstHop(headerValue(h, 'cf-connecting-ip')) ??\n    firstHop(headerValue(h, 'x-forwarded-for')) ??\n    firstHop(headerValue(h, 'x-real-ip'))\n  )\n}\n\n/** Pathname only — `req.url` carries the query string, and `req.path` is Express-only. */\nexport function resolvePathname(req: ClientRequestLike): string {\n  if (typeof req.path === 'string' && req.path.length > 0) return req.path\n  const url = req.url\n  if (!url) return '/'\n  // `WebRequestShim` already reduces the WHATWG `Request.url` to path+search,\n  // but an ABSOLUTE url would otherwise be returned whole — so a skip prefix\n  // like `/health` would never match `https://host/health`.\n  if (/^[a-z][a-z0-9+.-]*:\\/\\//i.test(url)) {\n    try {\n      return new URL(url).pathname || '/'\n    } catch {\n      return '/'\n    }\n  }\n  const q = url.indexOf('?')\n  return (q === -1 ? url : url.slice(0, q)) || '/'\n}\n"],"mappings":";;;;;;;;;;AAsCA,SAAS,SAAS,MAAoC,CACpD,OAAO,OAAO,OAAU,UAAY,MAAM,OAAS,EAAI,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAE,KAAK,EAAI,IAAA,EACvF,CAGA,SAAS,YACP,QACA,KACS,CACJ,WAIL,OADI,OAAQ,QAAoB,KAAQ,WAAoB,QAAoB,IAAI,IAAI,EAChF,QAA0D,KACpE,CAgBA,SAAgB,gBAAgB,IAA4C,CAI1E,GAAI,OAAO,IAAI,IAAO,UAAY,IAAI,GAAG,OAAS,EAAG,OAAO,IAAI,GAWhE,IAAM,cAAgB,IAAI,QAAQ,cAClC,GAAI,cAAe,OAAO,cAK1B,IAAM,EAAI,IAAI,QACd,OACE,SAAS,YAAY,EAAG,kBAAkB,CAAC,GAC3C,SAAS,YAAY,EAAG,iBAAiB,CAAC,GAC1C,SAAS,YAAY,EAAG,WAAW,CAAC,CAExC,CAGA,SAAgB,gBAAgB,IAAgC,CAC9D,GAAI,OAAO,IAAI,MAAS,UAAY,IAAI,KAAK,OAAS,EAAG,OAAO,IAAI,KACpE,IAAM,IAAM,IAAI,IAChB,GAAI,CAAC,IAAK,MAAO,IAIjB,GAAI,2BAA2B,KAAK,GAAG,EACrC,GAAI,CACF,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC,UAAY,GAClC,MAAQ,CACN,MAAO,GACT,CAEF,IAAM,EAAI,IAAI,QAAQ,GAAG,EACzB,OAAQ,IAAM,GAAK,IAAM,IAAI,MAAM,EAAG,CAAC,IAAM,GAC/C"}
+{"version":3,"file":"client-ip-D_XUCo45.mjs","names":[],"sources":["../src/http/client-ip.ts"],"sourcesContent":["/**\n * Client address + pathname resolution shared by everything that runs as\n * connect-style middleware.\n *\n * Fastify and h3 hand middleware the RAW node request, so the Express\n * conveniences (`req.ip`, `req.path`, `req.originalUrl`) are `undefined`\n * there. Reading them directly produced two live bugs:\n *\n *   rate-limit → every caller keyed as the `'127.0.0.1'` fallback, i.e. ONE\n *                shared bucket, so a single client could exhaust the limit\n *                for everyone\n *   csrf       → `ignorePaths` never matched, so configured exemptions were\n *                silently dead\n *\n * Edge-safe: no node imports.\n */\n\n/** The request members these helpers read, from node's shape rather than Express's. */\nexport interface ClientRequestLike {\n  url?: string\n  /** Express-only convenience. */\n  path?: string\n  /** Express-only; the full path before router mounting rewrote `url`. */\n  originalUrl?: string\n  /** Express and Fastify compute this from their trust-proxy settings. */\n  ip?: unknown\n  /**\n   * A plain object on every path the framework currently takes — `WebRequestShim`\n   * normalizes a WHATWG `Headers` before the context is built. A `Headers`\n   * instance is accepted defensively: it is not index-accessible, so if one ever\n   * did arrive, every lookup would return `undefined` SILENTLY and drop each\n   * caller into one shared rate-limit bucket.\n   */\n  headers?: Record<string, string | string[] | undefined> | Headers\n  socket?: { remoteAddress?: string }\n}\n\n/** First entry of a possibly comma-separated header value. */\nfunction firstHop(value: unknown): string | undefined {\n  return typeof value === 'string' && value.length > 0 ? value.split(',')[0]!.trim() : undefined\n}\n\n/** Read one header from either a plain object or a WHATWG `Headers`. */\nfunction headerValue(\n  headers: Record<string, string | string[] | undefined> | Headers | undefined,\n  name: string,\n): unknown {\n  if (!headers) return undefined\n  // `Headers` has no index access, so `headers[name]` silently yields\n  // `undefined` rather than the value.\n  if (typeof (headers as Headers).get === 'function') return (headers as Headers).get(name)\n  return (headers as Record<string, string | string[] | undefined>)[name]\n}\n\n/**\n * The client's IP address, or `undefined` when it cannot be determined.\n *\n * Prefers the address the runtime computed — Express derives `req.ip` from\n * `trust proxy`, Fastify from `trustProxy` — because raw forwarded headers are\n * client-SPOOFABLE wherever nothing normalizes them. h3 takes the same stance:\n * its `getRequestIP` only consults `x-forwarded-for` when explicitly opted in.\n *\n * Order is `req.ip` → `socket.remoteAddress` → forwarded headers. The socket\n * comes BEFORE the headers deliberately: it cannot be spoofed, whereas a direct\n * client can vary `x-forwarded-for` per request to get a fresh rate-limit\n * bucket each time. Headers are consulted only where there is no socket — the\n * web/edge entry, where the platform terminates the connection.\n */\nexport function resolveClientIp(req: ClientRequestLike): string | undefined {\n  // 1. What the runtime computed. Express derives `req.ip` from `trust proxy`,\n  //    Fastify from `trustProxy` — a value vetted against a CONFIGURED proxy,\n  //    which is the only reason to believe a forwarded header at all.\n  if (typeof req.ip === 'string' && req.ip.length > 0) return req.ip\n\n  // 2. The socket. Unspoofable, and present on every node runtime.\n  //\n  //    This MUST precede the headers. A raw Fastify / h3 request has no\n  //    `req.ip`, so consulting `x-forwarded-for` first let a DIRECT client send\n  //    a different value per request and land in a fresh rate-limit bucket each\n  //    time — evading the limit entirely. Behind a real proxy the socket is the\n  //    proxy's address, which buckets clients together; the fix for that is to\n  //    configure the runtime's trust-proxy setting so step 1 answers, not to\n  //    trust an unverified header here.\n  const socketAddress = req.socket?.remoteAddress\n  if (socketAddress) return socketAddress\n\n  // 3. Headers, only where there is no socket at all — the web/edge entry,\n  //    where the platform terminates the connection and these are the only\n  //    signal available.\n  const h = req.headers\n  return (\n    firstHop(headerValue(h, 'cf-connecting-ip')) ??\n    firstHop(headerValue(h, 'x-forwarded-for')) ??\n    firstHop(headerValue(h, 'x-real-ip'))\n  )\n}\n\n/** Pathname only — `req.url` carries the query string, and `req.path` is Express-only. */\nexport function resolvePathname(req: ClientRequestLike): string {\n  if (typeof req.path === 'string' && req.path.length > 0) return req.path\n  const url = req.url\n  if (!url) return '/'\n  // `WebRequestShim` already reduces the WHATWG `Request.url` to path+search,\n  // but an ABSOLUTE url would otherwise be returned whole — so a skip prefix\n  // like `/health` would never match `https://host/health`.\n  if (/^[a-z][a-z0-9+.-]*:\\/\\//i.test(url)) {\n    try {\n      return new URL(url).pathname || '/'\n    } catch {\n      return '/'\n    }\n  }\n  const q = url.indexOf('?')\n  return (q === -1 ? url : url.slice(0, q)) || '/'\n}\n"],"mappings":";;;;;;;;;;AAsCA,SAAS,SAAS,MAAoC,CACpD,OAAO,OAAO,OAAU,UAAY,MAAM,OAAS,EAAI,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,CAAE,KAAK,EAAI,IAAA,EACvF,CAGA,SAAS,YACP,QACA,KACS,CACJ,WAIL,OADI,OAAQ,QAAoB,KAAQ,WAAoB,QAAoB,IAAI,IAAI,EAChF,QAA0D,KACpE,CAgBA,SAAgB,gBAAgB,IAA4C,CAI1E,GAAI,OAAO,IAAI,IAAO,UAAY,IAAI,GAAG,OAAS,EAAG,OAAO,IAAI,GAWhE,IAAM,cAAgB,IAAI,QAAQ,cAClC,GAAI,cAAe,OAAO,cAK1B,IAAM,EAAI,IAAI,QACd,OACE,SAAS,YAAY,EAAG,kBAAkB,CAAC,GAC3C,SAAS,YAAY,EAAG,iBAAiB,CAAC,GAC1C,SAAS,YAAY,EAAG,WAAW,CAAC,CAExC,CAGA,SAAgB,gBAAgB,IAAgC,CAC9D,GAAI,OAAO,IAAI,MAAS,UAAY,IAAI,KAAK,OAAS,EAAG,OAAO,IAAI,KACpE,IAAM,IAAM,IAAI,IAChB,GAAI,CAAC,IAAK,MAAO,IAIjB,GAAI,2BAA2B,KAAK,GAAG,EACrC,GAAI,CACF,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC,UAAY,GAClC,MAAQ,CACN,MAAO,GACT,CAEF,IAAM,EAAI,IAAI,QAAQ,GAAG,EACzB,OAAQ,IAAM,GAAK,IAAM,IAAI,MAAM,EAAG,CAAC,IAAM,GAC/C"}

package/dist/config/index.d.mts

@@ -1,3 +1,3 @@
 
-import { a as baseEnvSchema, c as loadEnv, d as resetEnvCache, i as Env, l as loadEnvFromSchema, n as TypedConfigService, o as defineEnv, r as createConfigService, s as getEnv, t as ConfigService, u as reloadEnv } from "../index-Di64XOKG.mjs";
+import { a as baseEnvSchema, c as loadEnv, d as resetEnvCache, i as Env, l as loadEnvFromSchema, n as TypedConfigService, o as defineEnv, r as createConfigService, s as getEnv, t as ConfigService, u as reloadEnv } from "../index-BaMA8_NF.mjs";
 export { ConfigService, type Env, type TypedConfigService, baseEnvSchema, createConfigService, defineEnv, getEnv, loadEnv, loadEnvFromSchema, reloadEnv, resetEnvCache };

package/dist/config/index.mjs

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v8.0.0
+ * @forinda/kickjs v8.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,4 +8,4 @@
  *
  * @license MIT
  */
-import{a as loadEnvFromSchema,i as loadEnv,n as defineEnv,o as reloadEnv,r as getEnv,s as resetEnvCache,t as baseEnvSchema}from"../env-CabVU6cy.mjs";import{n as createConfigService,t as ConfigService}from"../config-ClZsO9eK.mjs";export{ConfigService,baseEnvSchema,createConfigService,defineEnv,getEnv,loadEnv,loadEnvFromSchema,reloadEnv,resetEnvCache};
+import{a as loadEnvFromSchema,i as loadEnv,n as defineEnv,o as reloadEnv,r as getEnv,s as resetEnvCache,t as baseEnvSchema}from"../env-C4hwX5of.mjs";import{n as createConfigService,t as ConfigService}from"../config-Bi6kDjo9.mjs";export{ConfigService,baseEnvSchema,createConfigService,defineEnv,getEnv,loadEnv,loadEnvFromSchema,reloadEnv,resetEnvCache};

package/dist/{config-ClZsO9eK.mjs → config-Bi6kDjo9.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs v8.0.0
+ * @forinda/kickjs v8.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,5 +8,5 @@
  *
  * @license MIT
  */
-import{i as loadEnv,o as reloadEnv}from"./env-CabVU6cy.mjs";import{Service}from"./core/decorators.mjs";import{t as __decorate}from"./decorate-DDLimr-C.mjs";let ConfigService=class{get env(){return loadEnv()}get(key){return this.env[key]}getAll(){return Object.freeze({...this.env})}reload(){reloadEnv(),loadEnv()}isProduction(){return this.env.NODE_ENV===`production`}isDevelopment(){return this.env.NODE_ENV===`development`}isTest(){return this.env.NODE_ENV===`test`}};ConfigService=__decorate([Service()],ConfigService);function createConfigService(schema){let SchemaConfigService=class{get env(){return loadEnv(schema)}get(key){return this.env[key]}getAll(){return Object.freeze({...this.env})}reload(){reloadEnv(),loadEnv(schema)}isProduction(){return this.env.NODE_ENV===`production`}isDevelopment(){return this.env.NODE_ENV===`development`}isTest(){return this.env.NODE_ENV===`test`}};return SchemaConfigService=__decorate([Service()],SchemaConfigService),SchemaConfigService}export{createConfigService as n,ConfigService as t};
-//# sourceMappingURL=config-ClZsO9eK.mjs.map
+import{i as loadEnv,o as reloadEnv}from"./env-C4hwX5of.mjs";import{Service}from"./core/decorators.mjs";import{t as __decorate}from"./decorate-C0Rr6ywx.mjs";let ConfigService=class{get env(){return loadEnv()}get(key){return this.env[key]}getAll(){return Object.freeze({...this.env})}reload(){reloadEnv(),loadEnv()}isProduction(){return this.env.NODE_ENV===`production`}isDevelopment(){return this.env.NODE_ENV===`development`}isTest(){return this.env.NODE_ENV===`test`}};ConfigService=__decorate([Service()],ConfigService);function createConfigService(schema){let SchemaConfigService=class{get env(){return loadEnv(schema)}get(key){return this.env[key]}getAll(){return Object.freeze({...this.env})}reload(){reloadEnv(),loadEnv(schema)}isProduction(){return this.env.NODE_ENV===`production`}isDevelopment(){return this.env.NODE_ENV===`development`}isTest(){return this.env.NODE_ENV===`test`}};return SchemaConfigService=__decorate([Service()],SchemaConfigService),SchemaConfigService}export{createConfigService as n,ConfigService as t};
+//# sourceMappingURL=config-Bi6kDjo9.mjs.map

package/dist/{config-ClZsO9eK.mjs.map → config-Bi6kDjo9.mjs.map}

@@ -1 +1 @@
-{"version":3,"file":"config-ClZsO9eK.mjs","names":[],"sources":["../src/config/config-service.ts"],"sourcesContent":["import type { z } from 'zod'\nimport { Service } from '../core/decorators'\nimport type { EnvKey } from '../core/decorators'\nimport { loadEnv, reloadEnv } from './env'\n\n/**\n * Constraint that locks the `key` argument to known `EnvKey` literals\n * once `kick typegen` has populated `KickEnv`. Mirrors the same trick\n * used by the `@Value` decorator: when `EnvKey` resolves to `never`\n * (no schema yet), accept any string for back-compat; once typegen\n * has run, require a known key.\n */\ntype ConfigKey<K extends string> = [EnvKey] extends [never] ? K : K & EnvKey\n\n/**\n * Resolve the return type for a `ConfigService.get(key)` call. When\n * `KickEnv` is populated and the key is a known one, returns the\n * schema-inferred type. Otherwise falls back to the caller-provided\n * generic `T` (default `any`) so existing call sites keep working.\n */\ntype ConfigValue<K extends string, T> = K extends EnvKey ? KickEnv[K] : T\n\n/**\n * Injectable service for accessing typed environment configuration.\n *\n * Once `kick typegen` has run against your `src/env.ts`, both `get()`\n * and `getAll()` are fully typed against the schema with **no extra\n * setup** — you just inject `ConfigService` and call it:\n *\n * ```ts\n * @Service()\n * class DatabaseService {\n *   @Autowired() private readonly config!: ConfigService\n *\n *   connect() {\n *     const url = this.config.get('DATABASE_URL')   // typed string\n *     const port = this.config.get('PORT')          // typed number\n *     // const bad = this.config.get('NOPE')        // tsc error\n *   }\n * }\n * ```\n *\n * Without typegen the previous `<T = any>` generic still works, so\n * legacy code calling `config.get<string>('DATABASE_URL')` keeps\n * compiling.\n */\n@Service()\nexport class ConfigService {\n  /**\n   * Read the current parsed env on every access. We deliberately do **not**\n   * snapshot in the constructor: if `ConfigService` is instantiated before\n   * the user's `defineEnv()` schema has been registered (e.g. DI wires it\n   * eagerly, or HMR's `reloadEnv()` cleared the cache between rebuilds),\n   * an eager snapshot would freeze the base shape and never see the\n   * extended values — even though `@Value()` (which reads lazily through\n   * `Container._envResolver`) would resolve them correctly.\n   *\n   * `loadEnv()` is sticky: once an extended schema has been parsed it\n   * keeps returning that schema's values, so this getter is cheap (one\n   * cached lookup) and always consistent with `@Value`.\n   */\n  private get env(): Record<string, any> {\n    return loadEnv() as Record<string, any>\n  }\n\n  /**\n   * Get an env variable by key.\n   *\n   * - When `kick typegen` has run, `key` is constrained to known\n   *   `KickEnv` keys and the return type is inferred from the schema.\n   * - When `KickEnv` is empty (no typegen run yet), any string is\n   *   accepted and `T` falls back to the explicit generic for\n   *   back-compat.\n   */\n  get<K extends string, T = any>(key: ConfigKey<K>): ConfigValue<K, T> {\n    return this.env[key] as ConfigValue<K, T>\n  }\n\n  /**\n   * Get all env config as a readonly object. When `KickEnv` is\n   * populated by typegen, returns `Readonly<KickEnv>` so the caller\n   * gets autocomplete on every key.\n   */\n  getAll(): [EnvKey] extends [never] ? Readonly<Record<string, any>> : Readonly<KickEnv> {\n    return Object.freeze({ ...this.env }) as any\n  }\n\n  /** Reload env from .env file (for HMR / file-watch scenarios) */\n  reload(): void {\n    reloadEnv()\n    // Touch loadEnv() so the resolver + cache are repopulated immediately.\n    loadEnv()\n  }\n\n  isProduction(): boolean {\n    return this.env.NODE_ENV === 'production'\n  }\n\n  isDevelopment(): boolean {\n    return this.env.NODE_ENV === 'development'\n  }\n\n  isTest(): boolean {\n    return this.env.NODE_ENV === 'test'\n  }\n}\n\n/**\n * Typed config service interface — provides autocomplete for env keys.\n * Use with `createConfigService()` for full type safety.\n */\nexport interface TypedConfigService<TEnv extends Record<string, any>> {\n  get<K extends string & keyof TEnv>(key: K): TEnv[K]\n  getAll(): Readonly<TEnv>\n  reload(): void\n  isProduction(): boolean\n  isDevelopment(): boolean\n  isTest(): boolean\n}\n\n/**\n * Create a typed ConfigService class bound to a specific Zod env schema.\n * The returned class is DI-injectable via `@Service()` and provides\n * fully typed `get()` with key autocomplete.\n *\n * @example\n * ```ts\n * const envSchema = defineEnv((base) =>\n *   base.extend({\n *     DATABASE_URL: z.string().url(),\n *     JWT_SECRET: z.string().min(32),\n *   })\n * )\n *\n * // Create a typed, injectable config service\n * export const AppConfigService = createConfigService(envSchema)\n * export type AppConfigService = InstanceType<typeof AppConfigService>\n *\n * // In a controller or service — inject it:\n * @Controller()\n * class UserController {\n *   constructor(@Inject(AppConfigService) private config: AppConfigService) {\n *     const dbUrl = config.get('DATABASE_URL')  // string — autocompletes!\n *     const bad = config.get('NOPE')             // TS error\n *   }\n * }\n * ```\n */\nexport function createConfigService<T extends z.ZodObject<any>>(schema: T) {\n  type TEnv = z.infer<T>\n\n  @Service()\n  class SchemaConfigService implements TypedConfigService<TEnv> {\n    /** See note on `ConfigService.env` — same eager-snapshot hazard. */\n    private get env(): TEnv {\n      return loadEnv(schema)\n    }\n\n    get<K extends string & keyof TEnv>(key: K): TEnv[K] {\n      return this.env[key]\n    }\n\n    getAll(): Readonly<TEnv> {\n      return Object.freeze({ ...this.env })\n    }\n\n    reload(): void {\n      reloadEnv()\n      loadEnv(schema)\n    }\n\n    isProduction(): boolean {\n      return this.env.NODE_ENV === 'production'\n    }\n\n    isDevelopment(): boolean {\n      return this.env.NODE_ENV === 'development'\n    }\n\n    isTest(): boolean {\n      return this.env.NODE_ENV === 'test'\n    }\n  }\n\n  return SchemaConfigService as {\n    new (): TypedConfigService<TEnv>\n  }\n}\n"],"mappings":";;;;;;;;;;4JA+CO,IAAM,cAAN,KAAoB,CAczB,IAAY,KAA2B,CACrC,OAAO,QAAQ,CACjB,CAWA,IAA+B,IAAsC,CACnE,OAAO,KAAK,IAAI,IAClB,CAOA,QAAuF,CACrF,OAAO,OAAO,OAAO,CAAE,GAAG,KAAK,GAAI,CAAC,CACtC,CAGA,QAAe,CACb,UAAU,EAEV,QAAQ,CACV,CAEA,cAAwB,CACtB,OAAO,KAAK,IAAI,WAAa,YAC/B,CAEA,eAAyB,CACvB,OAAO,KAAK,IAAI,WAAa,aAC/B,CAEA,QAAkB,CAChB,OAAO,KAAK,IAAI,WAAa,MAC/B,CACF,EA3DC,cAAA,WAAA,CAAA,QAAQ,CAAA,EAAA,aAAA,EAsGT,SAAgB,oBAAgD,OAAW,CAGzE,IACM,oBADN,KAC8D,CAE5D,IAAY,KAAY,CACtB,OAAO,QAAQ,MAAM,CACvB,CAEA,IAAmC,IAAiB,CAClD,OAAO,KAAK,IAAI,IAClB,CAEA,QAAyB,CACvB,OAAO,OAAO,OAAO,CAAE,GAAG,KAAK,GAAI,CAAC,CACtC,CAEA,QAAe,CACb,UAAU,EACV,QAAQ,MAAM,CAChB,CAEA,cAAwB,CACtB,OAAO,KAAK,IAAI,WAAa,YAC/B,CAEA,eAAyB,CACvB,OAAO,KAAK,IAAI,WAAa,aAC/B,CAEA,QAAkB,CAChB,OAAO,KAAK,IAAI,WAAa,MAC/B,CACF,EAEA,MAjCC,qBAAA,WAAA,CAAA,QAAQ,CAAA,EAAA,mBAAA,EAiCF,mBAGT"}
+{"version":3,"file":"config-Bi6kDjo9.mjs","names":[],"sources":["../src/config/config-service.ts"],"sourcesContent":["import type { z } from 'zod'\nimport { Service } from '../core/decorators'\nimport type { EnvKey } from '../core/decorators'\nimport { loadEnv, reloadEnv } from './env'\n\n/**\n * Constraint that locks the `key` argument to known `EnvKey` literals\n * once `kick typegen` has populated `KickEnv`. Mirrors the same trick\n * used by the `@Value` decorator: when `EnvKey` resolves to `never`\n * (no schema yet), accept any string for back-compat; once typegen\n * has run, require a known key.\n */\ntype ConfigKey<K extends string> = [EnvKey] extends [never] ? K : K & EnvKey\n\n/**\n * Resolve the return type for a `ConfigService.get(key)` call. When\n * `KickEnv` is populated and the key is a known one, returns the\n * schema-inferred type. Otherwise falls back to the caller-provided\n * generic `T` (default `any`) so existing call sites keep working.\n */\ntype ConfigValue<K extends string, T> = K extends EnvKey ? KickEnv[K] : T\n\n/**\n * Injectable service for accessing typed environment configuration.\n *\n * Once `kick typegen` has run against your `src/env.ts`, both `get()`\n * and `getAll()` are fully typed against the schema with **no extra\n * setup** — you just inject `ConfigService` and call it:\n *\n * ```ts\n * @Service()\n * class DatabaseService {\n *   @Autowired() private readonly config!: ConfigService\n *\n *   connect() {\n *     const url = this.config.get('DATABASE_URL')   // typed string\n *     const port = this.config.get('PORT')          // typed number\n *     // const bad = this.config.get('NOPE')        // tsc error\n *   }\n * }\n * ```\n *\n * Without typegen the previous `<T = any>` generic still works, so\n * legacy code calling `config.get<string>('DATABASE_URL')` keeps\n * compiling.\n */\n@Service()\nexport class ConfigService {\n  /**\n   * Read the current parsed env on every access. We deliberately do **not**\n   * snapshot in the constructor: if `ConfigService` is instantiated before\n   * the user's `defineEnv()` schema has been registered (e.g. DI wires it\n   * eagerly, or HMR's `reloadEnv()` cleared the cache between rebuilds),\n   * an eager snapshot would freeze the base shape and never see the\n   * extended values — even though `@Value()` (which reads lazily through\n   * `Container._envResolver`) would resolve them correctly.\n   *\n   * `loadEnv()` is sticky: once an extended schema has been parsed it\n   * keeps returning that schema's values, so this getter is cheap (one\n   * cached lookup) and always consistent with `@Value`.\n   */\n  private get env(): Record<string, any> {\n    return loadEnv() as Record<string, any>\n  }\n\n  /**\n   * Get an env variable by key.\n   *\n   * - When `kick typegen` has run, `key` is constrained to known\n   *   `KickEnv` keys and the return type is inferred from the schema.\n   * - When `KickEnv` is empty (no typegen run yet), any string is\n   *   accepted and `T` falls back to the explicit generic for\n   *   back-compat.\n   */\n  get<K extends string, T = any>(key: ConfigKey<K>): ConfigValue<K, T> {\n    return this.env[key] as ConfigValue<K, T>\n  }\n\n  /**\n   * Get all env config as a readonly object. When `KickEnv` is\n   * populated by typegen, returns `Readonly<KickEnv>` so the caller\n   * gets autocomplete on every key.\n   */\n  getAll(): [EnvKey] extends [never] ? Readonly<Record<string, any>> : Readonly<KickEnv> {\n    return Object.freeze({ ...this.env }) as any\n  }\n\n  /** Reload env from .env file (for HMR / file-watch scenarios) */\n  reload(): void {\n    reloadEnv()\n    // Touch loadEnv() so the resolver + cache are repopulated immediately.\n    loadEnv()\n  }\n\n  isProduction(): boolean {\n    return this.env.NODE_ENV === 'production'\n  }\n\n  isDevelopment(): boolean {\n    return this.env.NODE_ENV === 'development'\n  }\n\n  isTest(): boolean {\n    return this.env.NODE_ENV === 'test'\n  }\n}\n\n/**\n * Typed config service interface — provides autocomplete for env keys.\n * Use with `createConfigService()` for full type safety.\n */\nexport interface TypedConfigService<TEnv extends Record<string, any>> {\n  get<K extends string & keyof TEnv>(key: K): TEnv[K]\n  getAll(): Readonly<TEnv>\n  reload(): void\n  isProduction(): boolean\n  isDevelopment(): boolean\n  isTest(): boolean\n}\n\n/**\n * Create a typed ConfigService class bound to a specific Zod env schema.\n * The returned class is DI-injectable via `@Service()` and provides\n * fully typed `get()` with key autocomplete.\n *\n * @example\n * ```ts\n * const envSchema = defineEnv((base) =>\n *   base.extend({\n *     DATABASE_URL: z.string().url(),\n *     JWT_SECRET: z.string().min(32),\n *   })\n * )\n *\n * // Create a typed, injectable config service\n * export const AppConfigService = createConfigService(envSchema)\n * export type AppConfigService = InstanceType<typeof AppConfigService>\n *\n * // In a controller or service — inject it:\n * @Controller()\n * class UserController {\n *   constructor(@Inject(AppConfigService) private config: AppConfigService) {\n *     const dbUrl = config.get('DATABASE_URL')  // string — autocompletes!\n *     const bad = config.get('NOPE')             // TS error\n *   }\n * }\n * ```\n */\nexport function createConfigService<T extends z.ZodObject<any>>(schema: T) {\n  type TEnv = z.infer<T>\n\n  @Service()\n  class SchemaConfigService implements TypedConfigService<TEnv> {\n    /** See note on `ConfigService.env` — same eager-snapshot hazard. */\n    private get env(): TEnv {\n      return loadEnv(schema)\n    }\n\n    get<K extends string & keyof TEnv>(key: K): TEnv[K] {\n      return this.env[key]\n    }\n\n    getAll(): Readonly<TEnv> {\n      return Object.freeze({ ...this.env })\n    }\n\n    reload(): void {\n      reloadEnv()\n      loadEnv(schema)\n    }\n\n    isProduction(): boolean {\n      return this.env.NODE_ENV === 'production'\n    }\n\n    isDevelopment(): boolean {\n      return this.env.NODE_ENV === 'development'\n    }\n\n    isTest(): boolean {\n      return this.env.NODE_ENV === 'test'\n    }\n  }\n\n  return SchemaConfigService as {\n    new (): TypedConfigService<TEnv>\n  }\n}\n"],"mappings":";;;;;;;;;;4JA+CO,IAAM,cAAN,KAAoB,CAczB,IAAY,KAA2B,CACrC,OAAO,QAAQ,CACjB,CAWA,IAA+B,IAAsC,CACnE,OAAO,KAAK,IAAI,IAClB,CAOA,QAAuF,CACrF,OAAO,OAAO,OAAO,CAAE,GAAG,KAAK,GAAI,CAAC,CACtC,CAGA,QAAe,CACb,UAAU,EAEV,QAAQ,CACV,CAEA,cAAwB,CACtB,OAAO,KAAK,IAAI,WAAa,YAC/B,CAEA,eAAyB,CACvB,OAAO,KAAK,IAAI,WAAa,aAC/B,CAEA,QAAkB,CAChB,OAAO,KAAK,IAAI,WAAa,MAC/B,CACF,EA3DC,cAAA,WAAA,CAAA,QAAQ,CAAA,EAAA,aAAA,EAsGT,SAAgB,oBAAgD,OAAW,CAGzE,IACM,oBADN,KAC8D,CAE5D,IAAY,KAAY,CACtB,OAAO,QAAQ,MAAM,CACvB,CAEA,IAAmC,IAAiB,CAClD,OAAO,KAAK,IAAI,IAClB,CAEA,QAAyB,CACvB,OAAO,OAAO,OAAO,CAAE,GAAG,KAAK,GAAI,CAAC,CACtC,CAEA,QAAe,CACb,UAAU,EACV,QAAQ,MAAM,CAChB,CAEA,cAAwB,CACtB,OAAO,KAAK,IAAI,WAAa,YAC/B,CAEA,eAAyB,CACvB,OAAO,KAAK,IAAI,WAAa,aAC/B,CAEA,QAAkB,CAChB,OAAO,KAAK,IAAI,WAAa,MAC/B,CACF,EAEA,MAjCC,qBAAA,WAAA,CAAA,QAAQ,CAAA,EAAA,mBAAA,EAiCF,mBAGT"}

package/dist/{container-BW_MlgLj.d.mts → container-BA-O7uBF.d.mts}

@@ -133,6 +133,13 @@ declare class Container {
   static _onReady: ((container: Container) => void) | null;
   /** Callback invoked on reset so decorators can update their container reference */
   static _onReset: ((container: Container) => void) | null;
+  /**
+   * Seeds a NEWLY CREATED container with the decorator registrations, without
+   * adopting it as the global one. `_onReset` does both; an isolated container
+   * must only have the first half, or it would capture every subsequent
+   * decorator registration in the process.
+   */
+  static _onCreate: ((container: Container) => void) | null;
   /**
    * Environment resolver for @Value decorator. Set by the unified
    * `@forinda/kickjs` config layer to return Zod-validated, type-coerced
@@ -145,6 +152,16 @@ declare class Container {
    * AsyncLocalStorage store. Returns { instances: Map, values: Map } or
    * null if outside a request.
    */
+  /**
+   * Whether this container is the global singleton.
+   *
+   * The persistent store exists to carry the GLOBAL container's registrations
+   * across HMR and module re-evaluation. An isolated container is per-test and
+   * must neither write to it — a `registerInstance` override was replayed into
+   * every later `Container.reset()` — nor read from it, which would pull global
+   * state into a container created to be free of it.
+   */
+  private isGlobal;
   static _requestStoreProvider: (() => {
     instances: Map<any, any>;
     values: Map<any, any>;
@@ -278,4 +295,4 @@ declare class Container {
 }
 //#endregion
 export { tokenName as a, createToken as c, KickJsRegistry as i, isInjectionToken as l, ContainerChangeEvent as n, INJECTION_TOKEN as o, ContainerChangeListener as r, InjectionToken as s, Container as t };
-//# sourceMappingURL=container-BW_MlgLj.d.mts.map
+//# sourceMappingURL=container-BA-O7uBF.d.mts.map

package/dist/container-BA-O7uBF.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-BA-O7uBF.d.mts","names":[],"sources":["../src/core/token.ts","../src/core/container.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmDa;;;;;;;;;;UAWI,eAAe;YACpB;;WAED;;WAEA,QAAQ;;;;;;;;;iBAUH,YAAY,GAAG,eAAe,eAAe;;iBAQ7C,iBAAiB,iBAAiB,SAAS;;;;iBCL3C,UAAU;;UAqBT;EACf;EACA;EACA,OAAO;EACP;;;KAIU,2BAA2B,SAAS;;;;;;;;;;;;;;;;;;UAmB/B;;;;;;;;;;;;cA+BJ;iBACI;UACP;UACA;UAGA;UACA;UACA;0BACgB;;SAGjB,YAAY,WAAW;;SAEvB,YAAY,WAAW;;;;;;;SAQvB,aAAa,WAAW;;;;;;SAMxB,gBAAgB;;;;;;;;;;;;;;;;UAgBf;SAED;IACM,WAAW;IAAe,QAAQ;;SAGxC,eAAe;;;;;;SAkBf;;;;;;;;;;;;SAsDA,UAAU;;EAYjB,SAAS,YAAY,QAAQ,aAAa,QAAO;;EAcjD,gBAAgB,YAAY,oBAAoB,QAAO;;EAiDvD,iBAAiB,YAAY;;EAiC7B,IAAI;;EAKJ,oBAAoB;IAClB;IACA;IACA,MAAM;IACN;IACA;IACA;IACA;IACA;IACA,qBAAqB;IACrB;;;;;;;;;;;;;;;EAmCF,QAAQ,GAAG,OAAO,eAAe,KAAK;EACtC,QAAQ,GAAG,OAAO,YAAY,KAAK;EACnC,QAAQ,gBAAgB,yBAAyB,OAAO,IAAI,eAAe;EAC3E,QAAQ,SAAS,aAAa;;EAmH9B;;;;;;;;;;;;;;;;;;;;;;;;;EA+BA,SAAS,UAAU;;;;;;;;;EAanB,WAAW;;;;;;;UA8BH;;EA6CR;;;;;;;;;;;UA0BQ;UAgFA;;;;;;;;;;;UAwDA;UAuBA"}

package/dist/container-jtn5BmL5.mjs

@@ -0,0 +1,117 @@
+/**
+ * @forinda/kickjs v8.1.0
+ *
+ * Copyright (c) Felix Orinda
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @license MIT
+ */
+import{METADATA}from"./core/interfaces.mjs";import{createLogger}from"./core/logger.mjs";import{i as getMetaRecord,n as getClassMetaOrUndefined,o as getMethodMetaOrUndefined,r as getMetaMap,t as getClassMeta}from"./metadata-DUJjjW0o.mjs";import"reflect-metadata";let impl=null;function _setAssetResolver(fn){impl=fn}function resolveAssetViaSlot(namespace,key){if(!impl)throw Error(`@Asset('${namespace}/${key}'): the asset manager is not loaded. Import it (any import from '@forinda/kickjs' loads it) — note @Asset reads from the filesystem and is not supported on edge runtimes.`);return impl(namespace,key)}var KickError=class extends Error{code;summary;cause;fix;docsUrl;context;constructor(init){super(formatKickError(init,{color:!1})),this.name=`KickError`,this.code=init.code,this.summary=init.summary,init.cause!==void 0&&(this.cause=init.cause),init.fix!==void 0&&(this.fix=init.fix),init.docsUrl!==void 0&&(this.docsUrl=init.docsUrl),init.context!==void 0&&(this.context=init.context)}};function ansiEnabled(){return process.env.NO_COLOR?!1:process.env.FORCE_COLOR?!0:process.stderr?.isTTY===!0}function paint(text,code,enabled){return enabled?`[${code}m${text}`:text}const c={red:(s,enabled)=>paint(s,`31`,enabled),bold:(s,enabled)=>paint(s,`1`,enabled),dim:(s,enabled)=>paint(s,`2`,enabled),cyan:(s,enabled)=>paint(s,`36`,enabled),blue:(s,enabled)=>paint(s,`34`,enabled),underline:(s,enabled)=>paint(s,`4`,enabled)};function formatKickError(err,options={}){let color=options.color??ansiEnabled(),lines=[],code=c.bold(c.red(err.code,color),color);if(lines.push(`${code}: ${err.summary}`),err.cause){lines.push(``,`  ${c.bold(c.dim(`Cause:`,color),color)}`);for(let line of err.cause.split(`
+`))lines.push(`    ${highlightInline(line,color)}`)}if(err.fix){lines.push(``,`  ${c.bold(c.dim(`Fix:`,color),color)}`);for(let line of err.fix.split(`
+`))lines.push(`    ${highlightInline(line,color)}`)}return err.docsUrl&&(lines.push(``,`  ${c.bold(c.dim(`Docs:`,color),color)}`),lines.push(`    ${c.underline(c.blue(err.docsUrl,color),color)}`)),lines.join(`
+`)}function highlightInline(line,color){return color?line.replace(/`([^`]+)`/g,(_,inner)=>`\`${c.cyan(inner,!0)}\``):line}const DOCS_BASE=`https://kickjs.app`;function noProviderError(tokenName){return new KickError({code:`KICK001`,summary:`No provider for ${tokenName}`,cause:`\`${tokenName}\` was requested from the DI container but no binding is registered.
+This usually means one of:
+  • The class is decorated with @Service() / @Repository() / @Controller(),
+    but its enclosing module isn't passed to bootstrap({ modules: [...] }).
+  • The class isn't decorated at all (decorators register the binding).
+  • You're injecting a token (created with createToken()) that nothing
+    provides — add a Container.register(TOKEN, ...) call or a module that
+    binds it.`,fix:`If \`${tokenName}\` lives in a module, add the module to bootstrap:
+
+      bootstrap({
+        modules: [
+          UsersModule,        // add this
+          OtherModule,
+        ],
+      })
+
+If it's a custom token, register it explicitly:
+
+      const TENANT_REPO = createToken<TenantRepo>('TENANT_REPO')
+      Container.getInstance().register(TENANT_REPO, { useClass: PrismaTenantRepo })`,docsUrl:`${DOCS_BASE}/guide/dependency-injection#registering-services`,context:{token:tokenName}})}function requestScopeMiddlewareMissingError(tokenName){return new KickError({code:`KICK002`,summary:`Cannot resolve REQUEST-scoped "${tokenName}" — request scope middleware not mounted`,cause:`\`${tokenName}\` has \`scope: Scope.REQUEST\` but no AsyncLocalStorage frame is wired.
+The framework's request-scope middleware sets up that frame; without it,
+REQUEST-scoped resolutions have nowhere to cache the per-request instance.`,fix:`Add \`requestScopeMiddleware()\` to your global middleware pipeline,
+or let the framework auto-mount it by using \`contextStore: 'auto'\`
+(the default — only check this if you set it to 'manual' explicitly):
+
+      bootstrap({
+        modules,
+        // contextStore: 'auto',  // default; no need to set
+      })
+
+If you set \`contextStore: 'manual'\` deliberately (rare), you own the
+ALS wrapping — call \`requestStore.run({...}, () => ...)\` around the
+code that resolves the binding.`,docsUrl:`${DOCS_BASE}/guide/dependency-injection#scopes`,context:{token:tokenName}})}function requestScopeOutsideRequestError(tokenName){return new KickError({code:`KICK003`,summary:`Cannot resolve REQUEST-scoped "${tokenName}" outside an HTTP request`,cause:`\`${tokenName}\` has \`scope: Scope.REQUEST\` and was resolved outside
+any HTTP request context. The request-scope middleware is wired, but
+the call happened before a request started (e.g. in a top-level
+import, a constructor, a cron job, a test without setup).`,fix:`If the caller is request-scoped (controller, request-scoped service),
+make sure the call happens inside the request lifecycle, not at module
+load time.
+
+In tests, wrap setup in an ALS frame manually:
+
+      import { requestStore } from '@forinda/kickjs'
+
+      requestStore.run(
+        { requestId: 'test', instances: new Map(), values: new Map() },
+        () => {
+          const svc = container.resolve(MyRequestScopedService)
+          // ...
+        },
+      )
+
+If the caller is a SINGLETON, change \`${tokenName}\` to TRANSIENT or
+SINGLETON scope, or inject a factory instead of the instance directly.`,docsUrl:`${DOCS_BASE}/guide/dependency-injection#scopes`,context:{token:tokenName}})}function envValueMissingError(envKey){return new KickError({code:`KICK004`,summary:`@Value('${envKey}'): environment variable not set and no default provided`,cause:`\`@Value('${envKey}')\` resolved but the env var isn't present and the
+decorator didn't declare a default. Possible reasons:
+  • The variable is genuinely missing from your environment / .env file.
+  • Your \`src/env.ts\` calls \`loadEnv(envSchema)\` but \`src/index.ts\`
+    doesn't import \`./env\` before \`bootstrap()\`. Without that import
+    the schema never runs and ConfigService stays empty — \`@Value\`
+    only finds the var via the \`process.env\` fallback.`,fix:`Either set the variable in your shell / .env file:
+
+      ${envKey}=...
+
+Or add a default at the decorator:
+
+      @Value('${envKey}', { default: 'fallback' })
+      private value!: string
+
+If you're using a schema, make sure \`src/env.ts\` is imported from
+\`src/index.ts\` BEFORE bootstrap runs:
+
+      // src/index.ts
+      import 'reflect-metadata'
+      import './env'                  // ← this line is required
+      import { bootstrap } from '@forinda/kickjs'
+      // ...`,docsUrl:`${DOCS_BASE}/guide/configuration#wiring-the-schema-at-startup`,context:{envKey}})}function moduleRouteMissingControllerError(mountPath){return new KickError({code:`KICK005`,summary:`Module route at ${mountPath} requires either 'controller' or 'router'`,cause:`A module's \`routes()\` returned an entry for \`${mountPath}\` but didn't
+specify how to build the router. The framework needs either a decorated
+controller class (it calls \`buildRoutes()\` internally) or a hand-built
+Express Router.`,fix:`Pass \`controller:\` for the common case:
+
+      routes() {
+        return {
+          path: '${mountPath}',
+          controller: UsersController,
+        }
+      }
+
+Or pass \`router:\` for full control:
+
+      routes() {
+        return {
+          path: '${mountPath}',
+          router: myExpressRouter,
+        }
+      }`,docsUrl:`${DOCS_BASE}/guide/modules`,context:{mountPath}})}function duplicateRouteError(method,path,owner,prior){return new KickError({code:`KICK006`,summary:`Duplicate route: ${method} ${path} is registered twice`,cause:`\`${owner}\` registers \`${method} ${path}\`, but that verb + path is
+already claimed by \`${prior}\`. Only one handler can win at dispatch
+time, and which one depends on the engine — while \`kick typegen\` and
+the typed client may describe the other. Param names are ignored when
+comparing (\`/:id\` and \`/:taskId\` are the same route).`,fix:`Change one of the two paths, remove the duplicate handler, or mount
+the second controller under a different module path / version:
+
+      routes() {
+        return { path: '/tasks', controller: TasksController, version: 2 }
+      }`,docsUrl:`${DOCS_BASE}/guide/modules`,context:{method,path,owner,prior}})}const INJECTION_TOKEN=Symbol.for(`@kickjs/InjectionToken`);function createToken(name){return Object.freeze({[INJECTION_TOKEN]:!0,name})}function isInjectionToken(value){return typeof value==`object`&&!!value&&value[INJECTION_TOKEN]===!0}const log=createLogger(`Container`);function createReg(fields){return{kind:`unknown`,resolveCount:0,postConstructStatus:`skipped`,dependencies:[],...fields}}function tokenName(token){return typeof token==`symbol`?token.toString():isInjectionToken(token)?token.name:token?.name||String(token)}function getPersistentStore(){return globalThis.__kickjs_persistent||(globalThis.__kickjs_persistent={factories:[],instances:[],resolvedInstances:new Map}),globalThis.__kickjs_persistent}var Container=class Container{static instance;registrations=new Map;resolving=new Set;changeListeners=new Set;pendingChanges=[];notifyTimer=null;static DEBOUNCE_MS=50;static _onReady=null;static _onReset=null;static _onCreate=null;static _envResolver=null;isGlobal=!1;static _requestStoreProvider=null;static getInstance(){return Container.instance||(Container.instance=new Container,Container.instance.isGlobal=!0),Container._onReady&&=(Container._onReady(Container.instance),null),Container.instance}static reset(){Container.instance=new Container,Container.instance.isGlobal=!0,Container._onReset?.(Container.instance);let store=getPersistentStore();for(let{token,factory,scope}of store.factories)if(!Container.instance.has(token)){let name=tokenName(token),existing=store.resolvedInstances.get(name);Container.instance.registrations.set(token,createReg({target:Object,scope,factory,kind:`factory`,instance:existing,resolveCount:+!!existing,postConstructStatus:existing?`completed`:`skipped`}))}for(let{token,instance}of store.instances)Container.instance.has(token)||Container.instance.registrations.set(token,createReg({target:instance.constructor,scope:`singleton`,instance,kind:`instance`,postConstructStatus:`completed`,resolveCount:1}))}static create(){let container=new Container;return Container._onCreate?.(container),container}register(token,target,scope=`singleton`){let kind=getClassMeta(METADATA.CLASS_KIND,target,`unknown`),reg=createReg({target,scope,kind,dependencies:this.extractDependencies(target)});this.registrations.set(token,reg),typeof token==`function`&&token.name&&this.registrations.set(`__hmr__${token.name}`,reg),this.emit(token,`registered`,kind)}registerFactory(token,factory,scope=`singleton`){let store=getPersistentStore(),name=tokenName(token),factoryUnchanged=(this.isGlobal?store.factories.find(r=>tokenName(r.token)===name):void 0)?.factory===factory,existingInstance=this.isGlobal&&factoryUnchanged?store.resolvedInstances.get(name):void 0;if(this.isGlobal&&!factoryUnchanged&&store.resolvedInstances.delete(name),this.registrations.set(token,createReg({target:Object,scope,factory,kind:`factory`,instance:existingInstance,resolveCount:+!!existingInstance,postConstructStatus:existingInstance?`completed`:`skipped`})),this.isGlobal){let idx=store.factories.findIndex(r=>tokenName(r.token)===name);idx>=0?store.factories[idx]={token,factory,scope}:store.factories.push({token,factory,scope})}this.emit(name,`registered`,`factory`)}registerInstance(token,instance){let store=getPersistentStore(),name=tokenName(token);if(this.registrations.set(token,createReg({target:instance.constructor,scope:`singleton`,instance,kind:`instance`,postConstructStatus:`completed`,resolveCount:1,firstResolvedAt:Date.now(),lastResolvedAt:Date.now()})),this.isGlobal){store.resolvedInstances.set(name,instance);let idx=store.instances.findIndex(r=>tokenName(r.token)===name);idx>=0?store.instances[idx]={token,instance}:store.instances.push({token,instance})}this.emit(name,`registered`,`instance`)}has(token){return this.registrations.has(token)}getRegistrations(){let entries=[];for(let[token,reg]of this.registrations)entries.push({token:tokenName(token),scope:reg.scope,kind:reg.kind,instantiated:reg.scope===`singleton`?reg.instance!==void 0:reg.resolveCount>0,resolveCount:reg.resolveCount,lastResolvedAt:reg.lastResolvedAt,firstResolvedAt:reg.firstResolvedAt,resolveDurationMs:reg.resolveDurationMs,postConstructStatus:reg.postConstructStatus,dependencies:reg.dependencies});return entries}resolve(token){let reg=this.registrations.get(token);if(!reg&&typeof token==`function`&&token.name&&(reg=this.registrations.get(`__hmr__${token.name}`)),!reg)throw noProviderError(tokenName(token));if(reg.scope===`singleton`&&reg.instance!==void 0)return reg.resolveCount++,reg.lastResolvedAt=Date.now(),this.emit(token,`resolved`,reg.kind),reg.instance;if(reg.scope===`request`){if(!Container._requestStoreProvider)throw requestScopeMiddlewareMissingError(tokenName(token));let store=Container._requestStoreProvider();if(!store)throw requestScopeOutsideRequestError(tokenName(token));if(store.values.has(token))return reg.resolveCount++,reg.lastResolvedAt=Date.now(),this.emit(token,`resolved`,reg.kind),store.values.get(token);if(store.instances.has(token))return reg.resolveCount++,reg.lastResolvedAt=Date.now(),this.emit(token,`resolved`,reg.kind),store.instances.get(token);if(reg.factory){let start=performance.now(),instance=reg.factory();return reg.resolveDurationMs=performance.now()-start,reg.resolveCount++,reg.lastResolvedAt=Date.now(),reg.firstResolvedAt||=Date.now(),store.instances.set(token,instance),this.emit(token,`resolved`,reg.kind),instance}let start=performance.now(),instance=this.createInstance(reg);return reg.resolveDurationMs=performance.now()-start,reg.resolveCount++,reg.lastResolvedAt=Date.now(),reg.firstResolvedAt||=Date.now(),store.instances.set(token,instance),this.emit(token,`resolved`,reg.kind),instance}if(reg.factory){let start=performance.now(),instance=reg.factory();return reg.resolveDurationMs=performance.now()-start,reg.resolveCount++,reg.lastResolvedAt=Date.now(),reg.firstResolvedAt||=Date.now(),reg.scope===`singleton`&&(reg.instance=instance,this.isGlobal&&getPersistentStore().resolvedInstances.set(tokenName(token),instance)),this.emit(token,`resolved`,reg.kind),instance}if(this.resolving.has(token)){let chain=[...this.resolving].map(tokenName);throw chain.push(tokenName(token)),Error(`Circular dependency detected: ${chain.join(` -> `)}`)}this.resolving.add(token);try{let start=performance.now(),instance=this.createInstance(reg);return reg.resolveDurationMs=performance.now()-start,reg.resolveCount++,reg.lastResolvedAt=Date.now(),reg.firstResolvedAt||=Date.now(),reg.scope===`singleton`&&(reg.instance=instance),this.emit(token,`resolved`,reg.kind),instance}finally{this.resolving.delete(token)}}bootstrap(){}onChange(callback){return this.changeListeners.add(callback),()=>this.changeListeners.delete(callback)}invalidate(token){let name=tokenName(token),reg=this.registrations.get(token)??this.registrations.get(`__hmr__${name}`);if(reg&&!getPersistentStore().resolvedInstances.has(name)){reg.instance=void 0,reg.resolveCount=0,reg.postConstructStatus=`skipped`,this.emit(name,`invalidated`,reg.kind);for(let[depToken,depReg]of this.registrations)depReg.dependencies.includes(name)&&this.invalidate(depToken)}}emit(rawToken,event,kind){if(this.changeListeners.size===0)return;let token=tokenName(rawToken),existing=this.pendingChanges.find(p=>p.token===token&&p.event===event);existing?existing.timestamp=Date.now():this.pendingChanges.push({token,event,kind,timestamp:Date.now()}),this.notifyTimer&&clearTimeout(this.notifyTimer),this.notifyTimer=setTimeout(()=>{let batch=this.pendingChanges.splice(0);if(batch.length!==0)for(let listener of this.changeListeners)try{listener(batch)}catch{}},Container.DEBOUNCE_MS),this.notifyTimer.unref?.()}flushChanges(){this.notifyTimer&&=(clearTimeout(this.notifyTimer),null);let batch=this.pendingChanges.splice(0);if(batch.length!==0)for(let listener of this.changeListeners)try{listener(batch)}catch{}}buildPlan(reg){let paramTypes=getClassMeta(METADATA.PARAM_TYPES,reg.target,[]),injectTokens=getMetaRecord(METADATA.INJECT,reg.target),maxInjectIndex=Object.keys(injectTokens).length>0?Math.max(...Object.keys(injectTokens).map(Number))+1:0,paramCount=Math.max(paramTypes.length,maxInjectIndex),ctorTokens=[];for(let index=0;index<paramCount;index++){let token=injectTokens[index]||paramTypes[index];if(!token)throw Error(`Cannot resolve constructor parameter at index ${index} of ${tokenName(reg.target)}. No @Inject token and no design:paramtypes metadata (tsx/ts-node don't emit it). Add @Inject(Token) to every constructor parameter.`);if(reg.scope===`singleton`){let depReg=this.registrations.get(token);if(depReg&&depReg.scope===`request`)throw Error(`Cannot inject REQUEST-scoped "${tokenName(token)}" into SINGLETON "${tokenName(reg.target)}". Singletons outlive requests. Use TRANSIENT or REQUEST scope for the parent.`)}ctorTokens.push(token)}let autowiredProps=getMetaMap(METADATA.AUTOWIRED,reg.target.prototype),autowired=[];for(let[prop,token]of autowiredProps){let resolvedToken=token||getMethodMetaOrUndefined(METADATA.PROPERTY_TYPE,reg.target.prototype,prop);resolvedToken&&autowired.push([prop,resolvedToken])}let values=[...getMetaMap(METADATA.VALUE,reg.target.prototype).entries()],assetProps=getMetaMap(METADATA.ASSET,reg.target.prototype),assets=[];for(let[prop,config]of assetProps){let slashIdx=config.assetKey.indexOf(`/`);if(slashIdx===-1)throw Error(`@Asset('${config.assetKey}'): asset key must include a '/' separator (e.g. 'mails/welcome').`);assets.push([prop,{namespace:config.assetKey.slice(0,slashIdx),key:config.assetKey.slice(slashIdx+1)}])}return{ctorTokens,autowired,values,assets,postConstruct:getClassMetaOrUndefined(METADATA.POST_CONSTRUCT,reg.target.prototype)}}createInstance(reg){let plan=reg.plan??=this.buildPlan(reg),args=[];for(let token of plan.ctorTokens)args.push(this.resolve(token));let instance=new reg.target(...args);this.injectProperties(instance,plan);let postConstruct=plan.postConstruct;if(postConstruct&&typeof instance[postConstruct]==`function`)try{let result=instance[postConstruct]();result&&typeof result.then==`function`?(reg.postConstructStatus=`pending`,result.then(()=>{reg.postConstructStatus=`completed`}).catch(()=>{reg.postConstructStatus=`failed`}),log.warn(`@PostConstruct on ${tokenName(reg.target)}.${String(postConstruct)}() returned a Promise but the container is synchronous. The async operation will not be awaited.`)):reg.postConstructStatus=`completed`}catch(err){reg.postConstructStatus=`failed`,log.error(err,`@PostConstruct on ${tokenName(reg.target)}.${String(postConstruct)}() threw an error`)}return instance}extractDependencies(target){let paramTypes=getClassMeta(METADATA.PARAM_TYPES,target,[]),injectTokens=getMetaRecord(METADATA.INJECT,target),ctorDeps=paramTypes.map((type,index)=>tokenName(injectTokens[index]||type)),autowiredProps=getMetaMap(METADATA.AUTOWIRED,target.prototype),propDeps=[];for(let[prop,token]of autowiredProps){let resolvedToken=token||getMethodMetaOrUndefined(METADATA.PROPERTY_TYPE,target.prototype,prop);resolvedToken&&propDeps.push(tokenName(resolvedToken))}return[...new Set([...ctorDeps,...propDeps])]}injectProperties(instance,plan){for(let[prop,resolvedToken]of plan.autowired)Object.defineProperty(instance,prop,{get:()=>{let value=this.resolve(resolvedToken);return this.registrations.get(resolvedToken)?.scope===`singleton`&&Object.defineProperty(instance,prop,{value,enumerable:!0,configurable:!0,writable:!1}),value},enumerable:!0,configurable:!0});for(let[prop,config]of plan.values)Object.defineProperty(instance,prop,{get(){if(Container._envResolver){let val=Container._envResolver(config.envKey);if(val!==void 0)return val}let val=process.env[config.envKey];if(val!==void 0)return val;if(config.defaultValue!==void 0)return config.defaultValue;throw envValueMissingError(config.envKey)},enumerable:!0,configurable:!0});for(let[prop,{namespace,key}]of plan.assets)Object.defineProperty(instance,prop,{get(){return resolveAssetViaSlot(namespace,key)},enumerable:!0,configurable:!0})}};export{isInjectionToken as a,KickError as c,createToken as i,formatKickError as l,tokenName as n,duplicateRouteError as o,INJECTION_TOKEN as r,moduleRouteMissingControllerError as s,Container as t,_setAssetResolver as u};
+//# sourceMappingURL=container-jtn5BmL5.mjs.map

package/dist/container-jtn5BmL5.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-jtn5BmL5.mjs","names":["resolveAsset"],"sources":["../src/core/asset-resolver-slot.ts","../src/core/kick-error.ts","../src/core/kick-errors.ts","../src/core/token.ts","../src/core/container.ts"],"sourcesContent":["/**\n * Indirection slot between the DI container's `@Asset` property injection\n * and the asset manager. The container must NOT import `./assets` directly —\n * its eager `node:fs`/`node:path` imports would poison the edge-safe\n * `@forinda/kickjs/web` entry graph (every graph includes the container).\n *\n * `./assets` registers the real resolver at module scope, so any node app\n * that imports the asset manager (the core barrel does) gets full `@Asset`\n * behavior; an edge bundle that never imports it gets a clear error on\n * first `@Asset` property access instead of a broken bundle.\n */\n\ntype AssetResolver = (namespace: string, key: string) => unknown\n\nlet impl: AssetResolver | null = null\n\n/** Called by `./assets` at module scope to install the real resolver. */\nexport function _setAssetResolver(fn: AssetResolver): void {\n  impl = fn\n}\n\n/** Resolve an asset through the slot — throws when no asset manager is loaded. */\nexport function resolveAssetViaSlot(namespace: string, key: string): unknown {\n  if (!impl) {\n    throw new Error(\n      `@Asset('${namespace}/${key}'): the asset manager is not loaded. ` +\n        \"Import it (any import from '@forinda/kickjs' loads it) — note @Asset \" +\n        'reads from the filesystem and is not supported on edge runtimes.',\n    )\n  }\n  return impl(namespace, key)\n}\n","/**\n * Structured framework error with code, cause, and actionable fix hint.\n *\n * The goal is \"the developer who hits this knows what to do next.\" A\n * cryptic `Error('No binding found for: UserService')` becomes a\n * multi-line explanation pointing at the likely cause, the exact code\n * change to apply, and a docs link.\n *\n * `.message` carries the full multi-line plain-text body so Node's\n * default `Error.toString()` and unhandled-exception printing still\n * surface the helpful version. Call {@link formatKickError} to render a\n * colorized version for terminals.\n *\n * Per-error factories live in `kick-errors.ts` — those are the public\n * entry points framework code uses. `KickError` is exported so adopters\n * can build their own structured errors using the same shape.\n */\nexport interface KickErrorInit {\n  /** Short stable identifier (e.g. `KICK001`, `NO_PROVIDER`). */\n  code: string\n  /** One-line headline. */\n  summary: string\n  /** Multi-line explanation of why this happened. */\n  cause?: string\n  /** Multi-line actionable fix — show exact code if possible. */\n  fix?: string\n  /** Absolute URL to the docs page that covers this error. */\n  docsUrl?: string\n  /** Arbitrary structured fields for log consumers / debug tooling. */\n  context?: Record<string, unknown>\n}\n\nexport class KickError extends Error {\n  public readonly code: string\n  public readonly summary: string\n  public readonly cause?: string\n  public readonly fix?: string\n  public readonly docsUrl?: string\n  public readonly context?: Record<string, unknown>\n\n  constructor(init: KickErrorInit) {\n    super(formatKickError(init, { color: false }))\n    this.name = 'KickError'\n    this.code = init.code\n    this.summary = init.summary\n    if (init.cause !== undefined) this.cause = init.cause\n    if (init.fix !== undefined) this.fix = init.fix\n    if (init.docsUrl !== undefined) this.docsUrl = init.docsUrl\n    if (init.context !== undefined) this.context = init.context\n  }\n}\n\n// ── ANSI colour helpers ────────────────────────────────────────────────\n\n/**\n * `true` when the runtime can render ANSI escape codes on stderr.\n * Honors `NO_COLOR` (https://no-color.org) and `FORCE_COLOR`.\n */\nfunction ansiEnabled(): boolean {\n  if (process.env.NO_COLOR) return false\n  if (process.env.FORCE_COLOR) return true\n  // Node sets `isTTY` on the writable streams when stdout/stderr is a\n  // terminal. KickError output goes to stderr conceptually (it's an\n  // error), so we follow that stream's affordances.\n  return process.stderr?.isTTY === true\n}\n\n// Use the Unicode-escape form (`\u001b`) rather than the hex-escape (`\\x1b`)\n// for the ANSI ESC byte — both produce the same character, but oxlint's\n// `no-control-character` rule flags the hex form as \"unexpected control\n// character in string literal\". Functionally identical, lint-clean.\nconst ESC = '\u001b['\nconst RESET = `${ESC}0m`\n\nfunction paint(text: string, code: string, enabled: boolean): string {\n  return enabled ? `${ESC}${code}m${text}${RESET}` : text\n}\n\nconst c = {\n  red: (s: string, enabled: boolean) => paint(s, '31', enabled),\n  bold: (s: string, enabled: boolean) => paint(s, '1', enabled),\n  dim: (s: string, enabled: boolean) => paint(s, '2', enabled),\n  cyan: (s: string, enabled: boolean) => paint(s, '36', enabled),\n  blue: (s: string, enabled: boolean) => paint(s, '34', enabled),\n  underline: (s: string, enabled: boolean) => paint(s, '4', enabled),\n}\n\n// ── Formatter ─────────────────────────────────────────────────────────\n\nexport interface FormatKickErrorOptions {\n  /**\n   * Render ANSI colour codes. Defaults to TTY detection (`NO_COLOR` /\n   * `FORCE_COLOR` env vars honoured). Pass `false` for log files,\n   * structured loggers, or HTTP response bodies.\n   */\n  color?: boolean\n}\n\n/**\n * Render a {@link KickErrorInit} (or {@link KickError} instance) into a\n * multi-line human-readable string. Identical layout regardless of\n * colour — the colour flag only toggles ANSI codes.\n */\nexport function formatKickError(\n  err: KickErrorInit | KickError,\n  options: FormatKickErrorOptions = {},\n): string {\n  const color = options.color ?? ansiEnabled()\n  const lines: string[] = []\n\n  // Headline: `KICK001: No provider for UserService`\n  const code = c.bold(c.red(err.code, color), color)\n  lines.push(`${code}: ${err.summary}`)\n\n  if (err.cause) {\n    lines.push('', `  ${c.bold(c.dim('Cause:', color), color)}`)\n    for (const line of err.cause.split('\\n')) {\n      lines.push(`    ${highlightInline(line, color)}`)\n    }\n  }\n\n  if (err.fix) {\n    lines.push('', `  ${c.bold(c.dim('Fix:', color), color)}`)\n    for (const line of err.fix.split('\\n')) {\n      lines.push(`    ${highlightInline(line, color)}`)\n    }\n  }\n\n  if (err.docsUrl) {\n    lines.push('', `  ${c.bold(c.dim('Docs:', color), color)}`)\n    lines.push(`    ${c.underline(c.blue(err.docsUrl, color), color)}`)\n  }\n\n  return lines.join('\\n')\n}\n\n/**\n * Highlight inline `code spans` in a line of cause/fix text. Anything\n * between backticks gets cyan when colour is enabled; backticks stay\n * in the output so the plain-text rendering still distinguishes\n * literals.\n */\nfunction highlightInline(line: string, color: boolean): string {\n  if (!color) return line\n  return line.replace(/`([^`]+)`/g, (_, inner: string) => `\\`${c.cyan(inner, true)}\\``)\n}\n","/**\n * Catalog of framework errors with structured cause + fix hints.\n *\n * Each factory function returns a {@link KickError} with a stable\n * `code` (KICK001, KICK002, …), a human-readable summary, an\n * explanation of the likely cause, an actionable fix, and a docs URL.\n *\n * Adding a new error: pick the next free code, add the factory below,\n * call it from the framework site that used to throw a bare `Error`.\n * Keep the public function name descriptive — `noProviderError`,\n * `envValueMissingError` — so call sites grep cleanly.\n *\n * Codes are stable. Reordering or renumbering breaks adopters whose\n * tools key on `err.code`.\n */\nimport { KickError } from './kick-error'\n\nconst DOCS_BASE = 'https://kickjs.app'\n\n// ── DI container ──────────────────────────────────────────────────────\n\n/**\n * KICK001 — No provider registered for a token.\n *\n * Thrown by `Container.resolve()` when no binding can be found for the\n * requested token. The most common cause is forgetting to add the\n * enclosing module to `bootstrap({ modules })`.\n */\nexport function noProviderError(tokenName: string): KickError {\n  return new KickError({\n    code: 'KICK001',\n    summary: `No provider for ${tokenName}`,\n    cause: `\\`${tokenName}\\` was requested from the DI container but no binding is registered.\nThis usually means one of:\n  • The class is decorated with @Service() / @Repository() / @Controller(),\n    but its enclosing module isn't passed to bootstrap({ modules: [...] }).\n  • The class isn't decorated at all (decorators register the binding).\n  • You're injecting a token (created with createToken()) that nothing\n    provides — add a Container.register(TOKEN, ...) call or a module that\n    binds it.`,\n    fix: `If \\`${tokenName}\\` lives in a module, add the module to bootstrap:\n\n      bootstrap({\n        modules: [\n          UsersModule,        // add this\n          OtherModule,\n        ],\n      })\n\nIf it's a custom token, register it explicitly:\n\n      const TENANT_REPO = createToken<TenantRepo>('TENANT_REPO')\n      Container.getInstance().register(TENANT_REPO, { useClass: PrismaTenantRepo })`,\n    docsUrl: `${DOCS_BASE}/guide/dependency-injection#registering-services`,\n    context: { token: tokenName },\n  })\n}\n\n/**\n * KICK002 — REQUEST-scoped binding resolved without a request store\n * provider configured.\n */\nexport function requestScopeMiddlewareMissingError(tokenName: string): KickError {\n  return new KickError({\n    code: 'KICK002',\n    summary: `Cannot resolve REQUEST-scoped \"${tokenName}\" — request scope middleware not mounted`,\n    cause: `\\`${tokenName}\\` has \\`scope: Scope.REQUEST\\` but no AsyncLocalStorage frame is wired.\nThe framework's request-scope middleware sets up that frame; without it,\nREQUEST-scoped resolutions have nowhere to cache the per-request instance.`,\n    fix: `Add \\`requestScopeMiddleware()\\` to your global middleware pipeline,\nor let the framework auto-mount it by using \\`contextStore: 'auto'\\`\n(the default — only check this if you set it to 'manual' explicitly):\n\n      bootstrap({\n        modules,\n        // contextStore: 'auto',  // default; no need to set\n      })\n\nIf you set \\`contextStore: 'manual'\\` deliberately (rare), you own the\nALS wrapping — call \\`requestStore.run({...}, () => ...)\\` around the\ncode that resolves the binding.`,\n    docsUrl: `${DOCS_BASE}/guide/dependency-injection#scopes`,\n    context: { token: tokenName },\n  })\n}\n\n/**\n * KICK003 — REQUEST-scoped binding resolved outside any HTTP request\n * context (no ALS store active).\n */\nexport function requestScopeOutsideRequestError(tokenName: string): KickError {\n  return new KickError({\n    code: 'KICK003',\n    summary: `Cannot resolve REQUEST-scoped \"${tokenName}\" outside an HTTP request`,\n    cause: `\\`${tokenName}\\` has \\`scope: Scope.REQUEST\\` and was resolved outside\nany HTTP request context. The request-scope middleware is wired, but\nthe call happened before a request started (e.g. in a top-level\nimport, a constructor, a cron job, a test without setup).`,\n    fix: `If the caller is request-scoped (controller, request-scoped service),\nmake sure the call happens inside the request lifecycle, not at module\nload time.\n\nIn tests, wrap setup in an ALS frame manually:\n\n      import { requestStore } from '@forinda/kickjs'\n\n      requestStore.run(\n        { requestId: 'test', instances: new Map(), values: new Map() },\n        () => {\n          const svc = container.resolve(MyRequestScopedService)\n          // ...\n        },\n      )\n\nIf the caller is a SINGLETON, change \\`${tokenName}\\` to TRANSIENT or\nSINGLETON scope, or inject a factory instead of the instance directly.`,\n    docsUrl: `${DOCS_BASE}/guide/dependency-injection#scopes`,\n    context: { token: tokenName },\n  })\n}\n\n// ── Config / env wiring ───────────────────────────────────────────────\n\n/**\n * KICK004 — `@Value('X')` resolved but the env var isn't set and no\n * default was provided.\n *\n * This is the canonical \"you forgot to wire env\" symptom — surfaces\n * when ConfigService can't find the key. The fix usually involves\n * either setting the env var or wiring `loadEnv(envSchema)` at startup.\n */\nexport function envValueMissingError(envKey: string): KickError {\n  return new KickError({\n    code: 'KICK004',\n    summary: `@Value('${envKey}'): environment variable not set and no default provided`,\n    cause: `\\`@Value('${envKey}')\\` resolved but the env var isn't present and the\ndecorator didn't declare a default. Possible reasons:\n  • The variable is genuinely missing from your environment / .env file.\n  • Your \\`src/env.ts\\` calls \\`loadEnv(envSchema)\\` but \\`src/index.ts\\`\n    doesn't import \\`./env\\` before \\`bootstrap()\\`. Without that import\n    the schema never runs and ConfigService stays empty — \\`@Value\\`\n    only finds the var via the \\`process.env\\` fallback.`,\n    fix: `Either set the variable in your shell / .env file:\n\n      ${envKey}=...\n\nOr add a default at the decorator:\n\n      @Value('${envKey}', { default: 'fallback' })\n      private value!: string\n\nIf you're using a schema, make sure \\`src/env.ts\\` is imported from\n\\`src/index.ts\\` BEFORE bootstrap runs:\n\n      // src/index.ts\n      import 'reflect-metadata'\n      import './env'                  // ← this line is required\n      import { bootstrap } from '@forinda/kickjs'\n      // ...`,\n    docsUrl: `${DOCS_BASE}/guide/configuration#wiring-the-schema-at-startup`,\n    context: { envKey },\n  })\n}\n\n// ── Module setup ──────────────────────────────────────────────────────\n\n/**\n * KICK005 — A module's `routes()` return value declares a mount path\n * but provides neither a `controller` class nor a pre-built `router`.\n */\nexport function moduleRouteMissingControllerError(mountPath: string): KickError {\n  return new KickError({\n    code: 'KICK005',\n    summary: `Module route at ${mountPath} requires either 'controller' or 'router'`,\n    cause: `A module's \\`routes()\\` returned an entry for \\`${mountPath}\\` but didn't\nspecify how to build the router. The framework needs either a decorated\ncontroller class (it calls \\`buildRoutes()\\` internally) or a hand-built\nExpress Router.`,\n    fix: `Pass \\`controller:\\` for the common case:\n\n      routes() {\n        return {\n          path: '${mountPath}',\n          controller: UsersController,\n        }\n      }\n\nOr pass \\`router:\\` for full control:\n\n      routes() {\n        return {\n          path: '${mountPath}',\n          router: myExpressRouter,\n        }\n      }`,\n    docsUrl: `${DOCS_BASE}/guide/modules`,\n    context: { mountPath },\n  })\n}\n\n/**\n * KICK006 — Two handlers claim the same HTTP verb + mounted path. The\n * engine would silently dispatch one of them (Express/h3: first wins,\n * Fastify: its own throw), while typegen and the typed client may\n * describe the other — so this fails at boot instead.\n */\nexport function duplicateRouteError(\n  method: string,\n  path: string,\n  owner: string,\n  prior: string,\n): KickError {\n  return new KickError({\n    code: 'KICK006',\n    summary: `Duplicate route: ${method} ${path} is registered twice`,\n    cause: `\\`${owner}\\` registers \\`${method} ${path}\\`, but that verb + path is\nalready claimed by \\`${prior}\\`. Only one handler can win at dispatch\ntime, and which one depends on the engine — while \\`kick typegen\\` and\nthe typed client may describe the other. Param names are ignored when\ncomparing (\\`/:id\\` and \\`/:taskId\\` are the same route).`,\n    fix: `Change one of the two paths, remove the duplicate handler, or mount\nthe second controller under a different module path / version:\n\n      routes() {\n        return { path: '/tasks', controller: TasksController, version: 2 }\n      }`,\n    docsUrl: `${DOCS_BASE}/guide/modules`,\n    context: { method, path, owner, prior },\n  })\n}\n","/**\n * Collision-safe injection tokens with phantom type parameters.\n *\n * `createToken<T>(name)` is the recommended way to declare any DI token\n * that isn't a class. Each call returns a unique frozen object — even if\n * two files write `createToken<X>('Logger')`, they produce two distinct\n * references that the container treats as different tokens. Collisions\n * become impossible by construction, not by convention.\n *\n * The phantom type parameter `T` lets `container.resolve(token)` infer\n * the correct return type without any codegen.\n *\n * ## Hardening layers\n *\n * KickJS has four DI token kinds, listed from safest to riskiest:\n *\n * 1. **Class identity** — `container.resolve(UserService)`. Reference\n *    equality, never collides. Type-safe via `Constructor<T>` overload.\n * 2. **`createToken<T>(name)`** — frozen object identity, never collides.\n *    Type-safe via the `InjectionToken<T>` overload.\n * 3. **Symbol** — `Symbol('foo')` is unique per call but `Symbol.for('foo')`\n *    is interned and CAN collide. Discouraged.\n * 4. **Raw string `@Inject('foo')`** — high collision risk, untyped.\n *    Reserved for legacy code and runtime-computed token names.\n *\n * Prefer (1) and (2). Use (4) only when you have to.\n *\n * @example\n * ```ts\n * // src/tokens.ts\n * export const DATABASE_URL = createToken<string>('config.database.url')\n * export const FEATURE_FLAGS = createToken<FeatureFlags>('app.features')\n *\n * // bootstrap\n * container.registerInstance(DATABASE_URL, process.env.DATABASE_URL!)\n *\n * // anywhere else\n * const url = container.resolve(DATABASE_URL) // typed as `string`\n * ```\n *\n * @module @forinda/kickjs/core/token\n */\n\n/**\n * Symbol marker stamped on every InjectionToken so the container can\n * detect them at runtime regardless of which package created them.\n *\n * Uses `Symbol.for()` so cross-package isolation (different copies of\n * `@forinda/kickjs` loaded under different module identities) still\n * shares the same marker.\n */\nexport const INJECTION_TOKEN: unique symbol = Symbol.for('@kickjs/InjectionToken') as never\n\n/**\n * A type-safe DI token. Each `createToken()` call returns a unique frozen\n * object identified by reference, not by the `name` string. Two\n * `createToken<X>('foo')` calls in different files produce two distinct\n * tokens that the container treats independently.\n *\n * The phantom `_type` parameter is never assigned at runtime — it exists\n * solely to thread the type through `container.resolve(token)`.\n */\nexport interface InjectionToken<T> {\n  readonly [INJECTION_TOKEN]: true\n  /** Descriptive name used in error messages, logs, and devtools */\n  readonly name: string\n  /** Phantom — never assigned at runtime */\n  readonly _type?: T\n}\n\n/**\n * Create a collision-safe injection token.\n *\n * The returned token is a frozen object identified by reference, not by\n * the `name` string. The `name` is used only for error messages, logs,\n * and debugging.\n */\nexport function createToken<T>(name: string): InjectionToken<T> {\n  return Object.freeze({\n    [INJECTION_TOKEN]: true as const,\n    name,\n  })\n}\n\n/** Type guard — returns `true` if `value` is an InjectionToken */\nexport function isInjectionToken(value: unknown): value is InjectionToken<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    (value as Record<symbol, unknown>)[INJECTION_TOKEN] === true\n  )\n}\n","import 'reflect-metadata'\nimport {\n  Constructor,\n  Scope,\n  METADATA,\n  type ClassKind,\n  type PostConstructStatus,\n} from './interfaces'\n// Slot indirection, NOT `./assets` — that module's eager node:fs import\n// would poison the edge-safe web entry graph (see asset-resolver-slot.ts).\nimport { resolveAssetViaSlot as resolveAsset } from './asset-resolver-slot'\nimport {\n  envValueMissingError,\n  noProviderError,\n  requestScopeMiddlewareMissingError,\n  requestScopeOutsideRequestError,\n} from './kick-errors'\nimport { createLogger } from './logger'\nimport {\n  getClassMeta,\n  getClassMetaOrUndefined,\n  getMetaMap,\n  getMetaRecord,\n  getMethodMetaOrUndefined,\n} from './metadata'\nimport { isInjectionToken, type InjectionToken } from './token'\n\nconst log = createLogger('Container')\n\n/** Internal registration entry that tracks how a dependency should be resolved */\ninterface Registration {\n  target: Constructor\n  scope: Scope\n  instance?: any\n  factory?: () => any\n  // Observability fields\n  kind: ClassKind\n  resolveCount: number\n  lastResolvedAt?: number\n  firstResolvedAt?: number\n  resolveDurationMs?: number\n  postConstructStatus: PostConstructStatus\n  dependencies: string[]\n  /** Lazily built instantiation plan — see {@link Container.buildPlan}. */\n  plan?: InstantiationPlan\n}\n\n/**\n * Precomputed instantiation recipe for a class. Class metadata is immutable\n * after definition, so the Reflect reads (5 per create) and the derived\n * structures only need computing ONCE — previously they re-ran on every\n * REQUEST-scoped resolve (i.e. every request) and every TRANSIENT resolve.\n */\ninterface InstantiationPlan {\n  /** Ordered, validated constructor parameter tokens. */\n  ctorTokens: any[]\n  /** `@Autowired` properties: [property, resolved token]. */\n  autowired: Array<[string, any]>\n  /** `@Value` properties: [property, env config]. */\n  values: Array<[string, { envKey: string; defaultValue?: any }]>\n  /** `@Asset` properties: [property, pre-split namespace/key]. */\n  assets: Array<[string, { namespace: string; key: string }]>\n  /** `@PostConstruct` method name, if any. */\n  postConstruct?: string | symbol\n}\n\n/** Create a Registration with observability defaults */\nfunction createReg(\n  fields: Partial<Registration> & Pick<Registration, 'target' | 'scope'>,\n): Registration {\n  return {\n    kind: 'unknown',\n    resolveCount: 0,\n    postConstructStatus: 'skipped',\n    dependencies: [],\n    ...fields,\n  }\n}\n\n/** Format a token for display in error messages */\nexport function tokenName(token: any): string {\n  if (typeof token === 'symbol') return token.toString()\n  if (isInjectionToken(token)) return token.name\n  return token?.name || String(token)\n}\n\n// ── Persistent Store ────────────────────────────────────────────────────\n// globalThis-based storage that survives BOTH Container.reset() AND Vite's\n// ssrLoadModule() re-evaluation. When Vite re-evaluates a module, the\n// Container class gets a new identity (new statics). But globalThis persists.\n//\n// This is how DB connections, Redis clients, WsAdapter instances, and any\n// other stateful bindings survive HMR without being dropped.\n//\n// Pattern from: React Router (globalThis for state), Vinxi (globalThis.app)\n\n// ── Change Event System ─────────────────────────────────────────────────\n// Batched (50ms debounce) so `kick g module` creating 10+ files emits ONE\n// notification, not 10. Any adapter can subscribe: Swagger, DevTools, WS, etc.\n\n/** A single container change event */\nexport interface ContainerChangeEvent {\n  token: string\n  event: 'registered' | 'resolved' | 'invalidated'\n  kind?: ClassKind\n  timestamp: number\n}\n\n/** Listener that receives batched change events */\nexport type ContainerChangeListener = (changes: ContainerChangeEvent[]) => void\n\n/**\n * Type-safe registry of string DI tokens. Augmented by `kick typegen` —\n * the generated `.kickjs/types/registry.d.ts` adds entries like:\n *\n * ```ts\n * declare module '@forinda/kickjs' {\n *   interface KickJsRegistry {\n *     UserService: import('../../src/modules/users/user.service').UserService\n *   }\n * }\n * ```\n *\n * Once typegen has run, `container.resolve('UserService')` returns the\n * correct type instead of `any`. Class-token resolution\n * (`container.resolve(UserService)`) is already type-safe via the\n * `Constructor<T>` overload and does not need typegen.\n */\nexport interface KickJsRegistry {}\n\ninterface PersistentStore {\n  factories: Array<{ token: any; factory: () => any; scope: Scope }>\n  instances: Array<{ token: any; instance: any }>\n  /** Resolved instances keyed by string name — survives class identity changes */\n  resolvedInstances: Map<string, any>\n}\n\nfunction getPersistentStore(): PersistentStore {\n  if (!(globalThis as any).__kickjs_persistent) {\n    ;(globalThis as any).__kickjs_persistent = {\n      factories: [],\n      instances: [],\n      resolvedInstances: new Map(),\n    } satisfies PersistentStore\n  }\n  return (globalThis as any).__kickjs_persistent\n}\n\n/**\n * Inversion-of-Control (IoC) container that manages dependency registration,\n * resolution, and lifecycle. Implements the Singleton pattern so all parts of\n * the application share a single container instance.\n *\n * Supports constructor injection, property injection (@Autowired),\n * factory registrations, and lifecycle hooks (@PostConstruct).\n *\n * Persistent state (DB connections, Redis, etc.) is stored on globalThis so\n * it survives both Container.reset() and Vite module re-evaluation.\n */\nexport class Container {\n  private static instance: Container\n  private registrations = new Map<any, Registration>()\n  private resolving = new Set<any>()\n\n  // ── Reactive change tracking ──────────────────────────────────────\n  private changeListeners = new Set<ContainerChangeListener>()\n  private pendingChanges: ContainerChangeEvent[] = []\n  private notifyTimer: ReturnType<typeof setTimeout> | null = null\n  private static readonly DEBOUNCE_MS = 50\n\n  /** Callback set by the decorators module to flush pending registrations */\n  static _onReady: ((container: Container) => void) | null = null\n  /** Callback invoked on reset so decorators can update their container reference */\n  static _onReset: ((container: Container) => void) | null = null\n\n  /**\n   * Seeds a NEWLY CREATED container with the decorator registrations, without\n   * adopting it as the global one. `_onReset` does both; an isolated container\n   * must only have the first half, or it would capture every subsequent\n   * decorator registration in the process.\n   */\n  static _onCreate: ((container: Container) => void) | null = null\n  /**\n   * Environment resolver for @Value decorator. Set by the unified\n   * `@forinda/kickjs` config layer to return Zod-validated, type-coerced\n   * env values instead of raw process.env strings.\n   */\n  static _envResolver: ((key: string) => any) | null = null\n  /**\n   * Request store provider for REQUEST-scoped DI. Set by the HTTP layer\n   * inside `@forinda/kickjs` to return the current request's\n   * AsyncLocalStorage store. Returns { instances: Map, values: Map } or\n   * null if outside a request.\n   */\n  /**\n   * Whether this container is the global singleton.\n   *\n   * The persistent store exists to carry the GLOBAL container's registrations\n   * across HMR and module re-evaluation. An isolated container is per-test and\n   * must neither write to it — a `registerInstance` override was replayed into\n   * every later `Container.reset()` — nor read from it, which would pull global\n   * state into a container created to be free of it.\n   */\n  private isGlobal = false\n\n  static _requestStoreProvider:\n    | (() => { instances: Map<any, any>; values: Map<any, any> } | null)\n    | null = null\n\n  static getInstance(): Container {\n    if (!Container.instance) {\n      Container.instance = new Container()\n      Container.instance.isGlobal = true\n    }\n    // Flush any decorator registrations that queued before the container existed\n    if (Container._onReady) {\n      Container._onReady(Container.instance)\n      Container._onReady = null\n    }\n    return Container.instance\n  }\n\n  /**\n   * Resets the container by replacing the singleton with a fresh instance.\n   * Persistent registrations (DB, Redis, etc.) are replayed from globalThis\n   * so they survive both reset() and Vite module re-evaluation.\n   */\n  static reset(): void {\n    Container.instance = new Container()\n    Container.instance.isGlobal = true\n    // Notify decorators so they update their container reference\n    Container._onReset?.(Container.instance)\n    // Replay persistent registrations from globalThis store\n    const store = getPersistentStore()\n    for (const { token, factory, scope } of store.factories) {\n      if (!Container.instance.has(token)) {\n        // Check if we have a previously resolved instance for this token\n        const name = tokenName(token)\n        const existing = store.resolvedInstances.get(name)\n        Container.instance.registrations.set(\n          token,\n          createReg({\n            target: Object as any,\n            scope,\n            factory,\n            kind: 'factory',\n            instance: existing, // Reuse resolved instance if available\n            resolveCount: existing ? 1 : 0,\n            postConstructStatus: existing ? 'completed' : 'skipped',\n          }),\n        )\n      }\n    }\n    for (const { token, instance } of store.instances) {\n      if (!Container.instance.has(token)) {\n        Container.instance.registrations.set(\n          token,\n          createReg({\n            target: instance.constructor,\n            scope: Scope.SINGLETON,\n            instance,\n            kind: 'instance',\n            postConstructStatus: 'completed',\n            resolveCount: 1,\n          }),\n        )\n      }\n    }\n  }\n\n  /**\n   * Create an isolated container instance (not the global singleton).\n   * Useful for concurrent tests that must not share DI state.\n   *\n   * @example\n   * ```ts\n   * const container = Container.create()\n   * container.register(UserService, UserService)\n   * const svc = container.resolve(UserService)\n   * ```\n   */\n  static create(): Container {\n    const container = new Container()\n    // Decorators register at class-definition time, into whichever container\n    // was global then. Without this replay an isolated container is missing\n    // every @Service / @Repository / @Controller in the process — and\n    // `isolated: true` is what the generated docs recommend for test\n    // isolation, so the failure reached adopters as `No provider for X`.\n    Container._onCreate?.(container)\n    return container\n  }\n\n  /** Register a class constructor under the given token */\n  register(token: any, target: Constructor, scope: Scope = Scope.SINGLETON): void {\n    const kind = getClassMeta<ClassKind>(METADATA.CLASS_KIND, target, 'unknown')\n    const dependencies = this.extractDependencies(target)\n    const reg = createReg({ target, scope, kind, dependencies })\n    this.registrations.set(token, reg)\n    // Store a name-based fallback so HMR class re-creation (new identity)\n    // can still resolve by the original class name.\n    if (typeof token === 'function' && token.name) {\n      this.registrations.set(`__hmr__${token.name}`, reg)\n    }\n    this.emit(token, 'registered', kind)\n  }\n\n  /** Register a factory function under the given token */\n  registerFactory(token: any, factory: () => any, scope: Scope = Scope.SINGLETON): void {\n    const store = getPersistentStore()\n    const name = tokenName(token)\n    // Check if we already have a resolved instance from a previous HMR cycle.\n    // Only reuse if the factory hasn't changed (same reference). When a new\n    // factory is provided (e.g. swapping implementations), clear the stale\n    // instance so the new factory runs on next resolve.\n    // Reads are global-only too. An isolated container adopting a cached\n    // instance from the global store would be contaminated on creation — the\n    // same leak, in the other direction.\n    const existingEntry = this.isGlobal\n      ? store.factories.find((r) => tokenName(r.token) === name)\n      : undefined\n    const factoryUnchanged = existingEntry?.factory === factory\n    const existingInstance =\n      this.isGlobal && factoryUnchanged ? store.resolvedInstances.get(name) : undefined\n\n    // Clear stale resolved instance when factory changes\n    if (this.isGlobal && !factoryUnchanged) {\n      store.resolvedInstances.delete(name)\n    }\n\n    this.registrations.set(\n      token,\n      createReg({\n        target: Object as any,\n        scope,\n        factory,\n        kind: 'factory',\n        instance: existingInstance,\n        resolveCount: existingInstance ? 1 : 0,\n        postConstructStatus: existingInstance ? 'completed' : 'skipped',\n      }),\n    )\n    // Track in globalThis for persistence across HMR + module re-evaluation —\n    // global container only, or an isolated container's factories are replayed\n    // into the next Container.reset().\n    if (this.isGlobal) {\n      const idx = store.factories.findIndex((r) => tokenName(r.token) === name)\n      if (idx >= 0) {\n        store.factories[idx] = { token, factory, scope }\n      } else {\n        store.factories.push({ token, factory, scope })\n      }\n    }\n    this.emit(name, 'registered', 'factory')\n  }\n\n  /** Register a pre-constructed singleton instance */\n  registerInstance(token: any, instance: any): void {\n    const store = getPersistentStore()\n    const name = tokenName(token)\n\n    this.registrations.set(\n      token,\n      createReg({\n        target: instance.constructor,\n        scope: Scope.SINGLETON,\n        instance,\n        kind: 'instance',\n        postConstructStatus: 'completed',\n        resolveCount: 1,\n        firstResolvedAt: Date.now(),\n        lastResolvedAt: Date.now(),\n      }),\n    )\n    // Track in globalThis for persistence across HMR + module re-evaluation —\n    // global container only. An isolated one that wrote here had its overrides\n    // replayed into the next Container.reset().\n    if (this.isGlobal) {\n      store.resolvedInstances.set(name, instance)\n      const idx = store.instances.findIndex((r) => tokenName(r.token) === name)\n      if (idx >= 0) {\n        store.instances[idx] = { token, instance }\n      } else {\n        store.instances.push({ token, instance })\n      }\n    }\n    this.emit(name, 'registered', 'instance')\n  }\n\n  /** Check if a binding exists for the given token */\n  has(token: any): boolean {\n    return this.registrations.has(token)\n  }\n\n  /** Return a snapshot of all registered tokens with their scope and instantiation status */\n  getRegistrations(): Array<{\n    token: string\n    scope: string\n    kind: ClassKind\n    instantiated: boolean\n    resolveCount: number\n    lastResolvedAt?: number\n    firstResolvedAt?: number\n    resolveDurationMs?: number\n    postConstructStatus: PostConstructStatus\n    dependencies: string[]\n  }> {\n    const entries: Array<ReturnType<Container['getRegistrations']>[number]> = []\n    for (const [token, reg] of this.registrations) {\n      entries.push({\n        token: tokenName(token),\n        scope: reg.scope,\n        kind: reg.kind,\n        // Singletons check cached instance; transients check resolveCount\n        instantiated:\n          reg.scope === Scope.SINGLETON ? reg.instance !== undefined : reg.resolveCount > 0,\n        resolveCount: reg.resolveCount,\n        lastResolvedAt: reg.lastResolvedAt,\n        firstResolvedAt: reg.firstResolvedAt,\n        resolveDurationMs: reg.resolveDurationMs,\n        postConstructStatus: reg.postConstructStatus,\n        dependencies: reg.dependencies,\n      })\n    }\n    return entries\n  }\n\n  /**\n   * Resolve a dependency by its token.\n   *\n   * Four overloads, in order of preference:\n   * - **`InjectionToken<T>`** (from `createToken<T>(name)`) → returns `T`.\n   *   Collision-safe by construction; no codegen required.\n   * - **Class constructor** → returns an instance of that class. Always\n   *   type-safe; no codegen required.\n   * - **String token in `KickJsRegistry`** (populated by `kick typegen`) →\n   *   returns the augmented type.\n   * - **Anything else** → returns `any`. Use this only for legacy code or\n   *   string tokens that haven't been registered with typegen yet.\n   */\n  resolve<T>(token: InjectionToken<T>): T\n  resolve<T>(token: Constructor<T>): T\n  resolve<K extends keyof KickJsRegistry & string>(token: K): KickJsRegistry[K]\n  resolve<T = any>(token: any): T\n  resolve<T = any>(token: any): T {\n    let reg = this.registrations.get(token)\n    // HMR fallback: when Vite re-evaluates a module, decorated classes get new\n    // identity. Try resolving by class name if the primary token lookup fails.\n    if (!reg && typeof token === 'function' && token.name) {\n      reg = this.registrations.get(`__hmr__${token.name}`)\n    }\n    if (!reg) {\n      throw noProviderError(tokenName(token))\n    }\n\n    if (reg.scope === Scope.SINGLETON && reg.instance !== undefined) {\n      reg.resolveCount++\n      reg.lastResolvedAt = Date.now()\n      this.emit(token, 'resolved', reg.kind)\n      return reg.instance\n    }\n\n    // REQUEST scope: one instance per HTTP request, cached in AsyncLocalStorage\n    if (reg.scope === Scope.REQUEST) {\n      if (!Container._requestStoreProvider) {\n        throw requestScopeMiddlewareMissingError(tokenName(token))\n      }\n      const store = Container._requestStoreProvider()\n      if (!store) {\n        throw requestScopeOutsideRequestError(tokenName(token))\n      }\n      // Check for pre-registered request values (user, tenant, etc.)\n      if (store.values.has(token)) {\n        reg.resolveCount++\n        reg.lastResolvedAt = Date.now()\n        this.emit(token, 'resolved', reg.kind)\n        return store.values.get(token) as T\n      }\n      // Check per-request instance cache\n      if (store.instances.has(token)) {\n        reg.resolveCount++\n        reg.lastResolvedAt = Date.now()\n        this.emit(token, 'resolved', reg.kind)\n        return store.instances.get(token) as T\n      }\n      // Factory-registered binding: invoke the factory once per request\n      // and cache the result alongside class-instantiated REQUEST tokens.\n      // Without this branch, registerFactory(token, fn, Scope.REQUEST)\n      // silently falls through to createInstance(reg) which `new`s the\n      // factory's placeholder `target: Object` and returns an empty {}\n      // — the factory function never runs.\n      if (reg.factory) {\n        const start = performance.now()\n        const instance = reg.factory()\n        reg.resolveDurationMs = performance.now() - start\n        reg.resolveCount++\n        reg.lastResolvedAt = Date.now()\n        if (!reg.firstResolvedAt) reg.firstResolvedAt = Date.now()\n        store.instances.set(token, instance)\n        this.emit(token, 'resolved', reg.kind)\n        return instance as T\n      }\n      // Create instance and cache for this request only\n      const start = performance.now()\n      const instance = this.createInstance(reg)\n      reg.resolveDurationMs = performance.now() - start\n      reg.resolveCount++\n      reg.lastResolvedAt = Date.now()\n      if (!reg.firstResolvedAt) reg.firstResolvedAt = Date.now()\n      store.instances.set(token, instance)\n      this.emit(token, 'resolved', reg.kind)\n      return instance as T\n    }\n\n    if (reg.factory) {\n      const start = performance.now()\n      const instance = reg.factory()\n      reg.resolveDurationMs = performance.now() - start\n      reg.resolveCount++\n      reg.lastResolvedAt = Date.now()\n      if (!reg.firstResolvedAt) reg.firstResolvedAt = Date.now()\n      if (reg.scope === Scope.SINGLETON) {\n        reg.instance = instance\n        // Persist resolved factory instances so they survive module\n        // re-evaluation — global container only, for the same reason.\n        if (this.isGlobal) {\n          getPersistentStore().resolvedInstances.set(tokenName(token), instance)\n        }\n      }\n      this.emit(token, 'resolved', reg.kind)\n      return instance\n    }\n\n    if (this.resolving.has(token)) {\n      const chain = [...this.resolving].map(tokenName)\n      chain.push(tokenName(token))\n      throw new Error(`Circular dependency detected: ${chain.join(' -> ')}`)\n    }\n    this.resolving.add(token)\n\n    try {\n      const start = performance.now()\n      const instance = this.createInstance(reg)\n      reg.resolveDurationMs = performance.now() - start\n      reg.resolveCount++\n      reg.lastResolvedAt = Date.now()\n      if (!reg.firstResolvedAt) reg.firstResolvedAt = Date.now()\n      if (reg.scope === Scope.SINGLETON) {\n        reg.instance = instance\n      }\n      this.emit(token, 'resolved', reg.kind)\n      return instance\n    } finally {\n      this.resolving.delete(token)\n    }\n  }\n\n  /** Lifecycle hook called during Application.setup() after module registration */\n  bootstrap(): void {\n    // Reserved for future use — adapters and modules register via\n    // container.register(), registerFactory(), and registerInstance().\n  }\n\n  // ── Reactive Change API ─────────────────────────────────────────────\n\n  /**\n   * Subscribe to container changes. Returns an unsubscribe function.\n   *\n   * Changes are batched (50ms debounce) so bulk operations like\n   * `kick g module` creating 10+ files emit ONE batch, not 10 events.\n   *\n   * Any adapter can subscribe:\n   *   - SwaggerAdapter: re-build spec when controllers change\n   *   - DevToolsAdapter: push SSE events to dashboard\n   *   - WsAdapter: re-discover namespaces when controllers change\n   *   - OtelAdapter: emit tracing spans for DI resolution\n   *   - Custom user adapters\n   *\n   * @example\n   * ```ts\n   * const unsub = container.onChange((changes) => {\n   *   for (const c of changes) {\n   *     console.log(`${c.event}: ${c.token} (${c.kind})`)\n   *   }\n   * })\n   * // later:\n   * unsub()\n   * ```\n   */\n  onChange(callback: ContainerChangeListener): () => void {\n    this.changeListeners.add(callback)\n    return () => this.changeListeners.delete(callback)\n  }\n\n  /**\n   * Invalidate a specific registration. Clears the cached instance so the\n   * next resolve() creates a fresh one. Also invalidates dependents\n   * (anything that injected this token) by walking the dependency graph.\n   *\n   * Called by the Vite HMR plugin when a module file changes.\n   * Skips persistent registrations (DB connections, etc.).\n   */\n  invalidate(token: any): void {\n    const name = tokenName(token)\n    // Try both the token itself and the HMR fallback name\n    const reg = this.registrations.get(token) ?? this.registrations.get(`__hmr__${name}`)\n    if (!reg) return\n\n    // Don't invalidate persistent registrations (DB, Redis, etc.)\n    const store = getPersistentStore()\n    if (store.resolvedInstances.has(name)) return\n\n    // Clear cached instance — next resolve() will re-create\n    reg.instance = undefined\n    reg.resolveCount = 0\n    reg.postConstructStatus = 'skipped'\n    this.emit(name, 'invalidated', reg.kind)\n\n    // Walk dependency graph — invalidate anything that injected this token\n    for (const [depToken, depReg] of this.registrations) {\n      if (depReg.dependencies.includes(name)) {\n        this.invalidate(depToken)\n      }\n    }\n  }\n\n  /**\n   * Batch-emit a change event (debounced, flushed after 50ms of quiet).\n   * Takes the RAW token — `tokenName()` is only computed after the\n   * zero-listener guard, so the hot cached-singleton resolve path never pays\n   * the name derivation when nobody is watching (the production default).\n   */\n  private emit(rawToken: any, event: ContainerChangeEvent['event'], kind?: ClassKind): void {\n    // Zero-listener fast path. Nobody subscribes to container changes unless\n    // DevTools (or a test) calls `onChange` — the production default. Without\n    // this guard, every `resolve()` (including the hot cached-singleton path)\n    // would scan `pendingChanges`, push an entry, and reschedule a `setTimeout`\n    // only for the eventual flush to iterate an empty listener set and discard\n    // the batch. Short-circuiting here keeps `resolve()` allocation- and\n    // timer-free when no one is watching. When a listener attaches later,\n    // subsequent emits work exactly as before — past resolves had no observer\n    // to notify anyway.\n    if (this.changeListeners.size === 0) return\n    const token = tokenName(rawToken)\n\n    // Dedupe within the pending batch: a high-throughput TRANSIENT\n    // token that resolves 1000× per request would otherwise queue\n    // 1000 identical 'resolved' events. The downstream listener only\n    // cares that the token's state changed, so collapse to one entry\n    // (the earliest timestamp wins; the latest update is reflected\n    // in resolveCount/lastResolvedAt on the registration itself,\n    // which the listener reads at notify time).\n    const existing = this.pendingChanges.find((p) => p.token === token && p.event === event)\n    if (existing) {\n      existing.timestamp = Date.now()\n    } else {\n      this.pendingChanges.push({ token, event, kind, timestamp: Date.now() })\n    }\n\n    if (this.notifyTimer) clearTimeout(this.notifyTimer)\n    this.notifyTimer = setTimeout(() => {\n      const batch = this.pendingChanges.splice(0)\n      if (batch.length === 0) return\n      for (const listener of this.changeListeners) {\n        try {\n          listener(batch)\n        } catch {\n          // Don't let one broken listener break others\n        }\n      }\n    }, Container.DEBOUNCE_MS)\n    // Don't let a pending debounce window hold the event loop open — flush is\n    // best-effort telemetry, not critical work.\n    this.notifyTimer.unref?.()\n  }\n\n  /** Flush pending change events immediately (useful in tests) */\n  flushChanges(): void {\n    if (this.notifyTimer) {\n      clearTimeout(this.notifyTimer)\n      this.notifyTimer = null\n    }\n    const batch = this.pendingChanges.splice(0)\n    if (batch.length === 0) return\n    for (const listener of this.changeListeners) {\n      try {\n        listener(batch)\n      } catch {\n        // Don't let one broken listener break others\n      }\n    }\n  }\n\n  /**\n   * Build the one-time instantiation plan for a registration. Runs on the\n   * FIRST createInstance for the class — the metadata it reads is immutable\n   * after class definition, so every later create (REQUEST scope: every\n   * request) skips all Reflect reads and re-derivation.\n   *\n   * Scope validation (SINGLETON must not ctor-inject REQUEST) lives here\n   * too: it's a static property of the (parent, dep) registration pair, so\n   * checking it once at plan build is equivalent to the old per-create loop.\n   */\n  private buildPlan(reg: Registration): InstantiationPlan {\n    const paramTypes = getClassMeta<Constructor[]>(METADATA.PARAM_TYPES, reg.target, [])\n    const injectTokens = getMetaRecord<any>(METADATA.INJECT, reg.target)\n\n    // When emitDecoratorMetadata is unavailable (tsx, ts-node without\n    // SWC), paramTypes is empty even though @Inject set tokens on\n    // specific constructor indices. Derive the constructor arity from\n    // the @Inject metadata so constructor injection still works.\n    const maxInjectIndex =\n      Object.keys(injectTokens).length > 0\n        ? Math.max(...Object.keys(injectTokens).map(Number)) + 1\n        : 0\n    const paramCount = Math.max(paramTypes.length, maxInjectIndex)\n\n    const ctorTokens: any[] = []\n    for (let index = 0; index < paramCount; index++) {\n      const token = injectTokens[index] || paramTypes[index]\n      if (!token) {\n        throw new Error(\n          `Cannot resolve constructor parameter at index ${index} of ${tokenName(reg.target)}. ` +\n            `No @Inject token and no design:paramtypes metadata (tsx/ts-node don't emit it). ` +\n            `Add @Inject(Token) to every constructor parameter.`,\n        )\n      }\n      // Scope validation: SINGLETON cannot inject REQUEST-scoped dependencies\n      if (reg.scope === Scope.SINGLETON) {\n        const depReg = this.registrations.get(token)\n        if (depReg && depReg.scope === Scope.REQUEST) {\n          throw new Error(\n            `Cannot inject REQUEST-scoped \"${tokenName(token)}\" into SINGLETON \"${tokenName(reg.target)}\". ` +\n              `Singletons outlive requests. Use TRANSIENT or REQUEST scope for the parent.`,\n          )\n        }\n      }\n      ctorTokens.push(token)\n    }\n\n    // @Autowired properties — resolve each property's token once.\n    const autowiredProps = getMetaMap<string, any>(METADATA.AUTOWIRED, reg.target.prototype)\n    const autowired: InstantiationPlan['autowired'] = []\n    for (const [prop, token] of autowiredProps) {\n      const resolvedToken =\n        token || getMethodMetaOrUndefined(METADATA.PROPERTY_TYPE, reg.target.prototype, prop)\n      if (resolvedToken) autowired.push([prop, resolvedToken])\n    }\n\n    // @Value properties.\n    const valueProps = getMetaMap<string, { envKey: string; defaultValue?: any }>(\n      METADATA.VALUE,\n      reg.target.prototype,\n    )\n    const values: InstantiationPlan['values'] = [...valueProps.entries()]\n\n    // @Asset properties — pre-split namespace/key (and fail fast on bad keys).\n    const assetProps = getMetaMap<string, { assetKey: string }>(\n      METADATA.ASSET,\n      reg.target.prototype,\n    )\n    const assets: InstantiationPlan['assets'] = []\n    for (const [prop, config] of assetProps) {\n      const slashIdx = config.assetKey.indexOf('/')\n      if (slashIdx === -1) {\n        throw new Error(\n          `@Asset('${config.assetKey}'): asset key must include a '/' separator (e.g. 'mails/welcome').`,\n        )\n      }\n      assets.push([\n        prop,\n        { namespace: config.assetKey.slice(0, slashIdx), key: config.assetKey.slice(slashIdx + 1) },\n      ])\n    }\n\n    const postConstruct = getClassMetaOrUndefined<string | symbol>(\n      METADATA.POST_CONSTRUCT,\n      reg.target.prototype,\n    )\n\n    return { ctorTokens, autowired, values, assets, postConstruct }\n  }\n\n  private createInstance(reg: Registration): any {\n    const plan = (reg.plan ??= this.buildPlan(reg))\n\n    const args: any[] = []\n    for (const token of plan.ctorTokens) {\n      args.push(this.resolve(token))\n    }\n\n    const instance = new reg.target(...args)\n\n    // Property injection via @Autowired / @Value / @Asset\n    this.injectProperties(instance, plan)\n\n    // @PostConstruct lifecycle hook\n    const postConstruct = plan.postConstruct\n    if (postConstruct && typeof instance[postConstruct] === 'function') {\n      try {\n        const result = instance[postConstruct]()\n        if (result && typeof result.then === 'function') {\n          reg.postConstructStatus = 'pending'\n          ;(result as Promise<void>)\n            .then(() => {\n              reg.postConstructStatus = 'completed'\n            })\n            .catch(() => {\n              reg.postConstructStatus = 'failed'\n            })\n          log.warn(\n            `@PostConstruct on ${tokenName(reg.target)}.${String(postConstruct)}() returned a Promise ` +\n              `but the container is synchronous. The async operation will not be awaited.`,\n          )\n        } else {\n          reg.postConstructStatus = 'completed'\n        }\n      } catch (err) {\n        reg.postConstructStatus = 'failed'\n        log.error(\n          err,\n          `@PostConstruct on ${tokenName(reg.target)}.${String(postConstruct)}() threw an error`,\n        )\n      }\n    }\n\n    return instance\n  }\n\n  /**\n   * Extract every dependency token name a class declares — both\n   * constructor params (`@Inject` + emitted `design:paramtypes`) and\n   * `@Autowired` properties (read lazily at injection time, but\n   * captured here so devtools surfaces a complete dependency graph).\n   *\n   * Without the property branch, classes that rely entirely on\n   * `@Autowired` show `dependencies: []` in the introspection panel\n   * even though they have real DI deps — see /_debug topology.\n   */\n  private extractDependencies(target: Constructor): string[] {\n    const paramTypes = getClassMeta<Constructor[]>(METADATA.PARAM_TYPES, target, [])\n    const injectTokens = getMetaRecord<any>(METADATA.INJECT, target)\n    const ctorDeps = paramTypes.map((type, index) => {\n      const token = injectTokens[index] || type\n      return tokenName(token)\n    })\n\n    // @Autowired properties live on `target.prototype`. Token may be\n    // explicit (`@Autowired('SOME_TOKEN')`) or fall back to the\n    // emitted `design:type` metadata of the property.\n    const autowiredProps = getMetaMap<string, any>(METADATA.AUTOWIRED, target.prototype)\n    const propDeps: string[] = []\n    for (const [prop, token] of autowiredProps) {\n      const resolvedToken =\n        token || getMethodMetaOrUndefined(METADATA.PROPERTY_TYPE, target.prototype, prop)\n      if (resolvedToken) propDeps.push(tokenName(resolvedToken))\n    }\n\n    // De-dupe — a class can declare the same token in both surfaces.\n    return [...new Set([...ctorDeps, ...propDeps])]\n  }\n\n  private injectProperties(instance: any, plan: InstantiationPlan): void {\n    // @Autowired — lazy DI property injection. The getter re-resolves per\n    // access by design (a SINGLETON may lazily read a REQUEST-scoped dep at\n    // call time). For SINGLETON deps that laziness buys nothing after the\n    // first read — the container returns the same cached instance forever —\n    // so the getter memoizes itself into a plain data property then. REQUEST\n    // and TRANSIENT deps keep the live getter (memoizing would pin the first\n    // request's instance across requests).\n    for (const [prop, resolvedToken] of plan.autowired) {\n      Object.defineProperty(instance, prop, {\n        get: () => {\n          const value = this.resolve(resolvedToken)\n          const depReg = this.registrations.get(resolvedToken)\n          if (depReg?.scope === Scope.SINGLETON) {\n            Object.defineProperty(instance, prop, {\n              value,\n              enumerable: true,\n              configurable: true,\n              writable: false,\n            })\n          }\n          return value\n        },\n        enumerable: true,\n        configurable: true,\n      })\n    }\n\n    // @Value — lazy environment variable injection\n    for (const [prop, config] of plan.values) {\n      Object.defineProperty(instance, prop, {\n        get() {\n          // Use the registered env resolver if available (wired by the\n          // config layer in @forinda/kickjs). Returns Zod-validated,\n          // type-coerced values (e.g. PORT as number).\n          if (Container._envResolver) {\n            const val = Container._envResolver(config.envKey)\n            if (val !== undefined) return val\n          }\n\n          // Fallback to raw process.env for apps that haven't called loadEnv()\n          const val = process.env[config.envKey]\n          if (val !== undefined) return val\n          if (config.defaultValue !== undefined) return config.defaultValue\n          throw envValueMissingError(config.envKey)\n        },\n        enumerable: true,\n        configurable: true,\n      })\n    }\n\n    // @Asset — lazy asset path injection (assets-plan.md). Same lazy-\n    // getter pattern as @Value: resolve on every property access via\n    // the asset manager's cached resolver, not at class instantiation.\n    // namespace/key were pre-split at plan build.\n    for (const [prop, { namespace, key }] of plan.assets) {\n      Object.defineProperty(instance, prop, {\n        get() {\n          return resolveAsset(namespace, key)\n        },\n        enumerable: true,\n        configurable: true,\n      })\n    }\n  }\n}\n"],"mappings":"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"}