ezcfg 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,53 @@
+interface ConfigSpec<T> {
+    readonly _type: string;
+    resolve(errors: string[]): T | undefined;
+}
+type InferSpecType<S> = S extends ConfigSpec<infer T> ? T : S;
+type InferConfigType<S extends Record<string, unknown>> = {
+    readonly [K in keyof S]: InferSpecType<S[K]>;
+};
+declare function isConfigSpec(value: unknown): value is ConfigSpec<unknown>;
+
+declare class ConfigValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+
+interface ConfigOptions {
+    loadEnv?: boolean;
+    envLoader?: () => void;
+}
+declare function defineConfig<S extends Record<string, unknown>>(schema: S, options?: ConfigOptions): () => InferConfigType<S>;
+
+declare function loadEnvFiles({ basePath, nodeEnv, }?: {
+    basePath?: string;
+    nodeEnv?: string;
+}): void;
+
+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;
+}
+declare function env(key: string): EnvSpec<string>;
+declare function envOptional(key: string, defaultValue?: string): EnvSpec<string | undefined>;
+declare function envNumber(key: string): EnvSpec<number>;
+declare function envNumberOptional(key: string, defaultValue?: number): EnvSpec<number | undefined>;
+declare function envBoolean(key: string, defaultValue?: boolean): EnvSpec<boolean>;
+declare function envJson<T>(key: string): EnvSpec<T>;
+declare function envJsonOptional<T>(key: string, defaultValue?: T): EnvSpec<T | undefined>;
+
+interface DatabaseConfig {
+    readonly host: string;
+    readonly port: number;
+    readonly database: string;
+    readonly user: string;
+    readonly password?: string;
+    toString(): string;
+}
+
+export { type ConfigOptions, type ConfigSpec, ConfigValidationError, type DatabaseConfig, EnvSpec, type InferConfigType, type InferSpecType, defineConfig, env, envBoolean, envJson, envJsonOptional, envNumber, envNumberOptional, envOptional, isConfigSpec, loadEnvFiles };

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+interface ConfigSpec<T> {
+    readonly _type: string;
+    resolve(errors: string[]): T | undefined;
+}
+type InferSpecType<S> = S extends ConfigSpec<infer T> ? T : S;
+type InferConfigType<S extends Record<string, unknown>> = {
+    readonly [K in keyof S]: InferSpecType<S[K]>;
+};
+declare function isConfigSpec(value: unknown): value is ConfigSpec<unknown>;
+
+declare class ConfigValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+
+interface ConfigOptions {
+    loadEnv?: boolean;
+    envLoader?: () => void;
+}
+declare function defineConfig<S extends Record<string, unknown>>(schema: S, options?: ConfigOptions): () => InferConfigType<S>;
+
+declare function loadEnvFiles({ basePath, nodeEnv, }?: {
+    basePath?: string;
+    nodeEnv?: string;
+}): void;
+
+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;
+}
+declare function env(key: string): EnvSpec<string>;
+declare function envOptional(key: string, defaultValue?: string): EnvSpec<string | undefined>;
+declare function envNumber(key: string): EnvSpec<number>;
+declare function envNumberOptional(key: string, defaultValue?: number): EnvSpec<number | undefined>;
+declare function envBoolean(key: string, defaultValue?: boolean): EnvSpec<boolean>;
+declare function envJson<T>(key: string): EnvSpec<T>;
+declare function envJsonOptional<T>(key: string, defaultValue?: T): EnvSpec<T | undefined>;
+
+interface DatabaseConfig {
+    readonly host: string;
+    readonly port: number;
+    readonly database: string;
+    readonly user: string;
+    readonly password?: string;
+    toString(): string;
+}
+
+export { type ConfigOptions, type ConfigSpec, ConfigValidationError, type DatabaseConfig, EnvSpec, type InferConfigType, type InferSpecType, defineConfig, env, envBoolean, envJson, envJsonOptional, envNumber, envNumberOptional, envOptional, isConfigSpec, loadEnvFiles };

package/dist/index.js

