@zintrust/core 0.1.18 → 0.1.20

package/src/templates/project/basic/database/migrations/create_tasks_table.ts.tpl

@@ -0,0 +1,28 @@
+import { Schema as MigrationSchema, type Blueprint } from '@zintrust/core/migrations';
+import type { IDatabase } from '@zintrust/core/orm';
+
+export interface Migration {
+  up(db: IDatabase): Promise<void>;
+  down(db: IDatabase): Promise<void>;
+}
+
+export const migration: Migration = {
+  async up(db: IDatabase): Promise<void> {
+    const schema = MigrationSchema.create(db);
+
+    await schema.create('tasks', (table: Blueprint) => {
+      table.id();
+      table.string('title');
+      table.text('description').nullable();
+      table.string('status').default('pending');
+      table.unsignedBigInt('user_id');
+      table.foreign('user_id').references('id').on('users').onDelete('CASCADE');
+      table.timestamps();
+    });
+  },
+
+  async down(db: IDatabase): Promise<void> {
+    const schema = MigrationSchema.create(db);
+    await schema.dropIfExists('tasks');
+  },
+};

package/src/templates/project/basic/database/migrations/create_users_table.ts.tpl

@@ -0,0 +1,29 @@
+import { Schema as MigrationSchema, type Blueprint } from '@zintrust/core/migrations';
+import type { IDatabase } from '@zintrust/core/orm';
+
+export interface Migration {
+  up(db: IDatabase): Promise<void>;
+  down(db: IDatabase): Promise<void>;
+}
+
+export const migration: Migration = {
+  async up(db: IDatabase): Promise<void> {
+    const schema = MigrationSchema.create(db);
+
+    await schema.create('users', (table: Blueprint) => {
+      table.id();
+      table.string('name');
+      table.string('email').unique();
+      table.string('password');
+      table.timestamp('email_verified_at').nullable();
+      table.boolean('active').default(true);
+      table.timestamps();
+      table.timestamp('deleted_at').nullable();
+    });
+  },
+
+  async down(db: IDatabase): Promise<void> {
+    const schema = MigrationSchema.create(db);
+    await schema.dropIfExists('users');
+  },
+};

package/src/templates/project/basic/database/seeders/DatabaseSeeder.ts.tpl

@@ -0,0 +1,19 @@
+import { SeederDiscovery } from '@zintrust/core/seeders';
+import { SeederLoader } from '@zintrust/core/seeders';
+import { CommonUtils } from '@zintrust/core/common';
+import * as path from 'node:path';
+import type { IDatabase } from '@zintrust/core/orm';
+
+export const DatabaseSeeder = Object.freeze({
+  async run(db: IDatabase): Promise<void> {
+    const dir = CommonUtils.esmDirname(import.meta.url);
+    const files = SeederDiscovery.listSeederFiles(dir).filter((filePath) => {
+      const base = path.basename(filePath, path.extname(filePath));
+      return base !== 'DatabaseSeeder';
+    });
+
+    const seeders = await Promise.all(files.map((filePath) => SeederLoader.load(filePath)));
+
+    await Promise.all(seeders.map((seeder) => seeder.run(db)));
+  },
+});

package/src/templates/project/basic/database/seeders/UserSeeder.ts.tpl

@@ -0,0 +1,18 @@
+import type { IDatabase } from '@zintrust/core/orm';
+
+export interface Seeder {
+  run(db: IDatabase): Promise<void>;
+}
+
+export const UserSeeder: Seeder = Object.freeze({
+  async run(db: IDatabase): Promise<void> {
+    // Example: Use UserFactory from ../factories/UserFactory
+    // const users = UserFactory.count(5);
+    // for (const user of users) {
+    //   Insert user data into database
+    //   await db.query('INSERT INTO users (name, email, password, created_at, updated_at) VALUES (?, ?, ?, ?, ?)', [
+    //     user.name, user.email, user.password, user.created_at, user.updated_at
+    //   ]);
+    // }
+  },
+});

package/src/templates/project/basic/database/seeders/index.ts.tpl

@@ -0,0 +1,2 @@
+// Placeholder for seeders
+export const seeders = Object.freeze([] as const);

