@nifrajs/env 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nifra Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @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
+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
+import { defineEnv, env } from "@nifrajs/env"
+
+export const ENV = defineEnv({
+  DATABASE_URL: env.url(),
+  PORT: env.port({ default: 3000 }),
+  NODE_ENV: env.enum(["development", "production", "test"], { default: "development" }),
+  STRIPE_SECRET: env.string(),
+  DEBUG: env.boolean({ default: false }),
+  SENTRY_DSN: env.url({ optional: true }),
+})
+
+// ENV.PORT      → number
+// ENV.NODE_ENV  → "development" | "production" | "test"
+// ENV.DEBUG     → boolean
+// ENV.SENTRY_DSN → string | undefined
+```
+
+A missing/invalid var fails at import:
+
+```
+[nifra/env] invalid environment — 2 problem(s):
+  DATABASE_URL: must be a valid URL
+  STRIPE_SECRET: is required
+
+Set the variable(s) above and restart.
+```
+
+## Coercing helpers
+
+Every value in `process.env` is a `string | undefined`; these turn it into the value you want:
+
+| helper | type | notes |
+| --- | --- | --- |
+| `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.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 |
+
+`optional: true` makes the type `T | undefined`; `default` supplies a fallback when unset.
+
+## 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
+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` —
+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.

package/dist/define.d.ts

@@ -0,0 +1,39 @@
+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. */
+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 })`.
+     */
+    readonly source?: Record<string, string | undefined>;
+}
+/**
+ * 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
+ * import { defineEnv, env } from "@nifrajs/env"
+ * export const ENV = defineEnv({
+ *   DATABASE_URL: env.url(),
+ *   PORT: env.port({ default: 3000 }),
+ *   NODE_ENV: env.enum(["development", "production", "test"], { default: "development" }),
+ *   STRIPE_SECRET: env.string(),
+ *   DEBUG: env.boolean({ default: false }),
+ * })
+ * // 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
+ * 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.
+ */
+export declare function defineEnv<S extends EnvShape>(shape: S, options?: DefineEnvOptions): EnvResult<S>;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +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"}

package/dist/define.js

@@ -0,0 +1,52 @@
+/**
+ * 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
+ * import { defineEnv, env } from "@nifrajs/env"
+ * export const ENV = defineEnv({
+ *   DATABASE_URL: env.url(),
+ *   PORT: env.port({ default: 3000 }),
+ *   NODE_ENV: env.enum(["development", "production", "test"], { default: "development" }),
+ *   STRIPE_SECRET: env.string(),
+ *   DEBUG: env.boolean({ default: false }),
+ * })
+ * // 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
+ * 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.
+ */
+export function defineEnv(shape, options) {
+    const source = options?.source ??
+        globalThis.process?.env ??
+        {};
+    const out = {};
+    const problems = [];
+    for (const key of Object.keys(shape)) {
+        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
+            // configuration mistake, surfaced as a problem rather than an unhandled promise.
+            problems.push(`  ${key}: async validators are not supported in defineEnv`);
+            continue;
+        }
+        if (result.issues !== undefined) {
+            for (const i of result.issues)
+                problems.push(`  ${key}: ${i.message}`);
+        }
+        else {
+            out[key] = result.value;
+        }
+    }
+    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.`);
+    }
+    return Object.freeze(out);
+}
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +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"}

package/dist/helpers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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
+ * 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
+ * (it may be a secret). {@link defineEnv} prepends the variable name.
+ */
+import { type StandardSchemaV1 } from "./schema.js";
+interface Base<T> {
+    /** Used when the variable is unset/empty. Makes the variable optional-with-a-fallback. */
+    readonly default?: T;
+}
+interface Optional {
+    /** When true, an unset variable yields `undefined` instead of being an error. */
+    readonly optional?: boolean;
+}
+/** A required (or defaulted/optional) non-empty string. */
+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. */
+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>;
+/** One of a fixed set of string values. */
+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([...])`, … */
+export declare const env: {
+    string: typeof string;
+    number: typeof number;
+    port: typeof port;
+    boolean: typeof boolean;
+    enum: typeof enumValue;
+    url: typeof url;
+};
+export {};
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAErE,UAAU,IAAI,CAAC,CAAC;IACd,0FAA0F;IAC1F,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;CACrB;AACD,UAAU,QAAQ;IAChB,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC5B;AAID,2DAA2D;AAC3D,wBAAgB,MAAM,CAAC,IAAI,GAAE,IAAI,CAAC,MAAM,CAAC,GAAG,QAAa,GAAG,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC,CAS/F;AAED,wDAAwD;AACxD,wBAAgB,MAAM,CAAC,IAAI,GAAE,IAAI,CAAC,MAAM,CAAC,GAAG,QAAa,GAAG,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC,CAW/F;AAED,yCAAyC;AACzC,wBAAgB,IAAI,CAAC,IAAI,GAAE,IAAI,CAAC,MAAM,CAAM,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAYtE;AAKD,wGAAwG;AACxG,wBAAgB,OAAO,CAAC,IAAI,GAAE,IAAI,CAAC,OAAO,CAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAW3E;AAED,2CAA2C;AAC3C,wBAAgB,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,EACtE,MAAM,EAAE,CAAC,EACT,IAAI,GAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAM,GACzB,gBAAgB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAU7B;AAED,+FAA+F;AAC/F,wBAAgB,GAAG,CAAC,IAAI,GAAE,IAAI,CAAC,MAAM,CAAC,GAAG,QAAa,GAAG,gBAAgB,CAAC,MAAM,GAAG,SAAS,CAAC,CAa5F;AAED,gGAAgG;AAChG,eAAO,MAAM,GAAG;;;;;;;CAOf,CAAA"}

