@expressots/core 3.0.0-beta.4 → 4.0.0-preview.1

package/lib/esm/config/env-field-builders.js

@@ -0,0 +1,392 @@
+/**
+ * Environment Field Builders
+ *
+ * @module config
+ *
+ * Type-safe builders for configuration fields.
+ * Each builder creates a ConfigField with proper typing.
+ *
+ * @example
+ * ```typescript
+ * // UNIQUE: Full TypeScript inference, no type casting!
+ * const config = defineConfig({
+ *   port: Env.port("PORT", { default: 3000 }),
+ *   dbHost: Env.string("DB_HOST", { default: "localhost" }),
+ *   apiKey: Env.secret("API_KEY", { required: true }),
+ *   debug: Env.boolean("DEBUG", { default: false }),
+ *   logLevel: Env.enum("LOG_LEVEL", ["debug", "info", "warn", "error"]),
+ * });
+ *
+ * // TypeScript knows the exact types!
+ * config.values.port     // number
+ * config.values.dbHost   // string
+ * config.values.apiKey   // SecretValue
+ * config.values.debug    // boolean
+ * config.values.logLevel // "debug" | "info" | "warn" | "error"
+ * ```
+ */
+// ============================================================================
+// Field Builders
+// ============================================================================
+/**
+ * Create a string configuration field.
+ *
+ * @param envVar - Environment variable name
+ * @param options - Field options
+ * @returns ConfigField for string value
+ *
+ * @example
+ * ```typescript
+ * Env.string("DB_HOST", {
+ *   default: "localhost",
+ *   description: "Database host address"
+ * })
+ *
+ * // With format validation
+ * Env.string("USER_EMAIL", {
+ *   format: "email",
+ *   required: true
+ * })
+ * ```
+ */
+function string(envVar, options = {}) {
+    return {
+        envVar,
+        type: "string",
+        options: {
+            trim: true, // Default to trim
+            ...options,
+        },
+        isSecret: false,
+        errors: [],
+    };
+}
+/**
+ * Create a number configuration field.
+ *
+ * @param envVar - Environment variable name
+ * @param options - Field options
+ * @returns ConfigField for number value
+ *
+ * @example
+ * ```typescript
+ * Env.number("MAX_CONNECTIONS", {
+ *   default: 10,
+ *   min: 1,
+ *   max: 100
+ * })
+ *
+ * // Integer only
+ * Env.number("RETRY_COUNT", {
+ *   default: 3,
+ *   integer: true,
+ *   positive: true
+ * })
+ * ```
+ */
+function number(envVar, options = {}) {
+    return {
+        envVar,
+        type: "number",
+        options,
+        isSecret: false,
+        errors: [],
+    };
+}
+/**
+ * Create a boolean configuration field.
+ *
+ * Accepts: "true", "1", "yes", "on" as true
+ * Accepts: "false", "0", "no", "off" as false
+ *
+ * @param envVar - Environment variable name
+ * @param options - Field options
+ * @returns ConfigField for boolean value
+ *
+ * @example
+ * ```typescript
+ * Env.boolean("ENABLE_CACHE", { default: true })
+ * Env.boolean("DEBUG", { default: false })
+ * ```
+ */
+function boolean(envVar, options = {}) {
+    return {
+        envVar,
+        type: "boolean",
+        options: {
+            trueValues: ["true", "1", "yes", "on"],
+            falseValues: ["false", "0", "no", "off"],
+            ...options,
+        },
+        isSecret: false,
+        errors: [],
+    };
+}
+/**
+ * Create an enum configuration field.
+ *
+ * UNIQUE: Full TypeScript inference for enum values!
+ *
+ * @param envVar - Environment variable name
+ * @param values - Allowed enum values
+ * @param options - Field options
+ * @returns ConfigField for enum value
+ *
+ * @example
+ * ```typescript
+ * // TypeScript knows this is "debug" | "info" | "warn" | "error"
+ * Env.enum("LOG_LEVEL", ["debug", "info", "warn", "error"], {
+ *   default: "info"
+ * })
+ *
+ * // Case insensitive matching
+ * Env.enum("ENVIRONMENT", ["development", "staging", "production"], {
+ *   caseInsensitive: true
+ * })
+ * ```
+ */
+function enumField(envVar, values, options = {}) {
+    return {
+        envVar,
+        type: "enum",
+        options: {
+            ...options,
+            values,
+        },
+        isSecret: false,
+        errors: [],
+    };
+}
+/**
+ * Create a URL configuration field.
+ *
+ * @param envVar - Environment variable name
+ * @param options - Field options
+ * @returns ConfigField for URL string
+ *
+ * @example
+ * ```typescript
+ * Env.url("API_BASE_URL", {
+ *   required: true,
+ *   protocols: ["https"] // Only HTTPS allowed
+ * })
+ *
+ * Env.url("CALLBACK_URL", {
+ *   noTrailingSlash: true
+ * })
+ * ```
+ */
+function url(envVar, options = {}) {
+    return {
+        envVar,
+        type: "url",
+        options: {
+            protocols: ["http", "https"],
+            ...options,
+        },
+        isSecret: false,
+        errors: [],
+    };
+}
+/**
+ * Create a port configuration field.
+ *
+ * Auto-validates port range (1-65535).
+ *
+ * @param envVar - Environment variable name
+ * @param options - Field options
+ * @returns ConfigField for port number
+ *
+ * @example
+ * ```typescript
+ * Env.port("PORT", { default: 3000 })
+ *
+ * // Non-privileged ports only
+ * Env.port("APP_PORT", {
+ *   default: 8080,
+ *   noPrivileged: true // Must be >= 1024
+ * })
+ * ```
+ */
+function port(envVar, options = {}) {
+    return {
+        envVar,
+        type: "port",
+        options: {
+            min: options.noPrivileged ? 1024 : 1,
+            max: 65535,
+            ...options,
+        },
+        isSecret: false,
+        errors: [],
+    };
+}
+/**
+ * Create a secret configuration field.
+ *
+ * UNIQUE: Auto-redacted in logs, partial reveal in dev mode!
+ *
+ * Secrets:
+ * - Never logged in plain text
+ * - Show "[REDACTED]" when stringified
+ * - Can be partially revealed in development
+ * - Integrate with Logger's Redactor
+ *
+ * @param envVar - Environment variable name
+ * @param options - Field options
+ * @returns ConfigField for secret value
+ *
+ * @example
+ * ```typescript
+ * Env.secret("API_KEY", {
+ *   required: true,
+ *   minLength: 32,
+ *   description: "API authentication key"
+ * })
+ *
+ * // Access secret value
+ * const key = config.values.apiKey.value;
+ *
+ * // Safe logging (shows redacted)
+ * console.log(config.values.apiKey); // "[REDACTED]"
+ *
+ * // Partial reveal in dev
+ * console.log(config.values.apiKey.reveal()); // "sk_l...abcd"
+ * ```
+ */
+function secret(envVar, options = {}) {
+    return {
+        envVar,
+        type: "secret",
+        options: {
+            revealStart: 0,
+            revealEnd: 4,
+            allowPartialReveal: true,
+            ...options,
+        },
+        isSecret: true,
+        errors: [],
+    };
+}
+/**
+ * Create a JSON configuration field.
+ *
+ * Parses JSON string from environment variable.
+ *
+ * @param envVar - Environment variable name
+ * @param options - Field options
+ * @returns ConfigField for parsed JSON value
+ *
+ * @example
+ * ```typescript
+ * // Parse JSON object
+ * Env.json<{ host: string; port: number }>("DB_CONFIG", {
+ *   default: { host: "localhost", port: 5432 }
+ * })
+ *
+ * // With custom validator
+ * Env.json<string[]>("ALLOWED_ORIGINS", {
+ *   validate: (v) => Array.isArray(v) || "Must be an array"
+ * })
+ * ```
+ */
+function json(envVar, options = {}) {
+    return {
+        envVar,
+        type: "json",
+        options,
+        isSecret: false,
+        errors: [],
+    };
+}
+/**
+ * Create an array configuration field.
+ *
+ * Parses comma-separated string to array.
+ *
+ * @param envVar - Environment variable name
+ * @param options - Field options
+ * @returns ConfigField for array value
+ *
+ * @example
+ * ```typescript
+ * // String array (comma-separated)
+ * Env.array("ALLOWED_HOSTS", {
+ *   default: ["localhost"],
+ *   delimiter: ","
+ * })
+ * // "host1,host2,host3" → ["host1", "host2", "host3"]
+ *
+ * // Number array
+ * Env.array("RETRY_DELAYS", {
+ *   itemType: "number",
+ *   default: [100, 500, 1000]
+ * })
+ * ```
+ */
+function array(envVar, options = {}) {
+    return {
+        envVar,
+        type: "array",
+        options: {
+            delimiter: ",",
+            itemType: "string",
+            ...options,
+        },
+        isSecret: false,
+        errors: [],
+    };
+}
+// ============================================================================
+// Env Object Export
+// ============================================================================
+/**
+ * Environment configuration field builders.
+ *
+ * UNIQUE: Type-safe, zero-config environment configuration!
+ *
+ * @example
+ * ```typescript
+ * import { Env, defineConfig } from "@expressots/core";
+ *
+ * export const config = defineConfig({
+ *   // Full TypeScript inference!
+ *   server: {
+ *     port: Env.port("PORT", { default: 3000 }),
+ *     host: Env.string("HOST", { default: "0.0.0.0" }),
+ *   },
+ *   database: {
+ *     url: Env.url("DATABASE_URL", { required: true }),
+ *     pool: Env.number("DB_POOL_SIZE", { default: 10, min: 1, max: 100 }),
+ *   },
+ *   auth: {
+ *     secret: Env.secret("JWT_SECRET", { required: true, minLength: 32 }),
+ *     expiry: Env.string("JWT_EXPIRY", { default: "1h" }),
+ *   },
+ *   features: {
+ *     enableCache: Env.boolean("ENABLE_CACHE", { default: true }),
+ *     logLevel: Env.enum("LOG_LEVEL", ["debug", "info", "warn", "error"]),
+ *   },
+ * });
+ *
+ * // Usage with full type safety!
+ * config.values.server.port    // number
+ * config.values.auth.secret    // SecretValue
+ * config.values.features.logLevel // "debug" | "info" | "warn" | "error"
+ * ```
+ *
+ * @public API
+ */
+export const Env = {
+    string,
+    number,
+    boolean,
+    enum: enumField,
+    url,
+    port,
+    secret,
+    json,
+    array,
+};
+// Re-export individual builders for tree-shaking
+export { string as envString, number as envNumber, boolean as envBoolean, enumField as envEnum, url as envUrl, port as envPort, secret as envSecret, json as envJson, array as envArray, };