package/src/templates/project/basic/package.json.tpl

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@zintrust/core": "^0.1.4"
+    "@zintrust/core": "^{{coreVersion}}"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",

package/src/templates/project/basic/routes/api.ts.tpl

@@ -3,17 +3,19 @@
  * Demonstrates routing patterns
  */
 
-import { Env, type IRouter, Router } from '@zintrust/core';
-
-import { UserController } from '../app/Controllers/UserController';
-import { registerBroadcastRoutes } from './broadcast';
-import { registerHealthRoutes } from './health';
-import { registerStorageRoutes } from './storage';
+import { AuthController } from '@app/Controllers/AuthController';
+import { UserQueryBuilderController } from '@app/Controllers/UserQueryBuilderController';
+import { Env , Router } from '@zintrust/core';
+import type { MiddlewareKey ,  IRouter , IResponse, IRequest} from '@zintrust/core';
+import { registerBroadcastRoutes } from '@routes/broadcast';
+import { registerHealthRoutes } from '@routes/health';
+import { registerStorageRoutes } from '@routes/storage';
 
 export function registerRoutes(router: IRouter): void {
-  const userController = UserController.create();
+  const authController = AuthController.create();
+  const userController = UserQueryBuilderController.create();
   registerPublicRoutes(router);
-  registerApiV1Routes(router, userController);
+  registerApiV1Routes(router, authController, userController);
   registerAdminRoutes(router);
 }
 
