@expressots/core 3.0.0 → 4.0.0-preview.3

package/lib/esm/types/config/env-field-builders.d.ts

@@ -0,0 +1,327 @@
+/**
+ * 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"
+ * ```
+ */
+import { ConfigField, SecretConfigField, StringFieldOptions, NumberFieldOptions, BooleanFieldOptions, EnumFieldOptions, UrlFieldOptions, PortFieldOptions, SecretFieldOptions, JsonFieldOptions, ArrayFieldOptions } from "./config.interfaces.js";
+/**
+ * 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
+ * })
+ * ```
+ */
+declare function string(envVar: string, options?: StringFieldOptions): ConfigField<string, false>;
+/**
+ * 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
+ * })
+ * ```
+ */
+declare function number(envVar: string, options?: NumberFieldOptions): ConfigField<number, false>;
+/**
+ * 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 })
+ * ```
+ */
+declare function boolean(envVar: string, options?: BooleanFieldOptions): ConfigField<boolean, false>;
+/**
+ * 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
+ * })
+ * ```
+ */
+declare function enumField<T extends string>(envVar: string, values: ReadonlyArray<T>, options?: Omit<EnumFieldOptions<T>, "values">): ConfigField<T, false>;
+/**
+ * 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
+ * })
+ * ```
+ */
+declare function url(envVar: string, options?: UrlFieldOptions): ConfigField<string, false>;
+/**
+ * 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
+ * })
+ * ```
+ */
+declare function port(envVar: string, options?: PortFieldOptions): ConfigField<number, false>;
+/**
+ * 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"
+ * ```
+ */
+declare function secret(envVar: string, options?: SecretFieldOptions): SecretConfigField;
+/**
+ * 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"
+ * })
+ * ```
+ */
+declare function json<T>(envVar: string, options?: JsonFieldOptions<T>): ConfigField<T, false>;
+/**
+ * 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]
+ * })
+ * ```
+ */
+declare function array<T extends string | number>(envVar: string, options?: ArrayFieldOptions<T>): ConfigField<Array<T>, false>;
+/**
+ * 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
+ */
+/**
+ * Returns true when the current Node environment (`NODE_ENV`) matches the
+ * supplied name. Pass an array to match any of several names. The comparison
+ * is case-insensitive and falls back to `"development"` when `NODE_ENV` is
+ * unset, mirroring the convention used elsewhere in the framework.
+ *
+ * ```ts
+ * const config = defineConfig({
+ *   server: { port: when(Env.is("production"), 443, 3000) },
+ * });
+ * ```
+ *
+ * @public API
+ */
+declare function isEnvironment(name: string | Array<string>): boolean;
+/**
+ * Conditional helper for environment-specific config values.
+ *
+ * `when(condition, value, fallback)` returns `value` when `condition` is
+ * truthy, otherwise `fallback`. The condition can be either a boolean
+ * (typically the result of `Env.is(...)`) or a callable that's evaluated
+ * lazily. The latter form lets you defer side-effectful checks until the
+ * config is actually resolved.
+ *
+ * ```ts
+ * const config = defineConfig({
+ *   logging: {
+ *     level: when(Env.is("production"), "info", "debug"),
+ *     pretty: when(() => process.env.NO_COLOR !== "1", true, false),
+ *   },
+ * });
+ * ```
+ *
+ * @public API
+ */
+declare function envWhen<TValue, TFallback>(condition: boolean | (() => boolean), value: TValue, fallback: TFallback): TValue | TFallback;
+export declare const Env: {
+    readonly string: typeof string;
+    readonly number: typeof number;
+    readonly boolean: typeof boolean;
+    readonly enum: typeof enumField;
+    readonly url: typeof url;
+    readonly port: typeof port;
+    readonly secret: typeof secret;
+    readonly json: typeof json;
+    readonly array: typeof array;
+    readonly is: typeof isEnvironment;
+    readonly when: typeof envWhen;
+};
+export { isEnvironment as envIs, envWhen };
+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/types/config/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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"));
+ * ```
+ */
+export { defineConfig, Env } from "./define-config.js";
+export { envString, envNumber, envBoolean, envEnum, envUrl, envPort, envSecret, envJson, envArray, envIs, envWhen, } from "./env-field-builders.js";
+export type { ConfigValueType, ConfigEnvironment, ConfigLogLevel, BaseFieldOptions, StringFieldOptions, NumberFieldOptions, BooleanFieldOptions, EnumFieldOptions, UrlFieldOptions, PortFieldOptions, SecretFieldOptions, JsonFieldOptions, ArrayFieldOptions, ConfigField, ConfigValidationError, ConfigValidationResult, ConfigSchemaValue, ConfigSchema, DefineConfigOptions, ConfigChangeEvent, SecretValue, ResolvedConfig, IConfigInstance, } from "./config.interfaces.js";
+export { createSecretValue, isSecretValue } from "./secret-value.js";

package/lib/esm/types/config/secret-value.d.ts

@@ -0,0 +1,99 @@
+/**
+ * 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 { SecretValue, SecretFieldOptions } from "./config.interfaces.js";
+/**
+ * Implementation of SecretValue interface.
+ *
+ * @internal
+ */
+export declare class SecretValueImpl implements SecretValue {
+    private readonly _value;
+    private readonly _options;
+    private readonly _isDev;
+    constructor(value: string, options?: SecretFieldOptions);
+    /**
+     * Get the actual secret value.
+     */
+    get value(): string;
+    /**
+     * Check if secret is set (non-empty).
+     */
+    get isSet(): boolean;
+    /**
+     * Get length of secret.
+     */
+    get length(): number;
+    /**
+     * Returns redacted string for logging.
+     * Prevents accidental exposure in logs.
+     */
+    toString(): string;
+    /**
+     * Custom JSON serialization - always redacted.
+     */
+    toJSON(): string;
+    /**
+     * 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(): string;
+    /**
+     * Compare secret value without revealing.
+     * Safe for authentication checks.
+     *
+     * Uses timing-safe comparison to prevent timing attacks.
+     */
+    equals(other: string): boolean;
+}
+/**
+ * Create a SecretValue from a string.
+ *
+ * @param value - The secret string
+ * @param options - Secret field options
+ * @returns SecretValue wrapper
+ *
+ * @public API
+ */
+export declare function createSecretValue(value: string, options?: SecretFieldOptions): SecretValue;
+/**
+ * Check if a value is a SecretValue.
+ *
+ * @param value - Value to check
+ * @returns true if value is a SecretValue
+ *
+ * @public API
+ */
+export declare function isSecretValue(value: unknown): value is SecretValue;

package/lib/esm/types/console/color-codes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Type representing supported text colors.
+ */
+type Color = "red" | "green" | "yellow" | "blue" | "white" | "black" | "cyan" | "magenta" | "none";
+/**
+ * Mapping of text color codes.
+ *
+ * @remarks
+ * Defines the ANSI escape codes for the corresponding colors in the terminal.
+ */
+declare const colorCodes: Record<Color, string>;
+/**
+ * ANSI escape color codes mapping for different background colors.
+ */
+declare const bgColorCodes: Record<Color, string>;
+/**
+ * Enum representing possible color styles for console output.
+ *
+ * @remarks
+ * Enum values correspond to the string representations of colors.
+ */
+declare enum ColorStyle {
+    None = "none",
+    Yellow = "yellow",
+    Blue = "blue",
+    Green = "green",
+    Red = "red"
+}
+export { Color, ColorStyle, colorCodes, bgColorCodes };

package/lib/esm/types/console/console.d.ts

@@ -0,0 +1,83 @@
+import { IConsoleMessage } from "@expressots/shared";
+/**
+ * Console class for displaying styled startup messages.
+ *
+ * @layer public
+ * @audience application-developers
+ * @concept console-output
+ * @difficulty beginner
+ *
+ * @summary Quick Start
+ * Used internally by the framework to display startup banners.
+ * Typically you don't need to use this directly.
+ *
+ * @example
+ * ```typescript
+ * // Used internally by bootstrap()
+ * const console = container.get(Console);
+ * await console.messageServer(3000, "development", {
+ *   appName: "My App",
+ *   appVersion: "1.0.0"
+ * });
+ * ```
+ *
+ * @layer internal
+ * @audience framework-developers
+ *
+ * **Internal Architecture**
+ *
+ * Console provides:
+ * - ANSI color code support for terminal output
+ * - Environment-based color coding (dev=yellow, prod=green, other=red)
+ * - Startup banner formatting
+ *
+ * **Design Decisions**
+ * - Uses ANSI escape codes for cross-platform compatibility
+ * - Environment-based colors for quick visual feedback
+ * - Async methods for consistency with framework patterns
+ *
+ * @see {@link ColorStyle} for available colors
+ *
+ * @public API
+ */
+export declare class Console {
+    /**
+     * Print a message to the console with the specified color style.
+     *
+     * @layer internal
+     * @audience framework-developers
+     *
+     * @param message - The message to be printed.
+     * @param colorStyle - The color style for the message.
+     *
+     * @internal
+     */
+    private printColor;
+    /**
+     * Display a message in the console with details about the running server.
+     *
+     * @layer public
+     * @audience application-developers
+     *
+     * @param port - The port number the server is running on.
+     * @param environment - The server environment.
+     * @param consoleMessage - Optional application message details for console output.
+     *
+     * **Color Coding:**
+     * - `development` → Yellow background
+     * - `production` → Green background
+     * - Other → Red background
+     *
+     * @example
+     * ```typescript
+     * await console.messageServer(3000, "development", {
+     *   appName: "My API",
+     *   appVersion: "2.0.0"
+     * });
+     * // Output: [My API] version [2.0.0] is running on port [3000] - Environment: [development]
+     * ```
+     *
+     * @public API
+     */
+    messageServer(port: number, environment: string, consoleMessage?: IConsoleMessage): Promise<void>;
+}

package/lib/esm/types/console/index.d.ts

@@ -0,0 +1,2 @@
+export { IConsoleMessage } from "@expressots/shared";
+export { Console } from "./console.js";