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

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

@@ -0,0 +1,402 @@
+"use strict";
+/**
+ * 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"
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Env = void 0;
+exports.envString = string;
+exports.envNumber = number;
+exports.envBoolean = boolean;
+exports.envEnum = enumField;
+exports.envUrl = url;
+exports.envPort = port;
+exports.envSecret = secret;
+exports.envJson = json;
+exports.envArray = array;
+// ============================================================================
+// 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
+ */
+exports.Env = {
+    string,
+    number,
+    boolean,
+    enum: enumField,
+    url,
+    port,
+    secret,
+    json,
+    array,
+};

package/lib/cjs/config/index.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * 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"));
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSecretValue = exports.createSecretValue = exports.envArray = exports.envJson = exports.envSecret = exports.envPort = exports.envUrl = exports.envEnum = exports.envBoolean = exports.envNumber = exports.envString = exports.Env = exports.defineConfig = void 0;
+// ============================================================================
+// Core Exports
+// ============================================================================
+var define_config_js_1 = require("./define-config.js");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return define_config_js_1.defineConfig; } });
+Object.defineProperty(exports, "Env", { enumerable: true, get: function () { return define_config_js_1.Env; } });
+// Individual field builders (for tree-shaking)
+var env_field_builders_js_1 = require("./env-field-builders.js");
+Object.defineProperty(exports, "envString", { enumerable: true, get: function () { return env_field_builders_js_1.envString; } });
+Object.defineProperty(exports, "envNumber", { enumerable: true, get: function () { return env_field_builders_js_1.envNumber; } });
+Object.defineProperty(exports, "envBoolean", { enumerable: true, get: function () { return env_field_builders_js_1.envBoolean; } });
+Object.defineProperty(exports, "envEnum", { enumerable: true, get: function () { return env_field_builders_js_1.envEnum; } });
+Object.defineProperty(exports, "envUrl", { enumerable: true, get: function () { return env_field_builders_js_1.envUrl; } });
+Object.defineProperty(exports, "envPort", { enumerable: true, get: function () { return env_field_builders_js_1.envPort; } });
+Object.defineProperty(exports, "envSecret", { enumerable: true, get: function () { return env_field_builders_js_1.envSecret; } });
+Object.defineProperty(exports, "envJson", { enumerable: true, get: function () { return env_field_builders_js_1.envJson; } });
+Object.defineProperty(exports, "envArray", { enumerable: true, get: function () { return env_field_builders_js_1.envArray; } });
+// ============================================================================
+// Secret Value
+// ============================================================================
+var secret_value_js_1 = require("./secret-value.js");
+Object.defineProperty(exports, "createSecretValue", { enumerable: true, get: function () { return secret_value_js_1.createSecretValue; } });
+Object.defineProperty(exports, "isSecretValue", { enumerable: true, get: function () { return secret_value_js_1.isSecretValue; } });

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

@@ -0,0 +1,201 @@
+"use strict";
+/**
+ * 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
+ * ```
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecretValueImpl = void 0;
+exports.createSecretValue = createSecretValue;
+exports.isSecretValue = isSecretValue;
+const nodeCrypto = __importStar(require("crypto"));
+/**
+ * Implementation of SecretValue interface.
+ *
+ * @internal
+ */
+class SecretValueImpl {
+    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();
+    }
+}
+exports.SecretValueImpl = SecretValueImpl;
+/**
+ * Create a SecretValue from a string.
+ *
+ * @param value - The secret string
+ * @param options - Secret field options
+ * @returns SecretValue wrapper
+ *
+ * @public API
+ */
+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
+ */
+function isSecretValue(value) {
+    return value instanceof SecretValueImpl;
+}

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

@@ -12,6 +12,8 @@ const colorCodes = {
     green: "\x1b[32m",
     yellow: "\x1b[33m",
     blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
     white: "\x1b[37m",
     black: "\x1b[30m",
     none: "\x1b[0m",
@@ -25,6 +27,8 @@ const bgColorCodes = {
     green: "\x1b[42m",
     yellow: "\x1b[43m",
     blue: "\x1b[44m",
+    magenta: "\x1b[45m",
+    cyan: "\x1b[46m",
     white: "\x1b[47m",
     black: "\x1b[40m",
     none: "\x1b[0m",