ezcfg 0.2.0 → 0.3.1

package/README.md

@@ -9,8 +9,10 @@ Lite and easy configuration management for Node.js with full TypeScript support.
 
 - **Type-safe configuration** - Full TypeScript support with automatic type inference
 - **Automatic .env file loading** - Loads environment files based on `NODE_ENV`
+- **Direct .env file parsing** - Read from a specific `.env` file without modifying `process.env`
 - **Validation with clear error messages** - Collects all validation errors at once
-- **Zero runtime dependencies** - Only uses `dotenv` for .env file parsing
+- **PostgreSQL config support** - Built-in `postgresConfig` spec via `ezcfg/postgres`
+- **Extensible** - Implement `ConfigSpec` to add custom config types
 - **Singleton pattern** - Config is lazily evaluated and cached (except in test environment)
 
 ## Installation
@@ -90,12 +92,40 @@ const config = getConfig(); // Lazily evaluated and cached
 | `schema` | `Record<string, unknown>` | Object defining your configuration shape |
 | `options.loadEnv` | `boolean` | Whether to load .env files automatically (default: `false`) |
 | `options.envLoader` | `() => void` | Custom function to load environment variables |
+| `options.fromEnvFile` | `string` | Path to a `.env` file to parse directly (does not modify `process.env`) |
 
 **Behavior:**
 
 - Returns a factory function that lazily evaluates and caches the config
 - In test environment (`NODE_ENV=test`), config is re-evaluated on each call
 - Throws `ConfigValidationError` if any required values are missing
+- When `fromEnvFile` is set, the file is parsed into a local object and passed to each spec's `resolve()` — `process.env` is never modified
+
+---
+
+### `parseEnvFile(filePath)`
+
+Parses a `.env` file and returns its contents as a `Record<string, string>`. Does not modify `process.env`.
+
+```typescript
+import { parseEnvFile } from 'ezcfg';
+
+const env = parseEnvFile('/path/to/.env');
+// { DATABASE_URL: 'postgres://...', API_KEY: 'secret' }
+```
+
+Useful for injecting env vars into test runners:
+
+```typescript
+// vitest.config.ts
+import { parseEnvFile } from 'ezcfg';
+
+export default defineConfig({
+  test: {
+    env: parseEnvFile(resolve(__dirname, '.env')),
+  },
+});
+```
 
 ---
 
@@ -216,6 +246,90 @@ loadEnvFiles({
 });
 ```
 
+---
+
+## `ezcfg/postgres`
+
+PostgreSQL configuration support, available as a subpath import.
+
+```typescript
+import { postgresConfig, PostgresConfig } from 'ezcfg/postgres';
+```
+
+### `postgresConfig(prefix, mode?)`
+
+A `ConfigSpec` implementation for PostgreSQL database configuration. Use with `defineConfig`.
+
+```typescript
+import { defineConfig } from 'ezcfg';
+import { postgresConfig } from 'ezcfg/postgres';
+
+const getConfig = defineConfig({
+  db: postgresConfig('ORDER_DB'),           // reads ORDER_DB_URL
+  db2: postgresConfig('PG', 'fields'),      // reads PG_HOST, PG_PORT, etc.
+});
+
+getConfig().db.host;        // "localhost"
+getConfig().db.toString();  // "postgres://..."
+```
+
+**Parameters:**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prefix` | `string` | — | Environment variable prefix |
+| `mode` | `"url" \| "fields"` | `"url"` | `"url"` reads `{PREFIX}_URL`, `"fields"` reads individual fields |
+
+**Fields mode** reads: `{PREFIX}_HOST`, `{PREFIX}_PORT`, `{PREFIX}_DATABASE`, `{PREFIX}_USER`, `{PREFIX}_PASSWORD`
+
+### `PostgresConfig`
+
+Immutable value object representing a PostgreSQL connection configuration.
+
+```typescript
+import { PostgresConfig } from 'ezcfg/postgres';
+
+// From URL
+const config = PostgresConfig.fromUrl('postgres://user:pass@localhost:5432/mydb');
+
+// From environment variables
+const config = PostgresConfig.fromEnv('DATABASE');       // reads DATABASE_URL
+const config = PostgresConfig.fromEnv('PG', { mode: 'fields' });
+
+// Builder methods (each returns a new instance)
+config.withDatabase('other_db');
+config.withHost('remote-host');
+config.withPort(5433);
+config.withUser('admin');
+config.withPassword('secret');
+config.withPoolSize(10);
+config.withConnectionTimeout(5000);
+config.withIdleTimeout(30000);
+
+// Connection string
+config.toString();  // "postgres://user:pass@localhost:5432/mydb"
+```
+
+### Using with `fromEnvFile`
+
+`postgresConfig` works with `fromEnvFile` — the `.env` file is parsed locally without modifying `process.env`:
+
+```typescript
+import { defineConfig } from 'ezcfg';
+import { postgresConfig } from 'ezcfg/postgres';
+
+const getConfig = defineConfig(
+  { db: postgresConfig('DATABASE') },
+  { fromEnvFile: resolve(__dirname, '.env') }
+);
+
+// .env contains: DATABASE_URL=postgres://user@localhost/mydb
+const config = getConfig();
+config.db.database;  // "mydb"
+```
+
+---
+
 ## .env File Loading
 
 When `loadEnv: true` is set, ezcfg automatically loads environment files in the following order (later files override earlier ones):