package/dist/helpers.js

@@ -0,0 +1,115 @@
+/**
+ * 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
+ * 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
+ * (it may be a secret). {@link defineEnv} prepends the variable name.
+ */
+import { envSchema, issue } from "./schema.js";
+const isUnset = (raw) => raw === undefined || raw === "";
+/** A required (or defaulted/optional) non-empty string. */
+export function string(opts = {}) {
+    return envSchema((raw) => {
+        if (isUnset(raw)) {
+            if (opts.default !== undefined)
+                return { value: opts.default };
+            if (opts.optional)
+                return { value: undefined };
+            return issue("is required");
+        }
+        return { value: raw };
+    });
+}
+/** A finite number, coerced from its decimal string. */
+export function number(opts = {}) {
+    return envSchema((raw) => {
+        if (isUnset(raw)) {
+            if (opts.default !== undefined)
+                return { value: opts.default };
+            if (opts.optional)
+                return { value: undefined };
+            return issue("is required");
+        }
+        const n = Number(raw);
+        if (!Number.isFinite(n))
+            return issue("must be a number");
+        return { value: n };
+    });
+}
+/** A TCP port: an integer in 1–65535. */
+export function port(opts = {}) {
+    return envSchema((raw) => {
+        if (isUnset(raw)) {
+            if (opts.default !== undefined)
+                return { value: opts.default };
+            return issue("is required");
+        }
+        const n = Number(raw);
+        if (!Number.isInteger(n) || n < 1 || n > 65535) {
+            return issue("must be an integer port in 1–65535");
+        }
+        return { value: n };
+    });
+}
+const TRUE = new Set(["true", "1", "yes", "on"]);
+const FALSE = new Set(["false", "0", "no", "off", ""]);
+/** A boolean: `true`/`1`/`yes`/`on` → true; `false`/`0`/`no`/`off`/empty → false (case-insensitive). */
+export function boolean(opts = {}) {
+    return envSchema((raw) => {
+        if (raw === undefined) {
+            if (opts.default !== undefined)
+                return { value: opts.default };
+            return issue("is required");
+        }
+        const v = raw.trim().toLowerCase();
+        if (TRUE.has(v))
+            return { value: true };
+        if (FALSE.has(v))
+            return { value: false };
+        return issue("must be a boolean (true/false/1/0/yes/no/on/off)");
+    });
+}
+/** One of a fixed set of string values. */
+export function enumValue(values, opts = {}) {
+    const set = new Set(values);
+    return envSchema((raw) => {
+        if (raw === undefined || raw === "") {
+            if (opts.default !== undefined)
+                return { value: opts.default };
+            return issue(`is required (one of: ${values.join(", ")})`);
+        }
+        if (!set.has(raw))
+            return issue(`must be one of: ${values.join(", ")}`);
+        return { value: raw };
+    });
+}
+/** A valid absolute URL (parses with the WHATWG `URL`). Returns the normalized href string. */
+export function url(opts = {}) {
+    return envSchema((raw) => {
+        if (raw === undefined || raw === "") {
+            if (opts.default !== undefined)
+                return { value: opts.default };
+            if (opts.optional)
+                return { value: undefined };
+            return issue("is required");
+        }
+        try {
+            return { value: new URL(raw).href };
+        }
+        catch {
+            return issue("must be a valid URL");
+        }
+    });
+}
+/** The coercing env validators, grouped — `env.string()`, `env.port()`, `env.enum([...])`, … */
+export const env = {
+    string,
+    number,
+    port,
+    boolean,
+    enum: enumValue,
+    url,
+};
+//# sourceMappingURL=helpers.js.map

package/dist/helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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.
+ */
+export { type DefineEnvOptions, defineEnv, type EnvResult, type EnvShape } from "./define.js";
+export { boolean, enumValue, env, number, port, string, url } from "./helpers.js";
+export type { InferOutput, StandardResult, StandardSchemaV1 } from "./schema.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,gBAAgB,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAA;AAC7F,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,cAAc,CAAA;AACjF,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @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.
+ */
+export { defineEnv } from "./define.js";
+export { boolean, enumValue, env, number, port, string, url } from "./helpers.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAyB,SAAS,EAAiC,MAAM,aAAa,CAAA;AAC7F,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,cAAc,CAAA"}

package/dist/schema.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Minimal Standard Schema surface (the public https://standardschema.dev v1 spec), inlined so
+ * `@nifrajs/env` stays dependency-free and accepts validators from `t` (@nifrajs/schema), zod, valibot,
+ * or its own coercing `env.*` helpers interchangeably.
+ */
+export interface StandardIssue {
+    readonly message: string;
+}
+export type StandardResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardIssue>;
+};
+export interface StandardSchemaV1<Output = unknown> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>;
+        readonly types?: {
+            readonly output: Output;
+        };
+    };
+}
+/** Extract a Standard Schema's validated output type. */
+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. */
+export declare const issue: (message: string) => {
+    readonly issues: ReadonlyArray<StandardIssue>;
+};
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,MAAM,cAAc,CAAC,MAAM,IAC7B;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CAAE,CAAA;AAErD,MAAM,WAAW,gBAAgB,CAAC,MAAM,GAAG,OAAO;IAChD,QAAQ,CAAC,WAAW,EAAE;QACpB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;QACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,cAAc,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAA;QAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE;YAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAC7C,CAAA;CACF;AAED,yDAAyD;AACzD,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,gBAAgB,IAAI,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAA;AAEpG,oGAAoG;AACpG,wBAAgB,SAAS,CAAC,MAAM,EAC9B,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,KAAK,cAAc,CAAC,MAAM,CAAC,GAC5D,gBAAgB,CAAC,MAAM,CAAC,CAU1B;AAED,wFAAwF;AACxF,eAAO,MAAM,KAAK,GAAI,SAAS,MAAM,KAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,aAAa,CAAC,CAAA;CAErF,CAAA"}

package/dist/schema.js

