@nifrajs/env 2.2.0 → 2.4.0

package/README.md

@@ -1,12 +1,12 @@
 # @nifrajs/env
 
 Typed, validated environment variables. Define a schema once at startup; get a **frozen, typed**
-object — or a **loud boot-time failure listing every problem at once**, so a misconfigured deploy
+object - or a **loud boot-time failure listing every problem at once**, so a misconfigured deploy
 fails immediately instead of erroring on the first request that touches a bad var. The config half
 of nifra's "validate at every boundary" rule. Dependency-free, edge-safe.
 
 ```ts
-// env.ts — imported once at startup
+// env.ts - imported once at startup
 import { defineEnv, env } from "@nifrajs/env"
 
 export const ENV = defineEnv({
@@ -27,7 +27,7 @@ export const ENV = defineEnv({
 A missing/invalid var fails at import:
 
 ```
-[nifra/env] invalid environment — 2 problem(s):
+[nifra/env] invalid environment - 2 problem(s):
   DATABASE_URL: must be a valid URL
   STRIPE_SECRET: is required
 
@@ -42,7 +42,7 @@ Every value in `process.env` is a `string | undefined`; these turn it into the v
 | --- | --- | --- |
 | `env.string({ default?, optional? })` | `string` | empty string counts as unset |
 | `env.number({ default?, optional? })` | `number` | finite, coerced |
-| `env.port({ default? })` | `number` | integer 1–65535 |
+| `env.port({ default? })` | `number` | integer 1-65535 |
 | `env.boolean({ default? })` | `boolean` | `true`/`1`/`yes`/`on` vs `false`/`0`/`no`/`off`/empty |
 | `env.enum([...], { default? })` | union | one of the listed values |
 | `env.url({ default?, optional? })` | `string` | parses with WHATWG `URL`, returns the normalized href |
@@ -52,23 +52,23 @@ Every value in `process.env` is a `string | undefined`; these turn it into the v
 ## Bring your own validator
 
 `defineEnv` accepts **any Standard Schema** (`t` from `@nifrajs/schema`, zod, valibot), not just the
-`env.*` helpers — handy for a shape the helpers don't cover. Only the `env.*` helpers coerce from
+`env.*` helpers - handy for a shape the helpers don't cover. Only the `env.*` helpers coerce from
 strings, though: a plain `t.number()` would see the raw string, so reach for `env.number()` when you
 need coercion.
 
 ## Edge runtimes
 
-`defineEnv` reads `process.env` by default (Bun/Node). Cloudflare Workers has no `process.env` —
+`defineEnv` reads `process.env` by default (Bun/Node). Cloudflare Workers has no `process.env` -
 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
+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.
 
 ## For AI agents
 
-Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
 one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the

package/dist/define.d.ts

@@ -1,25 +1,25 @@
 import type { InferOutput, StandardSchemaV1 } from "./schema.js";
 /** A schema per variable name. */
 export type EnvShape = Record<string, StandardSchemaV1>;
