@effected/config-file 0.8.0 → 0.10.0

package/ConfigFile.js

@@ -14,11 +14,26 @@ import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PubSub, Sch
 *
 * @public
 */
-var ConfigFileNotFoundError = class extends Schema.TaggedError()("ConfigFileNotFoundError", { 
-/** The names of the resolvers that were probed, in order. */
-searched: Schema.Array(Schema.String) }) {
+var ConfigFileNotFoundError = class extends Schema.TaggedError()("ConfigFileNotFoundError", {
+	/** The names of the resolvers that were probed, in order. */
+	searched: Schema.Array(Schema.String),
+	/**
+	* The candidate paths the chain actually checked on disk, in probe order
+	* across every resolver — the failure-path mirror of {@link ConfigMatch}.
+	*
+	* @remarks
+	* One `searched` name can hide many paths: an `upwardWalk` with a
+	* `filenames` list probes every name at every ancestor. Resolvers that omit
+	* the optional `resolveProbe` member contribute nothing here, so the list
+	* can be shorter than the true search (or empty for a fully hand-rolled
+	* chain) — `searched` remains the complete resolver list either way.
+	*/
+	candidates: Schema.Array(Schema.String)
+}) {
 	get message() {
-		return `No config file found (searched: ${this.searched.join(", ")})`;
+		const count = this.candidates.length;
+		const probed = count === 0 ? "" : ` — ${count} candidate path${count === 1 ? "" : "s"} checked`;
+		return `No config file found (searched: ${this.searched.join(", ")}${probed})`;
 	}
 };
 /**
@@ -120,6 +135,13 @@ const withCodecPath = (error, target) => error instanceof ConfigCodecError && er
 	cause: error.cause,
 	path: target
 }) : error;
+/**
+* Put `header` in front of `document`, separated by exactly one newline.
+*
+* A header that already ends in a newline is not given another — a caller who
+* built the line with a trailing `"\n"` and one who did not get the same file.
+*/
+const prependHeader = (document, header) => header === void 0 ? document : header.endsWith("\n") ? `${header}${document}` : `${header}\n${document}`;
 const makeImpl = (options, fs, path, resolverEnv) => {
 	/**
 	* Publish one event, or nothing at all.
@@ -189,8 +211,15 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	});
 	const discover = Effect.fn("ConfigFile.discover")(function* () {
 		const sources = [];
+		const candidates = [];
 		for (const resolver of options.resolvers) {
-			const found = resolver.resolveMatch === void 0 ? Option.map(yield* Effect.provide(resolver.resolve, resolverEnv), (path) => ({ path })) : yield* Effect.provide(resolver.resolveMatch, resolverEnv);
+			let found;
+			if (resolver.resolveProbe !== void 0) {
+				const probe = yield* Effect.provide(resolver.resolveProbe, resolverEnv);
+				found = probe.match;
+				if (Option.isNone(found)) candidates.push(...probe.probed);
+			} else if (resolver.resolveMatch !== void 0) found = yield* Effect.provide(resolver.resolveMatch, resolverEnv);
+			else found = Option.map(yield* Effect.provide(resolver.resolve, resolverEnv), (path) => ({ path }));
 			if (Option.isSome(found)) {
 				const match = found.value;
 				const target = match.path;
@@ -207,7 +236,10 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 				});
 			}
 		}
-		return sources;
+		return {
+			sources,
+			candidates
+		};
 	});
 	const searched = options.resolvers.map((r) => r.name);
 	/**
@@ -232,15 +264,18 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		return value;
 	});
 	const load = Effect.fn("ConfigFile.load")(function* () {
-		const sources = yield* discover();
+		const { sources, candidates } = yield* discover();
 		if (sources.length === 0) {
 			yield* emit({ _tag: "NotFound" });
-			return yield* Effect.fail(new ConfigFileNotFoundError({ searched }));
+			return yield* Effect.fail(new ConfigFileNotFoundError({
+				searched,
+				candidates
+			}));
 		}
 		return yield* mergeAndEmit(sources);
 	});
 	const loadOrDefault = Effect.fn("ConfigFile.loadOrDefault")(function* (defaultValue) {
-		const sources = yield* discover();
+		const { sources } = yield* discover();
 		if (sources.length === 0) {
 			yield* emit({ _tag: "NotFound" });
 			return defaultValue;
@@ -252,24 +287,46 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		return yield* runValidate(decoded);
 	});
 	/**
-	* Shared by `write` and `save`. Not an `Effect.fn`: it is internal, and the
-	* public boundaries that call it already open a span.
+	* Schema-encode, stringify, and prepend the header. Shared by `encode`,
+	* `write` and `save`. Not an `Effect.fn`: it is internal, and the public
+	* boundaries that call it already open a span.
+	*
+	* `target` is the file this text is destined for, when there is one. It is
+	* only ever used to NAME the file in an error — `encode` passes `none` and
+	* its errors honestly carry no path.
 	*/
-	const encodeAndWrite = (value, target) => Effect.gen(function* () {
+	const encodeTo = (value, target, encodeOptions) => Effect.gen(function* () {
 		const encoded = yield* Schema.encodeEffect(options.schema)(value).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(new ConfigValidationError({
-			path: Option.some(target),
+			path: target,
 			issue: error.issue
 		}))));
-		const serialized = yield* options.codec.stringify(encoded).pipe(Effect.mapError((error) => withCodecPath(error, target)), Effect.tapError((error) => emit({
+		const serialized = yield* options.codec.stringify(encoded).pipe(Effect.mapError((error) => Option.match(target, {
+			onNone: () => error,
+			onSome: (file) => withCodecPath(error, file)
+		})));
+		return prependHeader(serialized, encodeOptions?.header);
+	});
+	/**
+	* `encodeTo` a known file, then write it. Shared by `write` and `save`.
+	*
+	* `StringifyFailed` is emitted HERE, not in `encodeTo`: it is a write-path
+	* event, and `encode` promises to publish nothing. A subscriber counting
+	* failed writes must not see a dry run's codec failure.
+	*/
+	const encodeAndWrite = (value, target, encodeOptions) => Effect.gen(function* () {
+		const serialized = yield* encodeTo(value, Option.some(target), encodeOptions).pipe(Effect.tapError((error) => error._tag === "ConfigCodecError" ? emit({
 			_tag: "StringifyFailed",
 			codec: options.codec.name,
 			error
-		})));
+		}) : Effect.void));
 		yield* fs.writeFileString(target, serialized).pipe(Effect.mapError((cause) => new ConfigFileWriteError({
 			path: target,
 			cause
 		})));
 	});
+	const encode = Effect.fn("ConfigFile.encode")(function* (value, encodeOptions) {
+		return yield* encodeTo(value, Option.none(), encodeOptions);
+	});
 	/**
 	* Resolve `defaultPath`, `mkdir -p` its parent and write. Shared by `save`
 	* and `update`, and — crucially — emits nothing.
@@ -290,8 +347,8 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		yield* encodeAndWrite(value, target);
 		return target;
 	});
-	const write = Effect.fn("ConfigFile.write")(function* (value, target) {
-		yield* encodeAndWrite(value, target);
+	const write = Effect.fn("ConfigFile.write")(function* (value, target, encodeOptions) {
+		yield* encodeAndWrite(value, target, encodeOptions);
 		yield* emit({
 			_tag: "Written",
 			path: target
@@ -332,9 +389,10 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	return {
 		load: load(),
 		loadFrom,
-		discover: discover(),
+		discover: Effect.map(discover(), (found) => found.sources),
 		loadOrDefault,
 		validate,
+		encode,
 		write,
 		save,
 		update

package/ConfigResolver.js

@@ -3,33 +3,44 @@ import { Walker } from "@effected/walker";
 
 //#region src/ConfigResolver.ts
 /**
-* Build a resolver from a match-reporting lookup, deriving `resolve` from it.
+* Build a resolver from a probe-reporting lookup, deriving `resolveMatch` and
+* `resolve` from it.
 *
 * @remarks
-* Every built-in goes through here, so `resolve` and `resolveMatch` are one
-* implementation and cannot drift.
+* Every built-in goes through here, so `resolve`, `resolveMatch` and
+* `resolveProbe` are one implementation and cannot drift.
 */
-const fromMatch = (name, resolveMatch) => ({
+const fromProbe = (name, resolveProbe) => ({
 	name,
-	resolve: Effect.map(resolveMatch, Option.map((match) => match.path)),
-	resolveMatch
+	resolve: Effect.map(resolveProbe, (probe) => Option.map(probe.match, (match) => match.path)),
+	resolveMatch: Effect.map(resolveProbe, (probe) => probe.match),
+	resolveProbe
 });
-/** Absorb any failure into `Option.none()` — the resolver contract. */
-const absorb = (effect) => Effect.catch(effect, () => Effect.succeed(Option.none()));
+/** Absorb any failure into an empty probe — the resolver contract. */
+const absorb = (effect) => Effect.catch(effect, () => Effect.succeed({
+	match: Option.none(),
+	probed: []
+}));
 const cwdOf = (given) => given ?? globalThis.process?.cwd?.() ?? "/";
-const explicitPath = (target) => fromMatch("explicit", absorb(Effect.gen(function* () {
-	return (yield* (yield* FileSystem.FileSystem).exists(target)) ? Option.some({ path: target }) : Option.none();
+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) => fromMatch("static", absorb(Effect.gen(function* () {
+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 (yield* fs.exists(candidate)) ? Option.some({
-		path: candidate,
-		dir: options.dir,
-		filename: options.filename
-	}) : Option.none();
+	return {
+		match: (yield* fs.exists(candidate)) ? Option.some({
+			path: candidate,
+			dir: options.dir,
+			filename: options.filename
+		}) : Option.none(),
+		probed: [candidate]
+	};
 })));
-const upwardWalk = (options) => fromMatch(options.name ?? "walk", Effect.gen(function* () {
+const upwardWalk = (options) => fromProbe(options.name ?? "walk", Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const subpaths = options.subpaths ?? ["."];
@@ -42,31 +53,50 @@ const upwardWalk = (options) => fromMatch(options.name ?? "walk", Effect.gen(fun
 		filename,
 		...options.subpaths !== void 0 && { subpath: sub }
 	});
-	const found = yield* Walker.firstMatch(candidates.map((candidate) => candidate.path), (candidate) => fs.exists(candidate));
-	return Option.flatMap(found, (target) => Option.fromNullishOr(candidates.find((candidate) => candidate.path === target)));
+	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
 * `workspaceRoot`, which differ only in how a "root" is detected.
 */
-const rootAnchored = (name, isRoot, options) => fromMatch(name, Effect.gen(function* () {
+const rootAnchored = (name, isRoot, options) => fromProbe(name, Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
 	const path = yield* Path.Path;
 	const dirs = yield* Walker.ascend(cwdOf(options.cwd));
 	const root = yield* Walker.findRoot(dirs, isRoot);
-	if (Option.isNone(root)) return Option.none();
+	if (Option.isNone(root)) return {
+		match: Option.none(),
+		probed: []
+	};
 	const subpaths = options.subpaths ?? ["."];
-	const found = yield* Walker.firstMatch(subpaths.map((sub) => path.join(root.value, sub, options.filename)), (candidate) => fs.exists(candidate));
-	return Option.map(found, (target) => {
-		const matchedSubpath = options.subpaths === void 0 ? void 0 : subpaths.find((sub) => path.join(root.value, sub, options.filename) === target);
-		return {
-			path: target,
-			dir: root.value,
-			filename: options.filename,
-			...matchedSubpath !== void 0 && { subpath: matchedSubpath }
-		};
+	const paths = subpaths.map((sub) => path.join(root.value, sub, options.filename));
+	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.map(found, (target) => {
+			const matchedSubpath = options.subpaths === void 0 ? void 0 : subpaths.find((sub) => path.join(root.value, sub, options.filename) === target);
+			return {
+				path: target,
+				dir: root.value,
+				filename: options.filename,
+				...matchedSubpath !== void 0 && { subpath: matchedSubpath }
+			};
+		}),
+		probed
+	};
 }));
 /** `.git` may be a directory (a normal repo) or a file (a worktree pointing at the real repo). */
 const isGitRoot = (dir) => Effect.gen(function* () {
@@ -90,18 +120,24 @@ const isWorkspaceRoot = (dir) => Effect.gen(function* () {
 });
 const gitRoot = (options) => rootAnchored("git", isGitRoot, options);
 const workspaceRoot = (options) => rootAnchored("workspace", isWorkspaceRoot, options);
-const systemEtc = (options) => fromMatch("system", absorb(Effect.gen(function* () {
-	if (globalThis.process?.platform === "win32") return Option.none();
+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 (yield* fs.exists(candidate)) ? Option.some({
-		path: candidate,
-		dir,
-		filename: options.filename
-	}) : Option.none();
+	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.

package/README.md

@@ -149,7 +149,7 @@ Every failure is a tagged error you route on with `Effect.catchTag`. The tags ex
 
 | Tag | Means | Recovery |
 | --- | --- | --- |
-| `ConfigFileNotFoundError` | The resolver chain matched nothing. Carries `searched`, the resolver names probed. | Fall back to defaults — the one failure that is often not an error. `loadOrDefault` handles it for you. |
+| `ConfigFileNotFoundError` | The resolver chain matched nothing. Carries `searched`, the resolver names probed, and `candidates`, the paths they actually checked on disk. | Fall back to defaults — the one failure that is often not an error. `loadOrDefault` handles it for you. |
 | `ConfigFileReadError` | A file was found but could not be read. Carries `path` and the structural `cause`. | Usually fatal: the file exists and the process cannot read it. Check permissions. |
 | `ConfigFileWriteError` | A file could not be written. Carries `path` and the structural `cause`. | Retry elsewhere, or surface to the user. |
 | `ConfigDefaultPathMissingError` | `save` or `update` was called on a service configured without a `defaultPath`. | A wiring bug, not a data condition. Fix the layer, or call `write` with an explicit path. |
@@ -158,7 +158,7 @@ Every failure is a tagged error you route on with `Effect.catchTag`. The tags ex
 | `ConfigMigrationError` | A versioned migration failed. Carries `version`, `name`, `phase` and the structural `cause`. | Report which step failed; the config on disk is left untouched. |
 | `ConfigEncryptionError` | An encrypt, decrypt, key-derivation or base64 step failed. Carries `phase` and the structural `cause`. | A wrong passphrase and a corrupt envelope both land here; inspect `phase`. |
 
-`ConfigLoadError`, `ConfigReadError`, `ConfigWriteError`, `ConfigSaveError` and `ConfigUpdateError` are exported unions naming exactly the failures each method can produce. Catching one tag narrows the union, leaving the rest to propagate:
+`ConfigLoadError`, `ConfigReadError`, `ConfigEncodeError`, `ConfigWriteError`, `ConfigSaveError` and `ConfigUpdateError` are exported unions naming exactly the failures each method can produce — `ConfigEncodeError` is `ConfigWriteError` minus `ConfigFileWriteError`, because `encode` never touches the disk. Catching one tag narrows the union, leaving the rest to propagate:
 
 ```ts
 import type { ConfigFileShape } from "@effected/config-file";
@@ -213,6 +213,7 @@ export const secret = EncryptedCodec(migrating, EncryptedCodecKey.fromPassphrase
 - `ConfigFile.Service` / `ConfigFile.layer` / `ConfigFile.testLayer` — a per-schema service class and its layers. `testLayer` seeds files into a temp directory and wires the *real* implementation over them, so tests exercise the actual pipeline rather than a stub that can drift from it.
 - `parseOptions` — decode options threaded into every decode, on the layer and on `read`. `onExcessProperty: "error"` is the only way to report a typo'd section or a field the schema deliberately removed.
 - `ConfigFile.read` — the one-shot escape from the service: read, decode and validate one explicit path, schema and codec named per call, with no resolver chain and no write path.
+- `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.

package/index.d.ts

@@ -281,6 +281,29 @@ export interface ConfigResolver<R = never> {
    * tail.
    */
   readonly resolveMatch?: Effect.Effect<Option.Option<ConfigMatch>, never, R>;
+  /**
+   * The same lookup, additionally reporting every candidate path actually
+   * checked on disk, in probe order.
+   *
+   * @remarks
+   * Optional, and optional forever: a hand-rolled resolver that omits it is a
+   * complete `ConfigResolver`, and the pipeline falls back to `resolveMatch`
+   * (then `resolve`), contributing nothing to
+   * `ConfigFileNotFoundError.candidates` — the failure-path mirror of
+   * `ConfigSource.match` degrading to a bare path. Every built-in implements
+   * it, and derives the other two from it, so the three can never disagree.
+   *
+   * It exists because a resolver's `name` under-reports a search once one
+   * resolver probes several candidates: after the `filenames`/`subpaths`
+   * forms of `upwardWalk`, one `searched` entry can hide dozens of probed
+   * paths, and "nothing found, here is what I looked for" becomes less
+   * informative than the chain actually is.
+   *
+   * `probed` reports what the lookup CHECKED, not everything it could have:
+   * a short-circuiting walk lists the prefix ending at the match, and an
+   * absorbed filesystem failure lists nothing.
+   */
+  readonly resolveProbe?: Effect.Effect<ConfigProbe, never, R>;
 }
 /**
  * How a resolver found a config file, not merely where.
@@ -305,6 +328,29 @@ interface ConfigMatch {
   /** The `filenames`/`filename` entry that matched, when the resolver takes one. */
   readonly filename?: string;
 }
+/**
+ * The full report of one resolver lookup: what matched, and what was checked.
+ *
+ * @remarks
+ * `probed` carries the candidate paths the resolver actually asked the
+ * filesystem about, in probe order — for `upwardWalk`, the prefix of its
+ * directory-major candidate list ending at the match, or the full list when
+ * nothing matched. It exists so the failure path can be as informative as the
+ * success path: {@link ConfigMatch} says which candidate won and anchored
+ * where; `probed` says what lost, and where the search looked.
+ *
+ * @public
+ */
+interface ConfigProbe {
+  /** The match, when a candidate existed on disk. */
+  readonly match: Option.Option<ConfigMatch>;
+  /**
+   * Candidate paths checked on disk, in probe order. Empty when the lookup
+   * produced no candidate to report — no root found, a platform short-circuit,
+   * or a filesystem failure absorbed across the whole probe.
+   */
+  readonly probed: ReadonlyArray<string>;
+}
 /**
  * Options for `ConfigResolver.upwardWalk`.
  *
@@ -486,6 +532,18 @@ export declare const MergeStrategy: {
 declare const ConfigFileNotFoundError_base: Schema.Class<ConfigFileNotFoundError, Schema.TaggedStruct<"ConfigFileNotFoundError", {
   /** The names of the resolvers that were probed, in order. */
   readonly searched: Schema.$Array<Schema.String>;
+  /**
+   * The candidate paths the chain actually checked on disk, in probe order
+   * across every resolver — the failure-path mirror of {@link ConfigMatch}.
+   *
+   * @remarks
+   * One `searched` name can hide many paths: an `upwardWalk` with a
+   * `filenames` list probes every name at every ancestor. Resolvers that omit
+   * the optional `resolveProbe` member contribute nothing here, so the list
+   * can be shorter than the true search (or empty for a fully hand-rolled
+   * chain) — `searched` remains the complete resolver list either way.
+   */
+  readonly candidates: Schema.$Array<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
 /**
  * Indicates that the resolver chain produced no configuration source.
@@ -600,6 +658,38 @@ type ConfigReadError = ConfigFileReadError | ConfigCodecError | ConfigValidation
  * @public
  */
 type ConfigWriteError = ConfigFileWriteError | ConfigCodecError | ConfigValidationError;
+/**
+ * The failure modes of {@link ConfigFileShape.encode}: everything on the write
+ * path except the write itself.
+ *
+ * @remarks
+ * Deliberately excludes {@link ConfigFileWriteError} — nothing touches the
+ * filesystem — so a `--dry-run` caller's error channel is honest about that.
+ *
+ * @public
+ */
+type ConfigEncodeError = ConfigCodecError | ConfigValidationError;
+/**
+ * Options shared by {@link ConfigFileShape.encode} and {@link ConfigFileShape.write}.
+ *
+ * @public
+ */
+interface ConfigEncodeOptions {
+  /**
+   * Text emitted **verbatim** in front of the serialized document, separated
+   * from it by exactly one newline. If `header` already ends in `"\n"`, no
+   * further newline is added.
+   *
+   * @remarks
+   * The caller owns the header's validity in the target format: `#` comment
+   * lines for TOML and YAML, `//` for JSONC. JSON has no comment syntax, so a
+   * header on a JSON codec yields an unparseable file by construction — the
+   * service does not check. The motivating case is a schema directive such as
+   * `#:schema https://example.com/config.schema.json` at the top of a TOML
+   * file, which editors read for completion and validation.
+   */
+  readonly header?: string;
+}
 /**
  * The failure modes of {@link ConfigFileShape.save}.
  *
@@ -646,15 +736,27 @@ interface ConfigFileShape<A> {
   readonly loadOrDefault: (defaultValue: A) => Effect.Effect<A, ConfigReadError>;
   /** Decode and validate an in-memory value. */
   readonly validate: (value: unknown) => Effect.Effect<A, ConfigValidationError>;
+  /**
+   * Encode `value` to its serialized text without writing anything.
+   *
+   * @remarks
+   * Produces byte-for-byte what `write(value, path, options)` puts on disk —
+   * the primitive for `--dry-run` and "show me the file" callers. Emits no
+   * event, because nothing was written. A codec failure here carries no
+   * `path`, and a validation failure's `path` is `Option.none()`: there is no
+   * file to name.
+   */
+  readonly encode: (value: A, options?: ConfigEncodeOptions) => Effect.Effect<string, ConfigEncodeError>;
   /**
    * Encode `value` and write it to an explicit `path`.
    *
    * @remarks
    * Does **not** create the parent directory — that is
    * {@link ConfigFileShape.save}'s job, and the distinction is load-bearing:
-   * `write` targets a path the caller already vouched for.
+   * `write` targets a path the caller already vouched for. `options` are the
+   * same as {@link ConfigFileShape.encode}'s, so the two stay in lockstep.
    */
-  readonly write: (value: A, path: string) => Effect.Effect<void, ConfigWriteError>;
+  readonly write: (value: A, path: string, options?: ConfigEncodeOptions) => Effect.Effect<void, ConfigWriteError>;
   /**
    * Resolve `defaultPath`, `mkdir -p` its parent, encode `value` into it, and
    * return the path written.
@@ -1231,5 +1333,5 @@ export declare const TomlCodec: ConfigCodec;
  */
 export declare const YamlCodec: ConfigCodec;
 //#endregion
-export type { ConfigCodec, ConfigEventsShape, ConfigFileMigration, ConfigFileOptions, ConfigFileShape, ConfigFileTestOptions, ConfigLoadError, ConfigMatch, ConfigMigrationOptions, ConfigReadError, ConfigReadOptions, ConfigSaveError, ConfigSource, ConfigUpdateError, ConfigWriteError, LayerConfigProviderOptions, NonEmptySources, UpwardWalkOptions };
+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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.8.0",
+	"version": "0.10.0",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [
@@ -45,8 +45,8 @@
 	"peerDependencies": {
 		"@effected/jsonc": "^0.11.0",
 		"@effected/toml": "^0.7.0",
-		"@effected/walker": "^0.8.0",
-		"@effected/yaml": "^0.15.0",
+		"@effected/walker": "^0.9.0",
+		"@effected/yaml": "^0.15.1",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {