@ayepi/env 0.4.1 → 0.5.0

package/README.md

@@ -100,6 +100,18 @@ env({
 })
 ```
 
+## Slices, prefixes and `.env.example`
+
+```ts
+import { env, envExample, mergeEnvs } from '@ayepi/env'
+
+const http = env({ PORT: z.number().default(3000).describe('Where to listen.') }, { prefix: 'APP_' }) // reads APP_PORT
+const db = env({ DB_FILE: z.string().default('app.sqlite') }, { prefix: 'APP_' })
+const settings = mergeEnvs(http, db)       // one typed view; a field in two slices fails to compile
+settings.parse()                           // one EnvError listing every bad field
+envExample(settings.describe())            // '# Where to listen.\nAPP_PORT=3000\n\nAPP_DB_FILE=app.sqlite\n'
+```
+
 ## Reactivity — `on(...)`
 
 Subscribe to the changes a `set(...)` (or a provider, in `asyncEnv`) causes. Computed fields update

package/ayepi-env.md

@@ -27,8 +27,9 @@ pnpm add @ayepi/env zod
 ## Two entry points
 
 - **`@ayepi/env`** — `env` (sync) and `asyncEnv` (async + providers); the `dynamic` / `pollProvider`
-  / `staticProvider` providers; `alias` (+ `varsOf`); the `coerce` primitive; `parseDotenv` (pure
-  string parser); `EnvError` and source helpers.
+  / `staticProvider` providers; `alias` (+ `varsOf`, `sourceKeyOf`); `mergeEnvs` (one view over
+  several slices); `envExample`; the `coerce` primitive; `parseDotenv` (pure string parser);
+  `EnvError` and source helpers.
 - **`@ayepi/env/load`** — `loadEnv` / `readEnvFile` (read `.env` + `.json` files into a source;
   the only `node:fs` user).
 
@@ -41,8 +42,18 @@ function env(input: EnvInput, options?: EnvOptions): Env<T>
 
 type EnvInput<Inherited> = Record<string, z.ZodType | ((inherited: Inherited) => z.ZodType | any)>
 
-interface Env<T> {
+interface EnvOptions {
+  prefix?: string                             // field PORT reads `${prefix}PORT` (aliases are read as written)
+  booleans?: { true?: string[]; false?: string[] }
+}
+
+interface Env<T> extends EnvView<T> {
   add<A>(input: A): Env<T & EnvOutput<…>>     // widen with more fields (factories see earlier fields)
+  with(fn: (env: Env<T>) => void): void       // run a side effect with the env
+  map<R>(fn: (env: Env<T>) => R): R           // run a fn with the env, return its result
+}
+
+interface EnvView<T> {                        // what Env and a mergeEnvs view share
   get<K extends keyof T>(key: K): T[K]        // resolve one field (lazy); throws EnvError if invalid
   set<K extends keyof T>(key: K, value: T[K] | string): void
   set(updates: { [K in keyof T]?: T[K] | string } & Record<string, unknown>): void
@@ -50,8 +61,7 @@ interface Env<T> {
   on(listener: (key, value) => void, opts?): () => void          // any field
   on<K>(key: K, listener: (value) => void, opts?): () => void    // one field
   on<K>(keys: K[], listener: (value) => void, opts?): () => void // several fields
-  with(fn: (env: Env<T>) => void): void       // run a side effect with the env
-  map<R>(fn: (env: Env<T>) => R): R           // run a fn with the env, return its result
+  describe(): readonly EnvFieldInfo[]         // every field: keys read, required, description, default, JSON Schema
 }
 ```
 
@@ -96,11 +106,15 @@ resolves every field and throws a single `EnvError` aggregating **all** failures
 ## `set(...)` and the source
 
 The live source is `process.env` (or `{}` off-Node) with your `set(...)` overrides merged **on top**
-(overrides win). `set(key, value)` and `set(updates)` both write into the override layer.
+(overrides win). `set(key, value)` and `set(updates)` both write into the override layer, which is
+keyed by **source key**.
 
 - Pass a **typed value** or a **raw string** — strings are coerced, typed values pass through.
-- `set(updates)` accepts known fields *and* arbitrary source keys (e.g. pass the whole `process.env`
-  or a loaded `.env`), so it composes with aliasing.
+- `set(key, value)` with a field's name writes under the first key that field reads (its prefixed
+  name, or its first alias — `sourceKeyOf(schema, key, prefix)`), so it always reaches the field.
+  A key that names no field is written as given.
+- `set(updates)` takes source keys as given (e.g. pass the whole `process.env` or a loaded
+  `.env`), so it composes with prefixes and aliasing.
 
 ```ts
 ENV.set('PORT', 8080)                  // typed
@@ -121,7 +135,62 @@ env({
 })
 ```
 
-`varsOf(schema, key)` (exported) returns the resolved key list.
+`varsOf(schema, key, prefix?)` (exported) returns the resolved key list.
+
+## Prefix — one namespace for every key
+
+`env(input, { prefix: 'APP_' })` makes field `PORT` read `APP_PORT`: the TypeScript name stays short
+and the namespace is written once. Keys named by `vars`/`var` metadata are read exactly as written
+(so an alias can reach an unprefixed key such as `PORT` from a platform). `asyncEnv` takes the same
+option.
+
+## `describe()` and `envExample(fields)`
+
+`describe()` lists every field in declaration order as an `EnvFieldInfo`:
+
+```ts
+interface EnvFieldInfo {
+  key: string                 // the field name you get()
+  vars: readonly string[]     // the source keys it reads (prefix and aliases applied); [] when computed
+  computed: boolean           // a factory that returned a plain value — reads no key
+  required: boolean           // the schema rejects a missing value (no default, not optional)
+  description?: string        // .describe(...) / .meta({ description })
+  default?: unknown           // the schema's default
+  schema?: Record<string, unknown> // JSON Schema of the accepted input (zod's toJSONSchema, io: 'input')
+}
+```
+
+A factory field is run to find its schema; if it throws (an earlier field it reads is invalid) it is
+reported as required with no `schema`. `envExample(fields)` renders the list as a commented
+`.env.example` — the description as `#` lines, `KEY=default`, `KEY=` marked `(required)`, or
+`# KEY=` when optional; computed fields are left out. A settings page can render the same list.
+
+```ts
+writeFileSync('.env.example', envExample(ENV.describe()))
+```
+
+## `mergeEnvs(...slices)` — one view over several configs
+
+A large app configures each module with its own slice. `mergeEnvs(a, b, …)` joins them into one
+`EnvView` of every field; each slice stays the source of truth for its fields:
+
+- `get` and single-field `set` go to the slice that owns the field; a bulk `set(updates)` (and a
+  single `set` of a key no field has) reaches every slice.
+- `parse()` resolves every slice and throws **one** `EnvError` with every slice's issues.
+- `on(key | keys, …)` subscribes in the owning slices; `on(listener)` in every slice (a `once`
+  listener fires once per slice). The returned function unsubscribes from all of them.
+- `describe()` lists every field, slice by slice.
+- Two slices declaring the same field name is a **compile-time error** naming it (for argument
+  tuples) and throws at runtime in every case.
+
+```ts
+import { env, mergeEnvs } from '@ayepi/env'
+
+const http = env({ PORT: z.number().default(3000) }, { prefix: 'APP_' })
+const db = env({ DB_FILE: z.string().default('app.sqlite') }, { prefix: 'APP_' })
+export const settings = mergeEnvs(http, db)   // EnvView<{ PORT: number; DB_FILE: string }>
+settings.parse()
+```
 
 ## Reactivity — `on(...)`
 
@@ -289,6 +358,8 @@ off(); ENV.close()
   calls, never its own group. Split into `add(...)` steps to express dependencies.
 - **Lazy.** Values resolve on `get`/`parse`, not at declaration. `get` throws for its one field;
   `parse` aggregates all failures.
+- **`set(updates)` is source-keyed.** With a `prefix`, `set({ PORT: '1' })` sets the source key
+  `PORT`, not the field; write `set('PORT', 1)` or `set({ APP_PORT: '1' })`.
 - **`set(...)` wins over `process.env`.** The source is `{ ...process.env, ...overrides }`. To make
   files lower precedence than `process.env`, spread `process.env` last into `set(...)`.
 - **Computed value fields aren't re-validated.** A factory returning a plain value is trusted as-is;