@@ -0,0 +1,22 @@
+/**
+ * Minimal Standard Schema surface (the public https://standardschema.dev v1 spec), inlined so
+ * `@nifrajs/env` stays dependency-free and accepts validators from `t` (@nifrajs/schema), zod, valibot,
+ * or its own coercing `env.*` helpers interchangeably.
+ */
+/** Build an env validator: a Standard Schema whose `validate` coerces from `string | undefined`. */
+export function envSchema(validate) {
+    return {
+        "~standard": {
+            version: 1,
+            vendor: "nifra-env",
+            validate: (value) => validate(value),
+            // Phantom: carries the output type for InferOutput; no runtime value.
+            types: undefined,
+        },
+    };
+}
+/** A single issue. Messages NEVER include the variable's value — it may be a secret. */
+export const issue = (message) => ({
+    issues: [{ message }],
+});
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsBH,oGAAoG;AACpG,MAAM,UAAU,SAAS,CACvB,QAA6D;IAE7D,OAAO;QACL,WAAW,EAAE;YACX,OAAO,EAAE,CAAC;YACV,MAAM,EAAE,WAAW;YACnB,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAA2B,CAAC;YAC1D,sEAAsE;YACtE,KAAK,EAAE,SAAmD;SAC3D;KACF,CAAA;AACH,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,OAAe,EAAqD,EAAE,CAAC,CAAC;IAC5F,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@nifrajs/env",
+  "version": "0.1.0-alpha.1",
+  "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",
+    "nifra",
+    "web-framework",
+    "full-stack",
+    "edge",
+    "ssr"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/env"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/define.ts

@@ -0,0 +1,70 @@
+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. */
+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 })`.
+   */
+  readonly source?: Record<string, string | undefined>
+}
+
+/**
+ * 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
+ * import { defineEnv, env } from "@nifrajs/env"
+ * export const ENV = defineEnv({
+ *   DATABASE_URL: env.url(),
+ *   PORT: env.port({ default: 3000 }),
+ *   NODE_ENV: env.enum(["development", "production", "test"], { default: "development" }),
+ *   STRIPE_SECRET: env.string(),
+ *   DEBUG: env.boolean({ default: false }),
+ * })
+ * // 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
+ * 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.
+ */
+export function defineEnv<S extends EnvShape>(shape: S, options?: DefineEnvOptions): EnvResult<S> {
+  const source =
+    options?.source ??
+    (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ??
+    {}
+  const out: Record<string, unknown> = {}
+  const problems: string[] = []
+
+  for (const key of Object.keys(shape)) {
+    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
+      // configuration mistake, surfaced as a problem rather than an unhandled promise.
+      problems.push(`  ${key}: async validators are not supported in defineEnv`)
+      continue
+    }
+    if (result.issues !== undefined) {
+      for (const i of result.issues) problems.push(`  ${key}: ${i.message}`)
+    } else {
+      out[key] = result.value
+    }
+  }
+
+  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.`,
+    )
+  }
+  return Object.freeze(out) as EnvResult<S>
+}

package/src/helpers.ts