@@ -0,0 +1,183 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ConfigValidationError: () => ConfigValidationError,
+  EnvSpec: () => EnvSpec,
+  defineConfig: () => defineConfig,
+  env: () => env,
+  envBoolean: () => envBoolean,
+  envJson: () => envJson,
+  envJsonOptional: () => envJsonOptional,
+  envNumber: () => envNumber,
+  envNumberOptional: () => envNumberOptional,
+  envOptional: () => envOptional,
+  isConfigSpec: () => isConfigSpec,
+  loadEnvFiles: () => loadEnvFiles
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/config-spec.ts
+function isConfigSpec(value) {
+  return typeof value === "object" && value !== null && "resolve" in value && typeof value.resolve === "function";
+}
+
+// src/errors.ts
+var ConfigValidationError = class extends Error {
+  constructor(errors) {
+    super(`Config validation failed:
+  - ${errors.join("\n  - ")}`);
+    this.errors = errors;
+    this.name = "ConfigValidationError";
+  }
+};
+
+// src/load-env-files.ts
+var import_node_fs = __toESM(require("fs"));
+var import_node_path = __toESM(require("path"));
+var import_dotenv = __toESM(require("dotenv"));
+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 (import_node_fs.default.existsSync(filePath)) {
+      import_dotenv.default.config({ path: filePath });
+    }
+  };
+  envFiles.reverse().forEach((file) => {
+    const filePath = import_node_path.default.resolve(basePath_, file);
+    loadEnvFile(filePath);
+  });
+}
+
+// src/define-config.ts
+function defineConfig(schema, options) {
+  let instance = null;
+  return () => {
+    if (instance && process.env.NODE_ENV !== "test") {
+      return instance;
+    }
+    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);
+      } else {
+        config[key] = value;
+      }
+    }
+    if (errors.length > 0) {
+      throw new ConfigValidationError(errors);
+    }
+    instance = config;
+    return instance;
+  };
+}
+
+// src/env-spec.ts
+var EnvSpec = class {
+  constructor(envKey, required, defaultValue, transform) {
+    this.envKey = envKey;
+    this.required = required;
+    this.defaultValue = defaultValue;
+    this.transform = transform;
+  }
+  _type = "env";
+  resolve(errors) {
+    const rawValue = process.env[this.envKey];
+    if (!rawValue && this.required) {
+      errors.push(`Missing required env: ${this.envKey}`);
+      return void 0;
+    }
+    if (rawValue !== void 0) {
+      try {
+        return this.transform ? this.transform(rawValue) : rawValue;
+      } catch (e) {
+        errors.push(`Failed to transform ${this.envKey}: ${e.message}`);
+        return void 0;
+      }
+    }
+    return this.defaultValue;
+  }
+};
+function env(key) {
+  return new EnvSpec(key, true);
+}
+function envOptional(key, defaultValue) {
+  return new EnvSpec(key, false, defaultValue);
+}
+function envNumber(key) {
+  return new EnvSpec(key, true, void 0, Number);
+}
+function envNumberOptional(key, defaultValue) {
+  return new EnvSpec(key, false, defaultValue, (v) => v ? Number(v) : void 0);
+}
+function envBoolean(key, defaultValue = false) {
+  return new EnvSpec(key, false, defaultValue, (v) => v === "true" || v === "1");
+}
+function envJson(key) {
+  return new EnvSpec(key, true, void 0, JSON.parse);
+}
+function envJsonOptional(key, defaultValue) {
+  return new EnvSpec(key, false, defaultValue, (v) => v ? JSON.parse(v) : void 0);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ConfigValidationError,
+  EnvSpec,
+  defineConfig,
+  env,
+  envBoolean,
+  envJson,
+  envJsonOptional,
+  envNumber,
+  envNumberOptional,
+  envOptional,
+  isConfigSpec,
+  loadEnvFiles
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/config-spec.ts","../src/errors.ts","../src/load-env-files.ts","../src/define-config.ts","../src/env-spec.ts"],"sourcesContent":["export {\n    type ConfigSpec,\n    type InferSpecType,\n    type InferConfigType,\n    isConfigSpec,\n} from \"./config-spec\";\n\nexport { ConfigValidationError } from \"./errors\";\n\nexport { defineConfig, type ConfigOptions } from \"./define-config\";\nexport { loadEnvFiles } from \"./load-env-files\";\n\nexport {\n    EnvSpec,\n    env,\n    envOptional,\n    envNumber,\n    envNumberOptional,\n    envBoolean,\n    envJson,\n    envJsonOptional,\n} from \"./env-spec\";\n\nexport type { DatabaseConfig } from \"./database-config\";\n","export interface ConfigSpec<T> {\n    readonly _type: string;\n    resolve(errors: string[]): T | undefined;\n}\n\nexport type InferSpecType<S> = S extends ConfigSpec<infer T> ? T : S;\n\nexport type InferConfigType<S extends Record<string, unknown>> = {\n    readonly [K in keyof S]: InferSpecType<S[K]>;\n};\n\nexport function isConfigSpec(value: unknown): value is ConfigSpec<unknown> {\n    return (\n        typeof value === \"object\" &&\n        value !== null &&\n        \"resolve\" in value &&\n        typeof (value as ConfigSpec<unknown>).resolve === \"function\"\n    );\n}\n","export class ConfigValidationError extends Error {\n    constructor(public readonly errors: string[]) {\n        super(`Config validation failed:\\n  - ${errors.join(\"\\n  - \")}`);\n        this.name = \"ConfigValidationError\";\n    }\n}\n","import fs from \"node:fs\";\nimport path from \"node:path\";\n\nimport dotenv from \"dotenv\";\n\nexport function loadEnvFiles({\n    basePath,\n    nodeEnv,\n}: {\n    basePath?: string;\n    nodeEnv?: string;\n} = {}): void {\n    const basePath_ = basePath ?? process.cwd();\n    const nodeEnv_ = nodeEnv ?? process.env.NODE_ENV ?? \"development\";\n\n    const envFiles = [\n        \".env\",\n        \".env.local\",\n        `.env.${nodeEnv_}`,\n        `.env.${nodeEnv_}.local`,\n    ];\n\n    const loadEnvFile = (filePath: string) => {\n        if (fs.existsSync(filePath)) {\n            dotenv.config({ path: filePath });\n        }\n    };\n\n    envFiles.reverse().forEach((file) => {\n        const filePath = path.resolve(basePath_, file);\n        loadEnvFile(filePath);\n    });\n}\n","import { type InferConfigType, isConfigSpec } from \"./config-spec\";\nimport { ConfigValidationError } from \"./errors\";\nimport { loadEnvFiles } from \"./load-env-files\";\n\nexport interface ConfigOptions {\n    loadEnv?: boolean;\n    envLoader?: () => void;\n}\n\nexport function defineConfig<S extends Record<string, unknown>>(\n    schema: S,\n    options?: ConfigOptions\n): () => InferConfigType<S> {\n    let instance: InferConfigType<S> | null = null;\n\n    return () => {\n        if (instance && process.env.NODE_ENV !== \"test\") {\n            return instance;\n        }\n\n        if (options?.loadEnv) {\n            if (options.envLoader) {\n                options.envLoader();\n            } else {\n                loadEnvFiles();\n            }\n        }\n\n        const config = {} as Record<string, unknown>;\n        const errors: string[] = [];\n\n        for (const [key, value] of Object.entries(schema)) {\n            if (isConfigSpec(value)) {\n                config[key] = value.resolve(errors);\n            } else {\n                config[key] = value;\n            }\n        }\n\n        if (errors.length > 0) {\n            throw new ConfigValidationError(errors);\n        }\n\n        instance = config as InferConfigType<S>;\n        return instance;\n    };\n}\n","import type { ConfigSpec } from \"./config-spec\";\n\nexport class EnvSpec<T> implements ConfigSpec<T> {\n    readonly _type = \"env\";\n\n    constructor(\n        private readonly envKey: string,\n        private readonly required: boolean,\n        private readonly defaultValue?: T,\n        private readonly transform?: (value: string) => T\n    ) {}\n\n    resolve(errors: string[]): T | undefined {\n        const rawValue = process.env[this.envKey];\n\n        if (!rawValue && this.required) {\n            errors.push(`Missing required env: ${this.envKey}`);\n            return undefined;\n        }\n\n        if (rawValue !== undefined) {\n            try {\n                return this.transform ? this.transform(rawValue) : (rawValue as T);\n            } catch (e) {\n                errors.push(`Failed to transform ${this.envKey}: ${(e as Error).message}`);\n                return undefined;\n            }\n        }\n\n        return this.defaultValue;\n    }\n}\n\nexport function env(key: string): EnvSpec<string> {\n    return new EnvSpec(key, true);\n}\n\nexport function envOptional(key: string, defaultValue?: string): EnvSpec<string | undefined> {\n    return new EnvSpec(key, false, defaultValue);\n}\n\nexport function envNumber(key: string): EnvSpec<number> {\n    return new EnvSpec(key, true, undefined, Number);\n}\n\nexport function envNumberOptional(key: string, defaultValue?: number): EnvSpec<number | undefined> {\n    return new EnvSpec(key, false, defaultValue, (v) => (v ? Number(v) : undefined));\n}\n\nexport function envBoolean(key: string, defaultValue = false): EnvSpec<boolean> {\n    return new EnvSpec(key, false, defaultValue, (v) => v === \"true\" || v === \"1\");\n}\n\nexport function envJson<T>(key: string): EnvSpec<T> {\n    return new EnvSpec(key, true, undefined, JSON.parse);\n}\n\nexport function envJsonOptional<T>(key: string, defaultValue?: T): EnvSpec<T | undefined> {\n    return new EnvSpec(key, false, defaultValue, (v) => (v ? JSON.parse(v) : undefined));\n}\n"],"mappings":"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","names":["fs","dotenv","path"]}

