@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/cjs/types/render/utils/package-resolver.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Package Resolver
+ *
+ * @description Enhanced package resolution with helpful error messages.
+ * Resolves packages from the user's project directory.
+ *
+ * @public API
+ */
+export declare class PackageResolver {
+    private logger;
+    constructor();
+    /**
+     * Resolve and require a package from the user's project.
+     *
+     * @param packageName - Package name to resolve
+     * @param options - Options to pass if package exports a function
+     * @returns The resolved package module
+     * @throws Error if package is not installed
+     */
+    resolve(packageName: string, ...options: Array<any>): any;
+    /**
+     * Check if a package is installed without throwing.
+     *
+     * @param packageName - Package name to check
+     * @returns Whether the package is installed
+     */
+    isInstalled(packageName: string): boolean;
+    /**
+     * Get the installed version of a package.
+     *
+     * @param packageName - Package name
+     * @returns Version string or null if not installed
+     */
+    getVersion(packageName: string): string | null;
+    /**
+     * Check multiple packages and return which ones are installed.
+     *
+     * @param packageNames - Package names to check
+     * @returns Object mapping package names to installation status
+     */
+    checkMultiple(packageNames: Array<string>): Record<string, boolean>;
+}
+/**
+ * Error thrown when a required package is not installed.
+ * @public API
+ */
+export declare class PackageNotInstalledError extends Error {
+    /** Package name that is not installed */
+    readonly packageName: string;
+    constructor(packageName: string);
+}
+/**
+ * Get the package resolver singleton.
+ *
+ * @returns Package resolver instance
+ */
+export declare function getPackageResolver(): PackageResolver;

package/lib/cjs/types/render/utils/view-scanner.d.ts

@@ -0,0 +1,74 @@
+import type { ViewInfo } from "../render-config.js";
+import type { EngineRegistry } from "../render-registry.js";
+/**
+ * View Scanner
+ *
+ * @description Scans directories for view files and provides information about them.
+ *
+ * @public API
+ */
+export declare class ViewScanner {
+    private registry;
+    /**
+     * Set the engine registry for extension mapping.
+     *
+     * @param registry - Engine registry instance
+     */
+    setRegistry(registry: EngineRegistry): void;
+    /**
+     * Scan a directory for view files.
+     *
+     * @param viewsDir - Directory to scan
+     * @param recursive - Whether to scan subdirectories
+     * @returns Array of view file paths
+     */
+    scanDirectory(viewsDir: string, recursive?: boolean): Promise<Array<string>>;
+    /**
+     * Scan multiple directories for view files.
+     *
+     * @param viewsDirs - Directories to scan
+     * @param recursive - Whether to scan subdirectories
+     * @returns Array of view file paths
+     */
+    scanDirectories(viewsDirs: Array<string>, recursive?: boolean): Promise<Array<string>>;
+    /**
+     * Get detailed information about view files.
+     *
+     * @param viewsDir - Directory to scan
+     * @returns Array of view information
+     */
+    getViewInfo(viewsDir: string): Promise<Array<ViewInfo>>;
+    /**
+     * Check if a file extension is a view file.
+     *
+     * @param extension - File extension
+     * @returns Whether it's a view file
+     */
+    private isViewFile;
+    /**
+     * Map a file extension to an engine type.
+     *
+     * @param extension - File extension
+     * @returns Engine type
+     */
+    private mapExtensionToEngine;
+    /**
+     * Check if any view files exist in common directories.
+     *
+     * @returns Object mapping directory names to whether they contain views
+     */
+    findViewDirectories(): Promise<Record<string, boolean>>;
+    /**
+     * Get extensions found in a directory.
+     *
+     * @param viewsDir - Directory to scan
+     * @returns Array of unique extensions
+     */
+    getExtensions(viewsDir: string): Promise<Array<string>>;
+}
+/**
+ * Get the view scanner singleton.
+ *
+ * @returns View scanner instance
+ */
+export declare function getViewScanner(): ViewScanner;

