@effected/config-file 0.19.1 → 0.20.1

package/ConfigFile.js

@@ -114,7 +114,6 @@ var ConfigValidationError = class extends Schema.TaggedError()("ConfigValidation
 		})}`;
 	}
 };
-const Service = () => (id) => Context.Service()(id);
 /**
 * Re-raise a codec failure with the file it came from attached.
 *
@@ -401,46 +400,6 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		update
 	};
 };
-const layer = (tag, options) => Layer.effect(tag, Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
-	const path = yield* Path.Path;
-	const resolverEnv = yield* Effect.context();
-	return makeImpl(options, fs, path, resolverEnv);
-}));
-const testLayer = (tag, options) => Layer.effect(tag, Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
-	const path = yield* Path.Path;
-	const resolverEnv = yield* Effect.context();
-	const dir = yield* fs.makeTempDirectory({ prefix: "effected-config-file-" }).pipe(Effect.orDie);
-	yield* Effect.addFinalizer(() => fs.remove(dir, { recursive: true }).pipe(Effect.orDie));
-	for (const [name, content] of Object.entries(options.files)) {
-		const target = path.join(dir, name);
-		yield* fs.makeDirectory(path.dirname(target), { recursive: true }).pipe(Effect.orDie);
-		yield* fs.writeFileString(target, content).pipe(Effect.orDie);
-	}
-	const resolvers = Object.keys(options.files).map((name) => ConfigResolver.staticDir({
-		dir,
-		filename: name
-	}));
-	return makeImpl({
-		schema: options.schema,
-		codec: options.codec,
-		strategy: options.strategy,
-		resolvers,
-		...options.validate !== void 0 && { validate: options.validate }
-	}, fs, path, resolverEnv);
-}));
-const read = (path, options) => Effect.gen(function* () {
-	const raw = yield* (yield* FileSystem.FileSystem).readFileString(path).pipe(Effect.mapError((cause) => new ConfigFileReadError({
-		path,
-		cause
-	})));
-	const parsed = yield* options.codec.parse(raw).pipe(Effect.mapError((error) => withCodecPath(error, path)));
-	return yield* Schema.decodeUnknownEffect(options.schema)(parsed, options.parseOptions).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
-		path: Option.some(path),
-		issue: error.issue
-	}))));
-}).pipe(Effect.withSpan("ConfigFile.read", { attributes: { path } }));
 /**
 * The config file service: a per-schema service factory, its layers, and the
 * one-shot {@link ConfigFile.read}.
@@ -471,7 +430,7 @@ var ConfigFile = class {
 	* >()("app/Secrets") {}
 	* ```
 	*/
-	static Service = Service;
+	static Service = () => (id) => Context.Service()(id);
 	/**
 	* Build the live layer for a config service class.
 	*
@@ -509,7 +468,12 @@ var ConfigFile = class {
 	* });
 	* ```
 	*/
-	static layer = layer;
+	static layer = (tag, options) => Layer.effect(tag, Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const resolverEnv = yield* Effect.context();
+		return makeImpl(options, fs, path, resolverEnv);
+	}));
 	/**
 	* A scoped layer that seeds `files` into a temp directory, wires the **real**
 	* live implementation over them, and removes the directory when the scope
@@ -543,7 +507,29 @@ var ConfigFile = class {
 	* }).pipe(Layer.provide(NodeServices.layer));
 	* ```
 	*/
-	static testLayer = testLayer;
+	static testLayer = (tag, options) => Layer.effect(tag, Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const resolverEnv = yield* Effect.context();
+		const dir = yield* fs.makeTempDirectory({ prefix: "effected-config-file-" }).pipe(Effect.orDie);
+		yield* Effect.addFinalizer(() => fs.remove(dir, { recursive: true }).pipe(Effect.orDie));
+		for (const [name, content] of Object.entries(options.files)) {
+			const target = path.join(dir, name);
+			yield* fs.makeDirectory(path.dirname(target), { recursive: true }).pipe(Effect.orDie);
+			yield* fs.writeFileString(target, content).pipe(Effect.orDie);
+		}
+		const resolvers = Object.keys(options.files).map((name) => ConfigResolver.staticDir({
+			dir,
+			filename: name
+		}));
+		return makeImpl({
+			schema: options.schema,
+			codec: options.codec,
+			strategy: options.strategy,
+			resolvers,
+			...options.validate !== void 0 && { validate: options.validate }
+		}, fs, path, resolverEnv);
+	}));
 	/**
 	* Read, decode and validate one explicit path — no service, no layer, no tag.
 	*
@@ -581,7 +567,17 @@ var ConfigFile = class {
 	* });
 	* ```
 	*/
