@nifrajs/env 5.0.0 → 5.1.0

package/README.md

@@ -64,8 +64,11 @@ pass the request's bindings: `defineEnv(shape, { source: env })`.
 ## Secret safety
 
 Error messages name the offending variable and the reason - **never its value** (it may be a
-secret). A BYO validator such as valibot may quote the value in its message; `defineEnv` replaces
-it with `<redacted>`. `defineEnv` returns a frozen object, so a validated config can't be mutated downstream.
+secret). A BYO validator such as valibot or zod may quote the value in its message, escaped or
+cut short, so when it refuses a set value `defineEnv` reports the variable as invalid without the
+validator's message. For an unset variable the message is shown, since there is no value to quote.
+Use the `env.*` helpers when you want the reason as well. `defineEnv` returns a frozen object, so a
+validated config can't be mutated downstream.
 
 ## For AI agents
 

package/dist/define.d.ts

@@ -31,10 +31,11 @@ export interface DefineEnvOptions {
  * // ENV.PORT: number, ENV.NODE_ENV: "development" | "production" | "test", … all validated.
  * ```
  *
- * Errors name the offending variable and the reason - never its value (it may be a secret); a BYO
- * validator's message that quotes the value gets `<redacted>` in its place. BYO
- * validators (`t`, zod, valibot) work too; only the `env.*` helpers coerce from strings, so a plain
- * `t.number()` would see the raw string - use `env.number()` for coercion.
+ * Errors name the offending variable and the reason - never its value (it may be a secret). BYO
+ * validators (`t`, zod, valibot) work too, but their messages may quote the value, so a set value
+ * they refuse is reported as invalid without their words; an unset one shows their message. Only the
+ * `env.*` helpers coerce from strings, so a plain `t.number()` would see the raw string - use
+ * `env.number()` for coercion.
  */
 export declare function defineEnv<S extends EnvShape>(shape: S, options?: DefineEnvOptions): EnvResult<S>;
 //# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEhE,kCAAkC;AAClC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;AAEvD,4EAA4E;AAC5E,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,QAAQ,IAAI;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA;AAE1F,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACrD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC,CAAC,CAAC,CAsChG"}
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEhE,kCAAkC;AAClC,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAA;AAEvD,4EAA4E;AAC5E,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,QAAQ,IAAI;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAA;AAE1F,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;CACrD;AAID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC,CAAC,CAAC,CAuChG"}

package/dist/define.js

@@ -1,3 +1,4 @@
+const WITHHELD = "is invalid (the validator's message is withheld, since it may quote the value)";
 /**
  * Validate the environment against a schema and return a **frozen, typed** object - or throw at
  * startup listing **every** problem at once (not just the first), so a misconfigured deploy fails
@@ -17,10 +18,11 @@
  * // ENV.PORT: number, ENV.NODE_ENV: "development" | "production" | "test", … all validated.
  * ```
  *
- * Errors name the offending variable and the reason - never its value (it may be a secret); a BYO
- * validator's message that quotes the value gets `<redacted>` in its place. BYO
- * validators (`t`, zod, valibot) work too; only the `env.*` helpers coerce from strings, so a plain
- * `t.number()` would see the raw string - use `env.number()` for coercion.
+ * Errors name the offending variable and the reason - never its value (it may be a secret). BYO
+ * validators (`t`, zod, valibot) work too, but their messages may quote the value, so a set value
+ * they refuse is reported as invalid without their words; an unset one shows their message. Only the
+ * `env.*` helpers coerce from strings, so a plain `t.number()` would see the raw string - use
+ * `env.number()` for coercion.
  */
 export function defineEnv(shape, options) {
     const source = options?.source ??
@@ -41,12 +43,14 @@ export function defineEnv(shape, options) {
         }
         if (result.issues !== undefined) {
             const raw = source[key];
-            // Only the `env.*` helpers promise value-free messages; valibot and hand-rolled validators
-            // quote the value, which may be a secret.
-            const foreign = schema["~standard"].vendor !== "nifra-env" && raw !== undefined && raw !== "";
-            for (const i of result.issues) {
-                problems.push(`  ${key}: ${foreign ? i.message.replaceAll(raw, "<redacted>") : i.message}`);
+            // Only the `env.*` helpers promise value-free messages. Another validator may quote the value
+            // escaped, truncated or transformed, past any search-and-replace, so its words are not shown.
+            if (schema["~standard"].vendor !== "nifra-env" && raw !== undefined && raw !== "") {
+                problems.push(`  ${key}: ${WITHHELD}`);
+                continue;
             }
+            for (const i of result.issues)
+                problems.push(`  ${key}: ${i.message}`);
         }
         else {
             out[key] = result.value;

package/dist/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,SAAS,CAAqB,KAAQ,EAAE,OAA0B;IAChF,MAAM,MAAM,GACV,OAAO,EAAE,MAAM;QACd,UAAyE,CAAC,OAAO,EAAE,GAAG;QACvF,EAAE,CAAA;IACJ,MAAM,GAAG,GAA4B,EAAE,CAAA;IACvC,MAAM,QAAQ,GAAa,EAAE,CAAA;IAE7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAqB,CAAA;QAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QACxD,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC9B,yFAAyF;YACzF,8FAA8F;YAC9F,8DAA8D;YAC9D,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;YACtB,QAAQ,CAAC,IAAI,CAAC,KAAK,GAAG,mDAAmD,CAAC,CAAA;YAC1E,SAAQ;QACV,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;YACvB,2FAA2F;YAC3F,0CAA0C;YAC1C,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,CAAA;YAC7F,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC9B,QAAQ,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAA;YAC7F,CAAC;QACH,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAA;QACzB,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,qCAAqC,QAAQ,CAAC,MAAM,iBAAiB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,4CAA4C,CACrI,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAiB,CAAA;AAC3C,CAAC"}
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAgBA,MAAM,QAAQ,GAAG,gFAAgF,CAAA;AAEjG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,SAAS,CAAqB,KAAQ,EAAE,OAA0B;IAChF,MAAM,MAAM,GACV,OAAO,EAAE,MAAM;QACd,UAAyE,CAAC,OAAO,EAAE,GAAG;QACvF,EAAE,CAAA;IACJ,MAAM,GAAG,GAA4B,EAAE,CAAA;IACvC,MAAM,QAAQ,GAAa,EAAE,CAAA;IAE7B,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAqB,CAAA;QAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAA;QACxD,IAAI,MAAM,YAAY,OAAO,EAAE,CAAC;YAC9B,yFAAyF;YACzF,8FAA8F;YAC9F,8DAA8D;YAC9D,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;YACtB,QAAQ,CAAC,IAAI,CAAC,KAAK,GAAG,mDAAmD,CAAC,CAAA;YAC1E,SAAQ;QACV,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAA;YACvB,8FAA8F;YAC9F,8FAA8F;YAC9F,IAAI,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,WAAW,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,EAAE,CAAC;gBAClF,QAAQ,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,QAAQ,EAAE,CAAC,CAAA;gBACtC,SAAQ;YACV,CAAC;YACD,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,MAAM;gBAAE,QAAQ,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAA;QACxE,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAA;QACzB,CAAC;IACH,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,qCAAqC,QAAQ,CAAC,MAAM,iBAAiB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,4CAA4C,CACrI,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,CAAiB,CAAA;AAC3C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/env",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Typed, validated environment variables for nifra - define a schema, get a frozen typed object, fail loud at boot listing every problem. Coercing helpers (number/port/boolean/url/enum) + any Standard Schema. Dependency-free, edge-safe.",
   "keywords": [
     "bun",

package/src/define.ts

@@ -14,6 +14,8 @@ export interface DefineEnvOptions {
   readonly source?: Record<string, string | undefined>
 }
 
+const WITHHELD = "is invalid (the validator's message is withheld, since it may quote the value)"
+
 /**
  * Validate the environment against a schema and return a **frozen, typed** object - or throw at
  * startup listing **every** problem at once (not just the first), so a misconfigured deploy fails
@@ -33,10 +35,11 @@ export interface DefineEnvOptions {
  * // ENV.PORT: number, ENV.NODE_ENV: "development" | "production" | "test", … all validated.
  * ```
  *
- * Errors name the offending variable and the reason - never its value (it may be a secret); a BYO
- * validator's message that quotes the value gets `<redacted>` in its place. BYO
- * validators (`t`, zod, valibot) work too; only the `env.*` helpers coerce from strings, so a plain
- * `t.number()` would see the raw string - use `env.number()` for coercion.
+ * Errors name the offending variable and the reason - never its value (it may be a secret). BYO
+ * validators (`t`, zod, valibot) work too, but their messages may quote the value, so a set value
+ * they refuse is reported as invalid without their words; an unset one shows their message. Only the
+ * `env.*` helpers coerce from strings, so a plain `t.number()` would see the raw string - use
+ * `env.number()` for coercion.
  */
 export function defineEnv<S extends EnvShape>(shape: S, options?: DefineEnvOptions): EnvResult<S> {
   const source =
@@ -59,12 +62,13 @@ export function defineEnv<S extends EnvShape>(shape: S, options?: DefineEnvOptio
     }
     if (result.issues !== undefined) {
       const raw = source[key]
-      // Only the `env.*` helpers promise value-free messages; valibot and hand-rolled validators
-      // quote the value, which may be a secret.
-      const foreign = schema["~standard"].vendor !== "nifra-env" && raw !== undefined && raw !== ""
-      for (const i of result.issues) {
-        problems.push(`  ${key}: ${foreign ? i.message.replaceAll(raw, "<redacted>") : i.message}`)
+      // Only the `env.*` helpers promise value-free messages. Another validator may quote the value
+      // escaped, truncated or transformed, past any search-and-replace, so its words are not shown.
+      if (schema["~standard"].vendor !== "nifra-env" && raw !== undefined && raw !== "") {
+        problems.push(`  ${key}: ${WITHHELD}`)
+        continue
       }
+      for (const i of result.issues) problems.push(`  ${key}: ${i.message}`)
     } else {
       out[key] = result.value
     }