@@ -241,7 +355,7 @@ When `loadEnv: true` is set, ezcfg automatically loads environment files in the
 When validation fails, ezcfg throws a `ConfigValidationError` with all errors collected:
 
 ```typescript
-import { defineConfig, env, ConfigValidationError } from 'ezcfg';
+import { defineConfig, env, envNumber, ConfigValidationError } from 'ezcfg';
 
 const getConfig = defineConfig({
   apiKey: env('API_KEY'),
@@ -297,7 +411,7 @@ const config = getConfig();
 You can also extract the config type for use elsewhere:
 
 ```typescript
-import { defineConfig, env, type InferConfigType } from 'ezcfg';
+import { defineConfig, env, envNumber, type InferConfigType } from 'ezcfg';
 
 const schema = {
   apiKey: env('API_KEY'),
@@ -315,75 +429,30 @@ function initializeApp(config: AppConfig) {
 }
 ```
 
-## Examples
-
-### Database Configuration
-
-```typescript
-import { defineConfig, env, envNumber, envOptional } from 'ezcfg';
-
-export const getDbConfig = defineConfig({
-  host: env('DB_HOST'),
-  port: envNumber('DB_PORT'),
-  database: env('DB_NAME'),
-  user: env('DB_USER'),
-  password: envOptional('DB_PASSWORD'),
-}, { loadEnv: true });
-
-// Usage
-const db = getDbConfig();
-const connectionString = `postgres://${db.user}:${db.password}@${db.host}:${db.port}/${db.database}`;
-```
+## Custom ConfigSpec
 
-### API Service Configuration
+Implement the `ConfigSpec` interface to create your own config types:
 
 ```typescript
-import { defineConfig, env, envNumber, envBoolean, envJsonOptional } from 'ezcfg';
-
-export const getConfig = defineConfig({
-  // Server
-  port: envNumber('PORT'),
-  host: envOptional('HOST', '0.0.0.0'),
-
-  // API Keys
-  apiKey: env('API_KEY'),
-  secretKey: env('SECRET_KEY'),
-
-  // Features
-  debug: envBoolean('DEBUG', false),
-  enableMetrics: envBoolean('ENABLE_METRICS', true),
+import type { ConfigSpec } from 'ezcfg';
 
-  // CORS
-  allowedOrigins: envJsonOptional<string[]>('ALLOWED_ORIGINS', ['http://localhost:3000']),
-}, { loadEnv: true });
-```
+class RedisConfigSpec implements ConfigSpec<RedisConfig> {
+  readonly _type = 'redis';
 
-### Multi-environment Setup
+  constructor(private readonly prefix: string) {}
 
-```
-project/
-├── .env                 # Shared defaults
-├── .env.local           # Local secrets (gitignored)
-├── .env.development     # Development settings
-├── .env.production      # Production settings
-└── .env.test            # Test settings
-```
+  resolve(errors: string[], envSource?: Record<string, string>): RedisConfig | undefined {
+    const source = envSource ?? process.env;
+    const url = source[`${this.prefix}_URL`];
 
-```bash
-# .env
-LOG_LEVEL=info
-API_TIMEOUT=5000
+    if (!url) {
+      errors.push(`Missing ${this.prefix}_URL`);
+      return undefined;
+    }
 
-# .env.development
-DEBUG=true
-API_URL=http://localhost:3000
-
-# .env.production
-DEBUG=false
-API_URL=https://api.example.com
-
-# .env.local (gitignored)
-API_KEY=your-secret-key
+    return new RedisConfig(url);
+  }
+}
 ```
 
 ## License

package/dist/computed-spec.d.ts

@@ -0,0 +1,9 @@
+import type { ConfigSpec } from "./config-spec.js";
+export declare class ComputedSpec<T> implements ConfigSpec<T> {
+    private readonly factory;
+    readonly _type = "computed";
+    constructor(factory: () => T);
+    resolve(errors: string[], _envSource?: Record<string, string>): T | undefined;
+}
+export declare function computed<T>(factory: () => T): ComputedSpec<T>;
+//# sourceMappingURL=computed-spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"computed-spec.d.ts","sourceRoot":"","sources":["../src/computed-spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,qBAAa,YAAY,CAAC,CAAC,CAAE,YAAW,UAAU,CAAC,CAAC,CAAC;IAGrC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,QAAQ,CAAC,KAAK,cAAc;IAE5B,YAA6B,OAAO,EAAE,MAAM,CAAC,EAAI;IAEjD,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAO5E;CACJ;AAED,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAE7D"}

package/dist/computed-spec.js

@@ -0,0 +1,20 @@
+export class ComputedSpec {
+    factory;
+    _type = "computed";
+    constructor(factory) {
+        this.factory = factory;
+    }
+    resolve(errors, _envSource) {
+        try {
+            return this.factory();
+        }
+        catch (e) {
+            errors.push(`Computed value failed: ${e.message}`);
+            return undefined;
+        }
+    }
+}
+export function computed(factory) {
+    return new ComputedSpec(factory);
+}
+//# sourceMappingURL=computed-spec.js.map

package/dist/computed-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"computed-spec.js","sourceRoot":"","sources":["../src/computed-spec.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,YAAY;IAGQ,OAAO;IAF3B,KAAK,GAAG,UAAU,CAAC;IAE5B,YAA6B,OAAgB,EAAE;uBAAlB,OAAO;IAAY,CAAC;IAEjD,OAAO,CAAC,MAAgB,EAAE,UAAmC,EAAiB;QAC1E,IAAI,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,MAAM,CAAC,IAAI,CAAC,0BAA2B,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;YAC9D,OAAO,SAAS,CAAC;QACrB,CAAC;IAAA,CACJ;CACJ;AAED,MAAM,UAAU,QAAQ,CAAI,OAAgB,EAAmB;IAC3D,OAAO,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC;AAAA,CACpC"}

package/dist/config-spec.d.ts

@@ -0,0 +1,10 @@
+export interface ConfigSpec<T> {
+    readonly _type: string;
+    resolve(errors: string[], envSource?: Record<string, string>): T | undefined;
+}
+export type InferSpecType<S> = S extends ConfigSpec<infer T> ? T : S;
+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-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-spec.d.ts","sourceRoot":"","sources":["../src/config-spec.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;CAChF;AAED,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAErE,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;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,OAAO,CAAC,CAOzE"}

package/dist/config-spec.js

@@ -0,0 +1,7 @@
+export function isConfigSpec(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "resolve" in value &&
+        typeof value.resolve === "function");
+}
+//# sourceMappingURL=config-spec.js.map

package/dist/config-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-spec.js","sourceRoot":"","sources":["../src/config-spec.ts"],"names":[],"mappings":"AAWA,MAAM,UAAU,YAAY,CAAC,KAAc,EAAgC;IACvE,OAAO,CACH,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,SAAS,IAAI,KAAK;QAClB,OAAQ,KAA6B,CAAC,OAAO,KAAK,UAAU,CAC/D,CAAC;AAAA,CACL"}

package/dist/database-config.d.ts

@@ -0,0 +1,9 @@
+export interface DatabaseConfig {
+    readonly host: string;
+    readonly port: number;
+    readonly database: string;
+    readonly user: string;
+    readonly password?: string;
+    toString(): string;
+}
+//# sourceMappingURL=database-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"database-config.d.ts","sourceRoot":"","sources":["../src/database-config.ts"],"names":[],"mappings":"AAAA,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;IAC3B,QAAQ,IAAI,MAAM,CAAC;CACtB"}

package/dist/database-config.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=database-config.js.map

package/dist/database-config.js.map

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

package/dist/define-config.d.ts

@@ -0,0 +1,9 @@
+import { type InferConfigType } from "./config-spec.js";
+export interface ConfigOptions {
+    loadEnv?: boolean;
+    envLoader?: () => void;
+    fromEnvFile?: string;
+}
+export declare function defineConfig<S extends Record<string, unknown>>(schema: S, options?: ConfigOptions): () => InferConfigType<S>;
+export declare function parseEnvFile(filePath: string): Record<string, string>;
+//# sourceMappingURL=define-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.d.ts","sourceRoot":"","sources":["../src/define-config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,eAAe,EAAgB,MAAM,kBAAkB,CAAC;AAItE,MAAM,WAAW,aAAa;IAC1B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,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,CAsC1B;AAED,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAGrE"}

package/dist/define-config.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import dotenv from "dotenv";
+import { isConfigSpec } from "./config-spec.js";
+import { ConfigValidationError } from "./errors.js";
+import { loadEnvFiles } from "./load-env-files.js";
+export function defineConfig(schema, options) {
+    let instance = null;
+    return () => {
+        if (instance && process.env.NODE_ENV !== "test") {
+            return instance;
+        }
+        let envSource;
+        if (options?.fromEnvFile) {
+            envSource = parseEnvFile(options.fromEnvFile);
+        }
+        else if (options?.loadEnv) {
+            if (options.envLoader) {
+                options.envLoader();
+            }
+            else {
+                loadEnvFiles();
+            }
+        }
+        const config = {};
+        const errors = [];
+        for (const [key, value] of Object.entries(schema)) {
+            if (isConfigSpec(value)) {
+                config[key] = value.resolve(errors, envSource);
+            }
+            else {
+                config[key] = value;
+            }
+        }
+        if (errors.length > 0) {
+            throw new ConfigValidationError(errors);
+        }
+        instance = config;
+        return instance;
+    };
+}
+export function parseEnvFile(filePath) {
+    const content = fs.readFileSync(filePath, "utf-8");
+    return dotenv.parse(content);
+}
+//# sourceMappingURL=define-config.js.map

package/dist/define-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-config.js","sourceRoot":"","sources":["../src/define-config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAwB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAQnD,MAAM,UAAU,YAAY,CACxB,MAAS,EACT,OAAuB,EACC;IACxB,IAAI,QAAQ,GAA8B,IAAI,CAAC;IAE/C,OAAO,GAAG,EAAE,CAAC;QACT,IAAI,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,EAAE,CAAC;YAC9C,OAAO,QAAQ,CAAC;QACpB,CAAC;QAED,IAAI,SAA6C,CAAC;QAElD,IAAI,OAAO,EAAE,WAAW,EAAE,CAAC;YACvB,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAClD,CAAC;aAAM,IAAI,OAAO,EAAE,OAAO,EAAE,CAAC;YAC1B,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;gBACpB,OAAO,CAAC,SAAS,EAAE,CAAC;YACxB,CAAC;iBAAM,CAAC;gBACJ,YAAY,EAAE,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,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;gBACtB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACnD,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,qBAAqB,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;QAED,QAAQ,GAAG,MAA4B,CAAC;QACxC,OAAO,QAAQ,CAAC;IAAA,CACnB,CAAC;AAAA,CACL;AAED,MAAM,UAAU,YAAY,CAAC,QAAgB,EAA0B;IACnE,MAAM,OAAO,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACnD,OAAO,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAAA,CAChC"}

package/dist/env-spec.d.ts

@@ -0,0 +1,18 @@
+import type { ConfigSpec } from "./config-spec.js";
+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[], envSource?: Record<string, string>): T | undefined;
+}
+export declare function env(key: string): EnvSpec<string>;
+export declare function envOptional(key: string, defaultValue?: string): EnvSpec<string | undefined>;
+export declare function envNumber(key: string): EnvSpec<number>;
+export declare function envNumberOptional(key: string, defaultValue?: number): EnvSpec<number | undefined>;
+export declare function envBoolean(key: string, defaultValue?: boolean): EnvSpec<boolean>;
+export declare function envJson<T>(key: string): EnvSpec<T>;
+export declare function envJsonOptional<T>(key: string, defaultValue?: T): EnvSpec<T | undefined>;
+//# sourceMappingURL=env-spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env-spec.d.ts","sourceRoot":"","sources":["../src/env-spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,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;IAEvB,YACqB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,OAAO,EACjB,YAAY,CAAC,eAAG,EAChB,SAAS,CAAC,oCAAsB,EACjD;IAEJ,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAkB3E;CACJ;AAED,wBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEhD;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE3F;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAEjG;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAE9E;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAElD;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAExF"}

package/dist/env-spec.js

@@ -0,0 +1,52 @@
+export 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, envSource) {
+        const rawValue = (envSource ?? 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;
+    }
+}
+export function env(key) {
+    return new EnvSpec(key, true);
+}
+export function envOptional(key, defaultValue) {
+    return new EnvSpec(key, false, defaultValue);
+}
+export function envNumber(key) {
+    return new EnvSpec(key, true, undefined, Number);
+}
+export function envNumberOptional(key, defaultValue) {
+    return new EnvSpec(key, false, defaultValue, (v) => (v ? Number(v) : undefined));
+}
+export function envBoolean(key, defaultValue = false) {
+    return new EnvSpec(key, false, defaultValue, (v) => v === "true" || v === "1");
+}
+export function envJson(key) {
+    return new EnvSpec(key, true, undefined, JSON.parse);
+}
+export function envJsonOptional(key, defaultValue) {
+    return new EnvSpec(key, false, defaultValue, (v) => (v ? JSON.parse(v) : undefined));
+}
+//# sourceMappingURL=env-spec.js.map

package/dist/env-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-spec.js","sourceRoot":"","sources":["../src/env-spec.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,OAAO;IAIK,MAAM;IACN,QAAQ;IACR,YAAY;IACZ,SAAS;IANrB,KAAK,GAAG,KAAK,CAAC;IAEvB,YACqB,MAAc,EACd,QAAiB,EACjB,YAAgB,EAChB,SAAgC,EACnD;sBAJmB,MAAM;wBACN,QAAQ;4BACR,YAAY;yBACZ,SAAS;IAC3B,CAAC;IAEJ,OAAO,CAAC,MAAgB,EAAE,SAAkC,EAAiB;QACzE,MAAM,QAAQ,GAAG,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEzD,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC7B,MAAM,CAAC,IAAI,CAAC,yBAAyB,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;YACpD,OAAO,SAAS,CAAC;QACrB,CAAC;QAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC;gBACD,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAE,QAAc,CAAC;YACvE,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACT,MAAM,CAAC,IAAI,CAAC,uBAAuB,IAAI,CAAC,MAAM,KAAM,CAAW,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC3E,OAAO,SAAS,CAAC;YACrB,CAAC;QACL,CAAC;QAED,OAAO,IAAI,CAAC,YAAY,CAAC;IAAA,CAC5B;CACJ;AAED,MAAM,UAAU,GAAG,CAAC,GAAW,EAAmB;IAC9C,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;AAAA,CACjC;AAED,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,YAAqB,EAA+B;IACzF,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;AAAA,CAChD;AAED,MAAM,UAAU,SAAS,CAAC,GAAW,EAAmB;IACpD,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAAA,CACpD;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,YAAqB,EAA+B;IAC/F,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAAA,CACpF;AAED,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,YAAY,GAAG,KAAK,EAAoB;IAC5E,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;AAAA,CAClF;AAED,MAAM,UAAU,OAAO,CAAI,GAAW,EAAc;IAChD,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;AAAA,CACxD;AAED,MAAM,UAAU,eAAe,CAAI,GAAW,EAAE,YAAgB,EAA0B;IACtF,OAAO,IAAI,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;AAAA,CACxF"}

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class ConfigValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,qBAAsB,SAAQ,KAAK;aAChB,MAAM,EAAE,MAAM,EAAE;IAA5C,YAA4B,MAAM,EAAE,MAAM,EAAE,EAG3C;CACJ"}

package/dist/errors.js

@@ -0,0 +1,9 @@
+export class ConfigValidationError extends Error {
+    errors;
+    constructor(errors) {
+        super(`Config validation failed:\n  - ${errors.join("\n  - ")}`);
+        this.errors = errors;
+        this.name = "ConfigValidationError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAChB,MAAM;IAAlC,YAA4B,MAAgB,EAAE;QAC1C,KAAK,CAAC,kCAAkC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;sBADzC,MAAM;QAE9B,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IAAA,CACvC;CACJ"}

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,YAAY,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EACH,OAAO,EACP,GAAG,EACH,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,OAAO,EACP,eAAe,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE5D,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { isConfigSpec, } from "./config-spec.js";
+export { ConfigValidationError } from "./errors.js";
+export { defineConfig, parseEnvFile } from "./define-config.js";
+export { loadEnvFiles } from "./load-env-files.js";
+export { EnvSpec, env, envOptional, envNumber, envNumberOptional, envBoolean, envJson, envJsonOptional, } from "./env-spec.js";
+export { ComputedSpec, computed } from "./computed-spec.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIH,YAAY,GACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEpD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAsB,MAAM,oBAAoB,CAAC;AACpF,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EACH,OAAO,EACP,GAAG,EACH,WAAW,EACX,SAAS,EACT,iBAAiB,EACjB,UAAU,EACV,OAAO,EACP,eAAe,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/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/load-env-files.d.ts.map

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

package/dist/load-env-files.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+export function loadEnvFiles({ basePath, nodeEnv, } = {}) {
+    const basePath_ = basePath ?? process.cwd();
+    const nodeEnv_ = nodeEnv ?? process.env.NODE_ENV ?? "development";
+    const envFiles = [
+        ".env",
+        ".env.local",
+        `.env.${nodeEnv_}`,
+        `.env.${nodeEnv_}.local`,
+    ];
+    const loadEnvFile = (filePath) => {
+        if (fs.existsSync(filePath)) {
+            dotenv.config({ path: filePath });
+        }
+    };
+    envFiles.reverse().forEach((file) => {
+        const filePath = path.resolve(basePath_, file);
+        loadEnvFile(filePath);
+    });
+}
+//# sourceMappingURL=load-env-files.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load-env-files.js","sourceRoot":"","sources":["../src/load-env-files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,MAAM,UAAU,YAAY,CAAC,EACzB,QAAQ,EACR,OAAO,GACV,GAGG,EAAE,EAAQ;IACV,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,MAAM,QAAQ,GAAG;QACb,MAAM;QACN,YAAY;QACZ,QAAQ,QAAQ,EAAE;QAClB,QAAQ,QAAQ,QAAQ;KAC3B,CAAC;IAEF,MAAM,WAAW,GAAG,CAAC,QAAgB,EAAE,EAAE,CAAC;QACtC,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QACtC,CAAC;IAAA,CACJ,CAAC;IAEF,QAAQ,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC/C,WAAW,CAAC,QAAQ,CAAC,CAAC;IAAA,CACzB,CAAC,CAAC;AAAA,CACN"}

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

@@ -0,0 +1,31 @@
+import type { ConfigSpec } from "./config-spec.js";
+import { PostgresConfig, type FromEnvOptions } from "./postgres-config.js";
+export declare class PostgresConfigSpec implements ConfigSpec<PostgresConfig> {
+    private readonly prefix;
+    private readonly mode;
+    readonly _type = "postgres";
+    constructor(prefix: string, mode?: FromEnvOptions["mode"]);
+    resolve(errors: string[], envSource?: Record<string, string>): PostgresConfig | undefined;
+}
+/**
+ * PostgreSQL database configuration from environment variables.
+ * Returns a PostgresConfig instance.
+ *
+ * @param prefix - Environment variable prefix
+ * @param mode - "url" reads {PREFIX}_URL, "fields" reads individual fields
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig, postgresConfig } from "ezcfg";
+ *
+ * const getConfig = defineConfig({
+ *     db: postgresConfig("ORDER_DB"),           // reads ORDER_DB_URL
+ *     db2: postgresConfig("PG", "fields"),      // reads PG_HOST, PG_PORT, etc.
+ * });
+ *
+ * getConfig().db.host;        // "localhost"
+ * getConfig().db.toString();  // "postgres://..."
+ * ```
+ */
+export declare function postgresConfig(prefix: string, mode?: FromEnvOptions["mode"]): PostgresConfigSpec;
+//# sourceMappingURL=postgres-config-spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-config-spec.d.ts","sourceRoot":"","sources":["../src/postgres-config-spec.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3E,qBAAa,kBAAmB,YAAW,UAAU,CAAC,cAAc,CAAC;IAI7D,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJzB,QAAQ,CAAC,KAAK,cAAc;IAE5B,YACqB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,cAAc,CAAC,MAAM,CAAS,EACrD;IAEJ,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,cAAc,GAAG,SAAS,CAOxF;CACJ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAC1B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,cAAc,CAAC,MAAM,CAAS,GACrC,kBAAkB,CAEpB"}