-	static read = read;
+	static read = (path, options) => Effect.gen(function* () {
+		const raw = yield* (yield* FileSystem.FileSystem).readFileString(path).pipe(Effect.mapError((cause) => new ConfigFileReadError({
+			path,
+			cause
+		})));
+		const parsed = yield* options.codec.parse(raw).pipe(Effect.mapError((error) => withCodecPath(error, path)));
+		return yield* Schema.decodeUnknownEffect(options.schema)(parsed, options.parseOptions).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
+			path: Option.some(path),
+			issue: error.issue
+		}))));
+	}).pipe(Effect.withSpan("ConfigFile.read", { attributes: { path } }));
 };
 
 export { ConfigDefaultPathMissingError, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigValidationError };

package/ConfigMigration.js

@@ -60,24 +60,6 @@ const runPhase = (phase, version, name, run) => Effect.suspend(run).pipe(Effect.
 	phase,
 	cause
 })));
-const make = (options) => {
-	const access = options.versionAccess ?? VersionAccess.default;
-	const sorted = [...options.migrations].sort((a, b) => a.version - b.version);
-	return {
-		name: options.codec.name,
-		stringify: options.codec.stringify,
-		parse: (raw) => Effect.gen(function* () {
-			let parsed = yield* options.codec.parse(raw);
-			if (sorted.length === 0) return parsed;
-			const current = yield* runPhase("read-version", 0, "", () => access.get(parsed));
-			for (const migration of sorted.filter((m) => m.version > current)) {
-				parsed = yield* runPhase("apply", migration.version, migration.name, () => migration.up(parsed));
-				parsed = yield* runPhase("write-version", migration.version, migration.name, () => access.set(parsed, migration.version));
-			}
-			return parsed;
-		})
-	};
-};
 /** Versioned migration support for config codecs. @public */
 var ConfigMigration = class {
 	constructor() {}
@@ -111,7 +93,24 @@ var ConfigMigration = class {
 	* });
 	* ```
 	*/
-	static make = make;
+	static make = (options) => {
+		const access = options.versionAccess ?? VersionAccess.default;
+		const sorted = [...options.migrations].sort((a, b) => a.version - b.version);
+		return {
+			name: options.codec.name,
+			stringify: options.codec.stringify,
+			parse: (raw) => Effect.gen(function* () {
+				let parsed = yield* options.codec.parse(raw);
+				if (sorted.length === 0) return parsed;
+				const current = yield* runPhase("read-version", 0, "", () => access.get(parsed));
+				for (const migration of sorted.filter((m) => m.version > current)) {
+					parsed = yield* runPhase("apply", migration.version, migration.name, () => migration.up(parsed));
+					parsed = yield* runPhase("write-version", migration.version, migration.name, () => access.set(parsed, migration.version));
+				}
+				return parsed;
+			})
+		};
+	};
 };
 
 export { ConfigMigration, ConfigMigrationError, VersionAccess };

package/ConfigResolver.js

@@ -22,48 +22,6 @@ const absorb = (effect) => Effect.catch(effect, () => Effect.succeed({
 	probed: []
 }));
 const cwdOf = (given) => given ?? globalThis.process?.cwd?.() ?? "/";
-const explicitPath = (target) => fromProbe("explicit", absorb(Effect.gen(function* () {
-	return {
-		match: (yield* (yield* FileSystem.FileSystem).exists(target)) ? Option.some({ path: target }) : Option.none(),
-		probed: [target]
-	};
-})));
-const staticDir = (options) => fromProbe("static", absorb(Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
-	const candidate = (yield* Path.Path).join(options.dir, options.filename);
-	return {
-		match: (yield* fs.exists(candidate)) ? Option.some({
-			path: candidate,
-			dir: options.dir,
-			filename: options.filename
-		}) : Option.none(),
-		probed: [candidate]
-	};
-})));
-const upwardWalk = (options) => fromProbe(options.name ?? "walk", Effect.gen(function* () {
-	const fs = yield* FileSystem.FileSystem;
-	const path = yield* Path.Path;
-	const subpaths = options.subpaths ?? ["."];
-	const filenames = options.filenames ?? [options.filename];
-	const dirs = yield* Walker.ascend(cwdOf(options.cwd), { ...options.stopAt !== void 0 && { stopAt: options.stopAt } });
-	const candidates = [];
-	for (const dir of dirs) for (const sub of subpaths) for (const filename of filenames) candidates.push({
-		path: path.join(dir, sub, filename),
-		dir,
-		filename,
-		...options.subpaths !== void 0 && { subpath: sub }
-	});
-	const paths = candidates.map((candidate) => candidate.path);
-	const found = yield* Walker.firstMatch(paths, (candidate) => fs.exists(candidate));
-	const probed = Option.match(found, {
-		onNone: () => paths,
-		onSome: (target) => paths.slice(0, paths.indexOf(target) + 1)
-	});
-	return {
-		match: Option.flatMap(found, (target) => Option.fromNullishOr(candidates.find((candidate) => candidate.path === target))),
-		probed
-	};
-}));
 /**
 * Ascend from `cwd` looking for the first directory where `isRoot` reports
 * true, then probe `subpaths` under it. Shared by `gitRoot` and
@@ -125,27 +83,6 @@ const isWorkspaceRoot = (dir) => Effect.gen(function* () {
 	if (yield* fs.exists(pkgPath)) return Option.isSome(decodeWorkspacesManifest(yield* fs.readFileString(pkgPath)));
 	return false;
 });
-const gitRoot = (options) => rootAnchored("git", isGitRoot, options);
-const workspaceRoot = (options) => rootAnchored("workspace", isWorkspaceRoot, options);
-const systemEtc = (options) => fromProbe("system", absorb(Effect.gen(function* () {
-	if (globalThis.process?.platform === "win32") return {
-		match: Option.none(),
-		probed: []
-	};
-	const fs = yield* FileSystem.FileSystem;
-	const path = yield* Path.Path;
-	const base = options.dir ?? "/etc";
-	const dir = path.join(base, options.app);
-	const candidate = path.join(dir, options.filename);
-	return {
-		match: (yield* fs.exists(candidate)) ? Option.some({
-			path: candidate,
-			dir,
-			filename: options.filename
-		}) : Option.none(),
-		probed: [candidate]
-	};
-})));
 /**
 * Built-in resolvers, in the order a typical chain uses them.
 *
@@ -154,9 +91,25 @@ const systemEtc = (options) => fromProbe("system", absorb(Effect.gen(function* (
 var ConfigResolver = class {
 	constructor() {}
 	/** Resolves to `target` when it exists on disk, or `Option.none()` when it does not — no walking, no filename convention. */
-	static explicitPath = explicitPath;
+	static explicitPath = (target) => fromProbe("explicit", absorb(Effect.gen(function* () {
+		return {
+			match: (yield* (yield* FileSystem.FileSystem).exists(target)) ? Option.some({ path: target }) : Option.none(),
+			probed: [target]
+		};
+	})));
 	/** Resolves `path.join(dir, filename)` when it exists on disk, or `Option.none()` when it does not. */
-	static staticDir = staticDir;
+	static staticDir = (options) => fromProbe("static", absorb(Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const candidate = (yield* Path.Path).join(options.dir, options.filename);
+		return {
+			match: (yield* fs.exists(candidate)) ? Option.some({
+				path: candidate,
+				dir: options.dir,
+				filename: options.filename
+			}) : Option.none(),
+			probed: [candidate]
+		};
+	})));
 	/**
 	* Ascends from `cwd` (or the process cwd) toward `stopAt`, resolving the
 	* first `subpaths/filename` combination found at each level.
@@ -172,24 +125,65 @@ var ConfigResolver = class {
 	* distinguishable; `ConfigSource.match` identifies the matching candidate
 	* more precisely still.
 	*/
-	static upwardWalk = upwardWalk;
+	static upwardWalk = (options) => fromProbe(options.name ?? "walk", Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const subpaths = options.subpaths ?? ["."];
+		const filenames = options.filenames ?? [options.filename];
+		const dirs = yield* Walker.ascend(cwdOf(options.cwd), { ...options.stopAt !== void 0 && { stopAt: options.stopAt } });
+		const candidates = [];
+		for (const dir of dirs) for (const sub of subpaths) for (const filename of filenames) candidates.push({
+			path: path.join(dir, sub, filename),
+			dir,
+			filename,
+			...options.subpaths !== void 0 && { subpath: sub }
+		});
+		const paths = candidates.map((candidate) => candidate.path);
+		const found = yield* Walker.firstMatch(paths, (candidate) => fs.exists(candidate));
+		const probed = Option.match(found, {
+			onNone: () => paths,
+			onSome: (target) => paths.slice(0, paths.indexOf(target) + 1)
+		});
+		return {
+			match: Option.flatMap(found, (target) => Option.fromNullishOr(candidates.find((candidate) => candidate.path === target))),
+			probed
+		};
+	}));
 	/**
 	* Ascends from `cwd` to the nearest workspace root — a directory with a
 	* `pnpm-workspace.yaml`, or a `package.json` carrying a `workspaces` field —
 	* then resolves the first `subpaths/filename` combination found under it.
 	*/
-	static workspaceRoot = workspaceRoot;
+	static workspaceRoot = (options) => rootAnchored("workspace", isWorkspaceRoot, options);
 	/**
 	* Ascends from `cwd` to the nearest git root — a directory containing a
 	* `.git` entry, directory or file (the latter for a worktree) — then
 	* resolves the first `subpaths/filename` combination found under it.
 	*/
-	static gitRoot = gitRoot;
+	static gitRoot = (options) => rootAnchored("git", isGitRoot, options);
 	/**
 	* Resolves `<dir>/<app>/<filename>` under the system config root (`/etc` by
 	* default). Always `Option.none()` on Windows, where `/etc` has no meaning.
 	*/
-	static systemEtc = systemEtc;
+	static systemEtc = (options) => fromProbe("system", absorb(Effect.gen(function* () {
+		if (globalThis.process?.platform === "win32") return {
+			match: Option.none(),
+			probed: []
+		};
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const base = options.dir ?? "/etc";
+		const dir = path.join(base, options.app);
+		const candidate = path.join(dir, options.filename);
+		return {
+			match: (yield* fs.exists(candidate)) ? Option.some({
+				path: candidate,
+				dir,
+				filename: options.filename
+			}) : Option.none(),
+			probed: [candidate]
+		};
+	})));
 };
 
 export { ConfigResolver };

package/MergeStrategy.js

@@ -2,39 +2,6 @@ import { canMerge, deepMerge } from "./internal/deepMerge.js";
 import { Effect } from "effect";
 
 // src/MergeStrategy.ts
-const firstMatch = () => ({
-	name: "first-match",
-	resolve: (sources) => Effect.succeed(sources[0].value)
-});
-/**
-* Deep-merge every contributing source, higher priority winning on conflict.
-*
-* @remarks
-* Two values merge only when both are record-like and share a prototype, so a
-* document decoded through `Schema.Class` merges with another of the same class
-* and **survives as a real instance** — `instanceof` holds and its getters
-* still work. Everything else is atomic: a nested `Date`, `Map`, `Set`,
-* `RegExp`, array, or class instance is taken whole from the highest-priority
-* source that defines it, never reshaped field-by-field.
-*
-* The alternative — spreading each value into a fresh object — would make
-* `load`'s declared `Effect<A>` a lie, handing back a structurally-equal plain
-* object whose class methods are gone and whose `Date` fields have decayed to
-* `{}`.
-*
-* Nested *plain* objects (a `Schema.Struct` section) still merge field-wise.
-*/
-const layeredMerge = () => ({
-	name: "layered-merge",
-	resolve: (sources) => {
-		let merged = sources[sources.length - 1]?.value;
-		for (let i = sources.length - 2; i >= 0; i--) {
-			const higher = sources[i]?.value;
-			merged = canMerge(merged, higher) ? deepMerge(higher, merged) : higher;
-		}
-		return Effect.succeed(merged);
-	}
-});
 /**
 * Built-in merge strategies: `firstMatch` (the highest-priority source wins
 * whole) and `layeredMerge` (every source deep-merged, higher priority winning).
@@ -53,8 +20,40 @@ const layeredMerge = () => ({
 * @public
 */
 const MergeStrategy = {
-	firstMatch,
-	layeredMerge
+	/** Take the highest-priority source whole. */
+	firstMatch: () => ({
+		name: "first-match",
+		resolve: (sources) => Effect.succeed(sources[0].value)
+	}),
+	/**
+	* Deep-merge every contributing source, higher priority winning on conflict.
+	*
+	* @remarks
+	* Two values merge only when both are record-like and share a prototype, so a
+	* document decoded through `Schema.Class` merges with another of the same class
+	* and **survives as a real instance** — `instanceof` holds and its getters
+	* still work. Everything else is atomic: a nested `Date`, `Map`, `Set`,
+	* `RegExp`, array, or class instance is taken whole from the highest-priority
+	* source that defines it, never reshaped field-by-field.
+	*
+	* The alternative — spreading each value into a fresh object — would make
+	* `load`'s declared `Effect<A>` a lie, handing back a structurally-equal plain
+	* object whose class methods are gone and whose `Date` fields have decayed to
+	* `{}`.
+	*
+	* Nested *plain* objects (a `Schema.Struct` section) still merge field-wise.
+	*/
+	layeredMerge: () => ({
+		name: "layered-merge",
+		resolve: (sources) => {
+			let merged = sources[sources.length - 1]?.value;
+			for (let i = sources.length - 2; i >= 0; i--) {
+				const higher = sources[i]?.value;
+				merged = canMerge(merged, higher) ? deepMerge(higher, merged) : higher;
+			}
+			return Effect.succeed(merged);
+		}
+	})
 };
 
 export { MergeStrategy };

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Composable config file loading for Effect. Declare a resolver chain — an explicit path, an upward walk from the cwd, the workspace or git root, `/etc` — decode every discovered file through an Effect `Schema`, and combine the results with a merge strategy. JSON, JSONC, YAML and TOML all decode with no extra install. Codecs, resolvers and merge strategies are pluggable seams, and failures arrive as tagged errors carrying structured payloads rather than prose, so "no config anywhere" is routable separately from "the config I found is broken".
+Composable config file loading for Effect. Declare a resolver chain — an explicit path, an upward walk from the cwd, the workspace or git root, `/etc` — decode every discovered file through an Effect `Schema`, and combine the results with a merge strategy. JSON decodes out of the box; JSONC, YAML and TOML each take one optional engine package. Codecs, resolvers and merge strategies are pluggable seams, and failures arrive as tagged errors carrying structured payloads rather than prose, so "no config anywhere" is routable separately from "the config I found is broken".
 
 > **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, built on stable
 > Effect v4 (`effect` `^4.0.0`) and still in `0.x` development. Stable Effect
@@ -33,11 +33,17 @@ npm install @effected/config-file effect @effect/platform-node
 pnpm add @effected/config-file effect @effect/platform-node
 ```
 
