@expressots/core 4.0.0-preview.1 → 4.0.0-preview.3

package/lib/cjs/types/provider/db-in-memory/storage/memory-store.d.ts

@@ -102,6 +102,24 @@ export declare class EntityNotFoundError extends Error {
     id: string;
     constructor(entityName: string, id: string);
 }
+/**
+ * Error thrown when a table reaches its configured record limit.
+ * @public API
+ */
+export declare class MaxRecordsExceededError extends Error {
+    tableName: string;
+    limit: number;
+    constructor(tableName: string, limit: number);
+}
+/**
+ * Error thrown when entity validation fails (when `@Entity({ validate: true })`).
+ * @public API
+ */
+export declare class EntityValidationError extends Error {
+    tableName: string;
+    field: string;
+    constructor(tableName: string, field: string, message?: string);
+}
 /**
  * Error thrown when an entity already exists.
  * @public API
@@ -143,6 +161,8 @@ export interface MemoryStoreOptions {
     timestamps?: boolean;
     /** Enable soft deletes */
     softDelete?: boolean;
+    /** Maximum number of records allowed in the table (0 = unlimited) */
+    maxRecordsPerTable?: number;
 }
 /**
  * High-performance in-memory storage for a single table/collection.
@@ -175,12 +195,26 @@ export declare class MemoryStore<T extends IEntity> {
     private autoGenerateFields;
     /** Default values */
     private defaultValues;
+    /** Maximum number of records allowed (0 = unlimited) */
+    private maxRecords;
+    /** Enable runtime validation (from @Entity({ validate: true })) */
+    private validate;
+    /** Fields that must be present and non-null when validation is enabled */
+    private requiredFields;
     constructor(tableName: string, options?: MemoryStoreOptions);
     /**
      * Load schema metadata from decorators.
      * @private
      */
     private loadSchemaMetadata;
+    /**
+     * Validate an entity against the schema (only when `validate` is enabled).
+     * Ensures required fields (primary key + unique, excluding @Nullable) are
+     * present and non-null.
+     * @private
+     * @throws ValidationError when a required field is missing or null
+     */
+    private validateEntity;
     /**
      * Apply auto-generation and defaults to entity.
      * @private

package/lib/cjs/types/provider/logger/logger.banner.d.ts

@@ -72,7 +72,7 @@ export declare class BannerGenerator {
      */
     private displayFullBanner;
     /**
-     * Display compact banner.
+     * Display compact banner using structured log format (cloud-friendly).
      */
     private displayCompactBanner;
     /**

package/lib/cjs/types/provider/logger/logger.config.d.ts

@@ -50,6 +50,13 @@ export interface LoggerConfig {
 }
 /**
  * Default logger configuration.
+ *
+ * Honours `process.env.LOG_LEVEL` when set so that any logs emitted
+ * BEFORE the application's `globalConfiguration()` runs (e.g. interceptor
+ * registration during container construction) are gated by the user's
+ * desired log level instead of the development default of `DEBUG`.
+ * Falls back to `DEBUG` in development and `INFO` in production.
+ *
  * @public API
  */
 export declare function getDefaultLoggerConfig(): LoggerConfig;

package/lib/cjs/types/provider/logger/logger.formatter.d.ts

