@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/render/render-service.d.ts

@@ -0,0 +1,157 @@
+import type { Application } from "express";
+import type { EngineAdapter, IRenderService } from "./render-interface.js";
+import type { RenderConfig, RenderOptions, StreamOptions, RenderMetrics, EngineType, PresetName } from "./render-config.js";
+/**
+ * Render Service
+ *
+ * @description Main service for managing view rendering across different engines.
+ * Provides a unified API for configuration, rendering, and introspection.
+ *
+ * @example
+ * ```typescript
+ * const renderService = new RenderService(app);
+ * await renderService.configure({
+ *   engine: 'react',
+ *   viewsDir: 'src/views',
+ *   ssr: { hydrate: true }
+ * });
+ * const html = await renderService.render('Home', { title: 'Welcome' });
+ * ```
+ *
+ * @public API
+ */
+export declare class RenderService implements IRenderService {
+    private registry;
+    private config;
+    private app;
+    private logger;
+    private activeEngine;
+    private metrics;
+    private renderTimes;
+    private isConfigured;
+    private hotReloader;
+    private viewDebugger;
+    private typeGenerator;
+    constructor(app: Application);
+    /**
+     * Configure the render service.
+     *
+     * @param config - Render configuration or preset name
+     */
+    configure(config?: RenderConfig | PresetName): Promise<void>;
+    /**
+     * Register a custom engine adapter.
+     *
+     * @param adapter - Engine adapter to register
+     */
+    registerEngine(adapter: EngineAdapter): void;
+    /**
+     * Get an engine by name.
+     *
+     * @param name - Engine name
+     * @returns Engine adapter or undefined
+     */
+    getEngine(name: string): EngineAdapter | undefined;
+    /**
+     * Get the currently active engine.
+     *
+     * @returns Active engine adapter
+     */
+    getActiveEngine(): EngineAdapter;
+    /**
+     * Render a view to string.
+     *
+     * @param view - View name or path
+     * @param data - Data to pass to the template
+     * @param options - Additional render options
+     * @returns Rendered HTML string
+     */
+    render(view: string, data?: any, options?: RenderOptions): Promise<string>;
+    /**
+     * Render a view as a stream.
+     *
+     * @param view - View name or path
+     * @param data - Data to pass to the template
+     * @param options - Stream options
+     * @returns Readable stream of HTML
+     */
+    renderStream(view: string, data?: any, options?: StreamOptions): NodeJS.ReadableStream;
+    /**
+     * Enable hot reload for views.
+     */
+    enableHotReload(): Promise<void>;
+    /**
+     * Enable view type generation.
+     */
+    enableTypeGeneration(): Promise<void>;
+    /**
+     * Enable the view debugger endpoint.
+     */
+    enableViewDebugger(): Promise<void>;
+    /**
+     * Get list of registered engine names.
+     *
+     * @returns Array of engine names
+     */
+    getRegisteredEngines(): Array<string>;
+    /**
+     * Get list of discovered view files.
+     *
+     * @returns Array of view file paths
+     */
+    getViewFiles(): Array<string>;
+    /**
+     * Get current configuration.
+     *
+     * @returns Render configuration
+     */
+    getConfig(): RenderConfig;
+    /**
+     * Get render metrics.
+     *
+     * @returns Render metrics
+     */
+    getMetrics(): RenderMetrics;
+    /**
+     * Check if an engine is available (installed).
+     *
+     * @param engine - Engine type to check
+     * @returns Whether the engine is available
+     */
+    isEngineAvailable(engine: EngineType): boolean;
+    /**
+     * Register built-in engine adapters.
+     */
+    private registerBuiltInAdapters;
+    /**
+     * Apply default configuration values.
+     *
+     * @param config - User configuration
+     * @returns Configuration with defaults applied
+     */
+    private applyDefaults;
+    /**
+     * Build engine-specific options from config.
+     *
+     * @param config - Render configuration
+     * @returns Engine options
+     */
+    private buildEngineOptions;
+    /**
+     * Update render metrics.
+     *
+     * @param engineName - Engine that performed the render
+     * @param renderTime - Time taken to render in ms
+     */
+    private updateMetrics;
+    /**
+     * Check if running in development mode.
+     *
+     * @returns Whether in development mode
+     */
+    private isDevelopment;
+    /**
+     * Log the current configuration.
+     */
+    private logConfiguration;
+}

package/lib/esm/types/render/utils/cache-manager.d.ts

@@ -0,0 +1,106 @@
+import type { CacheConfig } from "../render-config.js";
+/**
+ * Cache Manager
+ *
+ * @description Manages view caching with configurable strategies.
+ * Supports memory caching with TTL and LRU eviction.
+ *
+ * @public API
+ */
+export declare class CacheManager {
+    private cache;
+    private config;
+    private maxSize;
+    constructor(config?: CacheConfig);
+    /**
+     * Get a cached value.
+     *
+     * @param key - Cache key
+     * @returns Cached value or undefined if not found/expired
+     */
+    get<T>(key: string): T | undefined;
+    /**
+     * Set a cached value.
+     *
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Time-to-live in seconds (optional, uses config default)
+     */
+    set<T>(key: string, value: T, ttl?: number): void;
+    /**
+     * Check if a key exists in cache (and is not expired).
+     *
+     * @param key - Cache key
+     * @returns Whether the key exists and is valid
+     */
+    has(key: string): boolean;
+    /**
+     * Delete a cached value.
+     *
+     * @param key - Cache key
+     * @returns Whether the key was deleted
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all cached values.
+     */
+    clear(): void;
+    /**
+     * Get the number of cached items.
+     *
+     * @returns Cache size
+     */
+    get size(): number;
+    /**
+     * Get cache statistics.
+     *
+     * @returns Cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Remove expired entries.
+     *
+     * @returns Number of entries removed
+     */
+    cleanup(): number;
+    /**
+     * Update the cache configuration.
+     *
+     * @param config - New configuration
+     */
+    updateConfig(config: Partial<CacheConfig>): void;
+    /**
+     * Check if an entry is expired.
+     *
+     * @param entry - Cache entry
+     * @returns Whether the entry is expired
+     */
+    private isExpired;
+    /**
+     * Evict the least recently used entry.
+     */
+    private evictLRU;
+}
+/**
+ * Cache statistics.
+ * @public API
+ */
+export interface CacheStats {
+    /** Current cache size */
+    size: number;
+    /** Maximum cache size */
+    maxSize: number;
+    /** Total cache hits */
+    totalHits: number;
+    /** Number of expired entries */
+    expiredCount: number;
+    /** Whether caching is enabled */
+    enabled: boolean;
+}
+/**
+ * Get the cache manager singleton.
+ *
+ * @param config - Optional configuration
+ * @returns Cache manager instance
+ */
+export declare function getCacheManager(config?: CacheConfig): CacheManager;

package/lib/esm/types/render/utils/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Render Utilities
+ *
+ * @module render/utils
+ * @description Utility classes for the render engine system.
+ * @public API
+ */
+export { PackageResolver, PackageNotInstalledError, getPackageResolver, } from "./package-resolver.js";
+export { ViewScanner, getViewScanner } from "./view-scanner.js";
+export { CacheManager, getCacheManager } from "./cache-manager.js";
+export type { CacheStats } from "./cache-manager.js";

package/lib/esm/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/esm/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/esm/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/esm/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/esm/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;