-/** The frozen, validated result — each key typed by its schema's output. */
+/** The frozen, validated result - each key typed by its schema's output. */
 export type EnvResult<S extends EnvShape> = {
     readonly [K in keyof S]: InferOutput<S[K]>;
 };
 export interface DefineEnvOptions {
     /**
      * Where to read variables from. Defaults to `process.env` (Bun/Node). On Cloudflare Workers there
-     * is no `process.env` — pass the request's `env` bindings: `defineEnv(shape, { source: env })`.
+     * is no `process.env` - pass the request's `env` bindings: `defineEnv(shape, { source: env })`.
      */
     readonly source?: Record<string, string | undefined>;
 }
 /**
- * Validate the environment against a schema and return a **frozen, typed** object — or throw at
+ * 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
  * loud and immediately instead of erroring on the first request that touches a bad var. This is the
  * boot-time half of nifra's "validate at every boundary" rule, for config.
  *
  * ```ts
- * // env.ts — imported once at startup
+ * // env.ts - imported once at startup
  * import { defineEnv, env } from "@nifrajs/env"
  * export const ENV = defineEnv({
  *   DATABASE_URL: env.url(),
@@ -31,9 +31,9 @@ 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). BYO
+ * 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.
+ * `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.js

@@ -1,11 +1,11 @@
 /**
- * Validate the environment against a schema and return a **frozen, typed** object — or throw at
+ * 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
  * loud and immediately instead of erroring on the first request that touches a bad var. This is the
  * boot-time half of nifra's "validate at every boundary" rule, for config.
  *
  * ```ts
- * // env.ts — imported once at startup
+ * // env.ts - imported once at startup
  * import { defineEnv, env } from "@nifrajs/env"
  * export const ENV = defineEnv({
  *   DATABASE_URL: env.url(),
@@ -17,9 +17,9 @@
  * // 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). BYO
+ * 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.
+ * `t.number()` would see the raw string - use `env.number()` for coercion.
  */
 export function defineEnv(shape, options) {
     const source = options?.source ??
@@ -31,7 +31,7 @@ export function defineEnv(shape, options) {
         const schema = shape[key];
         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
+            // 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.
             problems.push(`  ${key}: async validators are not supported in defineEnv`);
             continue;
@@ -45,7 +45,7 @@ export function defineEnv(shape, options) {
         }
     }
     if (problems.length > 0) {
-        throw new Error(`[nifra/env] invalid environment — ${problems.length} problem(s):\n${problems.join("\n")}\n\nSet the variable(s) above and restart.`);
+        throw new Error(`[nifra/env] invalid environment - ${problems.length} problem(s):\n${problems.join("\n")}\n\nSet the variable(s) above and restart.`);
     }
     return Object.freeze(out);
 }

package/dist/helpers.d.ts

@@ -1,10 +1,10 @@
 /**
  * Coercing env validators. Every value in `process.env` is a `string | undefined`, so these turn
- * that into the typed value you actually want — with defaults, optionality, and clear errors. Each
+ * that into the typed value you actually want - with defaults, optionality, and clear errors. Each
  * is a Standard Schema, so they slot straight into {@link defineEnv} (and could be used anywhere a
  * Standard Schema is accepted).
  *
- * Error messages are **value-free** — they say what was wrong, never echo the variable's value
+ * Error messages are **value-free** - they say what was wrong, never echo the variable's value
  * (it may be a secret). {@link defineEnv} prepends the variable name.
  */
 import { type StandardSchemaV1 } from "./schema.js";
@@ -20,7 +20,7 @@ interface Optional {
 export declare function string(opts?: Base<string> & Optional): StandardSchemaV1<string | undefined>;
 /** A finite number, coerced from its decimal string. */
 export declare function number(opts?: Base<number> & Optional): StandardSchemaV1<number | undefined>;
-/** A TCP port: an integer in 1–65535. */
+/** A TCP port: an integer in 1-65535. */
 export declare function port(opts?: Base<number>): StandardSchemaV1<number>;
 /** A boolean: `true`/`1`/`yes`/`on` → true; `false`/`0`/`no`/`off`/empty → false (case-insensitive). */
 export declare function boolean(opts?: Base<boolean>): StandardSchemaV1<boolean>;
@@ -28,7 +28,7 @@ export declare function boolean(opts?: Base<boolean>): StandardSchemaV1<boolean>
 export declare function enumValue<const V extends readonly [string, ...string[]]>(values: V, opts?: Base<V[number]>): StandardSchemaV1<V[number]>;
 /** A valid absolute URL (parses with the WHATWG `URL`). Returns the normalized href string. */
 export declare function url(opts?: Base<string> & Optional): StandardSchemaV1<string | undefined>;
-/** The coercing env validators, grouped — `env.string()`, `env.port()`, `env.enum([...])`, … */
+/** The coercing env validators, grouped - `env.string()`, `env.port()`, `env.enum([...])`, … */
 export declare const env: {
     string: typeof string;
     number: typeof number;

package/dist/helpers.js

@@ -1,10 +1,10 @@
 /**
  * Coercing env validators. Every value in `process.env` is a `string | undefined`, so these turn
- * that into the typed value you actually want — with defaults, optionality, and clear errors. Each
+ * that into the typed value you actually want - with defaults, optionality, and clear errors. Each
  * is a Standard Schema, so they slot straight into {@link defineEnv} (and could be used anywhere a
  * Standard Schema is accepted).
  *
- * Error messages are **value-free** — they say what was wrong, never echo the variable's value
+ * Error messages are **value-free** - they say what was wrong, never echo the variable's value
  * (it may be a secret). {@link defineEnv} prepends the variable name.
  */
 import { envSchema, issue } from "./schema.js";
@@ -38,7 +38,7 @@ export function number(opts = {}) {
         return { value: n };
     });
 }