@@ -9,6 +9,16 @@ export interface FormatOptions {
     redact?: boolean;
     /** Custom redactor instance (uses global if not provided) */
     redactor?: Redactor;
+    /**
+     * Emit ANSI color escape codes. When false, the formatted output is
+     * post-processed to strip every ANSI escape. Defaults to true (colored).
+     *
+     * Disable this for non-TTY consumers like cloud log viewers (Azure
+     * App Service, AWS CloudWatch, Heroku, Kubernetes, etc.) and Studio's
+     * Live Logs panel, all of which display the raw text without
+     * interpreting terminal escape sequences.
+     */
+    colors?: boolean;
 }
 /**
  * Format log entry for development (human-readable, colored).

package/lib/cjs/types/provider/logger/logger.provider.d.ts

@@ -12,7 +12,7 @@ import { LogQueryOptions, LogQuery, QueryStats } from "./logger.query.js";
  * - Automatic context detection (class/method names)
  * - Request-scoped context via AsyncLocalStorage
  * - Child logger creation with inherited context
- * - Multiple log levels (TRACE, DEBUG, INFO, WARN, ERROR, FATAL)
+ * - Multiple log levels (ALL, DEBUG, INFO, WARN, ERROR, FATAL, SILENT)
  * - Pluggable transports (console, file, HTTP)
  * @public API
  */
