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

package/lib/esm/provider/logger/logger.formatter.js

@@ -1,6 +1,17 @@
 import { LogLevel, logLevelToString } from "./utils/log-levels.js";
 import { colorCodes } from "../../console/color-codes.js";
 import { getGlobalRedactor } from "./logger.redaction.js";
+/**
+ * Strip ANSI escape sequences (SGR colors, cursor moves, etc.) from a
+ * string. Cheap fast-path bails out when no escape character is present.
+ */
+// eslint-disable-next-line no-control-regex
+const ANSI_ESCAPE_REGEX = /\u001b\[[\d;?]*[ -/]*[@-~]/g;
+function stripAnsiEscapes(input) {
+    if (!input || input.indexOf("\u001b") === -1)
+        return input;
+    return input.replace(ANSI_ESCAPE_REGEX, "");
+}
 /**
  * Format log entry for development (human-readable, colored).
  * @param entry - Log entry to format
@@ -44,6 +55,13 @@ export function formatDev(entry, options) {
     if (processedEntry.flow) {
         output += formatFlow(processedEntry.flow, 2);
     }
+    // Strip ANSI escapes once at the end when colors are disabled. This is
+    // far simpler than threading a "useColors" flag through every nested
+    // `colorText(...)` call site and the perf cost (one regex pass over a
+    // log line) is negligible relative to the I/O that follows.
+    if (options?.colors === false) {
+        return stripAnsiEscapes(output);
+    }
     return output;
 }
 /**
@@ -106,7 +124,7 @@ function formatTimestamp(date) {
  */
 function getLevelColor(level) {
     switch (level) {
-        case LogLevel.TRACE:
+        case LogLevel.ALL:
             return "white";
         case LogLevel.DEBUG:
             return "blue";
@@ -331,6 +349,9 @@ export function formatGroupedDev(groupedEntry, options) {
             }
         }
     }
+    if (options?.colors === false) {
+        return stripAnsiEscapes(output);
+    }
     return output;
 }
 /**

package/lib/esm/provider/logger/logger.provider.js

@@ -25,11 +25,12 @@ import { LogQueryManager, LogQuery, exportToMarkdown, } 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
  */