package/lib/cjs/types/testing/create-test-app.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Zero-Config Test Application Setup
+ *
+ * @module testing
+ *
+ * Creates a fully functional test application with DI container,
+ * fluent request builder, and automatic cleanup.
+ *
+ * @example
+ * ```typescript
+ * describe("UserController", () => {
+ *   const { app, container, request } = await createTestApp(App);
+ *
+ *   test("GET /users returns user list", async () => {
+ *     const response = await request.get("/users");
+ *     expect(response.status).toBe(200);
+ *   });
+ * });
+ * ```
+ */
+import { IWebServer, IWebServerConstructor } from "@expressots/shared";
+import { CreateTestAppOptions, TestAppResult } from "./testing.interfaces.js";
+/**
+ * Create a fully functional test application with zero configuration.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept testing
+ *
+ * This function provides:
+ * - One-line test app creation
+ * - Full DI container access
+ * - Fluent HTTP request builder
+ * - Automatic cleanup
+ *
+ * @param AppClass - The application class to test
+ * @param options - Optional configuration
+ * @returns Test app result with app, container, and request builder
+ *
+ * @example
+ * ```typescript
+ * // Simplest usage - zero config
+ * const { app, container, request } = await createTestApp(App);
+ *
+ * // With mock providers
+ * const { app, request } = await createTestApp(App, {
+ *   mockProviders: [
+ *     { provide: UserService, useValue: mockUserService }
+ *   ]
+ * });
+ *
+ * // With custom environment
+ * const { app, request } = await createTestApp(App, {
+ *   env: {
+ *     DATABASE_URL: "memory://test",
+ *     JWT_SECRET: "test-secret"
+ *   }
+ * });
+ * ```
+ */
+export declare function createTestApp<T extends IWebServer>(AppClass: IWebServerConstructor<T>, options?: CreateTestAppOptions): Promise<TestAppResult>;
+/**
+ * Cleanup all active test apps.
+ * Useful for cleanup in test teardown.
+ */
+export declare function cleanupAllTestApps(): Promise<void>;
+/**
+ * Get the count of active test apps.
+ * Useful for debugging test cleanup issues.
+ */
+export declare function getActiveTestAppCount(): number;

package/lib/cjs/types/testing/create-test-database.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Database Testing Utilities
+ *
+ * @module testing
+ *
+ * Provides automatic test database setup/teardown with fixtures support.
+ *
+ * @example
+ * ```typescript
+ * const db = createTestDatabase({
+ *   type: "in-memory",
+ *   fixtures: [userFixtures, postFixtures]
+ * });
+ *
+ * beforeEach(async () => {
+ *   await db.reset();
+ * });
+ *
+ * test("user repository creates user", async () => {
+ *   const user = await userRepository.create({ name: "Test" });
+ *   const dbUser = await db.findOne("users", { id: user.id });
+ *   expect(dbUser).toMatchObject({ name: "Test" });
+ * });
+ * ```
+ */
+import { CreateTestDatabaseOptions, DatabaseFixture, ITestDatabase } from "./testing.interfaces.js";
+/**
+ * Create a test database instance.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept testing
+ *
+ * Provides automatic test database setup/teardown with fixtures.
+ *
+ * @param options - Database options
+ * @returns Test database instance
+ *
+ * @example
+ * ```typescript
+ * // In-memory database with fixtures
+ * const db = createTestDatabase({
+ *   type: "in-memory",
+ *   fixtures: [
+ *     {
+ *       table: "users",
+ *       data: [
+ *         { id: 1, name: "John", email: "john@test.com" },
+ *         { id: 2, name: "Jane", email: "jane@test.com" }
+ *       ]
+ *     }
+ *   ]
+ * });
+ *
+ * // Reset between tests
+ * beforeEach(async () => {
+ *   await db.reset();
+ * });
+ *
+ * // Use in tests
+ * test("creates a user", async () => {
+ *   const user = await db.insert("users", { name: "Test" });
+ *   expect(user.id).toBeDefined();
+ *
+ *   const found = await db.findOne("users", { id: user.id });
+ *   expect(found?.name).toBe("Test");
+ * });
+ * ```
+ */
+export declare function createTestDatabase(options?: CreateTestDatabaseOptions): ITestDatabase;
+/**
+ * Create a fixture factory helper.
+ *
+ * @example
+ * ```typescript
+ * const userFactory = createFixtureFactory<User>({
+ *   name: (i) => `User ${i}`,
+ *   email: (i) => `user${i}@test.com`,
+ *   role: "user"
+ * });
+ *
+ * const users = userFactory(5);
+ * // Creates 5 users with incremental names and emails
+ * ```
+ */
+export declare function createFixtureFactory<T extends Record<string, unknown>>(template: {
+    [K in keyof T]: T[K] | ((index: number) => T[K]);
+}): (count: number) => Array<T>;
+/**
+ * Create fixtures from a template.
+ *
+ * @example
+ * ```typescript
+ * const userFixtures = fixture("users", [
+ *   { id: 1, name: "Admin", role: "admin" },
+ *   { id: 2, name: "User", role: "user" }
+ * ]);
+ * ```
+ */
+export declare function fixture<T>(table: string, data: Array<T>, factory?: (count: number) => Array<T>): DatabaseFixture<T>;

