@hexaijs/utils 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Sangwoo Hyun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,325 @@
+# @hexaijs/utils
+
+> Configuration management utilities for hexai applications
+
+## Overview
+
+`@hexaijs/utils` provides utilities for managing application configuration in a type-safe, validated manner. The package currently focuses on configuration management, offering a declarative approach to reading and validating environment variables.
+
+The configuration system solves several common problems:
+
+1. **Type Safety** - Environment variables are strings, but your application needs typed values (numbers, booleans, objects). The config system handles transformation and inference automatically.
+2. **Validation at Startup** - Missing or invalid configuration is detected immediately when your application starts, not when the code path is first executed.
+3. **Singleton Management** - Configuration is resolved once and cached, with special handling for test environments.
+4. **Extensibility** - Custom config specs allow database packages and other infrastructure to integrate seamlessly.
+
+## Installation
+
+```bash
+npm install @hexaijs/utils
+```
+
+## Core Concepts
+
+### defineConfig
+
+`defineConfig` creates a typed configuration getter that resolves and validates configuration on first access.
+
+```typescript
+import {
+    defineConfig,
+    env,
+    envOptional,
+    envNumber,
+    envBoolean,
+} from "@hexaijs/utils/config";
+
+export const getConfig = defineConfig({
+    // Required string
+    apiKey: env("API_KEY"),
+
+    // Optional with default
+    logLevel: envOptional("LOG_LEVEL", "info"),
+
+    // Required number
+    port: envNumber("PORT"),
+
+    // Boolean with default
+    debug: envBoolean("DEBUG", false),
+
+    // Static values are also supported
+    appName: "my-app",
+    maxRetries: 3,
+});
+
+// Usage
+const config = getConfig();
+config.apiKey;      // string
+config.logLevel;    // string | undefined
+config.port;        // number
+config.debug;       // boolean
+config.appName;     // "my-app" (literal type preserved)
+config.maxRetries;  // 3 (literal type preserved)
+```
+
+The returned getter function caches the resolved config (singleton pattern). In test environments (`NODE_ENV=test`), the config is recreated on each call to reflect environment changes between tests.
+
+### Environment Variable Specs
+
+Builder functions for different data types:
+
+| Function | Type | Description |
+|----------|------|-------------|
+| `env(key)` | `string` | Required string |
+| `envOptional(key, default?)` | `string \| undefined` | Optional string with default |
+| `envNumber(key)` | `number` | Required number |
+| `envNumberOptional(key, default?)` | `number \| undefined` | Optional number |
+| `envBoolean(key, default)` | `boolean` | Boolean (`"true"`, `"1"` → true) |
+| `envJson<T>(key)` | `T` | Required JSON-parsed object |
+| `envJsonOptional<T>(key, default?)` | `T \| undefined` | Optional JSON object |
+
+```typescript
+import {
+    defineConfig,
+    env,
+    envNumber,
+    envBoolean,
+    envJson,
+} from "@hexaijs/utils/config";
+
+const getConfig = defineConfig({
+    // Required - throws ConfigValidationError if missing
+    databaseUrl: env("DATABASE_URL"),
+
+    // Number transformation
+    port: envNumber("PORT"),
+
+    // Boolean - recognizes "true" and "1"
+    enableMetrics: envBoolean("ENABLE_METRICS", false),
+
+    // JSON parsing with type inference
+    rateLimits: envJson<{ requests: number; window: number }>("RATE_LIMITS"),
+});
+```
+
+### ConfigValidationError
+
+When required environment variables are missing or transformation fails, `defineConfig` collects all errors and throws a single `ConfigValidationError`.
+
+```typescript
+import { defineConfig, env, ConfigValidationError } from "@hexaijs/utils/config";
+
+const getConfig = defineConfig({
+    apiKey: env("API_KEY"),
+    secretKey: env("SECRET_KEY"),
+    databaseUrl: env("DATABASE_URL"),
+});
+
+try {
+    const config = getConfig();
+} catch (e) {
+    if (e instanceof ConfigValidationError) {
+        console.error("Configuration errors:");
+        e.errors.forEach(err => console.error(`  - ${err}`));
+        // Config validation failed:
+        //   - Missing required env: API_KEY
+        //   - Missing required env: SECRET_KEY
+        //   - Missing required env: DATABASE_URL
+        process.exit(1);
+    }
+    throw e;
+}
+```
+
+All validation errors are collected before throwing, so you see every missing variable at once rather than fixing them one at a time.
+
+### Custom ConfigSpec
+
+The `ConfigSpec` interface allows you to create custom configuration resolvers. Infrastructure packages like `@hexaijs/postgres` use this to provide database configuration specs.
+
+```typescript
+import type { ConfigSpec } from "@hexaijs/utils/config";
+
+// Example: Custom config spec for Redis
+class RedisSpec implements ConfigSpec<RedisConfig> {
+    readonly _type = "redis";
+
+    constructor(private prefix: string) {}
+
+    resolve(errors: string[]): RedisConfig | undefined {
+        const host = process.env[`${this.prefix}_HOST`];
+        const port = process.env[`${this.prefix}_PORT`];
+
+        if (!host) {
+            errors.push(`Missing required env: ${this.prefix}_HOST`);
+            return undefined;
+        }
+
+        return {
+            host,
+            port: port ? parseInt(port) : 6379,
+        };
+    }
+}
+
+// Usage with defineConfig
+const getConfig = defineConfig({
+    redis: new RedisSpec("REDIS"),
+    apiKey: env("API_KEY"),
+});
+```
+
+The `resolve` method should push error messages to the `errors` array instead of throwing, allowing all errors to be collected.
+
+### DatabaseConfig Interface
+
+A common interface that database configuration classes implement, enabling polymorphic handling of different databases.
+
+```typescript
+import type { DatabaseConfig } from "@hexaijs/utils/config";
+
+// PostgresConfig from @hexaijs/postgres implements this interface
+interface DatabaseConfig {
+    readonly host: string;
+    readonly port: number;
+    readonly database: string;
+    readonly user: string;
+    readonly password?: string;
+    toString(): string;  // Returns connection URL
+}
+```
+
+This interface is used by database packages to provide type-safe configuration. See `@hexaijs/postgres` for a complete implementation.
+
+### Loading .env Files
+
+The `loadEnvFiles` function loads environment files following a standard precedence order.
+
+```typescript
+import { loadEnvFiles, defineConfig, env } from "@hexaijs/utils/config";
+
+// Option 1: Load env files before defining config
+loadEnvFiles();
+
+const getConfig = defineConfig({
+    apiKey: env("API_KEY"),
+});
+
+// Option 2: Use loadEnv option in defineConfig
+const getConfig = defineConfig(
+    { apiKey: env("API_KEY") },
+    { loadEnv: true }
+);
+```
+
+**File loading order** (later files override earlier):
+1. `.env` - Default values
+2. `.env.local` - Local overrides (gitignored)
+3. `.env.{NODE_ENV}` - Environment-specific (e.g., `.env.test`)
+4. `.env.{NODE_ENV}.local` - Local environment overrides
+
+```typescript
+// Custom base path and environment
+loadEnvFiles({
+    basePath: "/app/config",
+    nodeEnv: "staging",
+});
+```
+
+## Usage
+
+### Application Configuration Pattern
+
+A typical pattern for hexai applications:
+
+```typescript
+// config.ts
+import { defineConfig, env, envBoolean, envNumber } from "@hexaijs/utils/config";
+import { postgresConfig } from "@hexaijs/postgres";
+
+export const getConfig = defineConfig(
+    {
+        db: postgresConfig("ORDER_DB"),  // ConfigSpec - errors collected properly
+        port: envNumber("PORT"),
+        debug: envBoolean("DEBUG", false),
+        apiKey: env("API_KEY"),
+    },
+    { loadEnv: true }
+);
+
+// application-context.ts
+import { getConfig } from "./config";
+
+export class OrderApplicationContext {
+    private readonly config = getConfig();
+
+    getDatabase() {
+        return this.config.db;
+    }
+
+    getPort() {
+        return this.config.port;
+    }
+}
+```
+
+### Testing with Environment Changes
+
+In test environments, the config is recreated on each call:
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { defineConfig, env } from "@hexaijs/utils/config";
+
+describe("MyService", () => {
+    const originalEnv = process.env;
+
+    beforeEach(() => {
+        process.env = { ...originalEnv, NODE_ENV: "test" };
+    });
+
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+
+    it("uses API_KEY from environment", () => {
+        process.env.API_KEY = "test-key";
+
+        const getConfig = defineConfig({ apiKey: env("API_KEY") });
+
+        expect(getConfig().apiKey).toBe("test-key");
+    });
+
+    it("reflects environment changes", () => {
+        process.env.API_KEY = "first-key";
+        const getConfig = defineConfig({ apiKey: env("API_KEY") });
+
+        expect(getConfig().apiKey).toBe("first-key");
+
+        process.env.API_KEY = "second-key";
+        expect(getConfig().apiKey).toBe("second-key");
+    });
+});
+```
+
+## API Highlights
+
+| Export | Description |
+|--------|-------------|
+| `defineConfig(schema, options?)` | Creates typed config getter with validation |
+| `env(key)` | Required string environment variable |
+| `envOptional(key, default?)` | Optional string with default |
+| `envNumber(key)` | Required number (transforms string) |
+| `envNumberOptional(key, default?)` | Optional number |
+| `envBoolean(key, default)` | Boolean (`"true"`, `"1"` → true) |
+| `envJson<T>(key)` | Required JSON-parsed value |
+| `envJsonOptional<T>(key, default?)` | Optional JSON value |
+| `ConfigSpec<T>` | Interface for custom config specs |
+| `ConfigValidationError` | Error containing all validation failures |
+| `DatabaseConfig` | Common interface for database configs |
+| `loadEnvFiles(options?)` | Loads .env files with NODE_ENV awareness |
+
+## See Also
+
+- [@hexaijs/postgres](../postgres/README.md) - PostgresConfig implements DatabaseConfig, `postgresConfig()` helper for use with defineConfig
+- [@hexaijs/application](../application/README.md) - Application layer that uses configuration

package/dist/config/config-spec.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Base interface for all config specs.
+ * Implement this interface to create custom config specs that can be used with defineConfig.
+ *
+ * @example
+ * ```typescript
+ * class RedisSpec implements ConfigSpec<RedisConfig> {
+ *     readonly _type = "redis";
+ *
+ *     constructor(private prefix: string) {}
+ *
+ *     resolve(errors: string[]): RedisConfig | undefined {
+ *         try {
+ *             return RedisConfig.fromEnv(this.prefix);
+ *         } catch (e) {
+ *             errors.push((e as Error).message);
+ *             return undefined;
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export interface ConfigSpec<T> {
+    /**
+     * Unique type identifier for this spec.
+     * Used for debugging and error messages.
+     */
+    readonly _type: string;
+    /**
+     * Resolve the config value from environment.
+     * Should push error messages to the errors array instead of throwing.
+     *
+     * @param errors - Array to collect validation errors
+     * @returns The resolved value, or undefined if resolution failed
+     */
+    resolve(errors: string[]): T | undefined;
+}
+/**
+ * Type helper to infer result type from a ConfigSpec.
+ */
+export type InferSpecType<S> = S extends ConfigSpec<infer T> ? T : S;
+/**
+ * Type helper to infer config object type from schema.
+ */
+export type InferConfigType<S extends Record<string, unknown>> = {
+    readonly [K in keyof S]: InferSpecType<S[K]>;
+};
+export declare function isConfigSpec(value: unknown): value is ConfigSpec<unknown>;
+//# sourceMappingURL=config-spec.d.ts.map

package/dist/config/config-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-spec.d.ts","sourceRoot":"","sources":["../../src/config/config-spec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAErE;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC7D,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC/C,CAAC;AAGF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,OAAO,CAAC,CAOzE"}

package/dist/config/config-spec.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isConfigSpec = isConfigSpec;
+function isConfigSpec(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "resolve" in value &&
+        typeof value.resolve === "function");
+}
+//# sourceMappingURL=config-spec.js.map

package/dist/config/config-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-spec.js","sourceRoot":"","sources":["../../src/config/config-spec.ts"],"names":[],"mappings":";;AAoDA,oCAOC;AAPD,SAAgB,YAAY,CAAC,KAAc;IACvC,OAAO,CACH,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QAClB,OAAQ,KAA6B,CAAC,OAAO,KAAK,UAAU,CAC/D,CAAC;AACN,CAAC"}

package/dist/config/database-config.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Common interface for all database configurations.
+ *
+ * This interface defines the minimal contract that all database config
+ * implementations (PostgresConfig, MySQLConfig, etc.) must satisfy.
+ *
+ * Note: Builder methods (with*) are intentionally NOT included here.
+ * Each implementation returns its own concrete type for better type inference.
+ */
+export interface DatabaseConfig {
+    readonly host: string;
+    readonly port: number;
+    readonly database: string;
+    readonly user: string;
+    readonly password?: string;
+    /**
+     * Returns the connection URL string representation.
+     * Format varies by database type (e.g., postgres://, mysql://)
+     */
+    toString(): string;
+}
+//# sourceMappingURL=database-config.d.ts.map

package/dist/config/database-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-config.d.ts","sourceRoot":"","sources":["../../src/config/database-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,IAAI,MAAM,CAAC;CACtB"}

package/dist/config/database-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=database-config.js.map

package/dist/config/database-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-config.js","sourceRoot":"","sources":["../../src/config/database-config.ts"],"names":[],"mappings":""}

package/dist/config/define-config.d.ts

@@ -0,0 +1,45 @@
+import { type InferConfigType } from "./config-spec";
+export interface ConfigOptions {
+    /**
+     * Whether to load .env files before resolving config.
+     * @default false
+     */
+    loadEnv?: boolean;
+    /**
+     * Custom env loader function. Called when loadEnv is true.
+     * If not provided and loadEnv is true, uses dotenv.config().
+     */
+    envLoader?: () => void;
+}
+/**
+ * Defines a typed configuration with automatic validation and singleton management.
+ *
+ * @param schema - Configuration schema defining all config fields
+ * @param options - Optional configuration options
+ * @returns A function that returns the resolved config (singleton)
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig, env, envBoolean } from "@hexaijs/core";
+ * import { postgres } from "@hexaijs/postgres";
+ *
+ * export const getConfig = defineConfig({
+ *     db: postgres("ORDER_DB"),
+ *     apiKey: env("API_KEY"),
+ *     debug: envBoolean("DEBUG", false),
+ *     // Primitive values are also supported
+ *     appName: "my-app",
+ *     maxRetries: 3,
+ * });
+ *
+ * // Usage
+ * const config = getConfig();
+ * config.db.host;      // PostgresConfig property
+ * config.apiKey;       // string
+ * config.debug;        // boolean
+ * config.appName;      // "my-app" (literal type)
+ * config.maxRetries;   // 3 (literal type)
+ * ```
+ */
+export declare function defineConfig<S extends Record<string, unknown>>(schema: S, options?: ConfigOptions): () => InferConfigType<S>;
+//# sourceMappingURL=define-config.d.ts.map

package/dist/config/define-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAgB,MAAM,eAAe,CAAC;AAInE,MAAM,WAAW,aAAa;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1D,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,aAAa,GACxB,MAAM,eAAe,CAAC,CAAC,CAAC,CAoC1B"}

package/dist/config/define-config.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineConfig = defineConfig;
+const config_spec_1 = require("./config-spec");
+const errors_1 = require("./errors");
+const load_env_files_1 = require("./load-env-files");
+/**
+ * Defines a typed configuration with automatic validation and singleton management.
+ *
+ * @param schema - Configuration schema defining all config fields
+ * @param options - Optional configuration options
+ * @returns A function that returns the resolved config (singleton)
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig, env, envBoolean } from "@hexaijs/core";
+ * import { postgres } from "@hexaijs/postgres";
+ *
+ * export const getConfig = defineConfig({
+ *     db: postgres("ORDER_DB"),
+ *     apiKey: env("API_KEY"),
+ *     debug: envBoolean("DEBUG", false),
+ *     // Primitive values are also supported
+ *     appName: "my-app",
+ *     maxRetries: 3,
+ * });
+ *
+ * // Usage
+ * const config = getConfig();
+ * config.db.host;      // PostgresConfig property
+ * config.apiKey;       // string
+ * config.debug;        // boolean
+ * config.appName;      // "my-app" (literal type)
+ * config.maxRetries;   // 3 (literal type)
+ * ```
+ */
+function defineConfig(schema, options) {
+    let instance = null;
+    return () => {
+        // In test environment, always recreate to reflect env changes
+        if (instance && process.env.NODE_ENV !== "test") {
+            return instance;
+        }
+        // Load env files if requested
+        if (options?.loadEnv) {
+            if (options.envLoader) {
+                options.envLoader();
+            }
+            else {
+                (0, load_env_files_1.loadEnvFiles)();
+            }
+        }
+        const config = {};
+        const errors = [];
+        for (const [key, value] of Object.entries(schema)) {
+            if ((0, config_spec_1.isConfigSpec)(value)) {
+                config[key] = value.resolve(errors);
+            }
+            else {
+                config[key] = value;
+            }
+        }
+        if (errors.length > 0) {
+            throw new errors_1.ConfigValidationError(errors);
+        }
+        instance = config;
+        return instance;
+    };
+}
+//# sourceMappingURL=define-config.js.map

package/dist/config/define-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../../src/config/define-config.ts"],"names":[],"mappings":";;AAgDA,oCAuCC;AAvFD,+CAAmE;AACnE,qCAAiD;AACjD,qDAAgD;AAgBhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,YAAY,CACxB,MAAS,EACT,OAAuB;IAEvB,IAAI,QAAQ,GAA8B,IAAI,CAAC;IAE/C,OAAO,GAAG,EAAE;QACR,8DAA8D;QAC9D,IAAI,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;YAC9C,OAAO,QAAQ,CAAC;QACpB,CAAC;QAED,8BAA8B;QAC9B,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;YACnB,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBACpB,OAAO,CAAC,SAAS,EAAE,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACJ,IAAA,6BAAY,GAAE,CAAC;YACnB,CAAC;QACL,CAAC;QAED,MAAM,MAAM,GAAG,EAA6B,CAAC;QAC7C,MAAM,MAAM,GAAa,EAAE,CAAC;QAE5B,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAChD,IAAI,IAAA,0BAAY,EAAC,KAAK,CAAC,EAAE,CAAC;gBACtB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACxC,CAAC;iBAAM,CAAC;gBACJ,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACxB,CAAC;QACL,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,8BAAqB,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;QAED,QAAQ,GAAG,MAA4B,CAAC;QACxC,OAAO,QAAQ,CAAC;IACpB,CAAC,CAAC;AACN,CAAC"}

package/dist/config/env-spec.d.ts

@@ -0,0 +1,78 @@
+import type { ConfigSpec } from "./config-spec";
+/**
+ * Config spec for environment variables.
+ * Use the builder functions (env, envOptional, envNumber, etc.) instead of instantiating directly.
+ */
+export declare class EnvSpec<T> implements ConfigSpec<T> {
+    private readonly envKey;
+    private readonly required;
+    private readonly defaultValue?;
+    private readonly transform?;
+    readonly _type = "env";
+    constructor(envKey: string, required: boolean, defaultValue?: T | undefined, transform?: ((value: string) => T) | undefined);
+    resolve(errors: string[]): T | undefined;
+}
+/**
+ * Required string environment variable.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     apiKey: env("API_KEY"),
+ * });
+ * ```
+ */
+export declare function env(key: string): EnvSpec<string>;
+/**
+ * Optional string environment variable with default value.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     logLevel: envOptional("LOG_LEVEL", "info"),
+ * });
+ * ```
+ */
+export declare function envOptional(key: string, defaultValue?: string): EnvSpec<string | undefined>;
+/**
+ * Required number environment variable.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     port: envNumber("PORT"),
+ * });
+ * ```
+ */
+export declare function envNumber(key: string): EnvSpec<number>;
+/**
+ * Optional number environment variable with default value.
+ */
+export declare function envNumberOptional(key: string, defaultValue?: number): EnvSpec<number | undefined>;
+/**
+ * Boolean environment variable. Recognizes "true", "1" as true.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     debug: envBoolean("DEBUG", false),
+ * });
+ * ```
+ */
+export declare function envBoolean(key: string, defaultValue?: boolean): EnvSpec<boolean>;
+/**
+ * JSON environment variable. Parses JSON string into object.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     prompts: envJson<{ system: string }>("PROMPTS"),
+ * });
+ * ```
+ */
+export declare function envJson<T>(key: string): EnvSpec<T>;
+/**
+ * Optional JSON environment variable with default value.
+ */
+export declare function envJsonOptional<T>(key: string, defaultValue?: T): EnvSpec<T | undefined>;
+//# sourceMappingURL=env-spec.d.ts.map

package/dist/config/env-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-spec.d.ts","sourceRoot":"","sources":["../../src/config/env-spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD;;;GAGG;AACH,qBAAa,OAAO,CAAC,CAAC,CAAE,YAAW,UAAU,CAAC,CAAC,CAAC;IAIxC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IAN/B,QAAQ,CAAC,KAAK,SAAS;gBAGF,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,EACjB,YAAY,CAAC,EAAE,CAAC,YAAA,EAChB,SAAS,CAAC,GAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,aAAA;IAGrD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,CAAC,GAAG,SAAS;CAmB3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE3F;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAEjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAE9E;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAElD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAExF"}

package/dist/config/env-spec.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvSpec = void 0;
+exports.env = env;
+exports.envOptional = envOptional;
+exports.envNumber = envNumber;
+exports.envNumberOptional = envNumberOptional;
+exports.envBoolean = envBoolean;
+exports.envJson = envJson;
+exports.envJsonOptional = envJsonOptional;
+/**
+ * Config spec for environment variables.
+ * Use the builder functions (env, envOptional, envNumber, etc.) instead of instantiating directly.
+ */
+class EnvSpec {
+    envKey;
+    required;
+    defaultValue;
+    transform;
+    _type = "env";
+    constructor(envKey, required, defaultValue, transform) {
+        this.envKey = envKey;
+        this.required = required;
+        this.defaultValue = defaultValue;
+        this.transform = transform;
+    }
+    resolve(errors) {
+        const rawValue = process.env[this.envKey];
+        if (!rawValue && this.required) {
+            errors.push(`Missing required env: ${this.envKey}`);
+            return undefined;
+        }
+        if (rawValue !== undefined) {
+            try {
+                return this.transform ? this.transform(rawValue) : rawValue;
+            }
+            catch (e) {
+                errors.push(`Failed to transform ${this.envKey}: ${e.message}`);
+                return undefined;
+            }
+        }
+        return this.defaultValue;
+    }
+}
+exports.EnvSpec = EnvSpec;
+/**
+ * Required string environment variable.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     apiKey: env("API_KEY"),
+ * });
+ * ```
+ */
+function env(key) {
+    return new EnvSpec(key, true);
+}
+/**
+ * Optional string environment variable with default value.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     logLevel: envOptional("LOG_LEVEL", "info"),
+ * });
+ * ```
+ */
+function envOptional(key, defaultValue) {
+    return new EnvSpec(key, false, defaultValue);
+}
+/**
+ * Required number environment variable.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     port: envNumber("PORT"),
+ * });
+ * ```
+ */
+function envNumber(key) {
+    return new EnvSpec(key, true, undefined, Number);
+}
+/**
+ * Optional number environment variable with default value.
+ */
+function envNumberOptional(key, defaultValue) {
+    return new EnvSpec(key, false, defaultValue, (v) => (v ? Number(v) : undefined));
+}
+/**
+ * Boolean environment variable. Recognizes "true", "1" as true.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     debug: envBoolean("DEBUG", false),
+ * });
+ * ```
+ */
+function envBoolean(key, defaultValue = false) {
+    return new EnvSpec(key, false, defaultValue, (v) => v === "true" || v === "1");
+}
+/**
+ * JSON environment variable. Parses JSON string into object.
+ *
+ * @example
+ * ```typescript
+ * const getConfig = defineConfig({
+ *     prompts: envJson<{ system: string }>("PROMPTS"),
+ * });
+ * ```
+ */
+function envJson(key) {
+    return new EnvSpec(key, true, undefined, JSON.parse);
+}
+/**
+ * Optional JSON environment variable with default value.
+ */
+function envJsonOptional(key, defaultValue) {
+    return new EnvSpec(key, false, defaultValue, (v) => (v ? JSON.parse(v) : undefined));
+}
+//# sourceMappingURL=env-spec.js.map

package/dist/config/env-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-spec.js","sourceRoot":"","sources":["../../src/config/env-spec.ts"],"names":[],"mappings":"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"}

package/dist/config/env-spec.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=env-spec.spec.d.ts.map

package/dist/config/env-spec.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-spec.spec.d.ts","sourceRoot":"","sources":["../../src/config/env-spec.spec.ts"],"names":[],"mappings":""}

package/dist/config/env-spec.spec.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const env_spec_1 = require("./env-spec");
+const define_config_1 = require("./define-config");
+const errors_1 = require("./errors");
+(0, vitest_1.describe)("EnvSpec", () => {
+    const originalEnv = process.env;
+    (0, vitest_1.beforeEach)(() => {
+        process.env = { ...originalEnv, NODE_ENV: "test" };
+    });
+    (0, vitest_1.afterEach)(() => {
+        process.env = originalEnv;
+    });
+    (0, vitest_1.describe)("env()", () => {
+        (0, vitest_1.it)("should resolve required string env var", () => {
+            process.env.API_KEY = "secret-key";
+            const getConfig = (0, define_config_1.defineConfig)({ apiKey: (0, env_spec_1.env)("API_KEY") });
+            (0, vitest_1.expect)(getConfig().apiKey).toBe("secret-key");
+        });
+        (0, vitest_1.it)("should throw ConfigValidationError for missing required env", () => {
+            const getConfig = (0, define_config_1.defineConfig)({ apiKey: (0, env_spec_1.env)("MISSING_KEY") });
+            (0, vitest_1.expect)(() => getConfig()).toThrow(errors_1.ConfigValidationError);
+            (0, vitest_1.expect)(() => getConfig()).toThrow("Missing required env: MISSING_KEY");
+        });
+        (0, vitest_1.it)("should collect all missing env vars in error", () => {
+            const getConfig = (0, define_config_1.defineConfig)({
+                key1: (0, env_spec_1.env)("MISSING_1"),
+                key2: (0, env_spec_1.env)("MISSING_2"),
+                key3: (0, env_spec_1.env)("MISSING_3"),
+            });
+            try {
+                getConfig();
+                vitest_1.expect.fail("Should have thrown");
+            }
+            catch (e) {
+                (0, vitest_1.expect)(e).toBeInstanceOf(errors_1.ConfigValidationError);
+                const error = e;
+                (0, vitest_1.expect)(error.errors).toHaveLength(3);
+                (0, vitest_1.expect)(error.errors).toContain("Missing required env: MISSING_1");
+                (0, vitest_1.expect)(error.errors).toContain("Missing required env: MISSING_2");
+                (0, vitest_1.expect)(error.errors).toContain("Missing required env: MISSING_3");
+            }
+        });
+    });
+    (0, vitest_1.describe)("envOptional()", () => {
+        (0, vitest_1.it)("should resolve optional env var", () => {
+            process.env.LOG_LEVEL = "debug";
+            const getConfig = (0, define_config_1.defineConfig)({ logLevel: (0, env_spec_1.envOptional)("LOG_LEVEL") });
+            (0, vitest_1.expect)(getConfig().logLevel).toBe("debug");
+        });
+        (0, vitest_1.it)("should use default value when env is not set", () => {
+            const getConfig = (0, define_config_1.defineConfig)({ logLevel: (0, env_spec_1.envOptional)("LOG_LEVEL", "info") });
+            (0, vitest_1.expect)(getConfig().logLevel).toBe("info");
+        });
+        (0, vitest_1.it)("should return undefined when no default and env not set", () => {
+            const getConfig = (0, define_config_1.defineConfig)({ logLevel: (0, env_spec_1.envOptional)("LOG_LEVEL") });
+            (0, vitest_1.expect)(getConfig().logLevel).toBeUndefined();
+        });
+    });
+    (0, vitest_1.describe)("envNumber()", () => {
+        (0, vitest_1.it)("should resolve and transform to number", () => {
+            process.env.PORT = "3000";
+            const getConfig = (0, define_config_1.defineConfig)({ port: (0, env_spec_1.envNumber)("PORT") });
+            (0, vitest_1.expect)(getConfig().port).toBe(3000);
+            (0, vitest_1.expect)(typeof getConfig().port).toBe("number");
+        });
+        (0, vitest_1.it)("should throw for missing required number env", () => {
+            const getConfig = (0, define_config_1.defineConfig)({ port: (0, env_spec_1.envNumber)("PORT") });
+            (0, vitest_1.expect)(() => getConfig()).toThrow("Missing required env: PORT");
+        });
+    });
+    (0, vitest_1.describe)("envNumberOptional()", () => {
+        (0, vitest_1.it)("should resolve optional number with default", () => {
+            const getConfig = (0, define_config_1.defineConfig)({ timeout: (0, env_spec_1.envNumberOptional)("TIMEOUT", 5000) });
+            (0, vitest_1.expect)(getConfig().timeout).toBe(5000);
+        });
+        (0, vitest_1.it)("should parse env value when set", () => {
+            process.env.TIMEOUT = "10000";
+            const getConfig = (0, define_config_1.defineConfig)({ timeout: (0, env_spec_1.envNumberOptional)("TIMEOUT", 5000) });
+            (0, vitest_1.expect)(getConfig().timeout).toBe(10000);
+        });
+    });
+    (0, vitest_1.describe)("envBoolean()", () => {
+        (0, vitest_1.it)("should parse 'true' as true", () => {
+            process.env.DEBUG = "true";
+            const getConfig = (0, define_config_1.defineConfig)({ debug: (0, env_spec_1.envBoolean)("DEBUG") });
+            (0, vitest_1.expect)(getConfig().debug).toBe(true);
+        });
+        (0, vitest_1.it)("should parse '1' as true", () => {
+            process.env.DEBUG = "1";
+            const getConfig = (0, define_config_1.defineConfig)({ debug: (0, env_spec_1.envBoolean)("DEBUG") });
+            (0, vitest_1.expect)(getConfig().debug).toBe(true);
+        });
+        (0, vitest_1.it)("should parse other values as false", () => {
+            process.env.DEBUG = "false";
+            const getConfig = (0, define_config_1.defineConfig)({ debug: (0, env_spec_1.envBoolean)("DEBUG") });
+            (0, vitest_1.expect)(getConfig().debug).toBe(false);
+        });
+        (0, vitest_1.it)("should use default value when not set", () => {
+            const getConfig = (0, define_config_1.defineConfig)({ debug: (0, env_spec_1.envBoolean)("DEBUG", true) });
+            (0, vitest_1.expect)(getConfig().debug).toBe(true);
+        });
+    });
+    (0, vitest_1.describe)("envJson()", () => {
+        (0, vitest_1.it)("should parse JSON env var", () => {
+            process.env.CONFIG = JSON.stringify({ key: "value", num: 42 });
+            const getConfig = (0, define_config_1.defineConfig)({
+                config: (0, env_spec_1.envJson)("CONFIG"),
+            });
+            (0, vitest_1.expect)(getConfig().config).toEqual({ key: "value", num: 42 });
+        });
+        (0, vitest_1.it)("should throw for invalid JSON", () => {
+            process.env.CONFIG = "not-valid-json";
+            const getConfig = (0, define_config_1.defineConfig)({ config: (0, env_spec_1.envJson)("CONFIG") });
+            (0, vitest_1.expect)(() => getConfig()).toThrow("Failed to transform CONFIG");
+        });
+        (0, vitest_1.it)("should throw for missing required JSON env", () => {
+            const getConfig = (0, define_config_1.defineConfig)({ config: (0, env_spec_1.envJson)("CONFIG") });
+            (0, vitest_1.expect)(() => getConfig()).toThrow("Missing required env: CONFIG");
+        });
+    });
+    (0, vitest_1.describe)("envJsonOptional()", () => {
+        (0, vitest_1.it)("should return default when not set", () => {
+            const defaultConfig = { level: "info" };
+            const getConfig = (0, define_config_1.defineConfig)({ config: (0, env_spec_1.envJsonOptional)("CONFIG", defaultConfig) });
+            (0, vitest_1.expect)(getConfig().config).toEqual(defaultConfig);
+        });
+        (0, vitest_1.it)("should parse JSON when set", () => {
+            process.env.CONFIG = JSON.stringify({ level: "debug" });
+            const getConfig = (0, define_config_1.defineConfig)({ config: (0, env_spec_1.envJsonOptional)("CONFIG", { level: "info" }) });
+            (0, vitest_1.expect)(getConfig().config).toEqual({ level: "debug" });
+        });
+    });
+    (0, vitest_1.describe)("singleton behavior", () => {
+        (0, vitest_1.it)("should return same instance in non-test environment", () => {
+            process.env.NODE_ENV = "production";
+            process.env.API_KEY = "key1";
+            const getConfig = (0, define_config_1.defineConfig)({ apiKey: (0, env_spec_1.env)("API_KEY") });
+            const config1 = getConfig();
+            process.env.API_KEY = "key2";
+            const config2 = getConfig();
+            (0, vitest_1.expect)(config1).toBe(config2);
+            (0, vitest_1.expect)(config1.apiKey).toBe("key1");
+        });
+        (0, vitest_1.it)("should recreate config in test environment", () => {
+            process.env.NODE_ENV = "test";
+            process.env.API_KEY = "key1";
+            const getConfig = (0, define_config_1.defineConfig)({ apiKey: (0, env_spec_1.env)("API_KEY") });
+            const config1 = getConfig();
+            (0, vitest_1.expect)(config1.apiKey).toBe("key1");
+            process.env.API_KEY = "key2";
+            const config2 = getConfig();
+            (0, vitest_1.expect)(config2.apiKey).toBe("key2");
+        });
+    });
+    (0, vitest_1.describe)("type inference", () => {
+        (0, vitest_1.it)("should infer correct types", () => {
+            process.env.API_KEY = "secret";
+            process.env.PORT = "3000";
+            process.env.DEBUG = "true";
+            process.env.CONFIG = "{}";
+            const getConfig = (0, define_config_1.defineConfig)({
+                apiKey: (0, env_spec_1.env)("API_KEY"),
+                port: (0, env_spec_1.envNumber)("PORT"),
+                debug: (0, env_spec_1.envBoolean)("DEBUG"),
+                optional: (0, env_spec_1.envOptional)("OPTIONAL"),
+                json: (0, env_spec_1.envJson)("CONFIG"),
+            });
+            const config = getConfig();
+            // Type assertions - these would fail at compile time if types are wrong
+            const _apiKey = config.apiKey;
+            const _port = config.port;
+            const _debug = config.debug;
+            const _optional = config.optional;
+            const _json = config.json;
+            (0, vitest_1.expect)(_apiKey).toBeDefined();
+            (0, vitest_1.expect)(_port).toBeDefined();
+            (0, vitest_1.expect)(_debug).toBeDefined();
+            (0, vitest_1.expect)(_json).toBeDefined();
+        });
+    });
+});
+//# sourceMappingURL=env-spec.spec.js.map

package/dist/config/env-spec.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-spec.spec.js","sourceRoot":"","sources":["../../src/config/env-spec.spec.ts"],"names":[],"mappings":"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"}

package/dist/config/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Error thrown when config validation fails.
+ * Contains all validation errors collected during config resolution.
+ */
+export declare class ConfigValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/config/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/config/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;aAChB,MAAM,EAAE,MAAM,EAAE;gBAAhB,MAAM,EAAE,MAAM,EAAE;CAI/C"}

package/dist/config/errors.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigValidationError = void 0;
+/**
+ * Error thrown when config validation fails.
+ * Contains all validation errors collected during config resolution.
+ */
+class ConfigValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Config validation failed:\n  - ${errors.join("\n  - ")}`);
+        this.errors = errors;
+        this.name = "ConfigValidationError";
+    }
+}
+exports.ConfigValidationError = ConfigValidationError;
+//# sourceMappingURL=errors.js.map

package/dist/config/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/config/errors.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IAChB;IAA5B,YAA4B,MAAgB;QACxC,KAAK,CAAC,kCAAkC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QADzC,WAAM,GAAN,MAAM,CAAU;QAExC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACxC,CAAC;CACJ;AALD,sDAKC"}

package/dist/config/index.d.ts

@@ -0,0 +1,7 @@
+export { type ConfigSpec, type InferSpecType, type InferConfigType, isConfigSpec, } from "./config-spec";
+export { ConfigValidationError } from "./errors";
+export { defineConfig, type ConfigOptions } from "./define-config";
+export * from "./load-env-files";
+export { EnvSpec, env, envOptional, envNumber, envNumberOptional, envBoolean, envJson, envJsonOptional, } from "./env-spec";
+export { DatabaseConfig } from "./database-config";
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,YAAY,GACf,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACnE,cAAc,kBAAkB,CAAC;AAEjC,OAAO,EACH,OAAO,EACP,GAAG,EACH,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,OAAO,EACP,eAAe,GAClB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/config/index.js

@@ -0,0 +1,34 @@
+"use strict";
+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 __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envJsonOptional = exports.envJson = exports.envBoolean = exports.envNumberOptional = exports.envNumber = exports.envOptional = exports.env = exports.EnvSpec = exports.defineConfig = exports.ConfigValidationError = exports.isConfigSpec = void 0;
+var config_spec_1 = require("./config-spec");
+Object.defineProperty(exports, "isConfigSpec", { enumerable: true, get: function () { return config_spec_1.isConfigSpec; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "ConfigValidationError", { enumerable: true, get: function () { return errors_1.ConfigValidationError; } });
+var define_config_1 = require("./define-config");
+Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return define_config_1.defineConfig; } });
+__exportStar(require("./load-env-files"), exports);
+var env_spec_1 = require("./env-spec");
+Object.defineProperty(exports, "EnvSpec", { enumerable: true, get: function () { return env_spec_1.EnvSpec; } });
+Object.defineProperty(exports, "env", { enumerable: true, get: function () { return env_spec_1.env; } });
+Object.defineProperty(exports, "envOptional", { enumerable: true, get: function () { return env_spec_1.envOptional; } });
+Object.defineProperty(exports, "envNumber", { enumerable: true, get: function () { return env_spec_1.envNumber; } });
+Object.defineProperty(exports, "envNumberOptional", { enumerable: true, get: function () { return env_spec_1.envNumberOptional; } });
+Object.defineProperty(exports, "envBoolean", { enumerable: true, get: function () { return env_spec_1.envBoolean; } });
+Object.defineProperty(exports, "envJson", { enumerable: true, get: function () { return env_spec_1.envJson; } });
+Object.defineProperty(exports, "envJsonOptional", { enumerable: true, get: function () { return env_spec_1.envJsonOptional; } });
+//# sourceMappingURL=index.js.map

package/dist/config/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6CAKuB;AADnB,2GAAA,YAAY,OAAA;AAGhB,mCAAiD;AAAxC,+GAAA,qBAAqB,OAAA;AAE9B,iDAAmE;AAA1D,6GAAA,YAAY,OAAA;AACrB,mDAAiC;AAEjC,uCASoB;AARhB,mGAAA,OAAO,OAAA;AACP,+FAAA,GAAG,OAAA;AACH,uGAAA,WAAW,OAAA;AACX,qGAAA,SAAS,OAAA;AACT,6GAAA,iBAAiB,OAAA;AACjB,sGAAA,UAAU,OAAA;AACV,mGAAA,OAAO,OAAA;AACP,2GAAA,eAAe,OAAA"}

package/dist/config/load-env-files.d.ts

@@ -0,0 +1,5 @@
+export declare function loadEnvFiles({ basePath, nodeEnv, }?: {
+    basePath?: string;
+    nodeEnv?: string;
+}): void;
+//# sourceMappingURL=load-env-files.d.ts.map

package/dist/config/load-env-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-env-files.d.ts","sourceRoot":"","sources":["../../src/config/load-env-files.ts"],"names":[],"mappings":"AAKA,wBAAgB,YAAY,CAAC,EACzB,QAAQ,EACR,OAAO,GACV,GAAE;IACC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,IAAI,CA0BZ"}

package/dist/config/load-env-files.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadEnvFiles = loadEnvFiles;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const dotenv_1 = __importDefault(require("dotenv"));
+function loadEnvFiles({ basePath, nodeEnv, } = {}) {
+    const basePath_ = basePath ?? process.cwd();
+    const nodeEnv_ = nodeEnv ?? process.env.NODE_ENV ?? "development";
+    // List of environment files in the order of precedence
+    const envFiles = [
+        ".env", // Default
+        ".env.local", // Local overrides
+        `.env.${nodeEnv_}`, // Environment-specific settings
+        `.env.${nodeEnv_}.local`, // Local overrides of environment-specific settings
+    ];
+    // Function to load a single env file
+    const loadEnvFile = (filePath) => {
+        if (node_fs_1.default.existsSync(filePath)) {
+            dotenv_1.default.config({
+                path: filePath,
+            });
+        }
+    };
+    // Load env files in order of precedence
+    envFiles.reverse().forEach((file) => {
+        const filePath = node_path_1.default.resolve(basePath_, file);
+        loadEnvFile(filePath);
+    });
+}
+//# sourceMappingURL=load-env-files.js.map

package/dist/config/load-env-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-env-files.js","sourceRoot":"","sources":["../../src/config/load-env-files.ts"],"names":[],"mappings":";;;;;AAKA,oCAgCC;AArCD,sDAAyB;AACzB,0DAA6B;AAE7B,oDAA4B;AAE5B,SAAgB,YAAY,CAAC,EACzB,QAAQ,EACR,OAAO,MAIP,EAAE;IACF,MAAM,SAAS,GAAG,QAAQ,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAG,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,IAAI,aAAa,CAAC;IAElE,uDAAuD;IACvD,MAAM,QAAQ,GAAG;QACb,MAAM,EAAE,UAAU;QAClB,YAAY,EAAE,kBAAkB;QAChC,QAAQ,QAAQ,EAAE,EAAE,gCAAgC;QACpD,QAAQ,QAAQ,QAAQ,EAAE,mDAAmD;KAChF,CAAC;IAEF,qCAAqC;IACrC,MAAM,WAAW,GAAG,CAAC,QAAgB,EAAE,EAAE;QACrC,IAAI,iBAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,gBAAM,CAAC,MAAM,CAAC;gBACV,IAAI,EAAE,QAAQ;aACjB,CAAC,CAAC;QACP,CAAC;IACL,CAAC,CAAC;IAEF,wCAAwC;IACxC,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;QAChC,MAAM,QAAQ,GAAG,mBAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC/C,WAAW,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACP,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hexaijs/utils",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "0.1.0",
+  "description": "A collection of utility functions and value objects for hexai projects",
+  "license": "MIT",
+  "author": "Sangwoo Hyun <wkdny.hyun@gmail.com>",
+  "contributors": [
+    "Seungcheol Baek <victoryiron.baek@gmail.com>",
+    "Donghyun Lee <edonghyun@naver.com>"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/workingdanny911/hexai.git",
+    "directory": "packages/utils"
+  },
+  "homepage": "https://github.com/workingdanny911/hexai#readme",
+  "bugs": {
+    "url": "https://github.com/workingdanny911/hexai/issues"
+  },
+  "keywords": [
+    "hexai",
+    "hexagonal",
+    "clean-architecture",
+    "utilities",
+    "typescript"
+  ],
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "exports": {
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js",
+      "require": "./dist/config/index.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "scripts": {
+    "test": "vitest run",
+    "build": "tsc && tsc-alias"
+  }
+}