-/** A TCP port: an integer in 1–65535. */
+/** A TCP port: an integer in 1-65535. */
 export function port(opts = {}) {
     return envSchema((raw) => {
         if (isUnset(raw)) {
@@ -48,7 +48,7 @@ export function port(opts = {}) {
         }
         const n = Number(raw);
         if (!Number.isInteger(n) || n < 1 || n > 65535) {
-            return issue("must be an integer port in 1–65535");
+            return issue("must be an integer port in 1-65535");
         }
         return { value: n };
     });
@@ -103,7 +103,7 @@ export function url(opts = {}) {
         }
     });
 }
-/** The coercing env validators, grouped — `env.string()`, `env.port()`, `env.enum([...])`, … */
+/** The coercing env validators, grouped - `env.string()`, `env.port()`, `env.enum([...])`, … */
 export const env = {
     string,
     number,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/env — typed, validated environment variables. Define a schema once at startup; get a
+ * @nifrajs/env - typed, validated environment variables. Define a schema once at startup; get a
  * frozen typed object, or a loud boot-time failure listing every problem. Coercing helpers
  * (`env.number`/`port`/`boolean`/`url`/`enum`) turn `string | undefined` into the value you want;
  * any Standard Schema (`t`, zod, valibot) is also accepted. Dependency-free, edge-safe.

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/env — typed, validated environment variables. Define a schema once at startup; get a
+ * @nifrajs/env - typed, validated environment variables. Define a schema once at startup; get a
  * frozen typed object, or a loud boot-time failure listing every problem. Coercing helpers
  * (`env.number`/`port`/`boolean`/`url`/`enum`) turn `string | undefined` into the value you want;
  * any Standard Schema (`t`, zod, valibot) is also accepted. Dependency-free, edge-safe.

package/dist/schema.d.ts

@@ -26,7 +26,7 @@ export interface StandardSchemaV1<Output = unknown> {
 export type InferOutput<S extends StandardSchemaV1> = NonNullable<S["~standard"]["types"]>["output"];
 /** Build an env validator: a Standard Schema whose `validate` coerces from `string | undefined`. */
 export declare function envSchema<Output>(validate: (raw: string | undefined) => StandardResult<Output>): StandardSchemaV1<Output>;
-/** A single issue. Messages NEVER include the variable's value — it may be a secret. */
+/** A single issue. Messages NEVER include the variable's value - it may be a secret. */
 export declare const issue: (message: string) => {
     readonly issues: ReadonlyArray<StandardIssue>;
 };

package/dist/schema.js

@@ -15,7 +15,7 @@ export function envSchema(validate) {
         },
     };
 }
