feat(dotenv): support typed prefix

Author: bernard-ng

README.md

@@ -54,7 +54,7 @@ const { config, env } = loadConfig({
   env: { path: path.join(process.cwd(), ".env") },
   sources: [
     path.join("config", "default.yaml"),
-    { path: path.join("config", `${env("APP_ENV", { default: "dev" })}.yaml`), optional: true },
+    { path: path.join("config", `${env("NODE_ENV", { default: "dev" })}.yaml`), optional: true },
     { featureFlags: ["beta-search"] },
   ],
 });
@@ -94,7 +94,7 @@ const { config, env } = loadConfig({
   schema,
   env: {
     path: ".env",
-    knownKeys: ["APP_ENV", "DB_HOST", "DB_PORT"] as const,
+    knownKeys: ["NODE_ENV", "DB_HOST", "DB_PORT"] as const,
   },
 });
 
@@ -118,10 +118,10 @@ const schema = z.object({
   redisUrl: z.string().url(),
 });
 
-const env = createEnvAccessor(["APP_ENV", "APP_PORT", "REDIS_URL"] as const);
+const env = createEnvAccessor(["NODE_ENV", "APP_PORT", "REDIS_URL"] as const);
 
 const config = schema.parse({
-  appEnv: env("APP_ENV", { default: "dev" }),
+  appEnv: env("NODE_ENV", { default: "dev" }),
   port: Number(env("APP_PORT", { default: "3000" })),
   redisUrl: env("REDIS_URL"),
 });