@@ -0,0 +1,122 @@
+/**
+ * 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
+ * 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
+ * (it may be a secret). {@link defineEnv} prepends the variable name.
+ */
+
+import { envSchema, issue, type StandardSchemaV1 } from "./schema.ts"
+
+interface Base<T> {
+  /** Used when the variable is unset/empty. Makes the variable optional-with-a-fallback. */
+  readonly default?: T
+}
+interface Optional {
+  /** When true, an unset variable yields `undefined` instead of being an error. */
+  readonly optional?: boolean
+}
+
+const isUnset = (raw: string | undefined): boolean => raw === undefined || raw === ""
+
+/** A required (or defaulted/optional) non-empty string. */
+export function string(opts: Base<string> & Optional = {}): StandardSchemaV1<string | undefined> {
+  return envSchema((raw) => {
+    if (isUnset(raw)) {
+      if (opts.default !== undefined) return { value: opts.default }
+      if (opts.optional) return { value: undefined }
+      return issue("is required")
+    }
+    return { value: raw }
+  })
+}
+
+/** A finite number, coerced from its decimal string. */
+export function number(opts: Base<number> & Optional = {}): StandardSchemaV1<number | undefined> {
+  return envSchema((raw) => {
+    if (isUnset(raw)) {
+      if (opts.default !== undefined) return { value: opts.default }
+      if (opts.optional) return { value: undefined }
+      return issue("is required")
+    }
+    const n = Number(raw)
+    if (!Number.isFinite(n)) return issue("must be a number")
+    return { value: n }
+  })
+}
+
+/** A TCP port: an integer in 1–65535. */
+export function port(opts: Base<number> = {}): StandardSchemaV1<number> {
+  return envSchema((raw) => {
+    if (isUnset(raw)) {
+      if (opts.default !== undefined) return { value: opts.default }
+      return issue("is required")
+    }
+    const n = Number(raw)
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+      return issue("must be an integer port in 1–65535")
+    }
+    return { value: n }
+  }) as StandardSchemaV1<number>
+}
+
+const TRUE = new Set(["true", "1", "yes", "on"])
+const FALSE = new Set(["false", "0", "no", "off", ""])
+
+/** A boolean: `true`/`1`/`yes`/`on` → true; `false`/`0`/`no`/`off`/empty → false (case-insensitive). */
+export function boolean(opts: Base<boolean> = {}): StandardSchemaV1<boolean> {
+  return envSchema((raw) => {
+    if (raw === undefined) {
+      if (opts.default !== undefined) return { value: opts.default }
+      return issue("is required")
+    }
+    const v = raw.trim().toLowerCase()
+    if (TRUE.has(v)) return { value: true }
+    if (FALSE.has(v)) return { value: false }
+    return issue("must be a boolean (true/false/1/0/yes/no/on/off)")
+  }) as StandardSchemaV1<boolean>
+}
+
+/** One of a fixed set of string values. */
+export function enumValue<const V extends readonly [string, ...string[]]>(
+  values: V,
+  opts: Base<V[number]> = {},
+): StandardSchemaV1<V[number]> {
+  const set = new Set<string>(values)
+  return envSchema((raw) => {
+    if (raw === undefined || raw === "") {
+      if (opts.default !== undefined) return { value: opts.default }
+      return issue(`is required (one of: ${values.join(", ")})`)
+    }
+    if (!set.has(raw)) return issue(`must be one of: ${values.join(", ")}`)
+    return { value: raw as V[number] }
+  }) as StandardSchemaV1<V[number]>
+}
+
+/** A valid absolute URL (parses with the WHATWG `URL`). Returns the normalized href string. */
+export function url(opts: Base<string> & Optional = {}): StandardSchemaV1<string | undefined> {
+  return envSchema((raw) => {
+    if (raw === undefined || raw === "") {
+      if (opts.default !== undefined) return { value: opts.default }
+      if (opts.optional) return { value: undefined }
+      return issue("is required")
+    }
+    try {
+      return { value: new URL(raw).href }
+    } catch {
+      return issue("must be a valid URL")
+    }
+  })
+}
+
+/** The coercing env validators, grouped — `env.string()`, `env.port()`, `env.enum([...])`, … */
+export const env = {
+  string,
+  number,
+  port,
+  boolean,
+  enum: enumValue,
+  url,
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @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.
+ */
+
+export { type DefineEnvOptions, defineEnv, type EnvResult, type EnvShape } from "./define.ts"
+export { boolean, enumValue, env, number, port, string, url } from "./helpers.ts"
+export type { InferOutput, StandardResult, StandardSchemaV1 } from "./schema.ts"

package/src/schema.ts

@@ -0,0 +1,45 @@
+/**
+ * Minimal Standard Schema surface (the public https://standardschema.dev v1 spec), inlined so
+ * `@nifrajs/env` stays dependency-free and accepts validators from `t` (@nifrajs/schema), zod, valibot,
+ * or its own coercing `env.*` helpers interchangeably.
+ */
+
+export interface StandardIssue {
+  readonly message: string
+}
+
+export type StandardResult<Output> =
+  | { readonly value: Output; readonly issues?: undefined }
+  | { readonly issues: ReadonlyArray<StandardIssue> }
+
+export interface StandardSchemaV1<Output = unknown> {
+  readonly "~standard": {
+    readonly version: 1
+    readonly vendor: string
+    readonly validate: (value: unknown) => StandardResult<Output> | Promise<StandardResult<Output>>
+    readonly types?: { readonly output: Output }
+  }
+}
+
+/** Extract a Standard Schema's validated output type. */
+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 function envSchema<Output>(
+  validate: (raw: string | undefined) => StandardResult<Output>,
+): StandardSchemaV1<Output> {
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "nifra-env",
+      validate: (value) => validate(value as string | undefined),
+      // Phantom: carries the output type for InferOutput; no runtime value.
+      types: undefined as unknown as { readonly output: Output },
+    },
+  }
+}
+
+/** 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 }],
+})