package/lib/esm/config/index.js

@@ -0,0 +1,67 @@
+/**
+ * Enhanced Configuration Module
+ *
+ * @module config
+ *
+ * Type-safe, zero-config environment configuration for ExpressoTS.
+ *
+ * UNIQUE Features:
+ * - Full TypeScript inference (no type casting!)
+ * - Multi-environment defaults (dev/staging/prod)
+ * - Helpful validation errors with examples and hints
+ * - Secret management with auto-redaction
+ * - Documentation generation
+ * - Hot reload support
+ *
+ * @example
+ * ```typescript
+ * // 1. Define your config (one file, all type-safe!)
+ * import { defineConfig, Env } from "@expressots/core";
+ *
+ * export const config = defineConfig({
+ *   server: {
+ *     port: Env.port("PORT", { default: 3000 }),
+ *     host: Env.string("HOST", { default: "0.0.0.0" }),
+ *   },
+ *   database: {
+ *     url: Env.url("DATABASE_URL", { required: true }),
+ *     pool: Env.number("DB_POOL_SIZE", { default: 10, min: 1, max: 100 }),
+ *   },
+ *   auth: {
+ *     secret: Env.secret("JWT_SECRET", { required: true, minLength: 32 }),
+ *   },
+ *   features: {
+ *     logLevel: Env.enum("LOG_LEVEL", ["debug", "info", "warn", "error"]),
+ *     enableCache: Env.boolean("ENABLE_CACHE", { default: true }),
+ *   },
+ * });
+ *
+ * // 2. Use with FULL type safety!
+ * config.values.server.port      // number
+ * config.values.database.url     // string
+ * config.values.auth.secret      // SecretValue (auto-redacted)
+ * config.values.features.logLevel // "debug" | "info" | "warn" | "error"
+ *
+ * // 3. Validate at startup (automatically shows helpful errors)
+ * if (!config.isValid()) {
+ *   process.exit(1);
+ * }
+ *
+ * // 4. Safe logging (secrets auto-redacted)
+ * console.log(config.toObject());
+ * // { server: { port: 3000 }, auth: { secret: "[REDACTED]" }, ... }
+ *
+ * // 5. Generate documentation
+ * fs.writeFileSync("CONFIG.md", config.generateDocs("markdown"));
+ * ```
+ */
+// ============================================================================
+// Core Exports
+// ============================================================================
+export { defineConfig, Env } from "./define-config.js";
+// Individual field builders (for tree-shaking)
+export { envString, envNumber, envBoolean, envEnum, envUrl, envPort, envSecret, envJson, envArray, } from "./env-field-builders.js";
+// ============================================================================
+// Secret Value
+// ============================================================================
+export { createSecretValue, isSecretValue } from "./secret-value.js";