@@ -161,6 +161,9 @@ const { config } = loadConfig({
 ### Referencing environment variables
 
 - **Text-based configs** (JSON, YAML, INI): use `%env(DB_HOST)%`
+- **Typed placeholders**: `%env(number:PORT)%`, `%env(boolean:FEATURE)%`, `%env(string:NAME)%`
+  - When the entire value is a single placeholder, typed forms produce native values (number/boolean).
+  - When used inside larger strings (e.g. `"http://%env(API_HOST)%/v1"`), placeholders are interpolated as text.
 - **TypeScript configs**: call `env("DB_HOST")`; the helper is available globally when the module is evaluated
   - For tighter autocomplete you can build a project-local accessor via `createEnvAccessor(["DB_HOST", "DB_PORT"] as const)`
 
@@ -171,9 +174,9 @@ The `env()` helper throws when the variable is missing. Provide a default with `
 `loadConfig` automatically understands `.env` files when the `env` option is provided. The resolver honours the following precedence, mirroring Symfony's Dotenv component:
 
 1. `.env` (or `.env.dist` when `.env` is missing)
-2. `.env.local` (skipped when `APP_ENV === "test"`)
-3. `.env.<APP_ENV>`
-4. `.env.<APP_ENV>.local`
+2. `.env.local` (skipped when `NODE_ENV === "test"`)
+3. `.env.<NODE_ENV>`
+4. `.env.<NODE_ENV>.local`
 
 Local files always win over base files. The loaded keys are registered on the shared `env` accessor so they show up in editor autocomplete once your editor reloads types.
 

src/config.ts

@@ -1,4 +1,4 @@
-import { createRequire } from "module";
+import { createRequire } from "node:module";
 import fs from "node:fs";
 import path from "node:path";
 import vm from "node:vm";
@@ -93,13 +93,23 @@ export class ConfigParseError extends ConfigError {
 
 export class ConfigValidationError extends ConfigError {
   constructor(readonly issues: z.core.$ZodIssue[]) {
-    super("Configuration validation failed");
+    const formatPath = (path: Array<PropertyKey>) =>
+      path.length ? path.map(seg => (typeof seg === "number" ? `[${seg}]` : String(seg))).join(".") : "<root>";
+
+    const details = issues.map(iss => `${formatPath(iss.path)}: ${iss.message}`).join("\n");
+
+    super(`Configuration validation failed:\n${details}`);
     this.name = "ConfigValidationError";
   }
 }
 
 // Optimized constants / helpers (hoisted to avoid rework on hot paths)
-const ENV_PLACEHOLDER_REGEX = /%env\(([A-Z0-9_]+)\)%/gi;
+// Support optional type prefixes in placeholders: %env(type:VAR)%
+// - type can be one of: string | number | boolean (case-insensitive)
+// - When the entire value is a single placeholder, we can return a non-string (number/boolean)
+// - When embedded inside a larger string, we interpolate as a string
+const ENV_PLACEHOLDER_ANY = /%env\((?:(string|number|boolean):)?([A-Z0-9_]+)\)%/gi;
+const ENV_PLACEHOLDER_FULL = /^%env\((?:(string|number|boolean):)?([A-Z0-9_]+)\)%$/i;
 
 const TS_COMPILER_OPTS: ts.TranspileOptions = {
   compilerOptions: {
@@ -286,12 +296,12 @@ function parseFile(source: FileSource, cwd: string, accessor: EnvAccessor<string
     switch (format) {
       case "json":
         return ensureObject(JSON.parse(text), targetPath);
+      case "ts":
+        return ensureObject(loadTsModule(targetPath, text, accessor), targetPath);
       case "yaml":
         return ensureObject(YAML.parse(text), targetPath);
       case "ini":
         return ensureObject(ini.parse(text), targetPath);
-      case "ts":
-        return ensureObject(loadTsModule(targetPath, text, accessor), targetPath);
       default:
         throw new ConfigParseError(`Unsupported configuration format: ${format}`, targetPath);
     }
@@ -352,7 +362,22 @@ function ensureObject(value: unknown, origin: string): Record<string, unknown> {
 
 function resolvePlaceholders(value: unknown, accessor: EnvAccessor<string>): unknown {
   if (typeof value === "string") {
-    return value.replace(ENV_PLACEHOLDER_REGEX, (_m, name: string) => accessor(name));
+    // If the entire string is exactly one placeholder, allow non-string returns
+    const full = value.match(ENV_PLACEHOLDER_FULL);
+    if (full) {
+      const [, rawType, name] = full as unknown as [string, string | undefined, string];
+      const type = rawType ? rawType.toLowerCase() : undefined;
+      const raw = accessor(name as string);
+      return coerceEnvValue(raw, type);
+    }
+
+    // Otherwise, interpolate placeholders inside the string
+    return value.replace(ENV_PLACEHOLDER_ANY, (_m, rawType: string | undefined, name: string) => {
+      const type = rawType ? rawType.toLowerCase() : undefined;
+      const raw = accessor(name);
+      const coerced = coerceEnvValue(raw, type);
+      return String(coerced);
+    });
   }
   if (Array.isArray(value)) {
     const out = new Array(value.length);
@@ -369,6 +394,27 @@ function resolvePlaceholders(value: unknown, accessor: EnvAccessor<string>): unk
   return value;
 }
 
+function coerceEnvValue(raw: string, type?: string): unknown {
+  switch (type) {
+    case undefined:
+    case "string":
+      return raw;
+    case "number": {
+      const num = Number(raw);
+      return num; // May be NaN; let schema validation catch invalid cases
+    }
+    case "boolean": {
+      const norm = raw.trim().toLowerCase();
+      if (norm === "true" || norm === "1" || norm === "yes" || norm === "y" || norm === "on") return true;
+      if (norm === "false" || norm === "0" || norm === "no" || norm === "n" || norm === "off") return false;
+      // Fallback: non-empty strings are truthy, empty is falsey
+      return Boolean(norm);
+    }
+    default:
+      return raw;
+  }
+}
+
 /**
  * mergeValues:
  * - arrays: replace with next (clone)

src/dotenv.ts

@@ -1,6 +1,6 @@
-import { spawnSync } from "child_process";
-import fs from "fs";
-import path from "path";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
 
 // Hoisted regex & small helpers (avoid recompiles in hot paths)
 const RX_VARNAME_STICKY = /_?[A-Z][A-Z0-9_]*/y; // sticky var name
@@ -58,8 +58,8 @@ export default class Dotenv {
   private commandExpansionEnabled = false;
 
   constructor(
-    private envKey = "APP_ENV",
-    private debugKey = "APP_DEBUG"
+    private envKey = "NODE_ENV",
+    private debugKey = "NODE_DEBUG"
   ) {}
 
   setProdEnvs(prodEnvs: string[]) {
@@ -78,9 +78,9 @@ export default class Dotenv {
   /**
    * Symfony-like semantics:
    * - load .env (or .env.dist if .env missing)
-   * - infer APP_ENV (default 'dev') if missing
+   * - infer NODE_ENV (default 'dev') if missing
    * - load .env.local unless in test env
-   * - skip if APP_ENV == 'local'
+   * - skip if NODE_ENV == 'local'
    * - load .env.$env
    * - load .env.$env.local
    */
@@ -142,7 +142,7 @@ export default class Dotenv {
       this.loadEnv(p, k, defaultEnv, testEnvs, overrideExisting);
     }
 
-    // Compute APP_DEBUG
+    // Compute NODE_DEBUG
     const dk = this.debugKey;
     const currentEnv = process.env[this.envKey] ?? defaultEnv;
     const defaultDebug = !this.prodEnvs.includes(currentEnv);

tests/config.test.ts

@@ -231,3 +231,61 @@ describe("loadConfig", () => {
     expect(config.key).toBe("value");
   });
 });
+
+describe("typed %env(...)% placeholders", () => {
+  it("supports number placeholders (native type when standalone, string when embedded)", () => {
+    process.env.PORT = "8080";
+
+    const schema = z.object({
+      port: z.number(),
+      url: z.string(),
+    });
+
+    const { config } = loadConfig({
+      schema,
+      env: false,
+      sources: [{ port: "%env(number:PORT)%", url: "http://localhost:%env(number:PORT)%" }],
+    });
+
+    expect(config.port).toBe(8080);
+    expect(typeof config.port).toBe("number");
+    expect(config.url).toBe("http://localhost:8080");
+  });
+
+  it("supports boolean placeholders (native type)", () => {
+    process.env.FEATURE_ONE = "true";
+    process.env.FEATURE_TWO = "0"; // falsey
+
+    const schema = z.object({
+      featureOne: z.boolean(),
+      featureTwo: z.boolean(),
+    });
+
+    const { config } = loadConfig({
+      schema,
+      env: false,
+      sources: [{ featureOne: "%env(boolean:FEATURE_ONE)%", featureTwo: "%env(boolean:FEATURE_TWO)%" }],
+    });
+
+    expect(config.featureOne).toBe(true);
+    expect(config.featureTwo).toBe(false);
+  });
+
+  it("accepts explicit string type and interpolates inside larger strings", () => {
+    process.env.NAME = "service";
+
+    const schema = z.object({
+      name: z.string(),
+      location: z.string(),
+    });
+
+    const { config } = loadConfig({
+      schema,
+      env: false,
+      sources: [{ name: "%env(string:NAME)%", location: "/srv/%env(string:NAME)%/data" }],
+    });
+
+    expect(config.name).toBe("service");
+    expect(config.location).toBe("/srv/service/data");
+  });
+});