package/dist/postgres-config-spec.js

@@ -0,0 +1,43 @@
+import { PostgresConfig } from "./postgres-config.js";
+export class PostgresConfigSpec {
+    prefix;
+    mode;
+    _type = "postgres";
+    constructor(prefix, mode = "url") {
+        this.prefix = prefix;
+        this.mode = mode;
+    }
+    resolve(errors, envSource) {
+        try {
+            return PostgresConfig.fromEnv(this.prefix, { mode: this.mode }, envSource);
+        }
+        catch (e) {
+            errors.push(e.message);
+            return undefined;
+        }
+    }
+}
+/**
+ * PostgreSQL database configuration from environment variables.
+ * Returns a PostgresConfig instance.
+ *
+ * @param prefix - Environment variable prefix
+ * @param mode - "url" reads {PREFIX}_URL, "fields" reads individual fields
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig, postgresConfig } from "ezcfg";
+ *
+ * const getConfig = defineConfig({
+ *     db: postgresConfig("ORDER_DB"),           // reads ORDER_DB_URL
+ *     db2: postgresConfig("PG", "fields"),      // reads PG_HOST, PG_PORT, etc.
+ * });
+ *
+ * getConfig().db.host;        // "localhost"
+ * getConfig().db.toString();  // "postgres://..."
+ * ```
+ */
+export function postgresConfig(prefix, mode = "url") {
+    return new PostgresConfigSpec(prefix, mode);
+}
+//# sourceMappingURL=postgres-config-spec.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-config-spec.js","sourceRoot":"","sources":["../src/postgres-config-spec.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAuB,MAAM,sBAAsB,CAAC;AAE3E,MAAM,OAAO,kBAAkB;IAIN,MAAM;IACN,IAAI;IAJhB,KAAK,GAAG,UAAU,CAAC;IAE5B,YACqB,MAAc,EACd,IAAI,GAA2B,KAAK,EACvD;sBAFmB,MAAM;oBACN,IAAI;IACtB,CAAC;IAEJ,OAAO,CAAC,MAAgB,EAAE,SAAkC,EAA8B;QACtF,IAAI,CAAC;YACD,OAAO,cAAc,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,SAAS,CAAC,CAAC;QAC/E,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACT,MAAM,CAAC,IAAI,CAAE,CAAW,CAAC,OAAO,CAAC,CAAC;YAClC,OAAO,SAAS,CAAC;QACrB,CAAC;IAAA,CACJ;CACJ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAC1B,MAAc,EACd,IAAI,GAA2B,KAAK,EAClB;IAClB,OAAO,IAAI,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;AAAA,CAC/C"}