@@ -28,7 +30,7 @@ function registerPublicRoutes(router: IRouter): void {
 }
 
 function registerRootRoute(router: IRouter): void {
-  Router.get(router, '/', async (_req, res) => {
+  Router.get(router, '/', async (_req: IRequest, res:IResponse) => {
     res.json({
       framework: 'Zintrust Framework',
       app_name: Env.APP_NAME,
@@ -44,49 +46,85 @@ function registerRootRoute(router: IRouter): void {
  */
 function registerApiV1Routes(
   router: IRouter,
-  userController: ReturnType<typeof UserController.create>
+  authController: ReturnType<typeof AuthController.create>,
+  userController: ReturnType<typeof UserQueryBuilderController.create>
 ): void {
-  Router.group(router, '/api/v1', (r) => {
+  Router.group(router, '/api/v1', (r:IRouter) => {
     // Auth routes
-    Router.post(r, '/auth/login', async (_req, res) => {
-      res.json({ message: 'Login endpoint' });
+    Router.post<MiddlewareKey>(r, '/auth/login', authController.login, {
+      middleware: ['authRateLimit', 'validateLogin'],
     });
 
-    Router.post(r, '/auth/register', async (_req, res) => {
-      res.json({ message: 'Register endpoint' });
+    Router.post<MiddlewareKey>(r, '/auth/register', authController.register, {
+      middleware: ['authRateLimit', 'validateRegister'],
     });
 
-    // Protected routes (middleware is not modeled in Router.ts yet)
+    Router.post<MiddlewareKey>(r, '/auth/logout', authController.logout, {
+      middleware: ['auth', 'jwt'],
+    });
+    Router.post<MiddlewareKey>(r, '/auth/refresh', authController.refresh, {
+      middleware: ['auth', 'jwt'],
+    });
+
+    // Protected routes (Router supports per-route middleware metadata)
     const pr = r;
 
     // User resource (REST-ish)
-    Router.resource(pr, '/users', {
-      index: userController.index,
-      store: userController.store,
-      show: userController.show,
-      update: userController.update,
-      destroy: userController.destroy,
+    Router.resource<MiddlewareKey>(
+      pr,
+      '/users',
+      {
+        index: userController.index,
+        store: userController.store,
+        show: userController.show,
+        update: userController.update,
+        destroy: userController.destroy,
+      },
+      {
+        middleware: ['auth', 'jwt'],
+        store: { middleware: ['auth', 'jwt', 'userMutationRateLimit', 'validateUserStore'] },
+        update: { middleware: ['auth', 'jwt', 'userMutationRateLimit', 'validateUserUpdate'] },
+        destroy: { middleware: ['auth', 'jwt', 'userMutationRateLimit'] },
+      }
+    );
+
+    Router.post<MiddlewareKey>(pr, '/users/fill', userController.fill, {
+      middleware: ['auth', 'jwt', 'fillRateLimit', 'validateUserFill'],
     });
 
     // If the controller exposes create/edit, wire them explicitly.
-    Router.get(pr, '/users/create', userController.create);
-    Router.get(pr, '/users/:id/edit', userController.edit);
-
-    // Custom user routes
-    Router.get(pr, '/profile', async (_req, res) => {
-      res.json({ message: 'Get user profile' });
+    Router.get<MiddlewareKey>(pr, '/users/create', userController.create, {
+      middleware: ['auth', 'jwt'],
     });
-
-    Router.put(pr, '/profile', async (_req, res) => {
-      res.json({ message: 'Update user profile' });
+    Router.get<MiddlewareKey>(pr, '/users/:id/edit', userController.edit, {
+      middleware: ['auth', 'jwt'],
     });
 
+    // Custom user routes
+    Router.get<MiddlewareKey>(
+      pr,
+      '/profile',
+      async (_req: IRequest, res:IResponse) => {
+        res.json({ message: 'Get user profile' });
+      },
+      { middleware: ['auth', 'jwt'] }
+    );
+
+    Router.put<MiddlewareKey>(
+      pr,
+      '/profile',
+      async (_req: IRequest, res:IResponse) => {
+        res.json({ message: 'Update user profile' });
+      },
+      { middleware: ['auth', 'jwt'] }
+    );
+
     // Posts resource
-    Router.get(r, '/posts', async (_req, res) => {
+    Router.get(r, '/posts', async (_req: IRequest, res:IResponse) => {
       res.json({ data: [] });
     });
 
-    Router.get(r, '/posts/:id', async (req, res) => {
+    Router.get(r, '/posts/:id', async (req: IRequest, res:IResponse) => {
       const id = req.getParam('id');
       res.json({ data: { id } });
     });
@@ -97,12 +135,12 @@ function registerApiV1Routes(
  * Register admin routes
  */
 function registerAdminRoutes(router: IRouter): void {
-  Router.group(router, '/admin', (r) => {
-    Router.get(r, '/dashboard', async (_req, res) => {
+  Router.group(router, '/admin', (r:IRouter) => {
+    Router.get(r, '/dashboard', async (_req: IRequest, res:IResponse) => {
       res.json({ message: 'Admin dashboard' });
     });
 
-    Router.get(r, '/users', async (_req, res) => {
+    Router.get(r, '/users', async (_req: IRequest, res:IResponse) => {
       res.json({ data: [] });
     });
   });

package/src/templates/project/basic/routes/health.ts.tpl

@@ -3,12 +3,7 @@
  * Provides health, liveness, and readiness endpoints.
  */
 
-import { appConfig } from '../config/app';
-import { Env } from '../config/env';
-import { Logger } from '../config/logger';
-import { RuntimeHealthProbes } from '@zintrust/core';
-import { useDatabase } from '@zintrust/core';
-import { QueryBuilder } from '@zintrust/core';
+import { useDatabase, appConfig, Env , Logger, RuntimeHealthProbes, QueryBuilder} from '@zintrust/core';
 import { type IRouter, Router } from '@zintrust/core';
 
 export function registerHealthRoutes(router: IRouter): void {

package/src/templates/project/basic/routes/metrics.ts.tpl

@@ -0,0 +1,22 @@
+/**
+ * Metrics Routes
+ *
+ * Exposes Prometheus metrics when enabled.
+ */
+
+import { Env, PrometheusMetrics, type IRouter, Router } from '@zintrust/core';
+
+export function registerMetricsRoutes(router: IRouter): void {
+  if (Env.getBool('METRICS_ENABLED', false) === false) return;
+
+  const pathFromEnv = Env.get('METRICS_PATH', '/metrics').trim();
+  const path = pathFromEnv === '' ? '/metrics' : pathFromEnv;
+
+  Router.get(router, path, async (_req, res) => {
+    const { contentType, body } = await PrometheusMetrics.getMetricsText();
+    res.setHeader('Content-Type', contentType);
+    res.send(body);
+  });
+}
+
+export default registerMetricsRoutes;

package/src/templates/project/basic/src/index.ts.tpl

@@ -1,86 +1,13 @@
 /**
- * test-app - Zintrust Application Entry Point
+ * Zintrust Application Entry Point
  */
 
-import { Application, Env, Logger, Server } from '@zintrust/core';
-import process from '@zintrust/core/node';
-// Optional adapters/drivers registered via `zin plugin install`
-import './zintrust.plugins.js';
+import { isNodeMain, start } from '@zintrust/core/start';
 
-type AppInstance = ReturnType<typeof Application.create>;
-type ServerInstance = ReturnType<typeof Server.create>;
+// Cloudflare Workers entry.
+export { default } from '@zintrust/core/start';
 
-function withTimeout<T>(promise: Promise<T>, ms: number, timeoutMessage = 'Shutdown timed out'): Promise<T> {
-  if (!Number.isFinite(ms) || ms <= 0) return promise;
-
-  let timer: ReturnType<typeof setTimeout> | undefined;
-
-  const timeout = new Promise<never>((_, reject) => {
-    timer = setTimeout(() => reject(new globalThis.Error(timeoutMessage)), ms);
-  });
-
-  return Promise.race([promise, timeout]).finally(() => {
-    if (timer) clearTimeout(timer);
-  }) as Promise<T>;
-}
-
-async function stopServices(server: ServerInstance, app: AppInstance): Promise<void> {
-  await server.close();
-  await app.shutdown();
-}
-
-async function shutdownGracefully(signal: string, server: ServerInstance, app: AppInstance): Promise<void> {
-  Logger.info(`${signal} received, shutting down gracefully...`);
-
-  const timeoutMs = Env.getInt('SHUTDOWN_TIMEOUT', 1500);
-  const forceExitMs = Env.getInt('SHUTDOWN_FORCE_EXIT_MS', 2500);
-
-  const forceExitTimer = globalThis.setTimeout(() => {
-    process.exit(0);
-  }, forceExitMs);
-
-  (forceExitTimer as unknown as { unref?: () => void }).unref?.();
-
-  try {
-    await withTimeout(stopServices(server, app), timeoutMs);
-    globalThis.clearTimeout(forceExitTimer);
-    process.exit(0);
-  } catch (error) {
-    Logger.error('Graceful shutdown failed:', error);
-    process.exit(1);
-  }
+// Node entry (when executed as `node src/index.ts` / `tsx src/index.ts` etc.).
+if (isNodeMain(import.meta.url)) {
+  await start();
 }
-
-/**
- * Start the application
- */
-async function start() {
-  try {
-    // Create application instance
-    const app = Application.create();
-
-    // Boot application
-    await app.boot();
-
-    // Get port and host from environment
-    const port = Env.getInt('APP_PORT', 3000);
-    const host = Env.get('HOST', 'localhost');
-
-    // Create and start server
-    const server = Server.create(app, port, host);
-
-    // Start listening
-    await server.listen();
-
-    Logger.info(`Server running at http://${host}:${port}`);
-
-    process.on('SIGTERM', () => void shutdownGracefully('SIGTERM', server, app));
-    process.on('SIGINT', () => void shutdownGracefully('SIGINT', server, app));
-  } catch (error) {
-    Logger.error('Failed to start application:', error);
-    process.exit(1);
-  }
-}
-
-// Run start
-await start();

package/src/templates/project/basic/tsconfig.json.tpl

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "ignoreDeprecations": "6.0",
     "baseUrl": ".",
     "outDir": "./dist",
     "rootDir": "./",
@@ -13,22 +14,20 @@
       "@app/*": ["./app/*"],
       "@toolkit/*": ["./app/Toolkit/*"],
       "@config/*": ["./config/*"],
-      "@app/*": ["./app/*"],
-      "@toolkit/*": ["./app/Toolkit/*"],
       "@routes/*": ["./routes/*"],
       "@database/*": ["./database/*"],
 
-      "@tools/*": ["./src/tools/*"],
-      "@httpClient/*": ["./src/tools/http/*"],
-      "@templates": ["./src/tools/templates/index.ts"],
-      "@templates/*": ["./src/tools/templates/*"],
-      "@mail/*": ["./src/tools/mail/*"],
-      "@storage": ["./src/tools/storage/index.ts"],
-      "@storage/*": ["./src/tools/storage/*"],
-      "@drivers/*": ["./src/tools/storage/drivers/*"],
-      "@notification/*": ["./src/tools/notification/*"],
-      "@broadcast/*": ["./src/tools/broadcast/*"],
-      "@queue/*": ["./src/tools/queue/*"]
+      "@tools/*": ["app/Tools/*"],
+      "@httpClient/*": ["app/Tools/http/*"],
+      "@templates": ["app/Tools/templates/index.ts"],
+      "@templates/*": ["app/Tools/templates/*"],
+      "@mail/*": ["app/Tools/mail/*"],
+      "@storage": ["app/Tools/storage/index.ts"],
+      "@storage/*": ["app/Tools/storage/*"],
+      "@drivers/*": ["app/Tools/storage/drivers/*"],
+      "@notification/*": ["app/Tools/notification/*"],
+      "@broadcast/*": ["app/Tools/broadcast/*"],
+      "@queue/*": ["app/Tools/queue/*"]
     }
   },
   "include": ["src/**/*", "app/**/*", "routes/**/*", "database/**/*"],

package/src/testing/TestEnvironment.d.ts

@@ -0,0 +1,40 @@
+import { type IServiceContainer } from '../container/ServiceContainer';
+import { type IKernel } from '../http/Kernel';
+import { type IRouter } from '../routing/Router';
+export type TestHeaders = Record<string, string>;
+export type TestRequestInput = {
+    method: string;
+    path: string;
+    headers?: TestHeaders;
+    body?: unknown;
+    validated?: {
+        body?: unknown;
+        query?: unknown;
+        params?: unknown;
+        headers?: unknown;
+    };
+};
+export type TestResponse = {
+    status: number;
+    headers: Record<string, string | string[]>;
+    bodyText: string;
+    json: unknown;
+    cookies: Record<string, string>;
+};
+export type TestEnvironmentOptions = {
+    router?: IRouter;
+    container?: IServiceContainer;
+    registerRoutes?: (router: IRouter) => void;
+};
+export interface ITestEnvironment {
+    router: IRouter;
+    container: IServiceContainer;
+    kernel: IKernel;
+    request(input: TestRequestInput): Promise<TestResponse>;
+    swapSingleton<T>(key: string, instance: T): () => void;
+    swapFactory<T>(key: string, factory: () => T): () => void;
+}
+export declare const TestEnvironment: Readonly<{
+    create(options?: TestEnvironmentOptions): ITestEnvironment;
+}>;
+//# sourceMappingURL=TestEnvironment.d.ts.map

package/src/testing/TestEnvironment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestEnvironment.d.ts","sourceRoot":"","sources":["../../../src/testing/TestEnvironment.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACxF,OAAO,EAAU,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,EAAU,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGxD,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE;QACV,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC5C,CAAC;AA2HF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACxD,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,MAAM,IAAI,CAAC;IACvD,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC;CAC3D;AAED,eAAO,MAAM,eAAe;qBACV,sBAAsB,GAAQ,gBAAgB;EA6C9D,CAAC"}

package/src/testing/TestEnvironment.js

@@ -0,0 +1,141 @@
+import { ServiceContainer } from '../container/ServiceContainer.js';
+import { Kernel } from '../http/Kernel.js';
+import { Request } from '../http/Request.js';
+import { Response } from '../http/Response.js';
+import { Router } from '../routing/Router.js';
+const lowerCaseHeaders = (headers) => {
+    if (!headers)
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(headers))
+        out[k.toLowerCase()] = v;
+    return out;
+};
+const createNodeResStub = () => {
+    const headers = {};
+    let body = '';
+    const raw = {
+        statusCode: 200,
+        writableEnded: false,
+        setHeader(name, value) {
+            headers[name] = value;
+        },
+        end(data) {
+            raw.writableEnded = true;
+            if (data === undefined)
+                return;
+            body += Buffer.isBuffer(data) ? data.toString('utf8') : String(data);
+        },
+    };
+    return { raw, headers, getBody: () => body };
+};
+const parseJsonBody = (raw) => {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+};
+const cookiesFromSetCookieHeader = (setCookie) => {
+    const values = [];
+    if (Array.isArray(setCookie)) {
+        values.push(...setCookie.map(String));
+    }
+    else if (setCookie !== undefined && setCookie !== null) {
+        values.push(String(setCookie));
+    }
+    const result = {};
+    for (const cookie of values) {
+        const firstPart = cookie.split(';')[0] ?? '';
+        const idx = firstPart.indexOf('=');
+        if (idx <= 0)
+            continue;
+        const name = firstPart.slice(0, idx).trim();
+        const value = firstPart.slice(idx + 1).trim();
+        if (name !== '')
+            result[name] = value;
+    }
+    return result;
+};
+const createOverridableContainer = (base) => {
+    const overrides = new Map();
+    const swapSingleton = (key, instance) => {
+        overrides.set(key, { kind: 'singleton', value: instance });
+        return () => {
+            overrides.delete(key);
+        };
+    };
+    const swapFactory = (key, factory) => {
+        overrides.set(key, { kind: 'factory', factory });
+        return () => {
+            overrides.delete(key);
+        };
+    };
+    return {
+        bind: (key, factory) => base.bind(key, factory),
+        singleton: (key, factoryOrInstance) => base.singleton(key, factoryOrInstance),
+        resolve: (key) => {
+            const override = overrides.get(key);
+            if (override) {
+                return (override.kind === 'singleton' ? override.value : override.factory());
+            }
+            return base.resolve(key);
+        },
+        has: (key) => overrides.has(key) || base.has(key),
+        get: (key) => {
+            const override = overrides.get(key);
+            if (override) {
+                return (override.kind === 'singleton' ? override.value : override.factory());
+            }
+            return base.get(key);
+        },
+        flush: () => {
+            overrides.clear();
+            base.flush();
+        },
+        swapSingleton,
+        swapFactory,
+    };
+};
+export const TestEnvironment = Object.freeze({
+    create(options = {}) {
+        const router = options.router ?? Router.createRouter();
+        if (typeof options.registerRoutes === 'function')
+            options.registerRoutes(router);
+        const baseContainer = options.container ?? ServiceContainer.create();
+        const container = createOverridableContainer(baseContainer);
+        const kernel = Kernel.create(router, container);
+        return {
+            router,
+            container,
+            kernel,
+            async request(input) {
+                const nodeReq = {
+                    method: input.method,
+                    url: input.path,
+                    headers: lowerCaseHeaders(input.headers),
+                };
+                const nodeRes = createNodeResStub();
+                const req = Request.create(nodeReq);
+                if (input.body !== undefined)
+                    req.setBody(input.body);
+                if (input.validated !== undefined)
+                    req.validated = input.validated;
+                const res = Response.create(nodeRes.raw);
+                await kernel.handleRequest(req, res);
+                const bodyText = nodeRes.getBody();
+                const headers = nodeRes.headers;
+                return {
+                    status: nodeRes.raw.statusCode,
+                    headers,
+                    bodyText,
+                    json: parseJsonBody(bodyText),
+                    cookies: cookiesFromSetCookieHeader(headers['Set-Cookie']),
+                };
+            },
+            swapSingleton: container.swapSingleton,
+            swapFactory: container.swapFactory,
+        };
+    },
+});

package/src/testing/TestHttp.d.ts

@@ -0,0 +1,29 @@
+import { type IRequest, type ValidatedRequest } from '../http/Request';
+import type { IResponse } from '../http/Response';
+export type TestHttpRequestInput = {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    params?: Record<string, string>;
+    validated?: IRequest['validated'];
+    context?: Record<string, unknown>;
+};
+export type TestHttpResponseRecorder = IResponse & {
+    getBodyText: () => string;
+    getJson: () => unknown;
+    getHeaders: () => Record<string, string | string[]>;
+};
+export declare const TestHttp: Readonly<{
+    createRequest(input?: TestHttpRequestInput): IRequest;
+    createValidatedRequest<TBody = unknown, TQuery = unknown, TParams = unknown, THeaders = unknown>(input: Omit<TestHttpRequestInput, "validated"> & {
+        validated: {
+            body: TBody;
+            query: TQuery;
+            params: TParams;
+            headers: THeaders;
+        };
+    }): ValidatedRequest<TBody, TQuery, TParams, THeaders>;
+    createResponseRecorder(): TestHttpResponseRecorder;
+}>;
+//# sourceMappingURL=TestHttp.d.ts.map