-/** A single issue. Messages NEVER include the variable's value — it may be a secret. */
+/** A single issue. Messages NEVER include the variable's value - it may be a secret. */
 export const issue = (message) => ({
     issues: [{ message }],
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/env",
-  "version": "2.2.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.",
+  "version": "2.4.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",
     "typescript",

package/src/define.ts

@@ -3,25 +3,25 @@ import type { InferOutput, StandardSchemaV1 } from "./schema.ts"
 /** A schema per variable name. */
 export type EnvShape = Record<string, StandardSchemaV1>
 
-/** The frozen, validated result — each key typed by its schema's output. */
+/** The frozen, validated result - each key typed by its schema's output. */
 export type EnvResult<S extends EnvShape> = { readonly [K in keyof S]: InferOutput<S[K]> }
 
 export interface DefineEnvOptions {
   /**
    * Where to read variables from. Defaults to `process.env` (Bun/Node). On Cloudflare Workers there
-   * is no `process.env` — pass the request's `env` bindings: `defineEnv(shape, { source: env })`.
+   * is no `process.env` - pass the request's `env` bindings: `defineEnv(shape, { source: env })`.
    */
   readonly source?: Record<string, string | undefined>
 }
 
 /**
- * Validate the environment against a schema and return a **frozen, typed** object — or throw at
+ * 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
  * loud and immediately instead of erroring on the first request that touches a bad var. This is the
  * boot-time half of nifra's "validate at every boundary" rule, for config.
  *
  * ```ts
- * // env.ts — imported once at startup
+ * // env.ts - imported once at startup
  * import { defineEnv, env } from "@nifrajs/env"
  * export const ENV = defineEnv({
  *   DATABASE_URL: env.url(),
@@ -33,9 +33,9 @@ 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). BYO
+ * 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.
+ * `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 =
@@ -49,7 +49,7 @@ export function defineEnv<S extends EnvShape>(shape: S, options?: DefineEnvOptio
     const schema = shape[key] as StandardSchemaV1
     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
+      // 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.
       problems.push(`  ${key}: async validators are not supported in defineEnv`)
       continue
@@ -63,7 +63,7 @@ export function defineEnv<S extends EnvShape>(shape: S, options?: DefineEnvOptio
 
   if (problems.length > 0) {
     throw new Error(
-      `[nifra/env] invalid environment — ${problems.length} problem(s):\n${problems.join("\n")}\n\nSet the variable(s) above and restart.`,
+      `[nifra/env] invalid environment - ${problems.length} problem(s):\n${problems.join("\n")}\n\nSet the variable(s) above and restart.`,
     )
   }
   return Object.freeze(out) as EnvResult<S>

package/src/helpers.ts

@@ -1,10 +1,10 @@
 /**
  * Coercing env validators. Every value in `process.env` is a `string | undefined`, so these turn
- * that into the typed value you actually want — with defaults, optionality, and clear errors. Each
+ * that into the typed value you actually want - with defaults, optionality, and clear errors. Each
  * is a Standard Schema, so they slot straight into {@link defineEnv} (and could be used anywhere a
  * Standard Schema is accepted).
  *
- * Error messages are **value-free** — they say what was wrong, never echo the variable's value
+ * Error messages are **value-free** - they say what was wrong, never echo the variable's value
  * (it may be a secret). {@link defineEnv} prepends the variable name.
  */
 
@@ -47,7 +47,7 @@ export function number(opts: Base<number> & Optional = {}): StandardSchemaV1<num
   })
 }
 
-/** A TCP port: an integer in 1–65535. */
+/** A TCP port: an integer in 1-65535. */
 export function port(opts: Base<number> = {}): StandardSchemaV1<number> {
   return envSchema((raw) => {
     if (isUnset(raw)) {
@@ -56,7 +56,7 @@ export function port(opts: Base<number> = {}): StandardSchemaV1<number> {
     }
     const n = Number(raw)
     if (!Number.isInteger(n) || n < 1 || n > 65535) {
-      return issue("must be an integer port in 1–65535")
+      return issue("must be an integer port in 1-65535")
     }
     return { value: n }
   }) as StandardSchemaV1<number>
@@ -111,7 +111,7 @@ export function url(opts: Base<string> & Optional = {}): StandardSchemaV1<string
   })
 }
 
-/** The coercing env validators, grouped — `env.string()`, `env.port()`, `env.enum([...])`, … */
+/** The coercing env validators, grouped - `env.string()`, `env.port()`, `env.enum([...])`, … */
 export const env = {
   string,
   number,

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @nifrajs/env — typed, validated environment variables. Define a schema once at startup; get a
+ * @nifrajs/env - typed, validated environment variables. Define a schema once at startup; get a
  * frozen typed object, or a loud boot-time failure listing every problem. Coercing helpers
  * (`env.number`/`port`/`boolean`/`url`/`enum`) turn `string | undefined` into the value you want;
  * any Standard Schema (`t`, zod, valibot) is also accepted. Dependency-free, edge-safe.

package/src/schema.ts

@@ -39,7 +39,7 @@ export function envSchema<Output>(
   }
 }
 
-/** A single issue. Messages NEVER include the variable's value — it may be a secret. */
+/** A single issue. Messages NEVER include the variable's value - it may be a secret. */
 export const issue = (message: string): { readonly issues: ReadonlyArray<StandardIssue> } => ({
   issues: [{ message }],
 })