package/dist/index.mjs

@@ -0,0 +1,135 @@
+// src/config-spec.ts
+function isConfigSpec(value) {
+  return typeof value === "object" && value !== null && "resolve" in value && typeof value.resolve === "function";
+}
+
+// src/errors.ts
+var ConfigValidationError = class extends Error {
+  constructor(errors) {
+    super(`Config validation failed:
+  - ${errors.join("\n  - ")}`);
+    this.errors = errors;
+    this.name = "ConfigValidationError";
+  }
+};
+
+// src/load-env-files.ts
+import fs from "fs";
+import path from "path";
+import dotenv from "dotenv";
+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);
+  });
+}
+
+// src/define-config.ts
+function defineConfig(schema, options) {
+  let instance = null;
+  return () => {
+    if (instance && process.env.NODE_ENV !== "test") {
+      return instance;
+    }
+    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);
+      } else {
+        config[key] = value;
+      }
+    }
+    if (errors.length > 0) {
+      throw new ConfigValidationError(errors);
+    }
+    instance = config;
+    return instance;
+  };
+}
+
+// src/env-spec.ts
+var EnvSpec = class {
+  constructor(envKey, required, defaultValue, transform) {
+    this.envKey = envKey;
+    this.required = required;
+    this.defaultValue = defaultValue;
+    this.transform = transform;
+  }
+  _type = "env";
+  resolve(errors) {
+    const rawValue = process.env[this.envKey];
+    if (!rawValue && this.required) {
+      errors.push(`Missing required env: ${this.envKey}`);
+      return void 0;
+    }
+    if (rawValue !== void 0) {
+      try {
+        return this.transform ? this.transform(rawValue) : rawValue;
+      } catch (e) {
+        errors.push(`Failed to transform ${this.envKey}: ${e.message}`);
+        return void 0;
+      }
+    }
+    return this.defaultValue;
+  }
+};
+function env(key) {
+  return new EnvSpec(key, true);
+}
+function envOptional(key, defaultValue) {
+  return new EnvSpec(key, false, defaultValue);
+}
+function envNumber(key) {
+  return new EnvSpec(key, true, void 0, Number);
+}
+function envNumberOptional(key, defaultValue) {
+  return new EnvSpec(key, false, defaultValue, (v) => v ? Number(v) : void 0);
+}
+function envBoolean(key, defaultValue = false) {
+  return new EnvSpec(key, false, defaultValue, (v) => v === "true" || v === "1");
+}
+function envJson(key) {
+  return new EnvSpec(key, true, void 0, JSON.parse);
+}
+function envJsonOptional(key, defaultValue) {
+  return new EnvSpec(key, false, defaultValue, (v) => v ? JSON.parse(v) : void 0);
+}
+export {
+  ConfigValidationError,
+  EnvSpec,
+  defineConfig,
+  env,
+  envBoolean,
+  envJson,
+  envJsonOptional,
+  envNumber,
+  envNumberOptional,
+  envOptional,
+  isConfigSpec,
+  loadEnvFiles
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config-spec.ts","../src/errors.ts","../src/load-env-files.ts","../src/define-config.ts","../src/env-spec.ts"],"sourcesContent":["export interface ConfigSpec<T> {\n    readonly _type: string;\n    resolve(errors: string[]): T | undefined;\n}\n\nexport type InferSpecType<S> = S extends ConfigSpec<infer T> ? T : S;\n\nexport type InferConfigType<S extends Record<string, unknown>> = {\n    readonly [K in keyof S]: InferSpecType<S[K]>;\n};\n\nexport function isConfigSpec(value: unknown): value is ConfigSpec<unknown> {\n    return (\n        typeof value === \"object\" &&\n        value !== null &&\n        \"resolve\" in value &&\n        typeof (value as ConfigSpec<unknown>).resolve === \"function\"\n    );\n}\n","export class ConfigValidationError extends Error {\n    constructor(public readonly errors: string[]) {\n        super(`Config validation failed:\\n  - ${errors.join(\"\\n  - \")}`);\n        this.name = \"ConfigValidationError\";\n    }\n}\n","import fs from \"node:fs\";\nimport path from \"node:path\";\n\nimport dotenv from \"dotenv\";\n\nexport function loadEnvFiles({\n    basePath,\n    nodeEnv,\n}: {\n    basePath?: string;\n    nodeEnv?: string;\n} = {}): void {\n    const basePath_ = basePath ?? process.cwd();\n    const nodeEnv_ = nodeEnv ?? process.env.NODE_ENV ?? \"development\";\n\n    const envFiles = [\n        \".env\",\n        \".env.local\",\n        `.env.${nodeEnv_}`,\n        `.env.${nodeEnv_}.local`,\n    ];\n\n    const loadEnvFile = (filePath: string) => {\n        if (fs.existsSync(filePath)) {\n            dotenv.config({ path: filePath });\n        }\n    };\n\n    envFiles.reverse().forEach((file) => {\n        const filePath = path.resolve(basePath_, file);\n        loadEnvFile(filePath);\n    });\n}\n","import { type InferConfigType, isConfigSpec } from \"./config-spec\";\nimport { ConfigValidationError } from \"./errors\";\nimport { loadEnvFiles } from \"./load-env-files\";\n\nexport interface ConfigOptions {\n    loadEnv?: boolean;\n    envLoader?: () => void;\n}\n\nexport function defineConfig<S extends Record<string, unknown>>(\n    schema: S,\n    options?: ConfigOptions\n): () => InferConfigType<S> {\n    let instance: InferConfigType<S> | null = null;\n\n    return () => {\n        if (instance && process.env.NODE_ENV !== \"test\") {\n            return instance;\n        }\n\n        if (options?.loadEnv) {\n            if (options.envLoader) {\n                options.envLoader();\n            } else {\n                loadEnvFiles();\n            }\n        }\n\n        const config = {} as Record<string, unknown>;\n        const errors: string[] = [];\n\n        for (const [key, value] of Object.entries(schema)) {\n            if (isConfigSpec(value)) {\n                config[key] = value.resolve(errors);\n            } else {\n                config[key] = value;\n            }\n        }\n\n        if (errors.length > 0) {\n            throw new ConfigValidationError(errors);\n        }\n\n        instance = config as InferConfigType<S>;\n        return instance;\n    };\n}\n","import type { ConfigSpec } from \"./config-spec\";\n\nexport class EnvSpec<T> implements ConfigSpec<T> {\n    readonly _type = \"env\";\n\n    constructor(\n        private readonly envKey: string,\n        private readonly required: boolean,\n        private readonly defaultValue?: T,\n        private readonly transform?: (value: string) => T\n    ) {}\n\n    resolve(errors: string[]): T | undefined {\n        const rawValue = process.env[this.envKey];\n\n        if (!rawValue && this.required) {\n            errors.push(`Missing required env: ${this.envKey}`);\n            return undefined;\n        }\n\n        if (rawValue !== undefined) {\n            try {\n                return this.transform ? this.transform(rawValue) : (rawValue as T);\n            } catch (e) {\n                errors.push(`Failed to transform ${this.envKey}: ${(e as Error).message}`);\n                return undefined;\n            }\n        }\n\n        return this.defaultValue;\n    }\n}\n\nexport function env(key: string): EnvSpec<string> {\n    return new EnvSpec(key, true);\n}\n\nexport function envOptional(key: string, defaultValue?: string): EnvSpec<string | undefined> {\n    return new EnvSpec(key, false, defaultValue);\n}\n\nexport function envNumber(key: string): EnvSpec<number> {\n    return new EnvSpec(key, true, undefined, Number);\n}\n\nexport function envNumberOptional(key: string, defaultValue?: number): EnvSpec<number | undefined> {\n    return new EnvSpec(key, false, defaultValue, (v) => (v ? Number(v) : undefined));\n}\n\nexport function envBoolean(key: string, defaultValue = false): EnvSpec<boolean> {\n    return new EnvSpec(key, false, defaultValue, (v) => v === \"true\" || v === \"1\");\n}\n\nexport function envJson<T>(key: string): EnvSpec<T> {\n    return new EnvSpec(key, true, undefined, JSON.parse);\n}\n\nexport function envJsonOptional<T>(key: string, defaultValue?: T): EnvSpec<T | undefined> {\n    return new EnvSpec(key, false, defaultValue, (v) => (v ? JSON.parse(v) : undefined));\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "ezcfg",
+    "version": "0.1.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"
+        }
+    },
+    "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"
+    ]
+}