-Requires Node.js >=24.11.0. Every format is covered by that one install; there is no separate package to add for YAML or TOML.
+Requires Node.js >=24.11.0. That install covers JSON. To read JSONC, YAML or TOML, add the matching engine:
+
+```bash
+pnpm add @effected/jsonc   # for @effected/config-file/jsonc
+pnpm add @effected/yaml    # for @effected/config-file/yaml
+pnpm add @effected/toml    # for @effected/config-file/toml
+```
 
 All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
 
-`effect` v4 is a peer dependency, and so are `@effected/jsonc`, `@effected/toml`, `@effected/walker` and `@effected/yaml` — the first-party engines behind the JSONC, YAML and TOML codecs, plus the traversal primitive the `upwardWalk`, `workspaceRoot` and `gitRoot` resolvers are built on. Package managers that install peers automatically will pull them in; add them to your manifest explicitly if yours does not. The package declares no runtime dependencies of its own, so nothing it drags into your tree comes from outside `effect` and `@effected/*`.
+`effect` v4 is a peer dependency, and so are `@effected/walker` and `@effected/glob` — the traversal primitive the `upwardWalk`, `workspaceRoot` and `gitRoot` resolvers are built on, and the matcher it peers on. Package managers that install peers automatically will pull them in; add them to your manifest explicitly if yours does not. `@effected/jsonc`, `@effected/yaml` and `@effected/toml` are **optional** peers: only the `./jsonc`, `./yaml` and `./toml` subpaths load them, and the package root never does, so a JSON-only program installs and loads none of them. The package declares no runtime dependencies of its own, so nothing it drags into your tree comes from outside `effect` and `@effected/*`.
 
 Reading and writing files needs a `FileSystem` and a `Path` implementation, provided once at the edge — from `@effect/platform-node` on Node.
 
