@nifrajs/env 4.0.2 → 5.1.0

package/README.md

@@ -64,7 +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). `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

@@ -32,8 +32,10 @@ export interface DefineEnvOptions {
  * ```
  *
  * Errors name the offending variable and the reason - never its value (it may be a secret). 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.
+ * 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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC,CAAC,CAAC,CA8BhG"}
+{"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
@@ -18,8 +19,10 @@
  * ```
  *
  * Errors name the offending variable and the reason - never its value (it may be a secret). 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.
+ * 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 ??
@@ -32,11 +35,20 @@ export function defineEnv(shape, options) {
         const result = schema["~standard"].validate(source[key]);
         if (result instanceof Promise) {
             // Env validation must be synchronous (it runs once, at import) - an async validator is a
-            // configuration mistake, surfaced as a problem rather than an unhandled promise.
+            // configuration mistake, surfaced as a problem. Its promise is observed so a rejection is not
+            // reported as unhandled after the caller catches the refusal.
+            result.catch(() => { });
             problems.push(`  ${key}: async validators are not supported in defineEnv`);
             continue;
         }
         if (result.issues !== undefined) {
+            const raw = source[key];
+            // 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}`);
         }

package/dist/define.js.map

@@ -1 +1 @@
-{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;;;;;;;;;;GAsBG;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,iFAAiF;YACjF,QAAQ,CAAC,IAAI,CAAC,KAAK,GAAG,mDAAmD,CAAC,CAAA;YAC1E,SAAQ;QACV,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAChC,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"}
+{"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": "4.0.2",
+  "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
@@ -34,8 +36,10 @@ export interface DefineEnvOptions {
  * ```
  *
  * Errors name the offending variable and the reason - never its value (it may be a secret). 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.
+ * 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 =
@@ -50,11 +54,20 @@ export function defineEnv<S extends EnvShape>(shape: S, options?: DefineEnvOptio
     const result = schema["~standard"].validate(source[key])
     if (result instanceof Promise) {
       // Env validation must be synchronous (it runs once, at import) - an async validator is a
-      // configuration mistake, surfaced as a problem rather than an unhandled promise.
+      // configuration mistake, surfaced as a problem. Its promise is observed so a rejection is not
+      // reported as unhandled after the caller catches the refusal.
+      result.catch(() => {})
       problems.push(`  ${key}: async validators are not supported in defineEnv`)
       continue
     }
     if (result.issues !== undefined) {
+      const raw = source[key]
+      // 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