-let Logger = Logger_1 = class Logger {
+let Logger = class Logger {
+    static { Logger_1 = this; }
     pid;
     config;
     transports = [];
@@ -39,21 +40,40 @@ let Logger = Logger_1 = class Logger {
     groupingManager = null;
     healthMonitor = null;
     queryManager = null;
+    /**
+     * 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.
+     */
+    static defaultOverrides = {};
     name = "Logger Provider";
     version = "4.1.0";
     author = "Richard Zampieri";
     repo = "https://github.com/expressots/expressots";
     constructor() {
         this.pid = process.pid;
-        this.config = getDefaultLoggerConfig();
-        // Initialize with default console transport if none provided
+        // Merge module-level overrides on top of the built-in defaults so values
+        // set via Logger.configure(...) before container creation propagate to
+        // every instance. Caller-supplied transports replace the defaults, level
+        // is forwarded to the auto-installed console transport below.
+        const baseConfig = getDefaultLoggerConfig();
+        this.config = {
+            ...baseConfig,
+            ...Logger_1.defaultOverrides,
+        };
+        // Initialize with default console transport if none provided.
+        // Aligning the transport's level with the resolved logger level
+        // (which already honours `process.env.LOG_LEVEL`) keeps both
+        // filters consistent for messages emitted before any explicit
+        // `logger.configure({ level })` call.
         if (this.config.transports.length === 0) {
             const isDevelopment = process.env.NODE_ENV !== "production";
-            this.config.transports = [
-                isDevelopment
-                    ? ConsoleTransport.forDevelopment()
-                    : ConsoleTransport.forProduction(),
-            ];
+            const transport = isDevelopment
+                ? ConsoleTransport.forDevelopment()
+                : ConsoleTransport.forProduction();
+            transport.level = parseLogLevel(this.config.level);
+            this.config.transports = [transport];
         }
         this.transports = this.config.transports;
         // Initialize grouping manager with default config
@@ -61,6 +81,37 @@ let Logger = Logger_1 = class Logger {
         // Initialize query manager with default config
         this.queryManager = new LogQueryManager(this.config.query);
     }
+    /**
+     * 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) {
+        Logger_1.defaultOverrides = {
+            ...Logger_1.defaultOverrides,
+            ...config,
+        };
+    }
+    /**
+     * Reset the module-level overrides set by `Logger.configure`. Useful in
+     * tests to undo cross-test pollution.
+     *
+     * @public API
+     */
+    static resetConfigure() {
+        Logger_1.defaultOverrides = {};
+    }
     /**
      * Configure the logger.
      * @param config - Partial configuration to merge with defaults
@@ -132,7 +183,7 @@ let Logger = Logger_1 = class Logger {
      * @public API
      */
     trace(message, data) {
-        this.log(LogLevel.TRACE, message, { data });
+        this.log(LogLevel.ALL, message, { data });
     }
     /**
      * Log a debug message (detailed diagnostic).

package/lib/esm/provider/logger/transports/console.transport.js

@@ -1,5 +1,34 @@
 import { LogLevel, shouldLog } from "../utils/log-levels.js";
 import { formatDev, formatProd } from "../logger.formatter.js";
+/**
+ * Decide whether ANSI color codes should be emitted by default.
+ *
+ * Order of precedence (industry standard, matches chalk / supports-color):
+ *   1. `NO_COLOR` env var (any non-empty value)              → never colors
+ *   2. `FORCE_COLOR` env var (any non-"0"/"false" value)     → always colors
+ *   3. Process running in production                          → never colors
+ *   4. Stdout is a TTY                                        → colors
+ *   5. Otherwise (pipes, redirects, cloud log capture)       → no colors
+ *
+ * This means cloud platforms like Azure App Service, AWS CloudWatch,
+ * Heroku, Docker, Kubernetes, etc. — which all capture stdout into a
+ * non-TTY pipe — receive plain text by default, without users having
+ * to configure anything.
+ */
+function detectColorsDefault() {
+    const noColor = process.env.NO_COLOR;
+    if (noColor !== undefined && noColor !== "")
+        return false;
+    const forceColor = process.env.FORCE_COLOR;
+    if (forceColor !== undefined &&
+        forceColor !== "0" &&
+        forceColor !== "false") {
+        return true;
+    }
+    if (process.env.NODE_ENV === "production")
+        return false;
+    return Boolean(process.stdout && process.stdout.isTTY);
+}
 /**
  * Console transport for logging to stdout/stderr.
  * @public API
@@ -22,7 +51,7 @@ export class ConsoleTransport {
         this.enabled = options?.enabled ?? true;
         this.structured =
             options?.structured ?? process.env.NODE_ENV === "production";
-        this.colors = options?.colors ?? process.env.NODE_ENV !== "production";
+        this.colors = options?.colors ?? detectColorsDefault();
         this.pretty = options?.pretty ?? process.env.NODE_ENV !== "production";
         // Enable redaction by default in production
         this.redact = options?.redact ?? process.env.NODE_ENV === "production";
@@ -30,6 +59,13 @@ export class ConsoleTransport {
     }
     /**
      * 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
@@ -38,7 +74,7 @@ export class ConsoleTransport {
         return new ConsoleTransport({
             level: LogLevel.DEBUG,
             structured: false,
-            colors: true,
+            // Omit `colors` so the constructor's auto-detect kicks in.
             pretty: true,
             redact, // Usually disabled in development for easier debugging
         });
@@ -62,17 +98,44 @@ export class ConsoleTransport {
         if (!this.enabled || !shouldLog(entry.level, this.level)) {
             return;
         }
-        // Build format options with redaction settings
+        // Build format options with redaction + color settings. The color
+        // flag is honoured by `formatDev` / `formatGroupedDev`; `formatProd`
+        // (structured JSON) never emits color regardless.
         const formatOptions = {
             redact: this.redact,
             redactor: this.redactor,
+            colors: this.colors,
         };
         const formatted = this.structured
             ? formatProd(entry, formatOptions)
             : formatDev(entry, formatOptions);
-        // Use process.stdout/stderr directly to allow runtime interception
-        const stream = entry.level >= LogLevel.ERROR ? process.stderr : process.stdout;
-        stream.write(formatted);
+        // Strip trailing newline since console.* methods append their own.
+        const msg = formatted.endsWith("\n") ? formatted.slice(0, -1) : formatted;
+        // Route through console methods so Studio's LogCapture (which
+        // intercepts console.*) can forward these entries to the Live Logs UI.
+        // The level mapping mirrors the level chips Studio renders so messages
+        // land under the expected filter. We pass a single pre-formatted string
+        // so util.format never tries to interpret stray "%s"/"%d" tokens in
+        // user-supplied messages.
+        switch (entry.level) {
+            case LogLevel.DEBUG:
+            case LogLevel.ALL:
+                console.debug(msg);
+                break;
+            case LogLevel.INFO:
+                console.info(msg);
+                break;
+            case LogLevel.WARN:
+                console.warn(msg);
+                break;
+            case LogLevel.ERROR:
+            case LogLevel.FATAL:
+                console.error(msg);
+                break;
+            default:
+                console.log(msg);
+                break;
+        }
     }
     flush() {
         // Console doesn't need flushing

package/lib/esm/provider/logger/transports/file.transport.js

@@ -92,29 +92,34 @@ export class FileTransport {
         if (!this.enabled || !shouldLog(entry.level, this.level)) {
             return;
         }
-        const filename = this.getFilename();
-        const shouldRotate = this.shouldRotate(filename);
-        if (shouldRotate) {
-            await this.rotateFile(filename);
-        }
-        if (filename !== this.currentFilename) {
-            this.currentFilename = filename;
-            this.currentFileSize = await this.getFileSize(filename);
-        }
-        await this.ensureDirectory();
-        const filePath = join(this.directory, this.currentFilename);
-        const formatted = formatProd(entry) + "\n";
-        const entrySize = Buffer.byteLength(formatted, "utf8");
+        // Wrap the entire write pipeline in a single try/catch.
+        //
+        // FileTransport must NEVER throw out of `log()` — a logger that crashes
+        // the request that just wrote to it would be worse than a silent drop.
+        // We log a single line to stderr and move on; this matches the
+        // ConsoleTransport contract and keeps the framework's "logging never
+        // takes down the app" invariant.
         try {
+            const filename = this.getFilename();
+            const shouldRotate = this.shouldRotate(filename);
+            if (shouldRotate) {
+                await this.rotateFile(filename);
+            }
+            if (filename !== this.currentFilename) {
+                this.currentFilename = filename;
+                this.currentFileSize = await this.getFileSize(filename);
+            }
+            await this.ensureDirectory();
+            const filePath = join(this.directory, this.currentFilename);
+            const formatted = formatProd(entry) + "\n";
+            const entrySize = Buffer.byteLength(formatted, "utf8");
             await fs.appendFile(filePath, formatted, "utf8");
             this.currentFileSize += entrySize;
-            // Check if we need to rotate after this write
             if (this.maxSize > 0 && this.currentFileSize >= this.maxSize) {
                 await this.rotateFile(this.currentFilename);
             }
         }
         catch (error) {
-            // Silently fail to avoid log loops
             console.error(`[FileTransport] Failed to write log:`, error);
         }
     }
@@ -222,13 +227,17 @@ export class FileTransport {
         }
     }
     startCleanupInterval() {
-        // Run cleanup every hour
         this.cleanupInterval = setInterval(() => {
             this.cleanupOldFiles().catch((error) => {
                 console.error(`[FileTransport] Cleanup failed:`, error);
             });
-        }, 60 * 60 * 1000); // 1 hour
-        // Run initial cleanup
+        }, 60 * 60 * 1000);
+        // unref() so the cleanup timer never keeps the event loop alive on its own.
+        // Without this a short-lived script that uses FileTransport would hang
+        // for an hour at exit waiting on the next tick.
+        if (typeof this.cleanupInterval.unref === "function") {
+            this.cleanupInterval.unref();
+        }
         this.cleanupOldFiles().catch((error) => {
             console.error(`[FileTransport] Initial cleanup failed:`, error);
         });

package/lib/esm/provider/logger/utils/log-levels.js

@@ -5,8 +5,8 @@
  */
 export var LogLevel;
 (function (LogLevel) {
-    /** Ultra-detailed diagnostic information (function entry/exit) */
-    LogLevel[LogLevel["TRACE"] = 0] = "TRACE";
+    /** Show all logs (ultra-detailed diagnostic information, function entry/exit) */
+    LogLevel[LogLevel["ALL"] = 0] = "ALL";
     /** Detailed diagnostic information for debugging */
     LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
     /** General informational messages */
@@ -41,8 +41,9 @@ export function parseLogLevel(level) {
         return LogLevel.INFO;
     }
     switch (upperLevel) {
+        case "ALL":
         case "TRACE":
-            return LogLevel.TRACE;
+            return LogLevel.ALL;
         case "DEBUG":
             return LogLevel.DEBUG;
         case "INFO":
@@ -67,8 +68,8 @@ export function parseLogLevel(level) {
  */
 export function logLevelToString(level) {
     switch (level) {
-        case LogLevel.TRACE:
-            return "TRACE";
+        case LogLevel.ALL:
+            return "ALL";
         case LogLevel.DEBUG:
             return "DEBUG";
         case LogLevel.INFO:

package/lib/esm/provider/validation/adapters/index.js

@@ -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/esm/provider/validation/adapters/yup.adapter.js

@@ -0,0 +1,111 @@
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+/**
+ * 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 class YupValidatorAdapter {
+    name = "yup";
+    priority = 80;
+    canHandle(schema) {
+        if (schema === null || typeof schema !== "object")
+            return false;
+        const candidate = schema;
+        if (candidate.__isYupSchema__ === true)
+            return true;
+        return (typeof candidate.validate === "function" &&
+            typeof candidate.cast === "function");
+    }
+    async validate(data, schema, options) {
+        if (typeof schema.validate !== "function") {
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: "",
+                        message: "YupValidatorAdapter received a schema with no validate() method.",
+                        code: "invalid_schema",
+                    },
+                ],
+            };
+        }
+        try {
+            const yupOptions = {
+                abortEarly: options?.abortEarly ?? false,
+                stripUnknown: options?.stripUnknown ?? false,
+            };
+            const validated = await schema.validate(data, yupOptions);
+            return { success: true, data: validated };
+        }
+        catch (error) {
+            const yupError = error;
+            // yup batches per-field issues into `inner` when abortEarly is false,
+            // and emits a single message otherwise.
+            const issues = yupError?.inner && yupError.inner.length > 0
+                ? yupError.inner
+                : [yupError];
+            return {
+                success: false,
+                errors: this.mapIssues(issues),
+            };
+        }
+    }
+    async transform(data, schema) {
+        if (typeof schema.cast === "function") {
+            try {
+                return schema.cast(data);
+            }
+            catch {
+                return data;
+            }
+        }
+        return data;
+    }
+    mapIssues(issues) {
+        return issues.map((issue) => ({
+            path: issue.path ?? "",
+            message: issue.message ?? "Validation failed",
+            code: issue.type ?? "validation_error",
+            received: issue.value,
+        }));
+    }
+}
+/**
+ * Convenience factory matching the `createXxxValidator` naming used by the
+ * other adapters. Equivalent to `new YupValidatorAdapter()`.
+ *
+ * @public API
+ */
+export function createYupValidator() {
+    return new YupValidatorAdapter();
+}

package/lib/esm/provider/validation/adapters/zod.adapter.js

@@ -0,0 +1,130 @@
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+/**
+ * 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 class ZodValidatorAdapter {
+    name = "zod";
+    priority = 90;
+    canHandle(schema) {
+        if (schema === null || typeof schema !== "object")
+            return false;
+        const candidate = schema;
+        return (typeof candidate.safeParseAsync === "function" ||
+            typeof candidate.safeParse === "function" ||
+            typeof candidate.parseAsync === "function" ||
+            typeof candidate.parse === "function");
+    }
+    async validate(data, schema, 
+    // ValidationOptions accepted for interface compliance; Zod surfaces its own
+    // configuration through the schema itself, so options are not consumed here.
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _options) {
+        try {
+            // Prefer the safe variants because they encode the failure mode in the
+            // result rather than throwing.
+            if (typeof schema.safeParseAsync === "function") {
+                const r = await schema.safeParseAsync(data);
+                return r.success
+                    ? { success: true, data: r.data }
+                    : { success: false, errors: this.mapIssues(r.error?.issues ?? []) };
+            }
+            if (typeof schema.safeParse === "function") {
+                const r = schema.safeParse(data);
+                return r.success
+                    ? { success: true, data: r.data }
+                    : { success: false, errors: this.mapIssues(r.error?.issues ?? []) };
+            }
+            if (typeof schema.parseAsync === "function") {
+                const parsed = await schema.parseAsync(data);
+                return { success: true, data: parsed };
+            }
+            if (typeof schema.parse === "function") {
+                const parsed = schema.parse(data);
+                return { success: true, data: parsed };
+            }
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: "",
+                        message: "ZodValidatorAdapter received a schema with no parse/safeParse method.",
+                        code: "invalid_schema",
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            // zod throws ZodError for `parse`/`parseAsync`. Pull issues if present.
+            const maybeIssues = error?.issues;
+            if (Array.isArray(maybeIssues)) {
+                return { success: false, errors: this.mapIssues(maybeIssues) };
+            }
+            return {
+                success: false,
+                errors: [
+                    {
+                        path: "",
+                        message: error instanceof Error
+                            ? error.message
+                            : "Validation failed unexpectedly",
+                        code: "validation_error",
+                    },
+                ],
+            };
+        }
+    }
+    async transform(data, schema) {
+        const result = await this.validate(data, schema);
+        return result.success ? result.data : data;
+    }
+    mapIssues(issues) {
+        return issues.map((issue) => ({
+            path: issue.path.join("."),
+            message: issue.message,
+            code: issue.code ?? "validation_error",
+            received: issue.received,
+        }));
+    }
+}
+/**
+ * Convenience factory matching the `createXxxValidator` naming used by the
+ * other adapters. Equivalent to `new ZodValidatorAdapter()`.
+ *
+ * @public API
+ */
+export function createZodValidator() {
+    return new ZodValidatorAdapter();
+}

package/lib/esm/provider/validation/index.js

@@ -18,4 +18,4 @@ export { HelpfulErrorFormatter, } from "./helpful-error-formatter.js";
 // Type inference utilities
 export { getParameterType, getAllParameterTypes, getClassProperties, hasClassValidatorDecorators, isZodSchema, isClassConstructor, detectSchemaType, } from "./type-inference.js";
 // Built-in adapters
-export { ClassValidatorAdapter } from "./adapters/index.js";
+export { ClassValidatorAdapter, ZodValidatorAdapter, createZodValidator, YupValidatorAdapter, createYupValidator, } from "./adapters/index.js";