package/dist/postgres-config.d.ts

@@ -0,0 +1,43 @@
+import type { DatabaseConfig } from "./database-config.js";
+export interface PoolOptions {
+    size?: number;
+    connectionTimeout?: number;
+    idleTimeout?: number;
+}
+export interface FromEnvOptions {
+    /**
+     * Environment variable loading mode.
+     * - "url": Load from {PREFIX}_URL (default)
+     * - "fields": Load from {PREFIX}_HOST, {PREFIX}_PORT, {PREFIX}_DATABASE, {PREFIX}_USER, {PREFIX}_PASSWORD
+     */
+    mode?: "url" | "fields";
+}
+export declare class PostgresConfig implements DatabaseConfig {
+    readonly host: string;
+    readonly database: string;
+    readonly user: string;
+    readonly port: number;
+    readonly password?: string;
+    readonly pool?: PoolOptions;
+    constructor(config: {
+        database: string;
+        user?: string;
+        host?: string;
+        port?: number;
+        password?: string;
+        pool?: PoolOptions;
+    });
+    static fromUrl(value: string): PostgresConfig;
+    static fromEnv(prefix: string, options?: FromEnvOptions, envSource?: Record<string, string>): PostgresConfig;
+    private static parseUrl;
+    withDatabase(database: string): PostgresConfig;
+    withUser(user: string): PostgresConfig;
+    withPassword(password: string): PostgresConfig;
+    withHost(host: string): PostgresConfig;
+    withPort(port: number): PostgresConfig;
+    withPoolSize(size: number): PostgresConfig;
+    withConnectionTimeout(connectionTimeout: number): PostgresConfig;
+    withIdleTimeout(idleTimeout: number): PostgresConfig;
+    toString(): string;
+}
+//# sourceMappingURL=postgres-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-config.d.ts","sourceRoot":"","sources":["../src/postgres-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,MAAM,WAAW,WAAW;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC3B;;;;OAIG;IACH,IAAI,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAC;CAC3B;AAED,qBAAa,cAAe,YAAW,cAAc;IACjD,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,QAAQ,EAAE,MAAM,CAAC;IACjC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClC,SAAgB,IAAI,CAAC,EAAE,WAAW,CAAC;IAEnC,YAAY,MAAM,EAAE;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,WAAW,CAAC;KACtB,EAOA;IAED,OAAc,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAEnD;IAED,OAAc,OAAO,CACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,cAAc,EACxB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACnC,cAAc,CAgChB;IAED,OAAO,CAAC,MAAM,CAAC,QAAQ;IAqBhB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CASpD;IAEM,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAS5C;IAEM,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CASpD;IAEM,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAS5C;IAEM,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAS5C;IAEM,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAShD;IAEM,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG,cAAc,CAStE;IAEM,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,cAAc,CAS1D;IAEM,QAAQ,IAAI,MAAM,CA0BxB;CACJ"}