package/lib/esm/config/secret-value.js

@@ -0,0 +1,175 @@
+/**
+ * Secret Value Wrapper
+ *
+ * @module config
+ *
+ * Wraps sensitive values to prevent accidental logging.
+ *
+ * UNIQUE: Auto-redacted in logs, partial reveal in dev mode!
+ *
+ * @example
+ * ```typescript
+ * const secret = new SecretValueImpl("sk_live_abc123xyz789");
+ *
+ * // Safe for logging - shows redacted
+ * console.log(secret);        // "[REDACTED]"
+ * console.log(`Key: ${secret}`); // "Key: [REDACTED]"
+ *
+ * // Access actual value when needed
+ * const key = secret.value;   // "sk_live_abc123xyz789"
+ *
+ * // Partial reveal for debugging (dev mode only)
+ * console.log(secret.reveal()); // "sk_l...z789"
+ *
+ * // Safe comparison without revealing
+ * secret.equals("sk_live_abc123xyz789"); // true
+ * ```
+ */
+import * as nodeCrypto from "crypto";
+/**
+ * Implementation of SecretValue interface.
+ *
+ * @internal
+ */
+export class SecretValueImpl {
+    _value;
+    _options;
+    _isDev;
+    constructor(value, options = {}) {
+        this._value = value;
+        this._options = {
+            revealStart: 0,
+            revealEnd: 4,
+            allowPartialReveal: true,
+            ...options,
+        };
+        this._isDev = process.env.NODE_ENV === "development";
+    }
+    /**
+     * Get the actual secret value.
+     */
+    get value() {
+        return this._value;
+    }
+    /**
+     * Check if secret is set (non-empty).
+     */
+    get isSet() {
+        return (this._value !== undefined &&
+            this._value !== null &&
+            this._value.length > 0);
+    }
+    /**
+     * Get length of secret.
+     */
+    get length() {
+        return this._value?.length ?? 0;
+    }
+    /**
+     * Returns redacted string for logging.
+     * Prevents accidental exposure in logs.
+     */
+    toString() {
+        if (!this.isSet) {
+            return "[NOT SET]";
+        }
+        // In development, show partial if allowed
+        if (this._isDev && this._options.allowPartialReveal) {
+            return this.reveal();
+        }
+        return "[REDACTED]";
+    }
+    /**
+     * Custom JSON serialization - always redacted.
+     */
+    toJSON() {
+        return "[REDACTED]";
+    }
+    /**
+     * Partial reveal for debugging.
+     * Shows first/last N characters with dots in between.
+     *
+     * Only works in development mode with allowPartialReveal enabled.
+     *
+     * @example
+     * ```typescript
+     * // With revealStart: 4, revealEnd: 4
+     * secret.reveal() // "sk_l...z789"
+     * ```
+     */
+    reveal() {
+        if (!this.isSet) {
+            return "[NOT SET]";
+        }
+        // Only reveal in development if allowed
+        if (!this._isDev || !this._options.allowPartialReveal) {
+            return "[REDACTED]";
+        }
+        const value = this._value;
+        const revealStart = this._options.revealStart ?? 0;
+        const revealEnd = this._options.revealEnd ?? 4;
+        // If value is too short to reveal meaningfully
+        if (value.length <= revealStart + revealEnd + 3) {
+            return "[REDACTED]";
+        }
+        const start = value.slice(0, revealStart);
+        const end = value.slice(-revealEnd);
+        if (revealStart === 0) {
+            return `...${end}`;
+        }
+        return `${start}...${end}`;
+    }
+    /**
+     * Compare secret value without revealing.
+     * Safe for authentication checks.
+     *
+     * Uses timing-safe comparison to prevent timing attacks.
+     */
+    equals(other) {
+        if (!this.isSet || !other) {
+            return false;
+        }
+        // Use timing-safe comparison if available (Node.js crypto)
+        try {
+            const a = Buffer.from(this._value);
+            const b = Buffer.from(other);
+            if (a.length !== b.length) {
+                return false;
+            }
+            return nodeCrypto.timingSafeEqual(a, b);
+        }
+        catch {
+            // Fallback to regular comparison
+            return this._value === other;
+        }
+    }
+    /**
+     * Prevent inspection from revealing the value.
+     */
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return this.toString();
+    }
+}
+/**
+ * Create a SecretValue from a string.
+ *
+ * @param value - The secret string
+ * @param options - Secret field options
+ * @returns SecretValue wrapper
+ *
+ * @public API
+ */
+export function createSecretValue(value, options = {}) {
+    return new SecretValueImpl(value, options);
+}
+/**
+ * Check if a value is a SecretValue.
+ *
+ * @param value - Value to check
+ * @returns true if value is a SecretValue
+ *
+ * @public API
+ */
+export function isSecretValue(value) {
+    return value instanceof SecretValueImpl;
+}