package/dist/index.cjs

@@ -1,5 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_dotenv = require("./dotenv.cjs");
+let zod = require("zod");
 //#region src/coerce.ts
 /** Read a schema's internal `_zod.def` (zod v4 stores its definition there). */
 function def(schema) {
@@ -99,12 +100,23 @@ function coerce(schema, value, words) {
 function readMeta(schema) {
 	return schema.meta?.();
 }
-/** The source keys a field reads, in precedence order — its `vars`/`var` meta, else `[key]`. */
-function varsOf(schema, key) {
+/**
+* The source keys a field reads, in precedence order — its `vars`/`var` meta (taken as written), else
+* `[prefix + key]`.
+*/
+function varsOf(schema, key, prefix = "") {
 	const meta = readMeta(schema);
 	if (meta?.vars && meta.vars.length > 0) return meta.vars;
 	if (meta?.var) return [meta.var];
-	return [key];
+	return [prefix + key];
+}
+/**
+* The source key a field is written under by a single-field `set`: the first key it reads. `schema` is undefined for
+* a factory field, whose schema is only known once it runs; it is written under its prefixed name.
+*/
+function sourceKeyOf(schema, key, prefix = "") {
+	const meta = schema === void 0 ? void 0 : readMeta(schema);
+	return meta?.vars?.[0] ?? meta?.var ?? prefix + key;
 }
 /** Attach aliasing metadata: read `schema` from the first present of `keys`. */
 function alias(schema, ...keys) {
@@ -186,6 +198,32 @@ function changed(prev, next, deep) {
 }
 //#endregion
 //#region src/env.ts
+/**
+* # `env(...)` — the typed, lazy, reactive config builder
+*
+* Declare a config as a record of fields and get back a typed {@link Env}. A field is either:
+*
+* - a **zod schema** — read from a source key (its name, or its `vars` meta for aliasing),
+*   coerced from its string form and validated; or
+* - a **factory** `(inherited) => …` — called with the already-resolved fields from *earlier*
+*   `add(...)` groups. Return another **zod schema** (a schema that depends on other values),
+*   or return a **plain value** (a computed field derived purely from other fields).
+*
+* Resolution is **lazy**: nothing is parsed until you `get(...)` or `parse()`. Values come from
+* `process.env` by default; `set(...)` layers overrides on top. `on(...)` subscribes to changes
+* that `set(...)` causes; the keys a factory reads are auto-tracked so computed fields update too.
+*
+* ```ts
+* const ENV = env({ PORT: z.coerce.number().default(3000) })
+*   .add({ IS_PROD: (e) => e.NODE_ENV === 'production' })  // factory: computed value
+*
+* ENV.set(process.env)
+* ENV.get('PORT')   // typed, throws if invalid
+* ENV.parse()       // resolve everything; throws an aggregated EnvError
+* ```
+*
+* @module
+*/
 /** Normalize {@link EnvOptions} into the lowercased {@link BooleanWords} the coercer consumes. */
 function toWords(options) {
 	const b = options?.booleans;
@@ -206,9 +244,11 @@ var EnvImpl = class {
 	globalLs = /* @__PURE__ */ new Set();
 	prev = /* @__PURE__ */ new Map();
 	words;
+	prefix;
 	groupCount = 0;
 	constructor(input, options) {
 		this.words = toWords(options);
+		this.prefix = options?.prefix ?? "";
 		this.define(input);
 	}
 	/** Register a group of fields under the next group index. */
@@ -234,13 +274,12 @@ var EnvImpl = class {
 	/** A proxy over fields from groups *earlier* than `group`, recording which keys a factory reads. */
 	inheritedFor(group) {
 		const reads = /* @__PURE__ */ new Set();
-		const self = this;
-		const visible = (prop) => typeof prop === "string" && (self.defs.get(prop)?.group ?? Infinity) < group;
+		const visible = (prop) => typeof prop === "string" && (this.defs.get(prop)?.group ?? Infinity) < group;
 		return {
 			proxy: new Proxy(Object.create(null), {
-				get: (_t, prop) => visible(prop) ? (reads.add(prop), self.resolve(prop)) : void 0,
+				get: (_t, prop) => visible(prop) ? (reads.add(prop), this.resolve(prop)) : void 0,
 				has: (_t, prop) => visible(prop),
-				ownKeys: () => [...self.defs.values()].filter((f) => f.group < group).map((f) => f.key),
+				ownKeys: () => [...this.defs.values()].filter((f) => f.group < group).map((f) => f.key),
 				getOwnPropertyDescriptor: () => ({
 					enumerable: true,
 					configurable: true
@@ -249,34 +288,32 @@ var EnvImpl = class {
 			reads
 		};
 	}
+	/**
+	* What a field is made of: its schema, or the value its factory computed. A factory is run against the fields of
+	* earlier groups (recording what it reads); a throwing factory becomes an {@link EnvError} scoped to the field.
+	*/
+	produce(def) {
+		if (def.kind === "schema") return { schema: def.schema };
+		const { proxy, reads } = this.inheritedFor(def.group);
+		let produced;
+		try {
+			produced = def.factory(proxy);
+		} catch (err) {
+			throw new EnvError([customIssue(def.key, errMessage(err))]);
+		} finally {
+			this.deps.set(def.key, reads);
+		}
+		return isZodType(produced) ? { schema: produced } : { value: produced };
+	}
 	/** Resolve `key` to its value (cached). Throws an {@link EnvError} (scoped to `key`) on failure. */
 	resolve(key) {
 		if (this.cache.has(key)) return this.cache.get(key);
-		const def = this.defs.get(key);
-		let schema;
-		let computed;
-		let isComputed = false;
-		if (def.kind === "schema") schema = def.schema;
-		else {
-			const { proxy, reads } = this.inheritedFor(def.group);
-			let produced;
-			try {
-				produced = def.factory(proxy);
-			} catch (err) {
-				this.deps.set(key, reads);
-				throw new EnvError([customIssue(key, errMessage(err))]);
-			}
-			this.deps.set(key, reads);
-			if (isZodType(produced)) schema = produced;
-			else {
-				computed = produced;
-				isComputed = true;
-			}
-		}
+		const made = this.produce(this.defs.get(key));
 		let result;
-		if (isComputed) result = computed;
+		if ("value" in made) result = made.value;
 		else {
-			const raw = resolveRaw(this.source(), varsOf(schema, key));
+			const { schema } = made;
+			const raw = resolveRaw(this.source(), varsOf(schema, key, this.prefix));
 			const res = schema.safeParse(raw !== void 0 ? coerce(schema, raw, this.words) : void 0);
 			if (!res.success) throw new EnvError(keyed(key, res.error.issues));
 			result = res.data;
@@ -284,6 +321,28 @@ var EnvImpl = class {
 		this.cache.set(key, result);
 		return result;
 	}
+	describe() {
+		return [...this.defs.values()].map((def) => {
+			let made;
+			try {
+				made = this.produce(def);
+			} catch {
+				return {
+					key: def.key,
+					vars: [this.prefix + def.key],
+					computed: false,
+					required: true
+				};
+			}
+			if ("value" in made) return {
+				key: def.key,
+				vars: [],
+				computed: true,
+				required: false
+			};
+			return describeSchema(def.key, made.schema, this.prefix);
+		});
+	}
 	get(key) {
 		return this.resolve(key);
 	}
@@ -299,10 +358,16 @@ var EnvImpl = class {
 		return out;
 	}
 	set(keyOrUpdates, value) {
-		const updates = typeof keyOrUpdates === "string" ? { [keyOrUpdates]: value } : keyOrUpdates;
+		const updates = typeof keyOrUpdates === "string" ? { [this.sourceKey(keyOrUpdates)]: value } : keyOrUpdates;
 		Object.assign(this.overrides, updates);
 		this.invalidate();
 	}
+	/** The source key `set(key, value)` writes: a field's first source key, or `key` itself when no field has that name. */
+	sourceKey(key) {
+		const def = this.defs.get(key);
+		if (def === void 0) return key;
+		return sourceKeyOf(def.kind === "factory" ? void 0 : def.schema, key, this.prefix);
+	}
 	add(input) {
 		this.define(input);
 		this.cache.clear();
@@ -413,11 +478,118 @@ var EnvImpl = class {
 		}
 	}
 };
+/** Describe a field read through `schema`: the keys it reads, whether it is required, and its documented shape. */
+function describeSchema(key, schema, prefix) {
+	const { $schema: _dialect, ...shape } = zod.z.toJSONSchema(schema, {
+		io: "input",
+		unrepresentable: "any"
+	});
+	return {
+		key,
+		vars: varsOf(schema, key, prefix),
+		computed: false,
+		required: !schema.safeParse(void 0).success,
+		...schema.description === void 0 ? {} : { description: schema.description },
+		..."default" in shape ? { default: shape.default } : {},
+		schema: shape
+	};
+}
 /** Build a typed, lazy, reactive config from a record of fields. Reads `process.env` by default. */
 function env(input, options) {
 	return new EnvImpl(input, options);
 }
 //#endregion
+//#region src/merge.ts
+/** The engine behind {@link mergeEnvs}: each call goes to the slice that owns the field, or to every slice. */
+var MergedEnv = class {
+	slices;
+	owner = /* @__PURE__ */ new Map();
+	constructor(slices) {
+		this.slices = slices;
+		for (const slice of slices) for (const { key } of slice.describe()) {
+			if (this.owner.has(key)) throw new Error(`mergeEnvs: field "${key}" is declared by more than one env`);
+			this.owner.set(key, slice);
+		}
+	}
+	sliceOf(key) {
+		const slice = this.owner.get(key);
+		if (slice === void 0) throw new Error(`mergeEnvs: no env declares field "${key}"`);
+		return slice;
+	}
+	get(key) {
+		return this.sliceOf(key).get(key);
+	}
+	set(keyOrUpdates, value) {
+		if (typeof keyOrUpdates === "string") {
+			const slice = this.owner.get(keyOrUpdates);
+			if (slice !== void 0) return slice.set(keyOrUpdates, value);
+			for (const one of this.slices) one.set({ [keyOrUpdates]: value });
+			return;
+		}
+		for (const one of this.slices) one.set(keyOrUpdates);
+	}
+	parse() {
+		const out = {};
+		const issues = [];
+		for (const slice of this.slices) try {
+			Object.assign(out, slice.parse());
+		} catch (err) {
+			if (!(err instanceof EnvError)) throw err;
+			issues.push(...err.issues);
+		}
+		if (issues.length > 0) throw new EnvError(issues);
+		return out;
+	}
+	on(arg1, arg2, arg3) {
+		let offs;
+		if (typeof arg1 === "function") {
+			const listener = arg1;
+			offs = this.slices.map((slice) => slice.on(listener, arg2));
+		} else {
+			const keys = Array.isArray(arg1) ? arg1 : [String(arg1)];
+			const listener = arg2;
+			offs = keys.map((key) => this.sliceOf(key).on(key, listener, arg3));
+		}
+		return () => {
+			for (const off of offs) off();
+		};
+	}
+	describe() {
+		return this.slices.flatMap((slice) => slice.describe());
+	}
+};
+/**
+* Join config slices into one {@link EnvView} of every field. Each slice stays the source of truth for its own
+* fields: `get` and single-field `set` go to the owning slice, a bulk `set` reaches every slice, `parse` throws one
+* {@link EnvError} with every slice's issues, `on` subscribes in the owning slices, and `describe` lists all fields
+* in slice order. Two slices declaring the same field is a compile-time error (for literal tuples) and throws.
+* A `once` listener subscribed to all fields fires once per slice.
+*/
+function mergeEnvs(...envs) {
+	return new MergedEnv(envs);
+}
+//#endregion
+//#region src/example.ts
+/** The text a value has in a `.env` file: strings as written, anything else as JSON. */
+function dotenvText(value) {
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+/**
+* A `.env.example` for `fields`: each field read from a source key becomes a `KEY=default` line under its
+* description as a comment. A field with no default is written as an empty `KEY=` marked `(required)`, or
+* commented out when it is optional. Computed fields read no key and are left out.
+*/
+function envExample(fields) {
+	const blocks = fields.filter((field) => !field.computed).map((field) => {
+		const key = field.vars[0] ?? field.key;
+		const notes = [field.description, field.required ? "(required)" : void 0].filter((note) => note !== void 0);
+		const comment = notes.length === 0 ? [] : notes.join(" ").split("\n").map((text) => `# ${text}`);
+		const line = "default" in field ? `${key}=${dotenvText(field.default)}` : field.required ? `${key}=` : `# ${key}=`;
+		return [...comment, line].join("\n");
+	});
+	return blocks.length === 0 ? "" : `${blocks.join("\n\n")}\n`;
+}
+//#endregion
 //#region src/provider.ts
 /** Bind a field to a live {@link EnvProvider}; values are validated against `schema`. */
 function dynamic(provider, schema) {
@@ -467,9 +639,11 @@ var AsyncEnvImpl = class {
 	started = /* @__PURE__ */ new Set();
 	watchers = /* @__PURE__ */ new Map();
 	words;
+	prefix;
 	groupCount = 0;
 	constructor(input, options) {
 		this.words = toWords(options);
+		this.prefix = options?.prefix ?? "";
 		this.define(input);
 	}
 	define(input) {
@@ -525,7 +699,7 @@ var AsyncEnvImpl = class {
 	/** Do the work of resolving one field (no memoization — see {@link resolve}). */
 	async compute(key) {
 		const def = this.defs.get(key);
-		if (def.kind === "schema") return this.validate(def.schema, key, resolveRaw(this.source(), varsOf(def.schema, key)));
+		if (def.kind === "schema") return this.validate(def.schema, key, resolveRaw(this.source(), varsOf(def.schema, key, this.prefix)));
 		if (def.kind === "dynamic") {
 			await this.ensureStarted(def);
 			return this.validate(def.schema, key, this.dynamicRaw.get(def.key));
@@ -544,7 +718,7 @@ var AsyncEnvImpl = class {
 			throw new EnvError([customIssue(key, errMessage(err))]);
 		}
 		this.deps.set(key, reads);
-		if (isZodType(produced)) return this.validate(produced, key, resolveRaw(this.source(), varsOf(produced, key)));
+		if (isZodType(produced)) return this.validate(produced, key, resolveRaw(this.source(), varsOf(produced, key, this.prefix)));
 		return produced;
 	}
 	/** Resolve `key` (memoized per snapshot). Cleared by `set`/provider updates. */
@@ -581,10 +755,16 @@ var AsyncEnvImpl = class {
 		return out;
 	}
 	set(keyOrUpdates, value) {
-		const updates = typeof keyOrUpdates === "string" ? { [keyOrUpdates]: value } : keyOrUpdates;
+		const updates = typeof keyOrUpdates === "string" ? { [this.sourceKey(keyOrUpdates)]: value } : keyOrUpdates;
 		Object.assign(this.overrides, updates);
 		this.emitChange();
 	}
+	/** The source key `set(key, value)` writes: a field's first source key, or `key` itself when no field has that name. */
+	sourceKey(key) {
+		const def = this.defs.get(key);
+		if (def === void 0) return key;
+		return sourceKeyOf(def.kind === "factory" ? void 0 : def.schema, key, this.prefix);
+	}
 	add(input) {
 		this.define(input);
 		this.cache.clear();
@@ -730,10 +910,13 @@ exports.defaultSource = defaultSource;
 exports.dynamic = dynamic;
 exports.effectiveType = effectiveType;
 exports.env = env;
+exports.envExample = envExample;
 exports.isDynamic = isDynamic;
+exports.mergeEnvs = mergeEnvs;
 exports.mergeSources = mergeSources;
 exports.parseDotenv = require_dotenv.parseDotenv;
 exports.pollProvider = pollProvider;
 exports.resolveRaw = resolveRaw;
+exports.sourceKeyOf = sourceKeyOf;
 exports.staticProvider = staticProvider;
 exports.varsOf = varsOf;

package/dist/index.d.cts

@@ -27,7 +27,7 @@ declare function coerce(schema: z.ZodType, value: unknown, words?: BooleanWords)
 //#region src/env.d.ts
 
 /** A field definition: a zod schema, or a factory taking the inherited (earlier-group) values. */
-type EnvFieldDef<Inherited> = z.ZodType | ((inherited: Inherited) => z.ZodType | any);
+type EnvFieldDef<Inherited> = z.ZodType | ((inherited: Inherited) => unknown);
 /** The fields passed to {@link env} / {@link Env.add}. `Inherited` is the type resolved so far. */
 type EnvInput<Inherited> = Record<string, EnvFieldDef<Inherited>>;
 /** The resolved output type of an {@link EnvInput} (zod outputs, computed schema outputs, or plain values). */
@@ -38,6 +38,11 @@ type EnvSet<T extends object> = { [K in keyof T]?: T[K] | string } & {
 };
 /** Build-time options for {@link env} / {@link asyncEnv}. */
 interface EnvOptions {
+  /**
+   * Prepended to each field's name to make the source key it reads: with `prefix: 'APP_'`, field `PORT` reads
+   * `APP_PORT`. Keys named by `vars`/`var` metadata are read as written.
+   */
+  readonly prefix?: string;
   /**
    * Customize which strings coerce to booleans (case-insensitive). Each side you provide
    * **replaces** its default set; an omitted side keeps the default. E.g.
@@ -59,15 +64,33 @@ interface EnvOnOptions {
   /** Fire immediately on subscribe with the current value(s). */
   immediate?: boolean;
 }
-/** A typed, lazy, reactive config object built by {@link env}. */
-interface Env<T extends object> {
-  /** Add more fields; their factories receive the fields resolved so far. Returns a wider {@link Env}. */
-  add<A extends EnvInput<T>>(input: A): Env<T & EnvOutput<T, A>>;
+/** What {@link EnvView.describe} reports about one field — enough for a settings page or a `.env.example`. */
+interface EnvFieldInfo {
+  /** The field's name (the key you `get`). */
+  readonly key: string;
+  /** The source keys it reads, in precedence order (prefix and aliases applied); none for a computed field. */
+  readonly vars: readonly string[];
+  /** A value computed from other fields; it reads no source key and has no schema. */
+  readonly computed: boolean;
+  /** Whether a value must be given: the schema rejects a missing one (no default, not optional). */
+  readonly required: boolean;
+  /** The schema's description (`.describe(...)` or `.meta({ description })`). */
+  readonly description?: string;
+  /** The schema's default, when it has one. */
+  readonly default?: unknown;
+  /** The JSON Schema of the accepted input (unrepresentable parts become `{}`). */
+  readonly schema?: Readonly<Record<string, unknown>>;
+}
+/** The reading surface of a config: {@link Env} has it, and so does a {@link mergeEnvs} view over several. */
+interface EnvView<T extends object> {
   /** Resolve a single field (lazily). Throws an {@link EnvError} if that field is missing/invalid. */
   get<K extends keyof T>(key: K): T[K];
-  /** Override a single field/source key (typed value or raw string). */
+  /**
+   * Override a single field (typed value or raw string), written under the field's source key (its prefixed name,
+   * or its first alias). A key that names no field is written as a source key, as given.
+   */
   set<K extends keyof T>(key: K, value: T[K] | string): void;
-  /** Override several fields/source keys at once (e.g. pass `process.env` or a loaded `.env`). */
+  /** Override several source keys at once (e.g. pass `process.env` or a loaded `.env`); keys are used as given. */
   set(updates: EnvSet<T>): void;
   /** Resolve every field. Throws an aggregated {@link EnvError} listing all missing/invalid fields. */
   parse(): T;
@@ -77,6 +100,16 @@ interface Env<T extends object> {
   on<K extends keyof T>(key: K, listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
   /** Subscribe to several fields' changes with one listener. */
   on<K extends keyof T>(keys: readonly K[], listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /**
+   * Describe every field, in declaration order. A factory field is run to find its schema; one that throws (an
+   * earlier field it reads is invalid) is reported as required, without `schema`, `default` or `description`.
+   */
+  describe(): readonly EnvFieldInfo[];
+}
+/** A typed, lazy, reactive config object built by {@link env}. */
+interface Env<T extends object> extends EnvView<T> {
+  /** Add more fields; their factories receive the fields resolved so far. Returns a wider {@link Env}. */
+  add<A extends EnvInput<T>>(input: A): Env<T & EnvOutput<T, A>>;
   /** Run `fn` with this env (for grouped setup); returns nothing. */
   with(fn: (env: Env<T>) => void): void;
   /** Run `fn` with this env and return its result. */
@@ -85,6 +118,54 @@ interface Env<T extends object> {
 /** Build a typed, lazy, reactive config from a record of fields. Reads `process.env` by default. */
 declare function env<const T extends EnvInput<{}>>(input: T, options?: EnvOptions): Env<EnvOutput<{}, T>>;
 //#endregion
+//#region src/merge.d.ts
+/**
+ * Any config view: every {@link EnvView} member, with field names erased so a view of any fields fits (methods take
+ * `never` parameters, so this is the supertype of every `EnvView<T>`). Its fields are read from what `parse` returns.
+ */
+interface AnyEnvView {
+  get(key: never): unknown;
+  set(key: never, value: never): void;
+  parse(): object;
+  on(...args: never[]): () => void;
+  describe(): readonly EnvFieldInfo[];
+}
+/** The fields of a config view. */
+type FieldsOf<E> = E extends {
+  parse(): infer T;
+} ? T : never;
+/** The field names of a config view. */
+type NamesOf<E> = keyof FieldsOf<E> & string;
+/** The positions of a tuple (`'0' | '1' | …`); `never` for a plain array. */
+type Positions<T extends readonly unknown[]> = Exclude<keyof T, keyof unknown[]>;
+/** Field names that two different views of `T` both declare. */
+type SharedNames<T extends readonly unknown[]> = { [I in Positions<T>]: { [J in Positions<T>]: J extends I ? never : NamesOf<T[I]> & NamesOf<T[J]> }[Positions<T>] }[Positions<T>];
+/** Turn a union into the intersection of its members. */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+/**
+ * `T` when no field name is declared by more than one of its views; otherwise a tuple whose only element names the
+ * clash, so the call fails to compile with that message.
+ */
+type DisjointEnvs<T extends readonly unknown[]> = [SharedNames<T>] extends [never] ? T : readonly [`fields declared by more than one env: ${SharedNames<T>}`];
+/** The fields of every view in `T`, as one object type. */
+type MergedFields<T extends readonly unknown[]> = { [K in keyof UnionToIntersection<FieldsOf<T[number]>>]: UnionToIntersection<FieldsOf<T[number]>>[K] };
+/**
+ * Join config slices into one {@link EnvView} of every field. Each slice stays the source of truth for its own
+ * fields: `get` and single-field `set` go to the owning slice, a bulk `set` reaches every slice, `parse` throws one
+ * {@link EnvError} with every slice's issues, `on` subscribes in the owning slices, and `describe` lists all fields
+ * in slice order. Two slices declaring the same field is a compile-time error (for literal tuples) and throws.
+ * A `once` listener subscribed to all fields fires once per slice.
+ */
+declare function mergeEnvs<const T extends readonly [AnyEnvView, ...AnyEnvView[]]>(...envs: T & DisjointEnvs<T>): EnvView<MergedFields<T>>;
+//#endregion
+//#region src/example.d.ts
+/**
+ * A `.env.example` for `fields`: each field read from a source key becomes a `KEY=default` line under its
+ * description as a comment. A field with no default is written as an empty `KEY=` marked `(required)`, or
+ * commented out when it is optional. Computed fields read no key and are left out.
+ */
+declare function envExample(fields: readonly EnvFieldInfo[]): string;
+//#endregion
 //#region src/provider.d.ts
 /** A value, or a promise of one. */
 type MaybePromise<T> = T | Promise<T>;
@@ -115,7 +196,7 @@ declare function staticProvider(value: string | undefined): EnvProvider;
 //#endregion
 //#region src/async.d.ts
 /** A field for {@link asyncEnv}: zod schema, dynamic binding, or a (possibly async) factory. */
-type AsyncEnvFieldDef<Inherited> = z.ZodType | DynamicBinding<any> | ((inherited: Inherited) => MaybePromise<z.ZodType | any>);
+type AsyncEnvFieldDef<Inherited> = z.ZodType | DynamicBinding<unknown> | ((inherited: Inherited) => unknown);
 /** The fields passed to {@link asyncEnv} / {@link AsyncEnv.add}. */
 type AsyncEnvInput<Inherited> = Record<string, AsyncEnvFieldDef<Inherited>>;
 /** The resolved output type of an {@link AsyncEnvInput}. */
@@ -126,9 +207,9 @@ interface AsyncEnv<T extends object> {
   add<A extends AsyncEnvInput<T>>(input: A): AsyncEnv<T & AsyncEnvOutput<T, A>>;
   /** Resolve a single field (lazily, async). Rejects with an {@link EnvError} if missing/invalid. */
   get<K extends keyof T>(key: K): Promise<T[K]>;
-  /** Override a single field/source key (typed value or raw string). */
+  /** Override a single field (typed value or raw string), under its source key (prefixed name or first alias); another key is used as given. */
   set<K extends keyof T>(key: K, value: T[K] | string): void;
-  /** Override several fields/source keys at once. */
+  /** Override several source keys at once; keys are used as given. */
   set(updates: EnvSet<T>): void;
   /** Resolve every field. Rejects with an aggregated {@link EnvError} listing all failures. */
   parse(): Promise<T>;
@@ -158,9 +239,17 @@ interface EnvMeta {
   /** Several source keys to read this field from — first present wins. */
   readonly vars?: readonly string[];
 }
-/** The source keys a field reads, in precedence order — its `vars`/`var` meta, else `[key]`. */
-declare function varsOf(schema: z.ZodType, key: string): readonly string[];
+/**
+ * The source keys a field reads, in precedence order — its `vars`/`var` meta (taken as written), else
+ * `[prefix + key]`.
+ */
+declare function varsOf(schema: z.ZodType, key: string, prefix?: string): readonly string[];
+/**
+ * The source key a field is written under by a single-field `set`: the first key it reads. `schema` is undefined for
+ * a factory field, whose schema is only known once it runs; it is written under its prefixed name.
+ */
+declare function sourceKeyOf(schema: z.ZodType | undefined, key: string, prefix?: string): string;
 /** Attach aliasing metadata: read `schema` from the first present of `keys`. */
 declare function alias<S extends z.ZodType>(schema: S, ...keys: string[]): S;
 //#endregion
-export { type AsyncEnv, type AsyncEnvFieldDef, type AsyncEnvInput, type AsyncEnvOutput, type BooleanWords, DEFAULT_FALSE, DEFAULT_TRUE, type DynamicBinding, type Env, EnvError, type EnvFieldDef, type EnvInput, type EnvMeta, type EnvOnOptions, type EnvOptions, type EnvOutput, type EnvProvider, type EnvSet, type EnvSource, type MaybePromise, alias, asyncEnv, coerce, defaultSource, dynamic, effectiveType, env, isDynamic, mergeSources, parseDotenv, pollProvider, resolveRaw, staticProvider, varsOf };
+export { type AnyEnvView, type AsyncEnv, type AsyncEnvFieldDef, type AsyncEnvInput, type AsyncEnvOutput, type BooleanWords, DEFAULT_FALSE, DEFAULT_TRUE, type DisjointEnvs, type DynamicBinding, type Env, EnvError, type EnvFieldDef, type EnvFieldInfo, type EnvInput, type EnvMeta, type EnvOnOptions, type EnvOptions, type EnvOutput, type EnvProvider, type EnvSet, type EnvSource, type EnvView, type MaybePromise, type MergedFields, alias, asyncEnv, coerce, defaultSource, dynamic, effectiveType, env, envExample, isDynamic, mergeEnvs, mergeSources, parseDotenv, pollProvider, resolveRaw, sourceKeyOf, staticProvider, varsOf };

package/dist/index.d.ts

@@ -27,7 +27,7 @@ declare function coerce(schema: z.ZodType, value: unknown, words?: BooleanWords)
 //#region src/env.d.ts
 
 /** A field definition: a zod schema, or a factory taking the inherited (earlier-group) values. */
-type EnvFieldDef<Inherited> = z.ZodType | ((inherited: Inherited) => z.ZodType | any);
+type EnvFieldDef<Inherited> = z.ZodType | ((inherited: Inherited) => unknown);
 /** The fields passed to {@link env} / {@link Env.add}. `Inherited` is the type resolved so far. */
 type EnvInput<Inherited> = Record<string, EnvFieldDef<Inherited>>;
 /** The resolved output type of an {@link EnvInput} (zod outputs, computed schema outputs, or plain values). */
@@ -38,6 +38,11 @@ type EnvSet<T extends object> = { [K in keyof T]?: T[K] | string } & {
 };
 /** Build-time options for {@link env} / {@link asyncEnv}. */
 interface EnvOptions {
+  /**
+   * Prepended to each field's name to make the source key it reads: with `prefix: 'APP_'`, field `PORT` reads
+   * `APP_PORT`. Keys named by `vars`/`var` metadata are read as written.
+   */
+  readonly prefix?: string;
   /**
    * Customize which strings coerce to booleans (case-insensitive). Each side you provide
    * **replaces** its default set; an omitted side keeps the default. E.g.
@@ -59,15 +64,33 @@ interface EnvOnOptions {
   /** Fire immediately on subscribe with the current value(s). */
   immediate?: boolean;
 }
-/** A typed, lazy, reactive config object built by {@link env}. */
-interface Env<T extends object> {
-  /** Add more fields; their factories receive the fields resolved so far. Returns a wider {@link Env}. */
-  add<A extends EnvInput<T>>(input: A): Env<T & EnvOutput<T, A>>;
+/** What {@link EnvView.describe} reports about one field — enough for a settings page or a `.env.example`. */
+interface EnvFieldInfo {
+  /** The field's name (the key you `get`). */
+  readonly key: string;
+  /** The source keys it reads, in precedence order (prefix and aliases applied); none for a computed field. */
+  readonly vars: readonly string[];
+  /** A value computed from other fields; it reads no source key and has no schema. */
+  readonly computed: boolean;
+  /** Whether a value must be given: the schema rejects a missing one (no default, not optional). */
+  readonly required: boolean;
+  /** The schema's description (`.describe(...)` or `.meta({ description })`). */
+  readonly description?: string;
+  /** The schema's default, when it has one. */
+  readonly default?: unknown;
+  /** The JSON Schema of the accepted input (unrepresentable parts become `{}`). */
+  readonly schema?: Readonly<Record<string, unknown>>;
+}
+/** The reading surface of a config: {@link Env} has it, and so does a {@link mergeEnvs} view over several. */
+interface EnvView<T extends object> {
   /** Resolve a single field (lazily). Throws an {@link EnvError} if that field is missing/invalid. */
   get<K extends keyof T>(key: K): T[K];
-  /** Override a single field/source key (typed value or raw string). */
+  /**
+   * Override a single field (typed value or raw string), written under the field's source key (its prefixed name,
+   * or its first alias). A key that names no field is written as a source key, as given.
+   */
   set<K extends keyof T>(key: K, value: T[K] | string): void;
-  /** Override several fields/source keys at once (e.g. pass `process.env` or a loaded `.env`). */
+  /** Override several source keys at once (e.g. pass `process.env` or a loaded `.env`); keys are used as given. */
   set(updates: EnvSet<T>): void;
   /** Resolve every field. Throws an aggregated {@link EnvError} listing all missing/invalid fields. */
   parse(): T;
@@ -77,6 +100,16 @@ interface Env<T extends object> {
   on<K extends keyof T>(key: K, listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
   /** Subscribe to several fields' changes with one listener. */
   on<K extends keyof T>(keys: readonly K[], listener: (value: T[K]) => void, options?: EnvOnOptions): () => void;
+  /**
+   * Describe every field, in declaration order. A factory field is run to find its schema; one that throws (an
+   * earlier field it reads is invalid) is reported as required, without `schema`, `default` or `description`.
+   */
+  describe(): readonly EnvFieldInfo[];
+}
+/** A typed, lazy, reactive config object built by {@link env}. */
+interface Env<T extends object> extends EnvView<T> {
+  /** Add more fields; their factories receive the fields resolved so far. Returns a wider {@link Env}. */
+  add<A extends EnvInput<T>>(input: A): Env<T & EnvOutput<T, A>>;
   /** Run `fn` with this env (for grouped setup); returns nothing. */
   with(fn: (env: Env<T>) => void): void;
   /** Run `fn` with this env and return its result. */
@@ -85,6 +118,54 @@ interface Env<T extends object> {
 /** Build a typed, lazy, reactive config from a record of fields. Reads `process.env` by default. */
 declare function env<const T extends EnvInput<{}>>(input: T, options?: EnvOptions): Env<EnvOutput<{}, T>>;
 //#endregion
+//#region src/merge.d.ts
+/**
+ * Any config view: every {@link EnvView} member, with field names erased so a view of any fields fits (methods take
+ * `never` parameters, so this is the supertype of every `EnvView<T>`). Its fields are read from what `parse` returns.
+ */
+interface AnyEnvView {
+  get(key: never): unknown;
+  set(key: never, value: never): void;
+  parse(): object;
+  on(...args: never[]): () => void;
+  describe(): readonly EnvFieldInfo[];
+}
+/** The fields of a config view. */
+type FieldsOf<E> = E extends {
+  parse(): infer T;
+} ? T : never;
+/** The field names of a config view. */
+type NamesOf<E> = keyof FieldsOf<E> & string;
+/** The positions of a tuple (`'0' | '1' | …`); `never` for a plain array. */
+type Positions<T extends readonly unknown[]> = Exclude<keyof T, keyof unknown[]>;
+/** Field names that two different views of `T` both declare. */
+type SharedNames<T extends readonly unknown[]> = { [I in Positions<T>]: { [J in Positions<T>]: J extends I ? never : NamesOf<T[I]> & NamesOf<T[J]> }[Positions<T>] }[Positions<T>];
+/** Turn a union into the intersection of its members. */
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+/**
+ * `T` when no field name is declared by more than one of its views; otherwise a tuple whose only element names the
+ * clash, so the call fails to compile with that message.
+ */
+type DisjointEnvs<T extends readonly unknown[]> = [SharedNames<T>] extends [never] ? T : readonly [`fields declared by more than one env: ${SharedNames<T>}`];
+/** The fields of every view in `T`, as one object type. */
+type MergedFields<T extends readonly unknown[]> = { [K in keyof UnionToIntersection<FieldsOf<T[number]>>]: UnionToIntersection<FieldsOf<T[number]>>[K] };
+/**
+ * Join config slices into one {@link EnvView} of every field. Each slice stays the source of truth for its own
+ * fields: `get` and single-field `set` go to the owning slice, a bulk `set` reaches every slice, `parse` throws one
+ * {@link EnvError} with every slice's issues, `on` subscribes in the owning slices, and `describe` lists all fields
+ * in slice order. Two slices declaring the same field is a compile-time error (for literal tuples) and throws.
+ * A `once` listener subscribed to all fields fires once per slice.
+ */
+declare function mergeEnvs<const T extends readonly [AnyEnvView, ...AnyEnvView[]]>(...envs: T & DisjointEnvs<T>): EnvView<MergedFields<T>>;
+//#endregion
+//#region src/example.d.ts
+/**
+ * A `.env.example` for `fields`: each field read from a source key becomes a `KEY=default` line under its
+ * description as a comment. A field with no default is written as an empty `KEY=` marked `(required)`, or
+ * commented out when it is optional. Computed fields read no key and are left out.
+ */
+declare function envExample(fields: readonly EnvFieldInfo[]): string;
+//#endregion
 //#region src/provider.d.ts
 /** A value, or a promise of one. */
 type MaybePromise<T> = T | Promise<T>;
@@ -115,7 +196,7 @@ declare function staticProvider(value: string | undefined): EnvProvider;
 //#endregion
 //#region src/async.d.ts
 /** A field for {@link asyncEnv}: zod schema, dynamic binding, or a (possibly async) factory. */
-type AsyncEnvFieldDef<Inherited> = z.ZodType | DynamicBinding<any> | ((inherited: Inherited) => MaybePromise<z.ZodType | any>);
+type AsyncEnvFieldDef<Inherited> = z.ZodType | DynamicBinding<unknown> | ((inherited: Inherited) => unknown);
 /** The fields passed to {@link asyncEnv} / {@link AsyncEnv.add}. */
 type AsyncEnvInput<Inherited> = Record<string, AsyncEnvFieldDef<Inherited>>;
 /** The resolved output type of an {@link AsyncEnvInput}. */
@@ -126,9 +207,9 @@ interface AsyncEnv<T extends object> {
   add<A extends AsyncEnvInput<T>>(input: A): AsyncEnv<T & AsyncEnvOutput<T, A>>;
   /** Resolve a single field (lazily, async). Rejects with an {@link EnvError} if missing/invalid. */
   get<K extends keyof T>(key: K): Promise<T[K]>;
-  /** Override a single field/source key (typed value or raw string). */
+  /** Override a single field (typed value or raw string), under its source key (prefixed name or first alias); another key is used as given. */
   set<K extends keyof T>(key: K, value: T[K] | string): void;
-  /** Override several fields/source keys at once. */
+  /** Override several source keys at once; keys are used as given. */
   set(updates: EnvSet<T>): void;
   /** Resolve every field. Rejects with an aggregated {@link EnvError} listing all failures. */
   parse(): Promise<T>;
@@ -158,9 +239,17 @@ interface EnvMeta {
   /** Several source keys to read this field from — first present wins. */
   readonly vars?: readonly string[];
 }
-/** The source keys a field reads, in precedence order — its `vars`/`var` meta, else `[key]`. */
-declare function varsOf(schema: z.ZodType, key: string): readonly string[];
+/**
+ * The source keys a field reads, in precedence order — its `vars`/`var` meta (taken as written), else
+ * `[prefix + key]`.
+ */
+declare function varsOf(schema: z.ZodType, key: string, prefix?: string): readonly string[];
+/**
+ * The source key a field is written under by a single-field `set`: the first key it reads. `schema` is undefined for
+ * a factory field, whose schema is only known once it runs; it is written under its prefixed name.
+ */
+declare function sourceKeyOf(schema: z.ZodType | undefined, key: string, prefix?: string): string;
 /** Attach aliasing metadata: read `schema` from the first present of `keys`. */
 declare function alias<S extends z.ZodType>(schema: S, ...keys: string[]): S;
 //#endregion
-export { type AsyncEnv, type AsyncEnvFieldDef, type AsyncEnvInput, type AsyncEnvOutput, type BooleanWords, DEFAULT_FALSE, DEFAULT_TRUE, type DynamicBinding, type Env, EnvError, type EnvFieldDef, type EnvInput, type EnvMeta, type EnvOnOptions, type EnvOptions, type EnvOutput, type EnvProvider, type EnvSet, type EnvSource, type MaybePromise, alias, asyncEnv, coerce, defaultSource, dynamic, effectiveType, env, isDynamic, mergeSources, parseDotenv, pollProvider, resolveRaw, staticProvider, varsOf };
+export { type AnyEnvView, type AsyncEnv, type AsyncEnvFieldDef, type AsyncEnvInput, type AsyncEnvOutput, type BooleanWords, DEFAULT_FALSE, DEFAULT_TRUE, type DisjointEnvs, type DynamicBinding, type Env, EnvError, type EnvFieldDef, type EnvFieldInfo, type EnvInput, type EnvMeta, type EnvOnOptions, type EnvOptions, type EnvOutput, type EnvProvider, type EnvSet, type EnvSource, type EnvView, type MaybePromise, type MergedFields, alias, asyncEnv, coerce, defaultSource, dynamic, effectiveType, env, envExample, isDynamic, mergeEnvs, mergeSources, parseDotenv, pollProvider, resolveRaw, sourceKeyOf, staticProvider, varsOf };

package/dist/index.js

@@ -1,4 +1,5 @@
 import { t as parseDotenv } from "./dotenv.js";
+import { z } from "zod";
 //#region src/coerce.ts
 /** Read a schema's internal `_zod.def` (zod v4 stores its definition there). */
 function def(schema) {
@@ -98,12 +99,23 @@ function coerce(schema, value, words) {
 function readMeta(schema) {
 	return schema.meta?.();
 }
-/** The source keys a field reads, in precedence order — its `vars`/`var` meta, else `[key]`. */
-function varsOf(schema, key) {
+/**
+* The source keys a field reads, in precedence order — its `vars`/`var` meta (taken as written), else
+* `[prefix + key]`.
+*/
+function varsOf(schema, key, prefix = "") {
 	const meta = readMeta(schema);
 	if (meta?.vars && meta.vars.length > 0) return meta.vars;
 	if (meta?.var) return [meta.var];
-	return [key];
+	return [prefix + key];
+}
+/**
+* The source key a field is written under by a single-field `set`: the first key it reads. `schema` is undefined for
+* a factory field, whose schema is only known once it runs; it is written under its prefixed name.
+*/
+function sourceKeyOf(schema, key, prefix = "") {
+	const meta = schema === void 0 ? void 0 : readMeta(schema);
+	return meta?.vars?.[0] ?? meta?.var ?? prefix + key;
 }
 /** Attach aliasing metadata: read `schema` from the first present of `keys`. */
 function alias(schema, ...keys) {
@@ -185,6 +197,32 @@ function changed(prev, next, deep) {
 }
 //#endregion
 //#region src/env.ts
+/**
+* # `env(...)` — the typed, lazy, reactive config builder
+*
+* Declare a config as a record of fields and get back a typed {@link Env}. A field is either:
+*
+* - a **zod schema** — read from a source key (its name, or its `vars` meta for aliasing),
+*   coerced from its string form and validated; or
+* - a **factory** `(inherited) => …` — called with the already-resolved fields from *earlier*
+*   `add(...)` groups. Return another **zod schema** (a schema that depends on other values),
+*   or return a **plain value** (a computed field derived purely from other fields).
+*
+* Resolution is **lazy**: nothing is parsed until you `get(...)` or `parse()`. Values come from
+* `process.env` by default; `set(...)` layers overrides on top. `on(...)` subscribes to changes
+* that `set(...)` causes; the keys a factory reads are auto-tracked so computed fields update too.
+*
+* ```ts
+* const ENV = env({ PORT: z.coerce.number().default(3000) })
+*   .add({ IS_PROD: (e) => e.NODE_ENV === 'production' })  // factory: computed value
+*
+* ENV.set(process.env)
+* ENV.get('PORT')   // typed, throws if invalid
+* ENV.parse()       // resolve everything; throws an aggregated EnvError
+* ```
+*
+* @module
+*/
 /** Normalize {@link EnvOptions} into the lowercased {@link BooleanWords} the coercer consumes. */
 function toWords(options) {
 	const b = options?.booleans;
@@ -205,9 +243,11 @@ var EnvImpl = class {
 	globalLs = /* @__PURE__ */ new Set();
 	prev = /* @__PURE__ */ new Map();
 	words;
+	prefix;
 	groupCount = 0;
 	constructor(input, options) {
 		this.words = toWords(options);
+		this.prefix = options?.prefix ?? "";
 		this.define(input);
 	}
 	/** Register a group of fields under the next group index. */
@@ -233,13 +273,12 @@ var EnvImpl = class {
 	/** A proxy over fields from groups *earlier* than `group`, recording which keys a factory reads. */
 	inheritedFor(group) {
 		const reads = /* @__PURE__ */ new Set();
-		const self = this;
-		const visible = (prop) => typeof prop === "string" && (self.defs.get(prop)?.group ?? Infinity) < group;
+		const visible = (prop) => typeof prop === "string" && (this.defs.get(prop)?.group ?? Infinity) < group;
 		return {
 			proxy: new Proxy(Object.create(null), {
-				get: (_t, prop) => visible(prop) ? (reads.add(prop), self.resolve(prop)) : void 0,
+				get: (_t, prop) => visible(prop) ? (reads.add(prop), this.resolve(prop)) : void 0,
 				has: (_t, prop) => visible(prop),
-				ownKeys: () => [...self.defs.values()].filter((f) => f.group < group).map((f) => f.key),
+				ownKeys: () => [...this.defs.values()].filter((f) => f.group < group).map((f) => f.key),
 				getOwnPropertyDescriptor: () => ({
 					enumerable: true,
 					configurable: true
@@ -248,34 +287,32 @@ var EnvImpl = class {
 			reads
 		};
 	}
+	/**
+	* What a field is made of: its schema, or the value its factory computed. A factory is run against the fields of
+	* earlier groups (recording what it reads); a throwing factory becomes an {@link EnvError} scoped to the field.
+	*/
+	produce(def) {
+		if (def.kind === "schema") return { schema: def.schema };
+		const { proxy, reads } = this.inheritedFor(def.group);
+		let produced;
+		try {
+			produced = def.factory(proxy);
+		} catch (err) {
+			throw new EnvError([customIssue(def.key, errMessage(err))]);
+		} finally {
+			this.deps.set(def.key, reads);
+		}
+		return isZodType(produced) ? { schema: produced } : { value: produced };
+	}
 	/** Resolve `key` to its value (cached). Throws an {@link EnvError} (scoped to `key`) on failure. */
 	resolve(key) {
 		if (this.cache.has(key)) return this.cache.get(key);
-		const def = this.defs.get(key);
-		let schema;
-		let computed;
-		let isComputed = false;
-		if (def.kind === "schema") schema = def.schema;
-		else {
-			const { proxy, reads } = this.inheritedFor(def.group);
-			let produced;
-			try {
-				produced = def.factory(proxy);
-			} catch (err) {
-				this.deps.set(key, reads);
-				throw new EnvError([customIssue(key, errMessage(err))]);
-			}
-			this.deps.set(key, reads);
-			if (isZodType(produced)) schema = produced;
-			else {
-				computed = produced;
-				isComputed = true;
-			}
-		}
+		const made = this.produce(this.defs.get(key));
 		let result;
-		if (isComputed) result = computed;
+		if ("value" in made) result = made.value;
 		else {
-			const raw = resolveRaw(this.source(), varsOf(schema, key));
+			const { schema } = made;
+			const raw = resolveRaw(this.source(), varsOf(schema, key, this.prefix));
 			const res = schema.safeParse(raw !== void 0 ? coerce(schema, raw, this.words) : void 0);
 			if (!res.success) throw new EnvError(keyed(key, res.error.issues));
 			result = res.data;
@@ -283,6 +320,28 @@ var EnvImpl = class {
 		this.cache.set(key, result);
 		return result;
 	}
+	describe() {
+		return [...this.defs.values()].map((def) => {
+			let made;
+			try {
+				made = this.produce(def);
+			} catch {
+				return {
+					key: def.key,
+					vars: [this.prefix + def.key],
+					computed: false,
+					required: true
+				};
+			}
+			if ("value" in made) return {
+				key: def.key,
+				vars: [],
+				computed: true,
+				required: false
+			};
+			return describeSchema(def.key, made.schema, this.prefix);
+		});
+	}
 	get(key) {
 		return this.resolve(key);
 	}
@@ -298,10 +357,16 @@ var EnvImpl = class {
 		return out;
 	}
 	set(keyOrUpdates, value) {
-		const updates = typeof keyOrUpdates === "string" ? { [keyOrUpdates]: value } : keyOrUpdates;
+		const updates = typeof keyOrUpdates === "string" ? { [this.sourceKey(keyOrUpdates)]: value } : keyOrUpdates;
 		Object.assign(this.overrides, updates);
 		this.invalidate();
 	}
+	/** The source key `set(key, value)` writes: a field's first source key, or `key` itself when no field has that name. */
+	sourceKey(key) {
+		const def = this.defs.get(key);
+		if (def === void 0) return key;
+		return sourceKeyOf(def.kind === "factory" ? void 0 : def.schema, key, this.prefix);
+	}
 	add(input) {
 		this.define(input);
 		this.cache.clear();
@@ -412,11 +477,118 @@ var EnvImpl = class {
 		}
 	}
 };
+/** Describe a field read through `schema`: the keys it reads, whether it is required, and its documented shape. */
+function describeSchema(key, schema, prefix) {
+	const { $schema: _dialect, ...shape } = z.toJSONSchema(schema, {
+		io: "input",
+		unrepresentable: "any"
+	});
+	return {
+		key,
+		vars: varsOf(schema, key, prefix),
+		computed: false,
+		required: !schema.safeParse(void 0).success,
+		...schema.description === void 0 ? {} : { description: schema.description },
+		..."default" in shape ? { default: shape.default } : {},
+		schema: shape
+	};
+}
 /** Build a typed, lazy, reactive config from a record of fields. Reads `process.env` by default. */
 function env(input, options) {
 	return new EnvImpl(input, options);
 }
 //#endregion
+//#region src/merge.ts
+/** The engine behind {@link mergeEnvs}: each call goes to the slice that owns the field, or to every slice. */
+var MergedEnv = class {
+	slices;
+	owner = /* @__PURE__ */ new Map();
+	constructor(slices) {
+		this.slices = slices;
+		for (const slice of slices) for (const { key } of slice.describe()) {
+			if (this.owner.has(key)) throw new Error(`mergeEnvs: field "${key}" is declared by more than one env`);
+			this.owner.set(key, slice);
+		}
+	}
+	sliceOf(key) {
+		const slice = this.owner.get(key);
+		if (slice === void 0) throw new Error(`mergeEnvs: no env declares field "${key}"`);
+		return slice;
+	}
+	get(key) {
+		return this.sliceOf(key).get(key);
+	}
+	set(keyOrUpdates, value) {
+		if (typeof keyOrUpdates === "string") {
+			const slice = this.owner.get(keyOrUpdates);
+			if (slice !== void 0) return slice.set(keyOrUpdates, value);
+			for (const one of this.slices) one.set({ [keyOrUpdates]: value });
+			return;
+		}
+		for (const one of this.slices) one.set(keyOrUpdates);
+	}
+	parse() {
+		const out = {};
+		const issues = [];
+		for (const slice of this.slices) try {
+			Object.assign(out, slice.parse());
+		} catch (err) {
+			if (!(err instanceof EnvError)) throw err;
+			issues.push(...err.issues);
+		}
+		if (issues.length > 0) throw new EnvError(issues);
+		return out;
+	}
+	on(arg1, arg2, arg3) {
+		let offs;
+		if (typeof arg1 === "function") {
+			const listener = arg1;
+			offs = this.slices.map((slice) => slice.on(listener, arg2));
+		} else {
+			const keys = Array.isArray(arg1) ? arg1 : [String(arg1)];
+			const listener = arg2;
+			offs = keys.map((key) => this.sliceOf(key).on(key, listener, arg3));
+		}
+		return () => {
+			for (const off of offs) off();
+		};
+	}
+	describe() {
+		return this.slices.flatMap((slice) => slice.describe());
+	}
+};
+/**
+* Join config slices into one {@link EnvView} of every field. Each slice stays the source of truth for its own
+* fields: `get` and single-field `set` go to the owning slice, a bulk `set` reaches every slice, `parse` throws one
+* {@link EnvError} with every slice's issues, `on` subscribes in the owning slices, and `describe` lists all fields
+* in slice order. Two slices declaring the same field is a compile-time error (for literal tuples) and throws.
+* A `once` listener subscribed to all fields fires once per slice.
+*/
+function mergeEnvs(...envs) {
+	return new MergedEnv(envs);
+}
+//#endregion
+//#region src/example.ts
+/** The text a value has in a `.env` file: strings as written, anything else as JSON. */
+function dotenvText(value) {
+	return typeof value === "string" ? value : JSON.stringify(value);
+}
+/**
+* A `.env.example` for `fields`: each field read from a source key becomes a `KEY=default` line under its
+* description as a comment. A field with no default is written as an empty `KEY=` marked `(required)`, or
+* commented out when it is optional. Computed fields read no key and are left out.
+*/
+function envExample(fields) {
+	const blocks = fields.filter((field) => !field.computed).map((field) => {
+		const key = field.vars[0] ?? field.key;
+		const notes = [field.description, field.required ? "(required)" : void 0].filter((note) => note !== void 0);
+		const comment = notes.length === 0 ? [] : notes.join(" ").split("\n").map((text) => `# ${text}`);
+		const line = "default" in field ? `${key}=${dotenvText(field.default)}` : field.required ? `${key}=` : `# ${key}=`;
+		return [...comment, line].join("\n");
+	});
+	return blocks.length === 0 ? "" : `${blocks.join("\n\n")}\n`;
+}
+//#endregion
 //#region src/provider.ts
 /** Bind a field to a live {@link EnvProvider}; values are validated against `schema`. */
 function dynamic(provider, schema) {
@@ -466,9 +638,11 @@ var AsyncEnvImpl = class {
 	started = /* @__PURE__ */ new Set();
 	watchers = /* @__PURE__ */ new Map();
 	words;
+	prefix;
 	groupCount = 0;
 	constructor(input, options) {
 		this.words = toWords(options);
+		this.prefix = options?.prefix ?? "";
 		this.define(input);
 	}
 	define(input) {
@@ -524,7 +698,7 @@ var AsyncEnvImpl = class {
 	/** Do the work of resolving one field (no memoization — see {@link resolve}). */
 	async compute(key) {
 		const def = this.defs.get(key);
-		if (def.kind === "schema") return this.validate(def.schema, key, resolveRaw(this.source(), varsOf(def.schema, key)));
+		if (def.kind === "schema") return this.validate(def.schema, key, resolveRaw(this.source(), varsOf(def.schema, key, this.prefix)));
 		if (def.kind === "dynamic") {
 			await this.ensureStarted(def);
 			return this.validate(def.schema, key, this.dynamicRaw.get(def.key));
@@ -543,7 +717,7 @@ var AsyncEnvImpl = class {
 			throw new EnvError([customIssue(key, errMessage(err))]);
 		}
 		this.deps.set(key, reads);
-		if (isZodType(produced)) return this.validate(produced, key, resolveRaw(this.source(), varsOf(produced, key)));
+		if (isZodType(produced)) return this.validate(produced, key, resolveRaw(this.source(), varsOf(produced, key, this.prefix)));
 		return produced;
 	}
 	/** Resolve `key` (memoized per snapshot). Cleared by `set`/provider updates. */
@@ -580,10 +754,16 @@ var AsyncEnvImpl = class {
 		return out;
 	}
 	set(keyOrUpdates, value) {
-		const updates = typeof keyOrUpdates === "string" ? { [keyOrUpdates]: value } : keyOrUpdates;
+		const updates = typeof keyOrUpdates === "string" ? { [this.sourceKey(keyOrUpdates)]: value } : keyOrUpdates;
 		Object.assign(this.overrides, updates);
 		this.emitChange();
 	}
+	/** The source key `set(key, value)` writes: a field's first source key, or `key` itself when no field has that name. */
+	sourceKey(key) {
+		const def = this.defs.get(key);
+		if (def === void 0) return key;
+		return sourceKeyOf(def.kind === "factory" ? void 0 : def.schema, key, this.prefix);
+	}
 	add(input) {
 		this.define(input);
 		this.cache.clear();
@@ -719,4 +899,4 @@ function asyncEnv(input, options) {
 	return new AsyncEnvImpl(input, options);
 }
 //#endregion
-export { DEFAULT_FALSE, DEFAULT_TRUE, EnvError, alias, asyncEnv, coerce, defaultSource, dynamic, effectiveType, env, isDynamic, mergeSources, parseDotenv, pollProvider, resolveRaw, staticProvider, varsOf };
+export { DEFAULT_FALSE, DEFAULT_TRUE, EnvError, alias, asyncEnv, coerce, defaultSource, dynamic, effectiveType, env, envExample, isDynamic, mergeEnvs, mergeSources, parseDotenv, pollProvider, resolveRaw, sourceKeyOf, staticProvider, varsOf };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayepi/env",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Typed, lazy, reactive environment/config on zod — env({...}) reads process.env, records, .env/JSON files; coerces scalars and JSON-decodes complex types; computed fields, aliasing, and async/dynamic (live, subscribable) values",
   "license": "MIT",
   "publishConfig": {
@@ -48,14 +48,14 @@
     "node": ">=18"
   },
   "peerDependencies": {
-    "zod": "^4"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^2.1.8",
     "publint": "^0.3.0",
     "tsdown": "^0.12.0",
     "vitest": "^2.1.8",
-    "zod": "^4.4.3"
+    "zod": "^4.6.7"
   },
   "keywords": [
     "ayepi",