package/dist/postgres-config.js

@@ -0,0 +1,162 @@
+export class PostgresConfig {
+    host;
+    database;
+    user;
+    port;
+    password;
+    pool;
+    constructor(config) {
+        this.database = config.database;
+        this.password = config.password;
+        this.host = config.host ?? "localhost";
+        this.user = config.user ?? "postgres";
+        this.port = config.port ?? 5432;
+        this.pool = config.pool;
+    }
+    static fromUrl(value) {
+        return new PostgresConfig(PostgresConfig.parseUrl(value));
+    }
+    static fromEnv(prefix, options, envSource) {
+        const source = envSource ?? process.env;
+        const mode = options?.mode ?? "url";
+        if (mode === "url") {
+            const envKey = `${prefix}_URL`;
+            const url = source[envKey];
+            if (!url) {
+                throw new Error(`Environment variable ${envKey} is not set`);
+            }
+            return PostgresConfig.fromUrl(url);
+        }
+        // fields mode
+        const database = source[`${prefix}_DATABASE`];
+        if (!database) {
+            throw new Error(`Environment variable ${prefix}_DATABASE is not set`);
+        }
+        return new PostgresConfig({
+            database,
+            host: source[`${prefix}_HOST`],
+            port: source[`${prefix}_PORT`]
+                ? parseInt(source[`${prefix}_PORT`])
+                : undefined,
+            user: source[`${prefix}_USER`],
+            password: source[`${prefix}_PASSWORD`],
+        });
+    }
+    static parseUrl(value) {
+        const regex = /postgres(ql)?:\/\/(?<user>[^:/]+)(:(?<password>[^@]+))?@(?<host>[^:/]+)(:(?<port>\d+))?\/(?<database>.+)/;
+        const matches = value.match(regex);
+        if (!matches?.groups) {
+            throw new Error(`Invalid postgres url: ${value}`);
+        }
+        const { user, password, host, port, database } = matches.groups;
+        return {
+            host,
+            database,
+            user,
+            port: port ? parseInt(port) : 5432,
+            password,
+        };
+    }
+    withDatabase(database) {
+        return new PostgresConfig({
+            host: this.host,
+            database,
+            user: this.user,
+            port: this.port,
+            password: this.password,
+            pool: this.pool,
+        });
+    }
+    withUser(user) {
+        return new PostgresConfig({
+            host: this.host,
+            database: this.database,
+            user,
+            port: this.port,
+            password: this.password,
+            pool: this.pool,
+        });
+    }
+    withPassword(password) {
+        return new PostgresConfig({
+            host: this.host,
+            database: this.database,
+            user: this.user,
+            port: this.port,
+            password,
+            pool: this.pool,
+        });
+    }
+    withHost(host) {
+        return new PostgresConfig({
+            host,
+            database: this.database,
+            user: this.user,
+            port: this.port,
+            password: this.password,
+            pool: this.pool,
+        });
+    }
+    withPort(port) {
+        return new PostgresConfig({
+            host: this.host,
+            database: this.database,
+            user: this.user,
+            port,
+            password: this.password,
+            pool: this.pool,
+        });
+    }
+    withPoolSize(size) {
+        return new PostgresConfig({
+            host: this.host,
+            database: this.database,
+            user: this.user,
+            port: this.port,
+            password: this.password,
+            pool: { ...this.pool, size },
+        });
+    }
+    withConnectionTimeout(connectionTimeout) {
+        return new PostgresConfig({
+            host: this.host,
+            database: this.database,
+            user: this.user,
+            port: this.port,
+            password: this.password,
+            pool: { ...this.pool, connectionTimeout },
+        });
+    }
+    withIdleTimeout(idleTimeout) {
+        return new PostgresConfig({
+            host: this.host,
+            database: this.database,
+            user: this.user,
+            port: this.port,
+            password: this.password,
+            pool: { ...this.pool, idleTimeout },
+        });
+    }
+    toString() {
+        let url = `postgres://${this.user}`;
+        if (this.password) {
+            url += `:${this.password}`;
+        }
+        url += `@${this.host}:${this.port}/${this.database}`;
+        const queryParams = [];
+        if (this.pool?.size !== undefined) {
+            queryParams.push(`pool_size=${this.pool.size}`);
+        }
+        if (this.pool?.connectionTimeout !== undefined) {
+            queryParams.push(`connection_timeout=${this.pool.connectionTimeout}`);
+        }
+        if (this.pool?.idleTimeout !== undefined) {
+            queryParams.push(`idle_timeout=${this.pool.idleTimeout}`);
+        }
+        if (queryParams.length > 0) {
+            url += `?${queryParams.join("&")}`;
+        }
+        return url;
+    }
+}
+//# sourceMappingURL=postgres-config.js.map

