@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/middleware/middleware-utils.d.ts

@@ -0,0 +1,145 @@
+/**
+ * ExpressoTS v4 Middleware Utilities
+ *
+ * Utility functions for route-level middleware usage.
+ *
+ * @module middleware-utils
+ * @public API
+ */
+import type { Request, RequestHandler } from "express";
+/**
+ * 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 declare function use(...names: Array<string>): Array<RequestHandler>;
+/**
+ * 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 declare function compose(...middlewares: Array<RequestHandler | Array<RequestHandler>>): RequestHandler;
+/**
+ * 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 declare function when(condition: (req: Request) => boolean, middleware: RequestHandler): RequestHandler;
+/**
+ * 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 declare function parallel(middleware: RequestHandler): RequestHandler;
+/**
+ * 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 declare function timeout(ms: number, middleware: RequestHandler): RequestHandler;

package/lib/esm/types/middleware/presets-standalone.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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
+ */
+import type { Middleware } from "./middleware-service.js";
+import type { MiddlewareConfig } from "./middleware-config.js";
+/**
+ * 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 declare function definePreset(name: string, config: MiddlewareConfig): void;
+/**
+ * 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 declare function applyPreset(middleware: Middleware, name: string, overrides?: Partial<MiddlewareConfig>): void;
+/**
+ * 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 declare function getStandalonePresetNames(): Array<string>;
+/**
+ * Remove every preset registered through the standalone `definePreset`
+ * helper. Useful in tests; rarely needed at runtime.
+ *
+ * @public API
+ */
+export declare function clearStandalonePresets(): void;

