@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/middleware/middleware-utils.js

@@ -0,0 +1,273 @@
+/**
+ * ExpressoTS v4 Middleware Utilities
+ *
+ * Utility functions for route-level middleware usage.
+ *
+ * @module middleware-utils
+ * @public API
+ */
+import { getMiddlewareRegistry } from "./middleware-registry.js";
+/**
+ * Get registered middleware by name for use in route decorators.
+ *
+ * Uses **lazy resolution** - the middleware lookup happens at request time,
+ * not at decorator evaluation time. This allows you to register middleware
+ * in configureServices() and use them in decorators without timing issues.
+ *
+ * @example
+ * ```typescript
+ * import { use } from '@expressots/core';
+ *
+ * @controller('/users')
+ * export class UserController {
+ *
+ *   // Single middleware by name
+ *   @httpGet('/', ...use('auth'))
+ *   async getUsers() { }
+ *
+ *   // Multiple middleware by names
+ *   @httpPost('/', ...use('auth', 'validate-user', 'log-action'))
+ *   async createUser() { }
+ *
+ *   // Mix named and inline
+ *   @httpDelete('/:id', ...use('admin'), validateId)
+ *   async deleteUser() { }
+ * }
+ * ```
+ *
+ * @param names - Names of registered middleware
+ * @returns Array of Express handlers to spread into decorator
+ * @throws Error if middleware is not registered (at request time)
+ *
+ * @public API
+ */
+export function use(...names) {
+    // Return lazy wrappers for each name - resolution happens at request time
+    return names.map((name) => createLazyMiddleware(name));
+}
+/**
+ * Creates a lazy middleware wrapper that resolves the actual middleware
+ * at request time instead of at decorator evaluation time.
+ *
+ * @internal
+ */
+function createLazyMiddleware(name) {
+    return (req, res, next) => {
+        const registry = getMiddlewareRegistry();
+        const middleware = registry.get(name);
+        if (!middleware) {
+            const error = new Error(`Middleware '${name}' not registered. ` +
+                `Register it in app.ts: this.Middleware.register('${name}', handler)`);
+            return next(error);
+        }
+        // If it's an array of middleware, compose them
+        if (Array.isArray(middleware)) {
+            const composed = composeHandlers(middleware);
+            return composed(req, res, next);
+        }
+        // Single middleware
+        return middleware(req, res, next);
+    };
+}
+/**
+ * Internal helper to compose an array of handlers.
+ * @internal
+ */
+function composeHandlers(handlers) {
+    return (req, res, next) => {
+        let index = 0;
+        const runNext = (err) => {
+            if (err)
+                return next(err);
+            if (index >= handlers.length)
+                return next();
+            const handler = handlers[index++];
+            try {
+                const result = handler(req, res, runNext);
+                if (result && typeof result === "object" && "catch" in result) {
+                    result.catch(next);
+                }
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+        runNext();
+    };
+}
+/**
+ * Compose multiple middleware into a single handler.
+ *
+ * This is useful when you want to create reusable middleware chains
+ * that can be applied as a single middleware.
+ *
+ * @example
+ * ```typescript
+ * import { compose } from '@expressots/core';
+ *
+ * // Create a reusable auth chain
+ * const authChain = compose(verifyJwt, loadUser, checkPermissions);
+ *
+ * // Use as single middleware
+ * @httpGet('/', authChain)
+ * async getUsers() { }
+ *
+ * // Compose with use()
+ * @httpPost('/admin', compose(...use('auth'), validateBody))
+ * async adminAction() { }
+ * ```
+ *
+ * @param middlewares - Middleware handlers to compose
+ * @returns Single composed middleware handler
+ *
+ * @public API
+ */
+export function compose(...middlewares) {
+    // Flatten arrays
+    const handlers = middlewares.flat();
+    return (req, res, next) => {
+        let index = 0;
+        const runNext = (err) => {
+            if (err) {
+                return next(err);
+            }
+            if (index >= handlers.length) {
+                return next();
+            }
+            const handler = handlers[index++];
+            try {
+                const result = handler(req, res, runNext);
+                // Handle async middleware
+                if (result && typeof result === "object" && "catch" in result) {
+                    result.catch(next);
+                }
+            }
+            catch (error) {
+                next(error);
+            }
+        };
+        runNext();
+    };
+}
+/**
+ * Create a conditional middleware wrapper.
+ *
+ * The middleware only executes if the condition returns true.
+ *
+ * @example
+ * ```typescript
+ * import { when } from '@expressots/core';
+ *
+ * // Only log in development
+ * const devLogger = when(
+ *   (req) => process.env.NODE_ENV === 'development',
+ *   loggerMiddleware
+ * );
+ *
+ * // Skip for health checks
+ * const rateLimiter = when(
+ *   (req) => !req.path.startsWith('/health'),
+ *   rateLimitMiddleware
+ * );
+ * ```
+ *
+ * @param condition - Function that returns true to execute middleware
+ * @param middleware - Middleware to conditionally execute
+ * @returns Wrapped middleware
+ *
+ * @public API
+ */
+export function when(condition, middleware) {
+    return (req, res, next) => {
+        if (condition(req)) {
+            middleware(req, res, next);
+        }
+        else {
+            next();
+        }
+    };
+}
+/**
+ * Create a middleware that runs in parallel (non-blocking).
+ *
+ * Useful for logging, analytics, or other non-critical operations
+ * that shouldn't block the response.
+ *
+ * @example
+ * ```typescript
+ * import { parallel } from '@expressots/core';
+ *
+ * // Non-blocking analytics
+ * const analytics = parallel((req, res, next) => {
+ *   trackEvent(req.path);
+ *   next();
+ * });
+ * ```
+ *
+ * @param middleware - Middleware to run in parallel
+ * @returns Non-blocking middleware wrapper
+ *
+ * @public API
+ */
+export function parallel(middleware) {
+    return (req, res, next) => {
+        // Run middleware without waiting
+        setImmediate(() => {
+            middleware(req, res, () => {
+                // Swallow the next call - it's parallel
+            });
+        });
+        // Continue immediately
+        next();
+    };
+}
+/**
+ * Create a middleware with timeout.
+ *
+ * If the middleware doesn't call next() within the timeout,
+ * an error is passed to the error handler.
+ *
+ * @example
+ * ```typescript
+ * import { timeout } from '@expressots/core';
+ *
+ * // Wrap slow middleware with 5s timeout
+ * const slowMiddleware = timeout(5000, expensiveOperation);
+ * ```
+ *
+ * @param ms - Timeout in milliseconds
+ * @param middleware - Middleware to wrap
+ * @returns Wrapped middleware with timeout
+ *
+ * @public API
+ */
+export function timeout(ms, middleware) {
+    return (req, res, next) => {
+        let called = false;
+        const timer = setTimeout(() => {
+            if (!called) {
+                called = true;
+                const error = new Error(`Middleware timeout after ${ms}ms`);
+                error.status = 504;
+                next(error);
+            }
+        }, ms);
+        const wrappedNext = (err) => {
+            if (!called) {
+                called = true;
+                clearTimeout(timer);
+                next(err);
+            }
+        };
+        try {
+            middleware(req, res, wrappedNext);
+        }
+        catch (error) {
+            if (!called) {
+                called = true;
+                clearTimeout(timer);
+                next(error);
+            }
+        }
+    };
+}

package/lib/esm/middleware/presets-standalone.js

@@ -0,0 +1,87 @@
+/**
+ * Standalone (free-function) wrappers around the v4 middleware preset system.
+ *
+ * These exist alongside the `Middleware.definePreset` / `Middleware.applyPreset`
+ * instance methods so user code that doesn't have DI access to the `Middleware`
+ * provider — for example, declarative config files outside of the request
+ * lifecycle — can still register and apply presets.
+ *
+ * Usage:
+ * ```ts
+ * import { definePreset, applyPreset } from "@expressots/core";
+ *
+ * definePreset("my-api", {
+ *   parse: { json: { limit: "1mb" } },
+ *   security: { cors: { origin: "https://app.example.com" } },
+ * });
+ *
+ * // ...later, inside configureServices(), with the Middleware DI provider:
+ * applyPreset(this.services.middleware, "my-api");
+ * ```
+ *
+ * @public API
+ */
+/** Module-level registry of presets defined via the standalone helper. */
+const standalonePresets = new Map();
+/**
+ * Register a custom middleware preset under the given name.
+ *
+ * The preset is stored in a module-level registry so it can be referenced
+ * later by `applyPreset(middleware, name)`. Calling `definePreset` with an
+ * existing name overwrites the previous definition.
+ *
+ * @param name   unique identifier for the preset
+ * @param config v4 middleware config object describing the preset
+ *
+ * @public API
+ */
+export function definePreset(name, config) {
+    standalonePresets.set(name, config);
+}
+/**
+ * Apply a previously defined preset (built-in or registered via
+ * `definePreset`) to the supplied `Middleware` instance.
+ *
+ * Resolution order:
+ *  1. Built-in v4 presets (`api`, `web`, `spa`, `microservice`, `graphql`,
+ *     `minimal`, `development`, `production`) are matched by the
+ *     `Middleware` instance itself.
+ *  2. Custom presets previously registered via `Middleware.definePreset`
+ *     on the same instance.
+ *  3. Custom presets registered via the standalone `definePreset` here —
+ *     these are forwarded to the instance on demand.
+ *
+ * @param middleware the active `Middleware` provider (typically resolved from
+ *                   the DI container inside `configureServices()`)
+ * @param name       preset to apply
+ * @param overrides  optional partial config that is merged on top of the
+ *                   preset before application
+ *
+ * @public API
+ */
+export function applyPreset(middleware, name, overrides) {
+    const standalone = standalonePresets.get(name);
+    if (standalone !== undefined) {
+        middleware.definePreset(name, standalone);
+    }
+    middleware.applyPreset(name, overrides);
+}
+/**
+ * Returns the names of every preset registered through the standalone
+ * `definePreset` helper. Built-in presets and per-instance custom presets
+ * are NOT included — those live on the `Middleware` instance.
+ *
+ * @public API
+ */
+export function getStandalonePresetNames() {
+    return Array.from(standalonePresets.keys());
+}
+/**
+ * Remove every preset registered through the standalone `definePreset`
+ * helper. Useful in tests; rarely needed at runtime.
+ *
+ * @public API
+ */
+export function clearStandalonePresets() {
+    standalonePresets.clear();
+}

package/lib/esm/middleware/upload-registry.js

@@ -0,0 +1,84 @@
+/**
+ * ExpressoTS v4 Upload Configuration Registry
+ *
+ * Singleton registry for global upload configuration.
+ * Used by @FileUpload decorator to get default settings.
+ *
+ * @module upload-registry
+ * @public API
+ */
+/**
+ * Global upload configuration storage.
+ * @internal
+ */
+let globalUploadConfig = null;
+/**
+ * Set the global upload configuration.
+ * Called by Middleware.upload() when configuring uploads globally.
+ *
+ * @param config - Upload configuration
+ * @public API
+ */
+export function setGlobalUploadConfig(config) {
+    globalUploadConfig = config;
+}
+/**
+ * Get the global upload configuration.
+ * Used by @FileUpload decorator to get default settings.
+ *
+ * @returns The global upload config or null if not set
+ * @public API
+ */
+export function getGlobalUploadConfig() {
+    return globalUploadConfig;
+}
+/**
+ * Check if global upload configuration is set.
+ *
+ * @returns True if global config exists
+ * @public API
+ */
+export function hasGlobalUploadConfig() {
+    return globalUploadConfig !== null;
+}
+/**
+ * Clear the global upload configuration.
+ * Mainly for testing purposes.
+ *
+ * @internal
+ */
+export function clearGlobalUploadConfig() {
+    globalUploadConfig = null;
+}
+/**
+ * Merge upload configurations.
+ * Local config takes precedence over global config.
+ *
+ * @param global - Global configuration (defaults)
+ * @param local - Local configuration (overrides)
+ * @returns Merged configuration
+ * @public API
+ */
+export function mergeUploadConfigs(global, local) {
+    if (!global && !local) {
+        return {};
+    }
+    if (!global) {
+        return local;
+    }
+    if (!local) {
+        return global;
+    }
+    // Deep merge limits
+    const mergedLimits = global.limits || local.limits
+        ? {
+            ...global.limits,
+            ...local.limits,
+        }
+        : undefined;
+    return {
+        ...global,
+        ...local,
+        limits: mergedLimits,
+    };
+}

package/lib/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/lib/esm/path-resolver/index.js

@@ -0,0 +1,224 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-var-requires */
+/**
+ * TypeScript path mapping utilities.
+ *
+ * NOTE: Path aliases are automatically resolved at BUILD TIME by the ExpressoTS CLI.
+ * The `expressots build` command transforms path aliases (e.g., `@useCases/*`)
+ * to relative paths (e.g., `./useCases/*`) in the compiled output.
+ *
+ * This module provides runtime utilities for ADVANCED use cases only,
+ * such as custom build pipelines or programmatic path resolution.
+ *
+ * For standard usage, simply run `expressots build` followed by `expressots prod`.
+ *
+ * @module path-resolver
+ * @packageDocumentation
+ */
+import * as Module from "module";
+import * as path from "path";
+import * as fs from "fs";
+/**
+ * Register TypeScript path mappings for runtime resolution.
+ * This replaces the need for tsconfig-paths and register-path.js
+ *
+ * @param config - Path resolver configuration
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * registerPathMappings({
+ *   baseUrl: "./src",
+ *   paths: {
+ *     "@app/*": ["app/*"],
+ *     "@shared/*": ["shared/*"]
+ *   }
+ * });
+ * ```
+ */
+export function registerPathMappings(config) {
+    const { baseUrl, paths, rootDir = process.cwd() } = config;
+    const debug = process.env.LOG_PATH_RESOLUTION === "true";
+    // Resolve absolute base path
+    const absoluteBase = path.resolve(rootDir, baseUrl);
+    // Store original resolver
+    const originalResolveFilename = Module._resolveFilename;
+    // Create resolver function
+    const resolveWithPaths = function (request, parent, isMain, options) {
+        // Check if request matches any path mapping
+        for (const [alias, targets] of Object.entries(paths)) {
+            // Convert tsconfig path pattern to regex
+            // @entities/* -> ^@entities/(.*)$
+            const pattern = alias.replace(/\*/g, "(.*)").replace(/\//g, "\\/");
+            const regex = new RegExp(`^${pattern}$`);
+            const match = request.match(regex);
+            if (match) {
+                // Try each target path
+                for (const target of targets) {
+                    // Replace * with captured group
+                    const resolvedTarget = target.replace(/\*/g, match[1] || "");
+                    const fullPath = path.resolve(absoluteBase, resolvedTarget);
+                    // Try different extensions
+                    const extensions = [".js", ".json", "/index.js", ".node"];
+                    for (const ext of extensions) {
+                        const tryPath = fullPath.endsWith(".js")
+                            ? fullPath
+                            : fullPath + ext;
+                        if (fs.existsSync(tryPath)) {
+                            if (debug) {
+                                console.log(`[PathResolver] Resolved ${request} -> ${tryPath}`);
+                            }
+                            return originalResolveFilename.call(this, tryPath, parent, isMain, options);
+                        }
+                    }
+                }
+            }
+        }
+        // Fall back to original resolver
+        return originalResolveFilename.call(this, request, parent, isMain, options);
+    };
+    // Try multiple ways to override module resolution (Node version compatibility)
+    try {
+        // Method 1: Direct assignment (works on Node < 22)
+        Module._resolveFilename = resolveWithPaths;
+    }
+    catch {
+        try {
+            // Method 2: Object.defineProperty (Node 22+ where direct assignment fails)
+            Object.defineProperty(Module, "_resolveFilename", {
+                value: resolveWithPaths,
+                writable: true,
+                configurable: true,
+            });
+        }
+        catch (e) {
+            // Method 3: Use require.cache manipulation for Node 22+
+            // This is a fallback that doesn't require modifying Module internals
+            if (debug) {
+                console.log(`[PathResolver] Using fallback resolution method`);
+            }
+            // Store mappings for use with manual requires
+            global.__expressotsPathMappings = {
+                absoluteBase,
+                paths,
+                resolve: (request) => {
+                    for (const [alias, targets] of Object.entries(paths)) {
+                        const pattern = alias.replace(/\*/g, "(.*)").replace(/\//g, "\\/");
+                        const regex = new RegExp(`^${pattern}$`);
+                        const match = request.match(regex);
+                        if (match) {
+                            for (const target of targets) {
+                                const resolvedTarget = target.replace(/\*/g, match[1] || "");
+                                const fullPath = path.resolve(absoluteBase, resolvedTarget);
+                                const extensions = [".js", ".json", "/index.js", ".node"];
+                                for (const ext of extensions) {
+                                    const tryPath = fullPath.endsWith(".js")
+                                        ? fullPath
+                                        : fullPath + ext;
+                                    if (fs.existsSync(tryPath)) {
+                                        return tryPath;
+                                    }
+                                }
+                            }
+                        }
+                    }
+                    return null;
+                },
+            };
+        }
+    }
+}
+/**
+ * Load tsconfig and extract path mappings.
+ * Automatically called during bootstrap if tsconfig has paths.
+ *
+ * @param tsconfigPath - Path to tsconfig.json or tsconfig.build.json
+ * @returns Path resolver configuration or null if not found
+ * @internal
+ *
+ * @example
+ * ```typescript
+ * const config = loadPathMappingsFromTsConfig("./tsconfig.build.json");
+ * if (config) {
+ *   registerPathMappings(config);
+ * }
+ * ```
+ */
+export function loadPathMappingsFromTsConfig(tsconfigPath = "./tsconfig.json") {
+    const debug = process.env.LOG_PATH_RESOLUTION === "true";
+    try {
+        const configPath = path.resolve(process.cwd(), tsconfigPath);
+        if (debug) {
+            console.log(`[PathResolver] Loading: ${configPath}`);
+        }
+        if (!fs.existsSync(configPath)) {
+            if (debug) {
+                console.log(`[PathResolver] File not found: ${configPath}`);
+            }
+            return null;
+        }
+        // Use require() to load JSON - Node handles encoding, BOM, etc. automatically
+        // Clear cache first to ensure fresh load
+        delete require.cache[configPath];
+        const tsconfig = require(configPath);
+        const compilerOptions = tsconfig.compilerOptions;
+        if (!compilerOptions?.paths || !compilerOptions?.baseUrl) {
+            if (debug) {
+                console.log(`[PathResolver] Missing paths or baseUrl in ${tsconfigPath}`);
+                console.log(`[PathResolver] paths: ${JSON.stringify(compilerOptions?.paths)}`);
+                console.log(`[PathResolver] baseUrl: ${compilerOptions?.baseUrl}`);
+            }
+            return null;
+        }
+        // IMPORTANT: In production, resolve baseUrl relative to outDir
+        // outDir: "./dist", baseUrl: "./src" → resolve to "./dist/src"
+        let resolvedBaseUrl = compilerOptions.baseUrl;
+        const outDir = compilerOptions.outDir;
+        if (outDir) {
+            // We're in compiled output (dist/), adjust baseUrl relative to current directory
+            // Current dir is root (where dist/ is), baseUrl should be relative to that
+            resolvedBaseUrl = path.join(outDir, compilerOptions.baseUrl);
+        }
+        if (debug) {
+            console.log(`[PathResolver] Config loaded successfully:`);
+            console.log(`[PathResolver] baseUrl: ${resolvedBaseUrl}`);
+            console.log(`[PathResolver] paths: ${JSON.stringify(compilerOptions.paths)}`);
+        }
+        return {
+            baseUrl: resolvedBaseUrl,
+            paths: compilerOptions.paths,
+            rootDir: process.cwd(), // Always root of project
+        };
+    }
+    catch (error) {
+        if (debug) {
+            console.log(`[PathResolver] Error loading config: ${error}`);
+        }
+        // Silently fail - path aliases are optional
+        return null;
+    }
+}
+/**
+ * Initialize path resolution automatically.
+ * This is called by bootstrap() before the app starts.
+ *
+ * @param tsconfigPath - Optional path to tsconfig.json
+ * @returns true if paths were registered, false otherwise
+ * @public
+ *
+ * @example
+ * ```typescript
+ * // In production, initialize with build config
+ * if (process.env.NODE_ENV === "production") {
+ *   initializePathResolution("./tsconfig.build.json");
+ * }
+ * ```
+ */
+export function initializePathResolution(tsconfigPath) {
+    const config = loadPathMappingsFromTsConfig(tsconfigPath);
+    if (config) {
+        registerPathMappings(config);
+        return true;
+    }
+    return false;
+}

package/lib/esm/provider/db-in-memory/adapter/adapter.interface.js

@@ -0,0 +1,9 @@
+/**
+ * Data Adapter Interface for ExpressoTS
+ *
+ * The universal database adapter interface that enables seamless
+ * swapping between in-memory, Prisma, TypeORM, and other databases.
+ *
+ * @module db-in-memory/adapter
+ */
+export {};