package/dist/postgres-config.js.map

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

package/dist/postgres.d.ts

@@ -0,0 +1,3 @@
+export { PostgresConfig, type PoolOptions, type FromEnvOptions, } from "./postgres-config.js";
+export { PostgresConfigSpec, postgresConfig } from "./postgres-config-spec.js";
+//# sourceMappingURL=postgres.d.ts.map

package/dist/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,cAAc,EACd,KAAK,WAAW,EAChB,KAAK,cAAc,GACtB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/postgres.js

@@ -0,0 +1,3 @@
+export { PostgresConfig, } from "./postgres-config.js";
+export { PostgresConfigSpec, postgresConfig } from "./postgres-config-spec.js";
+//# sourceMappingURL=postgres.js.map

package/dist/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../src/postgres.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,cAAc,GAGjB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC"}

package/package.json

@@ -1,43 +1,44 @@
 {
-    "name": "ezcfg",
-    "version": "0.2.0",
-    "description": "Lite and easy configuration management for Node.js",
-    "license": "MIT",
-    "author": "Sangwoo Hyun <wkdny.hyun@gmail.com>",
-    "main": "./dist/index.js",
-    "module": "./dist/index.mjs",
-    "types": "./dist/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.mjs",
-            "require": "./dist/index.js"
-        }
+  "name": "ezcfg",
+  "version": "0.3.1",
+  "type": "module",
+  "description": "Lite and easy configuration management for Node.js",
+  "license": "MIT",
+  "author": "Sangwoo Hyun <wkdny.hyun@gmail.com>",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
     },
-    "files": [
-        "dist",
-        "LICENSE"
-    ],
-    "scripts": {
-        "build": "tsup",
-        "test": "vitest run",
-        "test:watch": "vitest"
-    },
-    "dependencies": {
-        "dotenv": "^17.2.3"
-    },
-    "devDependencies": {
-        "@types/node": "^25.1.0",
-        "tsup": "^8.5.1",
-        "typescript": "^5.9.3",
-        "vitest": "^4.0.18"
-    },
-    "keywords": [
-        "config",
-        "configuration",
-        "env",
-        "environment",
-        "typescript",
-        "type-safe"
-    ]
-}
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "dotenv": "^17.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "@typescript/native-preview": "^7.0.0-dev",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "keywords": [
+    "config",
+    "configuration",
+    "env",
+    "environment",
+    "typescript",
+    "type-safe"
+  ],
+  "scripts": {
+    "build": "tsgo -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}