package/lib/esm/types/middleware/upload-registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * ExpressoTS v4 Upload Configuration Registry
+ *
+ * Singleton registry for global upload configuration.
+ * Used by @FileUpload decorator to get default settings.
+ *
+ * @module upload-registry
+ * @public API
+ */
+import type { UploadConfig } from "./middleware-config.js";
+/**
+ * Set the global upload configuration.
+ * Called by Middleware.upload() when configuring uploads globally.
+ *
+ * @param config - Upload configuration
+ * @public API
+ */
+export declare function setGlobalUploadConfig(config: UploadConfig): void;
+/**
+ * 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 declare function getGlobalUploadConfig(): UploadConfig | null;
+/**
+ * Check if global upload configuration is set.
+ *
+ * @returns True if global config exists
+ * @public API
+ */
+export declare function hasGlobalUploadConfig(): boolean;
+/**
+ * Clear the global upload configuration.
+ * Mainly for testing purposes.
+ *
+ * @internal
+ */
+export declare function clearGlobalUploadConfig(): void;
+/**
+ * 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 declare function mergeUploadConfigs(global: UploadConfig | null, local?: Partial<UploadConfig>): UploadConfig;

package/lib/esm/types/path-resolver/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Path mapping configuration interface.
+ * Matches TypeScript's paths configuration.
+ */
+export interface PathMapping {
+    [pattern: string]: Array<string>;
+}
+/**
+ * Configuration for path resolver.
+ */
+export interface PathResolverConfig {
+    /**
+     * Base URL for path resolution (from tsconfig.json).
+     * @example "./src"
+     */
+    baseUrl: string;
+    /**
+     * Path mappings (from tsconfig.json paths).
+     * @example { "@app/*": ["app/*"], "@shared/*": ["shared/*"] }
+     */
+    paths: PathMapping;
+    /**
+     * Root directory for resolution.
+     * Defaults to process.cwd()
+     */
+    rootDir?: string;
+}
+/**
+ * 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 declare function registerPathMappings(config: PathResolverConfig): void;
+/**
+ * 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 declare function loadPathMappingsFromTsConfig(tsconfigPath?: string): PathResolverConfig | 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 declare function initializePathResolution(tsconfigPath?: string): boolean;

package/lib/esm/types/provider/db-in-memory/adapter/adapter.interface.d.ts

@@ -0,0 +1,222 @@
+/**
+ * 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
+ */
+import { IEntity } from "../schema/entity.interface.js";
+import { FindUniqueArgs, FindFirstArgs, FindManyArgs, CreateArgs, CreateManyArgs, UpdateArgs, UpdateManyArgs, UpsertArgs, DeleteArgs, DeleteManyArgs, CountArgs, AggregateArgs, AggregateResult, BatchPayload, GroupByArgs } from "../query/query.types.js";
+/**
+ * Universal Data Adapter Interface.
+ *
+ * This interface defines the contract that all database adapters must implement.
+ * By coding against this interface, applications can seamlessly swap between:
+ * - In-memory database (for development/testing)
+ * - Prisma (PostgreSQL, MySQL, SQLite, etc.)
+ * - TypeORM (any supported database)
+ * - Mongoose (MongoDB)
+ * - Custom implementations
+ *
+ * @example
+ * ```typescript
+ * // In development
+ * bind<IDataAdapter<User>>("UserAdapter").to(InMemoryAdapter);
+ *
+ * // In production (one line change)
+ * bind<IDataAdapter<User>>("UserAdapter").to(PrismaAdapter);
+ * ```
+ *
+ * @public API
+ */
+export interface IDataAdapter<T extends IEntity> {
+    /**
+     * Find a single unique record.
+     * @param args - Find unique arguments (must include unique field)
+     * @returns The found record or null
+     */
+    findUnique(args: FindUniqueArgs<T>): Promise<T | null>;
+    /**
+     * Find the first record matching the criteria.
+     * @param args - Find first arguments
+     * @returns The first matching record or null
+     */
+    findFirst(args?: FindFirstArgs<T>): Promise<T | null>;
+    /**
+     * Find multiple records matching the criteria.
+     * @param args - Find many arguments (optional)
+     * @returns Array of matching records
+     */
+    findMany(args?: FindManyArgs<T>): Promise<Array<T>>;
+    /**
+     * Find a record by ID or throw if not found.
+     * @param args - Find unique arguments
+     * @returns The found record
+     * @throws EntityNotFoundError if record not found
+     */
+    findUniqueOrThrow(args: FindUniqueArgs<T>): Promise<T>;
+    /**
+     * Find the first record or throw if none found.
+     * @param args - Find first arguments
+     * @returns The first matching record
+     * @throws EntityNotFoundError if no record found
+     */
+    findFirstOrThrow(args?: FindFirstArgs<T>): Promise<T>;
+    /**
+     * Create a new record.
+     * @param args - Create arguments
+     * @returns The created record
+     */
+    create(args: CreateArgs<T>): Promise<T>;
+    /**
+     * Create multiple records.
+     * @param args - Create many arguments
+     * @returns Batch payload with count
+     */
+    createMany(args: CreateManyArgs<T>): Promise<BatchPayload>;
+    /**
+     * Update an existing record.
+     * @param args - Update arguments
+     * @returns The updated record
+     * @throws EntityNotFoundError if record not found
+     */
+    update(args: UpdateArgs<T>): Promise<T>;
+    /**
+     * Update multiple records.
+     * @param args - Update many arguments
+     * @returns Batch payload with count
+     */
+    updateMany(args: UpdateManyArgs<T>): Promise<BatchPayload>;
+    /**
+     * Update or create a record.
+     * @param args - Upsert arguments
+     * @returns The upserted record
+     */
+    upsert(args: UpsertArgs<T>): Promise<T>;
+    /**
+     * Delete a record.
+     * @param args - Delete arguments
+     * @returns The deleted record
+     * @throws EntityNotFoundError if record not found
+     */
+    delete(args: DeleteArgs<T>): Promise<T>;
+    /**
+     * Delete multiple records.
+     * @param args - Delete many arguments
+     * @returns Batch payload with count
+     */
+    deleteMany(args?: DeleteManyArgs<T>): Promise<BatchPayload>;
+    /**
+     * Count records.
+     * @param args - Count arguments (optional)
+     * @returns Number of matching records
+     */
+    count(args?: CountArgs<T>): Promise<number>;
+    /**
+     * Execute aggregate operations.
+     * @param args - Aggregate arguments
+     * @returns Aggregate result
+     */
+    aggregate(args: AggregateArgs<T>): Promise<AggregateResult<T>>;
+    /**
+     * Group records by fields.
+     * @param args - Group by arguments
+     * @returns Array of grouped results
+     */
+    groupBy(args: GroupByArgs<T>): Promise<Array<Partial<T> & AggregateResult<T>>>;
+    /**
+     * Execute operations within a transaction.
+     * @param fn - Transaction function
+     * @returns Result of the transaction function
+     */
+    transaction<R>(fn: (tx: IDataAdapter<T>) => Promise<R>): Promise<R>;
+}
+/**
+ * Table-specific adapter interface for multi-table databases.
+ *
+ * @example
+ * ```typescript
+ * const users = db.table<User>("users");
+ * const posts = db.table<Post>("posts");
+ * ```
+ *
+ * @public API
+ */
+export interface ITableAdapter<T extends IEntity> extends IDataAdapter<T> {
+    /** Table/collection name */
+    readonly tableName: string;
+}
+/**
+ * Database adapter with multi-table support.
+ *
+ * @example
+ * ```typescript
+ * interface MyDB extends IMultiTableAdapter {
+ *   users: IDataAdapter<User>;
+ *   posts: IDataAdapter<Post>;
+ * }
+ * ```
+ *
+ * @public API
+ */
+export interface IMultiTableAdapter {
+    /**
+     * Get an adapter for a specific table.
+     * @param tableName - Name of the table
+     * @returns Table-specific adapter
+     */
+    table<T extends IEntity>(tableName: string): ITableAdapter<T>;
+    /**
+     * Execute operations across multiple tables in a transaction.
+     * @param fn - Transaction function
+     * @returns Result of the transaction function
+     */
+    transaction<R>(fn: (tx: IMultiTableAdapter) => Promise<R>): Promise<R>;
+}
+/**
+ * Subscription for reactive updates.
+ * @public API
+ */
+export interface ISubscription {
+    /** Unsubscribe from updates */
+    unsubscribe(): void;
+}
+/**
+ * Change event types.
+ * @public API
+ */
+export type ChangeType = "create" | "update" | "delete";
+/**
+ * Change event for reactive updates.
+ * @public API
+ */
+export interface ChangeEvent<T> {
+    /** Type of change */
+    type: ChangeType;
+    /** The entity after the change (undefined for delete) */
+    data?: T;
+    /** The entity before the change (undefined for create) */
+    previousData?: T;
+    /** Timestamp of the change */
+    timestamp: Date;
+}
+/**
+ * Reactive data adapter with subscription support.
+ * @public API
+ */
+export interface IReactiveDataAdapter<T extends IEntity> extends IDataAdapter<T> {
+    /**
+     * Subscribe to all changes.
+     * @param callback - Function called on each change
+     * @returns Subscription to unsubscribe
+     */
+    subscribe(callback: (event: ChangeEvent<T>) => void): ISubscription;
+    /**
+     * Subscribe to specific change types.
+     * @param type - Type of change to subscribe to
+     * @param callback - Function called on each change
+     * @returns Subscription to unsubscribe
+     */
+    on(type: ChangeType, callback: (event: ChangeEvent<T>) => void): ISubscription;
+}