@@ -26,11 +26,42 @@ declare class Logger implements IProvider {
     private groupingManager;
     private healthMonitor;
     private queryManager;
+    /**
+     * Module-level overrides applied by `Logger.configure(...)` on top of the
+     * built-in defaults. Used by the constructor of every future `Logger`
+     * instance so application-wide config (e.g. log level, transports) can be
+     * set once before bootstrap, before any DI container exists.
+     */
+    private static defaultOverrides;
     name: string;
     version: string;
     author: string;
     repo: string;
     constructor();
+    /**
+     * Configure the default LoggerConfig used by every future `Logger`
+     * instance constructed in this process.
+     *
+     * Use this from application config files **before** bootstrap so the DI
+     * container's Logger picks up the correct level / transports / grouping /
+     * health / redaction settings without needing to inject and reconfigure it.
+     * Calls are merged: later calls override earlier ones, but unspecified
+     * keys keep their previously-set values.
+     *
+     * Already-constructed Logger instances are NOT mutated by this call —
+     * use the instance method `logger.configure(...)` to update a live one.
+     *
+     * @param config - Partial configuration to merge with the defaults.
+     * @public API
+     */
+    static configure(config: Partial<LoggerConfig>): void;
+    /**
+     * Reset the module-level overrides set by `Logger.configure`. Useful in
+     * tests to undo cross-test pollution.
+     *
+     * @public API
+     */
+    static resetConfigure(): void;
     /**
      * Configure the logger.
      * @param config - Partial configuration to merge with defaults

package/lib/cjs/types/provider/logger/transports/console.transport.d.ts

@@ -32,6 +32,13 @@ export declare class ConsoleTransport implements ILogTransport {
     });
     /**
      * Create a console transport optimized for development.
+     *
+     * Colors are auto-detected: they're emitted when stdout is a TTY
+     * (your terminal) and disabled when stdout is piped or captured by
+     * a cloud log collector (Azure App Service, AWS CloudWatch, Heroku,
+     * Docker, Kubernetes, etc.). Respects the standard `NO_COLOR` and
+     * `FORCE_COLOR` environment variables.
+     *
      * @param redact - Enable redaction (default: false for development)
      * @returns ConsoleTransport configured for development
      * @public API

package/lib/cjs/types/provider/logger/utils/log-levels.d.ts

@@ -4,8 +4,8 @@
  * @public API
  */
 export declare enum LogLevel {
-    /** Ultra-detailed diagnostic information (function entry/exit) */
-    TRACE = 0,
+    /** Show all logs (ultra-detailed diagnostic information, function entry/exit) */
+    ALL = 0,
     /** Detailed diagnostic information for debugging */
     DEBUG = 1,
     /** General informational messages */
@@ -23,7 +23,7 @@ export declare enum LogLevel {
  * String representation of log levels for backward compatibility.
  * @public API
  */
-export type LogLevelString = "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL" | "SILENT" | "NONE";
+export type LogLevelString = "ALL" | "TRACE" | "DEBUG" | "INFO" | "WARN" | "ERROR" | "FATAL" | "SILENT" | "NONE";
 /**
  * Legacy log level for backward compatibility.
  * Maps to INFO level.

package/lib/cjs/types/provider/validation/adapters/index.d.ts

@@ -2,9 +2,12 @@
  * Validation Adapters
  * @module @expressots/core/validation/adapters
  *
- * Built-in adapters for validation libraries.
- * Additional adapters (Zod, Yup, Joi) available as separate packages:
- * - @expressots/validator-zod
- * - @expressots/validator-yup
+ * Built-in adapters for validation libraries. The validation libraries
+ * themselves (`class-validator`, `zod`, `yup`) are *optional peer
+ * dependencies* — install only the one(s) you actually use.
+ *
+ * Additional Joi adapter is on the roadmap.
  */
 export { ClassValidatorAdapter } from "./class-validator.adapter.js";
+export { ZodValidatorAdapter, createZodValidator } from "./zod.adapter.js";
+export { YupValidatorAdapter, createYupValidator } from "./yup.adapter.js";

package/lib/cjs/types/provider/validation/adapters/yup.adapter.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Yup Validation Adapter
+ * @module @expressots/core/validation
+ *
+ * Built-in adapter for the [yup](https://github.com/jquense/yup) validation
+ * library. `yup` is declared as an *optional* peer dependency: install it
+ * explicitly (`npm i yup`) to enable this adapter.
+ *
+ * @example
+ * ```ts
+ * import * as yup from "yup";
+ * import { validationRegistry, createYupValidator } from "@expressots/core";
+ *
+ * validationRegistry.register(createYupValidator());
+ *
+ * const CreateUserSchema = yup.object({
+ *   email: yup.string().email().required(),
+ *   age:   yup.number().integer().min(18).required(),
+ * });
+ *
+ * @controller("/users")
+ * class UsersController {
+ *   @Post("/")
+ *   create(@body(CreateUserSchema) input: yup.InferType<typeof CreateUserSchema>) {
+ *     // input is fully typed and validated
+ *   }
+ * }
+ * ```
+ */
+import { IValidationAdapter, ValidationOptions, ValidationResult } from "../validation.interface.js";
+/** Subset of yup's surface we depend on, structurally typed. */
+interface YupLikeSchema {
+    readonly __isYupSchema__?: boolean;
+    validate?(data: unknown, options?: YupOptions): Promise<unknown>;
+    validateSync?(data: unknown, options?: YupOptions): unknown;
+    cast?(data: unknown, options?: YupOptions): unknown;
+}
+interface YupOptions {
+    abortEarly?: boolean;
+    stripUnknown?: boolean;
+    context?: unknown;
+}
+/**
+ * Adapter for [yup](https://github.com/jquense/yup). Detects yup schemas at
+ * runtime by checking for the `__isYupSchema__` brand or the presence of a
+ * `validate` + `cast` method pair.
+ *
+ * @public API
+ */
+export declare class YupValidatorAdapter implements IValidationAdapter<YupLikeSchema> {
+    readonly name = "yup";
+    readonly priority = 80;
+    canHandle(schema: unknown): boolean;
+    validate(data: unknown, schema: YupLikeSchema, options?: ValidationOptions): Promise<ValidationResult>;
+    transform(data: unknown, schema: YupLikeSchema): Promise<unknown>;
+    private mapIssues;
+}
+/**
+ * Convenience factory matching the `createXxxValidator` naming used by the
+ * other adapters. Equivalent to `new YupValidatorAdapter()`.
+ *
+ * @public API
+ */
+export declare function createYupValidator(): YupValidatorAdapter;
+export {};

package/lib/cjs/types/provider/validation/adapters/zod.adapter.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Zod Validation Adapter
+ * @module @expressots/core/validation
+ *
+ * Built-in adapter for the [zod](https://zod.dev) validation library.
+ * `zod` is declared as an *optional* peer dependency: install it explicitly
+ * (`npm i zod`) to enable this adapter; otherwise validation falls back to
+ * the next registered adapter.
+ *
+ * @example
+ * ```ts
+ * import { z } from "zod";
+ * import { validationRegistry, ZodValidatorAdapter, createZodValidator } from "@expressots/core";
+ *
+ * validationRegistry.register(createZodValidator());
+ *
+ * const CreateUserSchema = z.object({
+ *   email: z.string().email(),
+ *   age:   z.number().int().min(18),
+ * });
+ *
+ * @controller("/users")
+ * class UsersController {
+ *   @Post("/")
+ *   create(@body(CreateUserSchema) input: z.infer<typeof CreateUserSchema>) {
+ *     // input is fully typed and validated
+ *   }
+ * }
+ * ```
+ */
+import { IValidationAdapter, ValidationOptions, ValidationResult } from "../validation.interface.js";
+/**
+ * Minimal structural typing for the subset of zod we actually call. We cannot
+ * import zod directly from core (it is an optional peer), but we type the
+ * schema we receive as `unknown` and refine via the runtime `canHandle` check.
+ */
+interface ZodLikeSchema {
+    readonly _def?: unknown;
+    parse?(data: unknown): unknown;
+    parseAsync?(data: unknown): Promise<unknown>;
+    safeParseAsync?(data: unknown): Promise<{
+        success: boolean;
+        data?: unknown;
+        error?: {
+            issues: Array<ZodIssue>;
+        };
+    }>;
+    safeParse?(data: unknown): {
+        success: boolean;
+        data?: unknown;
+        error?: {
+            issues: Array<ZodIssue>;
+        };
+    };
+}
+interface ZodIssue {
+    path: Array<string | number>;
+    message: string;
+    code?: string;
+    received?: unknown;
+}
+/**
+ * Adapter for [zod](https://zod.dev). Picks up any zod schema (`z.object`,
+ * `z.string`, ...) at runtime by structural detection — no compile-time
+ * dependency on `zod` is required.
+ *
+ * @public API
+ */
+export declare class ZodValidatorAdapter implements IValidationAdapter<ZodLikeSchema> {
+    readonly name = "zod";
+    readonly priority = 90;
+    canHandle(schema: unknown): boolean;
+    validate(data: unknown, schema: ZodLikeSchema, _options?: ValidationOptions): Promise<ValidationResult>;
+    transform(data: unknown, schema: ZodLikeSchema): Promise<unknown>;
+    private mapIssues;
+}
+/**
+ * Convenience factory matching the `createXxxValidator` naming used by the
+ * other adapters. Equivalent to `new ZodValidatorAdapter()`.
+ *
+ * @public API
+ */
+export declare function createZodValidator(): ZodValidatorAdapter;
+export {};

package/lib/cjs/types/provider/validation/index.d.ts

@@ -16,4 +16,4 @@ export { ValidationRegistry } from "./validation-registry.js";
 export { SmartFieldDetector } from "./smart-field-detector.js";
 export { HelpfulErrorFormatter, type ErrorFormat, type FormattedErrorResponse, } from "./helpful-error-formatter.js";
 export { getParameterType, getAllParameterTypes, getClassProperties, hasClassValidatorDecorators, isZodSchema, isClassConstructor, detectSchemaType, type InferredTypeInfo, type InferredPropertyInfo, } from "./type-inference.js";
-export { ClassValidatorAdapter } from "./adapters/index.js";
+export { ClassValidatorAdapter, ZodValidatorAdapter, createZodValidator, YupValidatorAdapter, createYupValidator, } from "./adapters/index.js";

package/lib/cjs/types/render/features/view-debugger.d.ts

@@ -27,6 +27,16 @@ export declare class ViewDebugger {
      * Handle the view preview endpoint.
      */
     private handlePreviewEndpoint;
+    /**
+     * Normalise the `view` route param across Express 4 and 5.
+     *
+     * Express 4 / path-to-regexp v6 captured `/__views/preview/:view(*)`
+     * as a single string. Express 5 / path-to-regexp v8 changed the
+     * named-splat capture to `string[]` (one entry per slash-separated
+     * segment). The view engine needs the slash-joined form, so we always
+     * collapse the array shape back to that.
+     */
+    private resolveViewParam;
     /**
      * Handle the view info endpoint.
      */

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

@@ -345,13 +345,15 @@ export interface FluentRequest {
      */
     expect<T>(assertion: (response: FluentResponse<T>) => void): FluentRequest;
     /**
-     * Execute the request and return the response.
+     * Execute the request and return the response. Body type defaults to
+     * `any` for ergonomic test code — see {@link FluentResponse} for the
+     * rationale and how to opt into strict typing via `<T>`.
      */
-    execute<T = unknown>(): Promise<FluentResponse<T>>;
+    execute<T = any>(): Promise<FluentResponse<T>>;
     /**
      * Alias for execute().
      */
-    end<T = unknown>(): Promise<FluentResponse<T>>;
+    end<T = any>(): Promise<FluentResponse<T>>;
 }
 /**
  * Time assertion options for performance testing.
@@ -372,8 +374,30 @@ export interface TimeAssertion {
 }
 /**
  * Fluent response object.
+ *
+ * The body type defaults to `any` rather than `unknown` — this is a
+ * deliberate ergonomics call for a *test-time* HTTP client API.
+ *
+ * Tests written against ExpressoTS controllers usually look like:
+ *
+ *   const r = await testApp.request.get("/users/1").execute();
+ *   expect(r.body.id).toBe(1);
+ *
+ * With `body: unknown` (the type-safe default), every property access
+ * trips TS18046 and forces every test to either pass an inline generic
+ * (`.execute<{ id: number }>()`) or cast (`(r.body as { id: number })`).
+ * That's the right default for *production* code where you don't
+ * actually know the response shape — but in a test, the fixture _is_
+ * the type contract: the test file already encodes the expected shape
+ * in its assertions, so the type check is redundant noise.
+ *
+ * Users who want strict typing can still parameterise: the generic
+ * is preserved on `request.execute<T>()` and on `FluentResponse<T>`
+ * itself, so opting into a typed body remains a single keystroke
+ * (`.execute<UserDto>()`). This mirrors how `supertest` and `axios`
+ * default — both publish `body: any` for the same reason.
  */
-export interface FluentResponse<T = unknown> {
+export interface FluentResponse<T = any> {
     /**
      * Response status code.
      */
@@ -387,7 +411,8 @@ export interface FluentResponse<T = unknown> {
      */
     headers: Record<string, string>;
     /**
-     * Parsed response body.
+     * Parsed response body. Defaults to `any` — see the interface
+     * docstring for the rationale and how to opt into strict typing.
      */
     body: T;
     /**
@@ -487,7 +512,7 @@ export interface SnapshotRequest {
     expectContentType(type: string | RegExp): SnapshotRequest;
     expectBodyPath(path: string, expected: unknown): SnapshotRequest;
     expect<T>(assertion: (response: FluentResponse<T>) => void): SnapshotRequest;
-    execute<T = unknown>(): Promise<FluentResponse<T>>;
+    execute<T = any>(): Promise<FluentResponse<T>>;
     /**
      * Assert response matches snapshot.
      */

package/lib/esm/application/application-factory.js

@@ -119,6 +119,12 @@ export class AppFactory {
      *
      * @throws {Error} If webServerType is not a valid constructor
      *
+     * @deprecated Use `bootstrap()` from `@expressots/core` instead. `bootstrap()`
+     * additionally handles environment file loading, port configuration,
+     * graceful shutdown, the startup banner, and configuration validation.
+     * `AppFactory.create()` will keep working for advanced use cases but is
+     * scheduled for removal in a future major release.
+     *
      * @public API
      */
     static async create(webServerType) {