package/lib/cjs/types/testing/fluent-request.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Fluent HTTP Testing API
+ *
+ * @module testing
+ *
+ * Provides a chainable, readable, type-safe API for HTTP testing.
+ * Better than supertest with built-in performance assertions.
+ *
+ * @example
+ * ```typescript
+ * await request(app)
+ *   .get("/users/123")
+ *   .expectStatus(200)
+ *   .expectBody<User>({ id: 123, name: "John" })
+ *   .expectTime({ lessThan: 100 });
+ * ```
+ */
+import { FluentRequestBuilder } from "./testing.interfaces.js";
+/**
+ * Create a fluent request builder for a base URL.
+ */
+export declare function createFluentRequest(baseUrl: string): FluentRequestBuilder;
+/**
+ * Create a standalone request builder from an app or URL.
+ *
+ * @example
+ * ```typescript
+ * // With app
+ * const response = await request(app).get("/users").execute();
+ *
+ * // With URL
+ * const response = await request("http://localhost:3000").get("/users").execute();
+ * ```
+ */
+export declare function request(appOrUrl: {
+    baseUrl: string;
+} | string): FluentRequestBuilder;

package/lib/cjs/types/testing/index.d.ts

@@ -0,0 +1,93 @@
+/**
+ * ExpressoTS Testing Module
+ *
+ * @module testing
+ *
+ * Comprehensive testing utilities for ExpressoTS applications.
+ * Provides zero-config setup, smart mocks, fluent HTTP testing,
+ * snapshot testing, and built-in load testing.
+ *
+ * UNIQUE FEATURES (No other framework has these!):
+ * - Zero-config test app creation
+ * - Smart mocking with auto-discovery
+ * - Fluent HTTP testing API (better than supertest)
+ * - API snapshot testing
+ * - Built-in load testing with percentile metrics
+ * - Database testing utilities
+ * - Request context mocking
+ *
+ * @example
+ * ```typescript
+ * // Zero-config test setup
+ * import { createTestApp } from "@expressots/testing";
+ *
+ * describe("UserController", () => {
+ *   let app, request;
+ *
+ *   beforeAll(async () => {
+ *     ({ app, request } = await createTestApp(App));
+ *   });
+ *
+ *   test("GET /users returns user list", async () => {
+ *     const response = await request
+ *       .get("/users")
+ *       .expectStatus(200)
+ *       .expectBody((body) => body.length > 0)
+ *       .expectTime({ lessThan: 100 })
+ *       .execute();
+ *
+ *     expect(response.body).toHaveLength(2);
+ *   });
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Smart mocking
+ * import { mockProvider } from "@expressots/testing";
+ *
+ * test("UserService creates user", async () => {
+ *   const { service, mocks } = mockProvider(UserService, {
+ *     mocks: {
+ *       UserRepository: {
+ *         create: jest.fn().mockResolvedValue({ id: 1, name: "John" })
+ *       }
+ *     }
+ *   });
+ *
+ *   const user = await service.createUser({ name: "John" });
+ *   expect(user.id).toBe(1);
+ *   expect(mocks.UserRepository.create).toHaveBeenCalled();
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Load testing (UNIQUE!)
+ * import { loadTest } from "@expressots/testing";
+ *
+ * test("handles 1000 concurrent requests", async () => {
+ *   const results = await loadTest(app, {
+ *     endpoint: "/users",
+ *     concurrent: 1000,
+ *     duration: "10s",
+ *     assertions: {
+ *       maxErrorRate: 0.01,
+ *       maxP95: 200
+ *     }
+ *   });
+ *
+ *   expect(results.assertionsPassed).toBe(true);
+ *   expect(results.p95ResponseTime).toBeLessThan(200);
+ * });
+ * ```
+ */
+export * from "./testing.interfaces.js";
+export { createTestApp, cleanupAllTestApps, getActiveTestAppCount, } from "./create-test-app.js";
+export { mockProvider, createMock, createMockObject, spyOn, } from "./mock-provider.js";
+export { createFluentRequest, request } from "./fluent-request.js";
+export { snapshotRequest, toMatchApiSnapshot } from "./snapshot-request.js";
+export { loadTest, benchmark, stressTest } from "./load-test.js";
+export { createTestDatabase, createFixtureFactory, fixture, } from "./create-test-database.js";
+export { mockContext, mockExecutionContext, mockNextFunction, mockReqRes, } from "./mock-context.js";
+export { expressoTSMatchers, setupExpressoTSMatchers } from "./matchers.js";