@@ -80,7 +86,8 @@ Effect.runPromise(program.pipe(Effect.provide(AppConfigLive), Effect.provide(Pla
 Resolvers are consulted in priority order, highest first. `MergeStrategy.firstMatch` takes the winner; `MergeStrategy.layeredMerge` deep-merges every source that matched, with higher-priority keys overwriting lower ones:
 
 ```ts
-import { ConfigFile, ConfigResolver, MergeStrategy, YamlCodec } from "@effected/config-file";
+import { ConfigFile, ConfigResolver, MergeStrategy } from "@effected/config-file";
+import { YamlCodec } from "@effected/config-file/yaml";
 import { Schema } from "effect";
 
 class Settings extends Schema.Class<Settings>("Settings")({ port: Schema.Number }) {}
@@ -176,16 +183,16 @@ export const loadOrFallback = (config: ConfigFileShape<AppShape>) =>
 
 ## Codecs
 
-Four codecs ship in the package, each a free-standing named export:
+Four codecs ship in the package, each a free-standing named export. `JsonCodec` comes from the package root; the other three each have their own subpath and an optional engine peer to install beside it:
 
-| Codec | Format | Engine |
-| ----- | ------ | ------ |
-| `JsonCodec` | JSON | the host `JSON` global, no parser at all |
-| `JsoncCodec` | JSONC | `@effected/jsonc` |
-| `YamlCodec` | YAML | `@effected/yaml` |
-| `TomlCodec` | TOML | `@effected/toml` |
+| Codec | Format | Import from | Engine |
+| ----- | ------ | ----------- | ------ |
+| `JsonCodec` | JSON | `@effected/config-file` | the host `JSON` global, no parser at all |
+| `JsoncCodec` | JSONC | `@effected/config-file/jsonc` | `@effected/jsonc` |
+| `YamlCodec` | YAML | `@effected/config-file/yaml` | `@effected/yaml` |
+| `TomlCodec` | TOML | `@effected/config-file/toml` | `@effected/toml` |
 
-One install covers every format, and you still pay only for the parser you name. The codecs are free-standing exports rather than properties of a namespace object, so importing `TomlCodec` never references the YAML or JSONC bindings, their parsing engines are unreachable from your entrypoint and a bundler drops them. A JSON-only application ships no parser at all.
+You install and load only the parser you name. The root never reaches a subpath, so a JSON-only application installs no parser and ships none. Each subpath reaches only its own engine, and the codecs are never collected into a namespace object, so importing `TomlCodec` never references the YAML or JSONC bindings.
 
 Codecs compose. `EncryptedCodec` wraps any codec with AES-GCM, and `ConfigMigration.make` wraps any codec so parsed content is brought up to the latest version. Each *widens* the error channel rather than flattening its failures into the inner codec's error, and a decorated codec plugs into `ConfigFile.layer`, `ConfigFile.testLayer` and `ConfigFile.read` like any other: their error unions widen with it. A service key names the widened error as its third type argument:
 
@@ -242,7 +249,7 @@ Leave the third type argument off and the `ConfigFile.layer` call is a compile e
 - `encode` / `write` / `save` / `update` — the write path. `encode(value, options?)` returns the serialized text a `write` would put on disk without writing, emitting an event or naming a path in its errors: the primitive behind a `--dry-run` flag. `write` takes an explicit path the caller vouches for; `save` and `update` resolve the layer's `defaultPath` and create its parent directory. `encode` and `write` accept `{ header }`, text prepended verbatim above the document with exactly one newline between — a `#:schema https://…` directive atop a TOML file, say. The caller owns its validity in the target format; JSON has no comment syntax, so a header on `JsonCodec` yields an unparseable file by construction.
 - `ConfigResolver` — `explicitPath`, `staticDir`, `upwardWalk`, `workspaceRoot`, `gitRoot` and `systemEtc`. A resolver's error channel is `never` by contract: every filesystem failure becomes `Option.none()`, so one unreadable tier never aborts the chain.
 - `MergeStrategy` — `firstMatch` and `layeredMerge`, combining discovered sources in priority order.
-- `JsonCodec`, `JsoncCodec`, `YamlCodec`, `TomlCodec` — JSON, JSONC, YAML and TOML in the box, exported free-standing so an unused format's engine is tree-shaken away.
+- `JsonCodec` (root), `JsoncCodec` (`./jsonc`), `YamlCodec` (`./yaml`), `TomlCodec` (`./toml`) — JSON, JSONC, YAML and TOML, exported free-standing and split by subpath so an unused format's engine is neither installed nor loaded.
 - `ConfigCodec` / `EncryptedCodec` / `ConfigMigration` — a pluggable codec seam, generic in its error type so decorators widen rather than flatten. `ConfigCodec` is the interface: bring your own format by satisfying it.
 - `ConfigEvents` — an opt-in `PubSub` of `ConfigEvent`, honestly zero-cost when omitted: no `events` option means no context lookup at all. Failure events carry the structured typed error, never a `reason` string.
 - `asConfigProvider` / `layerConfigProvider` — expose a loaded, validated document as a v4 `ConfigProvider`, layered beneath the ambient one so an environment variable overrides the file it was deployed with.

package/index.d.ts

@@ -48,13 +48,14 @@ export declare class ConfigCodecError extends ConfigCodecError_base {
  * decorator codecs such as `EncryptedCodec` and `ConfigMigration.make` widen it
  * rather than flattening their own failures into a string.
  *
- * The four built-in codecs — `JsonCodec`, `JsoncCodec`, `YamlCodec` and
- * `TomlCodec` — are free-standing named exports, one per module, and are
- * deliberately never collected into a namespace object. Collecting them would
- * make this module a dispatch table: referencing it at all would reach every
- * codec, and every codec would reach its parsing engine, so importing the JSON
- * codec alone would drag the JSONC, YAML and TOML engines into the bundle.
- * Name the one codec you use and a bundler drops the rest.
+ * The four built-in codecs are free-standing named exports, one per module,
+ * and are deliberately never collected into a namespace object. `JsonCodec`
+ * ships from the package root; `JsoncCodec`, `YamlCodec` and `TomlCodec` ship
+ * from the `./jsonc`, `./yaml` and `./toml` subpaths, whose engines are
+ * optional peers the root never reaches. Collecting them would make this module
+ * a dispatch table: referencing it at all would reach every codec, and every
+ * codec would reach its parsing engine, so importing the JSON codec alone would
+ * drag the JSONC, YAML and TOML engines into the bundle.
  *
  * @public
  */
@@ -575,7 +576,26 @@ export interface MergeStrategy<A> {
  * @public
  */
 export declare const MergeStrategy: {
+  /** Take the highest-priority source whole. */
   readonly firstMatch: <A>() => MergeStrategy<A>;
+  /**
+   * Deep-merge every contributing source, higher priority winning on conflict.
+   *
+   * @remarks
+   * Two values merge only when both are record-like and share a prototype, so a
+   * document decoded through `Schema.Class` merges with another of the same class
+   * and **survives as a real instance** — `instanceof` holds and its getters
+   * still work. Everything else is atomic: a nested `Date`, `Map`, `Set`,
+   * `RegExp`, array, or class instance is taken whole from the highest-priority
+   * source that defines it, never reshaped field-by-field.
+   *
+   * The alternative — spreading each value into a fresh object — would make
+   * `load`'s declared `Effect<A>` a lie, handing back a structurally-equal plain
+   * object whose class methods are gone and whose `Date` fields have decayed to
+   * `{}`.
+   *
+   * Nested *plain* objects (a `Schema.Struct` section) still merge field-wise.
+   */
   readonly layeredMerge: <A>() => MergeStrategy<A>;
 };
 declare const ConfigFileNotFoundError_base: Schema.Class<ConfigFileNotFoundError, Schema.TaggedStruct<"ConfigFileNotFoundError", {
@@ -1464,53 +1484,5 @@ export declare function EncryptedCodec<E>(inner: ConfigCodec<E>, keySource: Encr
  * @public
  */
 export declare const JsonCodec: ConfigCodec;
-/**
- * A `ConfigCodec` backed by `@effected/jsonc`: JSON with comments and
- * trailing commas.
- *
- * @remarks
- * `@effected/jsonc` does not expose a `stringify` — its schema layer's encode
- * direction is `JSON.stringify` (comments never survive a round-trip encode;
- * see `Jsonc.fromString`'s remarks), so `stringify` here calls `JSON.stringify`
- * directly and wraps a thrown defect the same way `JsonCodec` does.
- * Both directions preserve the underlying failure structurally in `cause` —
- * never stringified.
- *
- * @public
- */
-export declare const JsoncCodec: ConfigCodec;
-/**
- * A `ConfigCodec` backed by `@effected/toml`.
- *
- * @remarks
- * `@effected/toml`'s input hardening — a nesting-depth cap on arrays and
- * inline tables, enforced independently on both the parse and stringify
- * sides — fails through the typed error channel, so a hostile config file
- * surfaces as a `ConfigCodecError` rather than crashing the process. Both
- * directions preserve the underlying failure structurally in `cause` —
- * never stringified.
- *
- * Stringify is genuinely fallible beyond hostile input: TOML has no null,
- * so a document carrying `null` (or any other unrepresentable value, an
- * out-of-int64-range `bigint`, a circular reference) fails with a
- * `ConfigCodecError` whose `cause` is the structured `TomlStringifyError`.
- *
- * @public
- */
-export declare const TomlCodec: ConfigCodec;
-/**
- * A `ConfigCodec` backed by `@effected/yaml`.
- *
- * @remarks
- * `@effected/yaml`'s input hardening — an alias-expansion budget guarding
- * against "billion laughs" alias bombs, and a collection-nesting depth cap —
- * fails through the typed error channel, so a hostile config file surfaces
- * as a `ConfigCodecError` rather than crashing the process. Both directions
- * preserve the underlying failure structurally in `cause` — never
- * stringified.
- *
- * @public
- */
-export declare const YamlCodec: ConfigCodec;
 export type { ConfigCodec, ConfigEncodeError, ConfigEncodeOptions, ConfigEventsShape, ConfigFileMigration, ConfigFileOptions, ConfigFileShape, ConfigFileTestOptions, ConfigLoadError, ConfigMatch, ConfigMigrationOptions, ConfigProbe, ConfigReadError, ConfigReadOptions, ConfigSaveError, ConfigSource, ConfigUpdateError, ConfigWriteError, LayerConfigProviderOptions, NonEmptySources, UpwardWalkOptions };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -6,9 +6,6 @@ import { ConfigMigration, ConfigMigrationError, VersionAccess } from "./ConfigMi
 import { asConfigProvider, layerConfigProvider } from "./ConfigProvider.js";
 import { ConfigEncryptionError, EncryptedCodec, EncryptedCodecKey } from "./EncryptedCodec.js";
 import { JsonCodec } from "./JsonCodec.js";
-import { JsoncCodec } from "./JsoncCodec.js";
 import { MergeStrategy } from "./MergeStrategy.js";
-import { TomlCodec } from "./TomlCodec.js";
-import { YamlCodec } from "./YamlCodec.js";
 
-export { ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigMigration, ConfigMigrationError, ConfigResolver, ConfigSourceRef, ConfigValidationError, EncryptedCodec, EncryptedCodecKey, JsonCodec, JsoncCodec, MergeStrategy, TomlCodec, VersionAccess, YamlCodec, asConfigProvider, layerConfigProvider };
+export { ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigMigration, ConfigMigrationError, ConfigResolver, ConfigSourceRef, ConfigValidationError, EncryptedCodec, EncryptedCodecKey, JsonCodec, MergeStrategy, VersionAccess, asConfigProvider, layerConfigProvider };

package/jsonc.d.ts

@@ -0,0 +1,17 @@
+import { ConfigCodec } from "@effected/config-file";
+/**
+ * A `ConfigCodec` backed by `@effected/jsonc`: JSON with comments and
+ * trailing commas.
+ *
+ * @remarks
+ * `@effected/jsonc` does not expose a `stringify` — its schema layer's encode
+ * direction is `JSON.stringify` (comments never survive a round-trip encode;
+ * see `Jsonc.fromString`'s remarks), so `stringify` here calls `JSON.stringify`
+ * directly and wraps a thrown defect the same way `JsonCodec` does.
+ * Both directions preserve the underlying failure structurally in `cause` —
+ * never stringified.
+ *
+ * @public
+ */
+export declare const JsoncCodec: ConfigCodec;
+//# sourceMappingURL=jsonc.d.ts.map

package/jsonc.js

@@ -0,0 +1,3 @@
+import { JsoncCodec } from "./JsoncCodec.js";
+
+export { JsoncCodec };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.19.1",
+	"version": "0.20.1",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [
@@ -40,16 +40,42 @@
 			"import": "./index.js",
 			"default": "./index.js"
 		},
+		"./jsonc": {
+			"types": "./jsonc.d.ts",
+			"import": "./jsonc.js",
+			"default": "./jsonc.js"
+		},
+		"./toml": {
+			"types": "./toml.d.ts",
+			"import": "./toml.js",
+			"default": "./toml.js"
+		},
+		"./yaml": {
+			"types": "./yaml.d.ts",
+			"import": "./yaml.js",
+			"default": "./yaml.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
 		"@effected/glob": "^0.14.0",
 		"@effected/jsonc": "^0.20.0",
 		"@effected/toml": "^0.16.0",
-		"@effected/walker": "^0.19.0",
-		"@effected/yaml": "^0.25.0",
+		"@effected/walker": "^0.20.1",
+		"@effected/yaml": "^0.25.1",
 		"effect": "^4.0.0"
 	},
+	"peerDependenciesMeta": {
+		"@effected/jsonc": {
+			"optional": true
+		},
+		"@effected/toml": {
+			"optional": true
+		},
+		"@effected/yaml": {
+			"optional": true
+		}
+	},
 	"engines": {
 		"node": ">=24.11.0"
 	}

package/toml.d.ts

@@ -0,0 +1,21 @@
+import { ConfigCodec } from "@effected/config-file";
+/**
+ * A `ConfigCodec` backed by `@effected/toml`.
+ *
+ * @remarks
+ * `@effected/toml`'s input hardening — a nesting-depth cap on arrays and
+ * inline tables, enforced independently on both the parse and stringify
+ * sides — fails through the typed error channel, so a hostile config file
+ * surfaces as a `ConfigCodecError` rather than crashing the process. Both
+ * directions preserve the underlying failure structurally in `cause` —
+ * never stringified.
+ *
+ * Stringify is genuinely fallible beyond hostile input: TOML has no null,
+ * so a document carrying `null` (or any other unrepresentable value, an
+ * out-of-int64-range `bigint`, a circular reference) fails with a
+ * `ConfigCodecError` whose `cause` is the structured `TomlStringifyError`.
+ *
+ * @public
+ */
+export declare const TomlCodec: ConfigCodec;
+//# sourceMappingURL=toml.d.ts.map

package/toml.js

@@ -0,0 +1,3 @@
+import { TomlCodec } from "./TomlCodec.js";
+
+export { TomlCodec };

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.1"
+      "packageVersion": "7.59.4"
     }
   ]
 }

package/yaml.d.ts

@@ -0,0 +1,16 @@
+import { ConfigCodec } from "@effected/config-file";
+/**
+ * A `ConfigCodec` backed by `@effected/yaml`.
+ *
+ * @remarks
+ * `@effected/yaml`'s input hardening — an alias-expansion budget guarding
+ * against "billion laughs" alias bombs, and a collection-nesting depth cap —
+ * fails through the typed error channel, so a hostile config file surfaces
+ * as a `ConfigCodecError` rather than crashing the process. Both directions
+ * preserve the underlying failure structurally in `cause` — never
+ * stringified.
+ *
+ * @public
+ */
+export declare const YamlCodec: ConfigCodec;
+//# sourceMappingURL=yaml.d.ts.map

package/yaml.js

@@ -0,0 +1,3 @@
+import { YamlCodec } from "./YamlCodec.js";
+
+export { YamlCodec };