package/lib/esm/console/color-codes.js

@@ -0,0 +1,46 @@
+/**
+ * Mapping of text color codes.
+ *
+ * @remarks
+ * Defines the ANSI escape codes for the corresponding colors in the terminal.
+ */
+const colorCodes = {
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
+    white: "\x1b[37m",
+    black: "\x1b[30m",
+    none: "\x1b[0m",
+};
+/**
+ * ANSI escape color codes mapping for different background colors.
+ */
+const bgColorCodes = {
+    red: "\x1b[41m",
+    green: "\x1b[42m",
+    yellow: "\x1b[43m",
+    blue: "\x1b[44m",
+    magenta: "\x1b[45m",
+    cyan: "\x1b[46m",
+    white: "\x1b[47m",
+    black: "\x1b[40m",
+    none: "\x1b[0m",
+};
+/**
+ * Enum representing possible color styles for console output.
+ *
+ * @remarks
+ * Enum values correspond to the string representations of colors.
+ */
+var ColorStyle;
+(function (ColorStyle) {
+    ColorStyle["None"] = "none";
+    ColorStyle["Yellow"] = "yellow";
+    ColorStyle["Blue"] = "blue";
+    ColorStyle["Green"] = "green";
+    ColorStyle["Red"] = "red";
+})(ColorStyle || (ColorStyle = {}));
+export { ColorStyle, colorCodes, bgColorCodes };