package/lib/cjs/types/testing/load-test.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Built-in Load Testing Utilities
+ *
+ * @module testing
+ *
+ * UNIQUE FEATURE: No other framework has built-in load testing!
+ *
+ * Provides comprehensive load testing with:
+ * - Concurrent request handling
+ * - Ramp-up strategies
+ * - Percentile metrics (p95, p99)
+ * - Real-time assertions
+ * - Progress callbacks
+ *
+ * @example
+ * ```typescript
+ * const results = await loadTest(app, {
+ *   endpoint: "/users",
+ *   concurrent: 1000,
+ *   duration: "10s",
+ *   rampUp: "2s"
+ * });
+ *
+ * expect(results.p95ResponseTime).toBeLessThan(200);
+ * expect(results.errorRate).toBeLessThan(0.01);
+ * ```
+ */
+import { LoadTestOptions, LoadTestResults, LoadTestAssertions, HttpMethod } from "./testing.interfaces.js";
+/**
+ * Run load test against an endpoint.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept testing
+ *
+ * UNIQUE FEATURE: Built-in load testing with percentile metrics!
+ *
+ * @param appOrUrl - Test app or base URL
+ * @param options - Load test options
+ * @returns Load test results with comprehensive metrics
+ *
+ * @example
+ * ```typescript
+ * // Basic load test
+ * const results = await loadTest(app, {
+ *   endpoint: "/users",
+ *   concurrent: 100,
+ *   duration: "30s"
+ * });
+ *
+ * console.log(`Throughput: ${results.throughput} req/s`);
+ * console.log(`P95: ${results.p95ResponseTime}ms`);
+ *
+ * // With assertions
+ * const results = await loadTest(app, {
+ *   endpoint: "/api/data",
+ *   concurrent: 500,
+ *   duration: "1m",
+ *   rampUp: "10s",
+ *   assertions: {
+ *     maxErrorRate: 0.01,
+ *     maxP95: 200,
+ *     minThroughput: 100
+ *   }
+ * });
+ *
+ * expect(results.assertionsPassed).toBe(true);
+ * ```
+ */
+export declare function loadTest(appOrUrl: {
+    baseUrl: string;
+} | string, options: LoadTestOptions): Promise<LoadTestResults>;
+/**
+ * Quick benchmark function for simple performance testing.
+ *
+ * @param fn - Function to benchmark
+ * @param iterations - Number of iterations
+ * @returns Benchmark results
+ *
+ * @example
+ * ```typescript
+ * const results = await benchmark(async () => {
+ *   await userService.getUser("123");
+ * }, 1000);
+ *
+ * console.log(`Average: ${results.average}ms`);
+ * ```
+ */
+export declare function benchmark(fn: () => Promise<unknown> | unknown, iterations?: number): Promise<{
+    average: number;
+    min: number;
+    max: number;
+    median: number;
+    p95: number;
+    p99: number;
+    total: number;
+}>;
+/**
+ * Stress test - gradually increase load until failure.
+ *
+ * @param appOrUrl - Test app or base URL
+ * @param options - Stress test options
+ * @returns Maximum sustainable load
+ *
+ * @example
+ * ```typescript
+ * const result = await stressTest(app, {
+ *   endpoint: "/api/data",
+ *   startConcurrent: 10,
+ *   stepSize: 10,
+ *   maxConcurrent: 500,
+ *   thresholds: {
+ *     maxErrorRate: 0.05,
+ *     maxP95: 500
+ *   }
+ * });
+ *
+ * console.log(`Max sustainable load: ${result.maxConcurrent} concurrent requests`);
+ * ```
+ */
+export declare function stressTest(appOrUrl: {
+    baseUrl: string;
+} | string, options: {
+    endpoint: string;
+    method?: HttpMethod;
+    startConcurrent?: number;
+    stepSize?: number;
+    maxConcurrent?: number;
+    stepDuration?: string;
+    thresholds?: LoadTestAssertions;
+}): Promise<{
+    maxConcurrent: number;
+    breakingPoint: number;
+    results: Array<{
+        concurrent: number;
+        passed: boolean;
+        metrics: Partial<LoadTestResults>;
+    }>;
+}>;