@effected/config-file 0.20.1 → 0.22.0

package/ConfigFile.js

@@ -260,24 +260,65 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		});
 		return value;
 	});
-	const load = Effect.fn("ConfigFile.load")(function* () {
+	/**
+	* `load`, also reporting the highest-priority source's path. `update` needs
+	* the path its own load read, so `saveTarget: "source"` writes where it
+	* read. Not an `Effect.fn`: the public boundaries that call it open the span.
+	*/
+	const loadWithSource = () => Effect.gen(function* () {
 		const { sources, candidates } = yield* discover();
-		if (sources.length === 0) {
+		const [first] = sources;
+		if (first === void 0) {
 			yield* emit({ _tag: "NotFound" });
 			return yield* Effect.fail(new ConfigFileNotFoundError({
 				searched,
 				candidates
 			}));
 		}
-		return yield* mergeAndEmit(sources);
+		return {
+			value: yield* mergeAndEmit(sources),
+			source: first.path
+		};
 	});
-	const loadOrDefault = Effect.fn("ConfigFile.loadOrDefault")(function* (defaultValue) {
+	/** `loadOrDefault`, also reporting the highest-priority source's path when there is one. */
+	const loadOrDefaultWithSource = (defaultValue) => Effect.gen(function* () {
 		const { sources } = yield* discover();
-		if (sources.length === 0) {
+		const [first] = sources;
+		if (first === void 0) {
 			yield* emit({ _tag: "NotFound" });
-			return defaultValue;
+			return {
+				value: defaultValue,
+				source: Option.none()
+			};
 		}
-		return yield* mergeAndEmit(sources);
+		return {
+			value: yield* mergeAndEmit(sources),
+			source: Option.some(first.path)
+		};
+	});
+	const load = Effect.fn("ConfigFile.load")(function* () {
+		return (yield* loadWithSource()).value;
+	});
+	const loadOrDefault = Effect.fn("ConfigFile.loadOrDefault")(function* (defaultValue) {
+		return (yield* loadOrDefaultWithSource(defaultValue)).value;
+	});
+	/**
+	* Whether `save` and `update` write to the source they found rather than `defaultPath`. Unset, it follows the
+	* strategy: `firstMatch` writes the file that is in effect; `layeredMerge` and any custom strategy write
+	* `defaultPath`, where the merged value flattens least harmfully.
+	*/
+	const toSource = (options.saveTarget ?? (options.strategy.name === "first-match" ? "source" : "default")) === "source";
+	/**
+	* The first path the resolver chain finds, by lookup alone: no file is read,
+	* so `save` gains no read or decode failure. Every resolver's `resolve` is
+	* total by contract.
+	*/
+	const locate = Effect.gen(function* () {
+		for (const resolver of options.resolvers) {
+			const found = yield* Effect.provide(resolver.resolve, resolverEnv);
+			if (Option.isSome(found)) return found;
+		}
+		return Option.none();
 	});
 	const validate = Effect.fn("ConfigFile.validate")(function* (value) {
 		const decoded = yield* decode(value, Option.none());
@@ -338,10 +379,14 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	* emitting boundary sits in the public method, never in the shared internals
 	* it delegates to.
 	*/
-	const saveTo = (value) => Effect.gen(function* () {
-		const configured = options.defaultPath;
-		if (configured === void 0) return yield* Effect.fail(new ConfigDefaultPathMissingError({}));
-		const target = yield* Effect.provide(configured, resolverEnv);
+	const saveTo = (value, source) => Effect.gen(function* () {
+		let target;
+		if (Option.isSome(source)) target = source.value;
+		else {
+			const configured = options.defaultPath;
+			if (configured === void 0) return yield* Effect.fail(new ConfigDefaultPathMissingError({}));
+			target = yield* Effect.provide(configured, resolverEnv);
+		}
 		yield* fs.makeDirectory(path.dirname(target), { recursive: true }).pipe(Effect.mapError((cause) => new ConfigFileWriteError({
 			path: target,
 			cause
@@ -357,7 +402,7 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 		});
 	});
 	const save = Effect.fn("ConfigFile.save")(function* (value) {
-		const target = yield* saveTo(value);
+		const target = yield* saveTo(value, toSource ? yield* locate : Option.none());
 		yield* emit({
 			_tag: "Saved",
 			path: target
@@ -379,8 +424,12 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	const updateLock = Semaphore.makeUnsafe(1);
 	const update = Effect.fn("ConfigFile.update")(function* (fn, defaultValue) {
 		return yield* updateLock.withPermits(1)(Effect.gen(function* () {
-			const updated = fn(defaultValue !== void 0 ? yield* loadOrDefault(defaultValue) : yield* load());
-			const target = yield* saveTo(updated);
+			const current = defaultValue !== void 0 ? yield* loadOrDefaultWithSource(defaultValue) : yield* Effect.map(loadWithSource(), ({ value, source }) => ({
+				value,
+				source: Option.some(source)
+			}));
+			const updated = fn(current.value);
+			const target = yield* saveTo(updated, toSource ? current.source : Option.none());
 			yield* emit({
 				_tag: "Updated",
 				path: target
@@ -527,7 +576,8 @@ var ConfigFile = class {
 			codec: options.codec,
 			strategy: options.strategy,
 			resolvers,
-			...options.validate !== void 0 && { validate: options.validate }
+			...options.validate !== void 0 && { validate: options.validate },
+			...options.saveTarget !== void 0 && { saveTarget: options.saveTarget }
 		}, fs, path, resolverEnv);
 	}));
 	/**

package/ConfigMerge.js

@@ -0,0 +1,73 @@
+import { deepMerge } from "./internal/deepMerge.js";
+
+// src/ConfigMerge.ts
+/**
+* Pure, synchronous merging of config values: the merge
+* `MergeStrategy.layeredMerge` runs, without `ConfigSource` wrappers or an
+* `Effect`.
+*
+* @remarks
+* A module of its own, imported from the root: it reaches no codec and no
+* parsing engine, so importing it costs a consumer nothing else.
+*
+* @example
+* ```ts
+* import { ConfigMerge } from "@effected/config-file";
+*
+* const profile = { server: { host: "localhost", port: 8080 }, tags: ["a"] };
+* const user = { server: { port: 9090 }, tags: ["b"] };
+* console.log(ConfigMerge.deep(profile, user));
+* // => { server: { port: 9090, host: "localhost" }, tags: ["b"] }
+* ```
+*
+* @public
+*/
+var ConfigMerge = class {
+	constructor() {}
+	/**
+	* Merges `override` over `base`, `override` winning on every conflict.
+	* Neither input is modified.
+	*
+	* @remarks
+	* The rules, which are `MergeStrategy.layeredMerge`'s too:
+	*
+	* - **Which values merge.** Two plain objects merge field-wise, whichever
+	*   of `Object.prototype` and `null` each has as its prototype, so a
+	*   null-prototype object and an ordinary one merge with each other. At the
+	*   top level only, two instances of one class (a decoded `Schema.Class`
+	*   document) merge too. Any other pair is atomic and `override` wins whole.
+	* - **The result's prototype** is `override`'s, so a class instance stays
+	*   an instance and a null-prototype override yields a null-prototype
+	*   result.
+	* - **Arrays are atomic.** `override`'s array replaces `base`'s whole;
+	*   nothing is concatenated or merged by index. So are `Date`, `Map`,
+	*   `Set`, `RegExp` and nested class instances.
+	* - **Presence decides, not value.** An own key on `override` wins even
+	*   when its value is `undefined`; to inherit `base`'s value, omit the key.
+	* - **Prototype keys are dropped.** At every level that merges,
+	*   `__proto__`, `constructor` and `prototype` are skipped on both sides,
+	*   and every key is written as an own data property, so neither input can
+	*   reach `Object.prototype` or replace the result's prototype. A config
+	*   whose real data uses one of those names loses that key at those
+	*   levels. A value taken whole is shared as it is, so an own `__proto__`
+	*   data key inside it (as `JSON.parse` writes one) stays, and stays inert.
+	* - **Only own enumerable string keys** are read. Symbol keys,
+	*   non-enumerable properties and getters on the prototype are not copied.
+	* - **Nothing is cloned.** Merged levels are fresh objects; every value
+	*   taken whole is the same reference as in its input.
+	* - **Shared and cyclic inputs keep their shape.** Each pair of objects
+	*   merges once: a subobject that two keys share on both sides yields one
+	*   merged object both keys share, and a cycle in the inputs becomes the
+	*   same cycle in the result. That also bounds the work to one merge per
+	*   distinct pair, so a cyclic input returns promptly.
+	* - **It is total.** Nested levels merge down to a depth of 1024, far below
+	*   any decoded document; below that, `override`'s value is taken whole,
+	*   so a pathologically deep input returns instead of overflowing the
+	*   stack.
+	*/
+	static deep(base, override) {
+		return deepMerge(base, override);
+	}
+};
+
+export { ConfigMerge };

package/ConfigResolver.js

@@ -111,8 +111,8 @@ var ConfigResolver = class {
 		};
 	})));
 	/**
-	* Ascends from `cwd` (or the process cwd) toward `stopAt`, resolving the
-	* first `subpaths/filename` combination found at each level.
+	* Ascends from `cwd` (or the process cwd) toward `stopAt` or `ceiling`,
+	* resolving the first `subpaths/filename` combination found at each level.
 	*
 	* @remarks
 	* `filenames` replaces `filename` with a per-directory candidate list: every
@@ -130,7 +130,7 @@ var ConfigResolver = class {
 		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 dirs = options.ceiling !== void 0 ? yield* Walker.ascendWithin(cwdOf(options.cwd), Option.some(options.ceiling)) : 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),

package/MergeStrategy.js

@@ -1,4 +1,4 @@
-import { canMerge, deepMerge } from "./internal/deepMerge.js";
+import { deepMerge } from "./internal/deepMerge.js";
 import { Effect } from "effect";
 
 // src/MergeStrategy.ts
@@ -42,15 +42,16 @@ const MergeStrategy = {
 	* `{}`.
 	*
 	* Nested *plain* objects (a `Schema.Struct` section) still merge field-wise.
+	*
+	* Each step of the fold is `ConfigMerge.deep(lower, higher)`, so the rules
+	* documented there (arrays, `undefined`, prototype keys, null-prototype
+	* objects) are this strategy's rules too.
 	*/
 	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;
-			}
+			for (let i = sources.length - 2; i >= 0; i--) merged = deepMerge(merged, sources[i]?.value);
 			return Effect.succeed(merged);
 		}
 	})

package/index.d.ts

@@ -411,16 +411,53 @@ interface ConfigProbe {
  * (`".config/app.toml"`), which is how a mixed convention is spelled without a
  * `subpaths` cross product.
  *
+ * At most one of `stopAt` (a lexical ceiling) and `ceiling` (a physical
+ * one) is given. Bound the walk by a path git answered — `Git.repoRoot` — with
+ * `ceiling`; `stopAt` never matches a symlink-resolved spelling of the start.
+ *
  * @public
  */
-type UpwardWalkOptions = {
+type UpwardWalkOptions = ({
   /** The single file name probed at each ancestor directory. */
   readonly filename: string;
   readonly filenames?: undefined;
+} | {
+  /**
+   * The candidate file names probed at each ancestor directory, in order,
+   * before the walk ascends.
+   */
+  readonly filenames: ReadonlyArray<string>;
+  readonly filename?: undefined;
+}) & ({
+  /**
+   * An absolute ceiling the walk stops at, inclusive, compared
+   * LEXICALLY (`Walker.ascend`'s `stopAt`).
+   *
+   * @remarks
+   * A ceiling spelled differently from the walk's own path never
+   * matches, and the walk runs on to the filesystem root. That is
+   * every physical path — `Git.repoRoot`'s answer from a symlinked or
+   * macOS-tmpdir start — so bound by such a path with `ceiling`.
+   */
+  readonly stopAt?: string;
+  readonly ceiling?: undefined;
+} | {
+  /**
+   * A ceiling the walk stops at, inclusive, compared PHYSICALLY: the
+   * nearest ancestor whose real path is the ceiling's real path
+   * (`Walker.ascendWithin`).
+   *
+   * @remarks
+   * For a ceiling that may be spelled differently from the walk's own
+   * path, above all `Git.repoRoot`'s symlink-resolved answer. Omit it
+   * to walk to the filesystem root. A relative ceiling is a defect.
+   * Cannot be combined with `stopAt`.
+   */
+  readonly ceiling?: string;
+  readonly stopAt?: undefined;
+}) & {
   /** Where the walk starts. Defaults to the process cwd. */
   readonly cwd?: string;
-  /** An absolute ceiling the walk stops at, inclusive. */
-  readonly stopAt?: string;
   /** Directories probed under each ancestor, in order. Defaults to `["."]`. */
   readonly subpaths?: ReadonlyArray<string>;
   /**
@@ -433,21 +470,6 @@ type UpwardWalkOptions = {
    * identifies the matching candidate rather than the resolver.
    */
   readonly name?: string;
-} | {
-  /**
-   * The candidate file names probed at each ancestor directory, in order,
-   * before the walk ascends.
-   */
-  readonly filenames: ReadonlyArray<string>;
-  readonly filename?: undefined;
-  /** Where the walk starts. Defaults to the process cwd. */
-  readonly cwd?: string;
-  /** An absolute ceiling the walk stops at, inclusive. */
-  readonly stopAt?: string;
-  /** Directories probed under each ancestor, in order. Defaults to `["."]`. */
-  readonly subpaths?: ReadonlyArray<string>;
-  /** The resolver's reported name. Defaults to `"walk"`. */
-  readonly name?: string;
 };
 /**
  * Built-in resolvers, in the order a typical chain uses them.
@@ -464,8 +486,8 @@ export declare class ConfigResolver {
     readonly filename: string;
   }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
   /**
-   * Ascends from `cwd` (or the process cwd) toward `stopAt`, resolving the
-   * first `subpaths/filename` combination found at each level.
+   * Ascends from `cwd` (or the process cwd) toward `stopAt` or `ceiling`,
+   * resolving the first `subpaths/filename` combination found at each level.
    *
    * @remarks
    * `filenames` replaces `filename` with a per-directory candidate list: every
@@ -595,6 +617,10 @@ export declare const MergeStrategy: {
    * `{}`.
    *
    * Nested *plain* objects (a `Schema.Struct` section) still merge field-wise.
+   *
+   * Each step of the fold is `ConfigMerge.deep(lower, higher)`, so the rules
+   * documented there (arrays, `undefined`, prototype keys, null-prototype
+   * objects) are this strategy's rules too.
    */
   readonly layeredMerge: <A>() => MergeStrategy<A>;
 };
@@ -843,8 +869,13 @@ interface ConfigFileShape<A, CE = ConfigCodecError> {
    */
   readonly write: (value: A, path: string, options?: ConfigEncodeOptions) => Effect.Effect<void, ConfigWriteError<CE>>;
   /**
-   * Resolve `defaultPath`, `mkdir -p` its parent, encode `value` into it, and
-   * return the path written.
+   * Resolve the write target, `mkdir -p` its parent, encode `value` into it,
+   * and return the path written.
+   *
+   * @remarks
+   * The target follows {@link ConfigFileOptions.saveTarget}: `defaultPath`,
+   * or under `"source"` (the default for `firstMatch`) the first file the
+   * resolver chain finds, falling back to `defaultPath`.
    */
   readonly save: (value: A) => Effect.Effect<string, ConfigSaveError<CE>>;
   /**
@@ -854,6 +885,11 @@ interface ConfigFileShape<A, CE = ConfigCodecError> {
    * @remarks
    * With `defaultValue` the load cannot fail with
    * {@link ConfigFileNotFoundError}; without it, it can.
+   *
+   * The result goes where {@link ConfigFileOptions.saveTarget} says: under
+   * `"source"` (the default for `firstMatch`) back to the highest-priority
+   * file the load read, or `defaultPath` when the load found none and fell
+   * back to `defaultValue`; under `"default"` to `defaultPath`.
    */
   readonly update: (fn: (current: A) => A, defaultValue?: A) => Effect.Effect<A, ConfigUpdateError<CE>>;
 }
@@ -931,6 +967,39 @@ interface ConfigFileOptions<A, I, RR, CE = ConfigCodecError> {
    * {@link ConfigDefaultPathMissingError}.
    */
   readonly defaultPath?: Effect.Effect<string, never, RR>;
+  /**
+   * Where {@link ConfigFileShape.save} and {@link ConfigFileShape.update}
+   * write: `"default"` always writes `defaultPath`; `"source"` writes the
+   * highest-priority file the resolver chain finds, and `defaultPath` only
+   * when it finds none.
+   *
+   * @remarks
+   * Unset, it follows the strategy.
+   * {@link (MergeStrategy:variable).firstMatch} defaults to `"source"`:
+   * the file that was read is the file in effect, so writing anywhere else
+   * puts the change in a file the next run does not read (or creates a
+   * second, competing config). {@link (MergeStrategy:variable).layeredMerge}
+   * and any custom strategy default to `"default"`. A custom strategy is
+   * matched by its `name`, so one that calls itself `"first-match"` takes
+   * `firstMatch`'s default.
+   *
+   * Pin `"default"` when the program writes state of its own rather than
+   * the user's settings: under `"source"` a write can land in a file found
+   * by walking up, such as a project file checked into a repository.
+   *
+   * `update` writes to the first source of the load it just ran, under its
+   * lock. `save` runs the resolver chain's lookups to find the target and
+   * reads no file. With nothing found and no `defaultPath`, both fail with
+   * {@link ConfigDefaultPathMissingError}, as under `"default"`.
+   *
+   * Under {@link (MergeStrategy:variable).layeredMerge}, `update`'s value
+   * is the merge of every source, so `"source"` writes the lower layers'
+   * values into the top file. That is the same flattening `"default"` does
+   * into `defaultPath`, but in a file the user reads; pair `"source"` with
+   * {@link (MergeStrategy:variable).firstMatch} when each file should keep
+   * only its own keys.
+   */
+  readonly saveTarget?: "default" | "source";
   /**
    * The opt-in event hook. Pass the `ConfigEvents` class itself.
    *
@@ -953,8 +1022,10 @@ interface ConfigFileOptions<A, I, RR, CE = ConfigCodecError> {
  *
  * It also has no `defaultPath`. Nothing in the temp directory is a defensible
  * default write target, so `save` and `update` fail with
- * {@link ConfigDefaultPathMissingError} under this layer — the honest answer.
- * Exercise the write path with {@link ConfigFile.layer} instead.
+ * {@link ConfigDefaultPathMissingError} under this layer — the honest answer —
+ * unless the write target is `"source"` (the default under `firstMatch`) and
+ * a seeded file was found, which they then write. Otherwise exercise the
+ * write path with {@link ConfigFile.layer}.
  *
  * `CE` is the codec's error channel, as on {@link ConfigFileOptions}.
  *
@@ -983,6 +1054,18 @@ interface ConfigFileTestOptions<A, I, CE = ConfigCodecError> {
   readonly files: Record<string, string>;
   /** An optional caller-supplied check run after schema decoding. */
   readonly validate?: (value: A) => Effect.Effect<A, ConfigValidationError>;
+  /**
+   * Where `save` and `update` write, as on
+   * {@link ConfigFileOptions.saveTarget}, including its strategy-dependent
+   * default.
+   *
+   * @remarks
+   * Under `"source"` they write the seeded file the load read, so the
+   * write path can be tested over this layer. With nothing found there is no
+   * `defaultPath` to fall back to, so they fail with
+   * {@link ConfigDefaultPathMissingError}.
+   */
+  readonly saveTarget?: "default" | "source";
 }
 /**
  * Options for {@link ConfigFile.read}.
@@ -1161,6 +1244,72 @@ export declare class ConfigFile {
    */
   static readonly read: <A, I, CE = ConfigCodecError>(path: string, options: ConfigReadOptions<A, I, CE>) => Effect.Effect<A, ConfigReadError<CE>, FileSystem.FileSystem>;
 }
+/**
+ * Pure, synchronous merging of config values: the merge
+ * `MergeStrategy.layeredMerge` runs, without `ConfigSource` wrappers or an
+ * `Effect`.
+ *
+ * @remarks
+ * A module of its own, imported from the root: it reaches no codec and no
+ * parsing engine, so importing it costs a consumer nothing else.
+ *
+ * @example
+ * ```ts
+ * import { ConfigMerge } from "@effected/config-file";
+ *
+ * const profile = { server: { host: "localhost", port: 8080 }, tags: ["a"] };
+ * const user = { server: { port: 9090 }, tags: ["b"] };
+ * console.log(ConfigMerge.deep(profile, user));
+ * // => { server: { port: 9090, host: "localhost" }, tags: ["b"] }
+ * ```
+ *
+ * @public
+ */
+export declare class ConfigMerge {
+  private constructor();
+  /**
+   * Merges `override` over `base`, `override` winning on every conflict.
+   * Neither input is modified.
+   *
+   * @remarks
+   * The rules, which are `MergeStrategy.layeredMerge`'s too:
+   *
+   * - **Which values merge.** Two plain objects merge field-wise, whichever
+   *   of `Object.prototype` and `null` each has as its prototype, so a
+   *   null-prototype object and an ordinary one merge with each other. At the
+   *   top level only, two instances of one class (a decoded `Schema.Class`
+   *   document) merge too. Any other pair is atomic and `override` wins whole.
+   * - **The result's prototype** is `override`'s, so a class instance stays
+   *   an instance and a null-prototype override yields a null-prototype
+   *   result.
+   * - **Arrays are atomic.** `override`'s array replaces `base`'s whole;
+   *   nothing is concatenated or merged by index. So are `Date`, `Map`,
+   *   `Set`, `RegExp` and nested class instances.
+   * - **Presence decides, not value.** An own key on `override` wins even
+   *   when its value is `undefined`; to inherit `base`'s value, omit the key.
+   * - **Prototype keys are dropped.** At every level that merges,
+   *   `__proto__`, `constructor` and `prototype` are skipped on both sides,
+   *   and every key is written as an own data property, so neither input can
+   *   reach `Object.prototype` or replace the result's prototype. A config
+   *   whose real data uses one of those names loses that key at those
+   *   levels. A value taken whole is shared as it is, so an own `__proto__`
+   *   data key inside it (as `JSON.parse` writes one) stays, and stays inert.
+   * - **Only own enumerable string keys** are read. Symbol keys,
+   *   non-enumerable properties and getters on the prototype are not copied.
+   * - **Nothing is cloned.** Merged levels are fresh objects; every value
+   *   taken whole is the same reference as in its input.
+   * - **Shared and cyclic inputs keep their shape.** Each pair of objects
+   *   merges once: a subobject that two keys share on both sides yields one
+   *   merged object both keys share, and a cycle in the inputs becomes the
+   *   same cycle in the result. That also bounds the work to one merge per
+   *   distinct pair, so a cyclic input returns promptly.
+   * - **It is total.** Nested levels merge down to a depth of 1024, far below
+   *   any decoded document; below that, `override`'s value is taken whole,
+   *   so a pathologically deep input returns instead of overflowing the
+   *   stack.
+   */
+  static deep<A>(base: A, override: A): A;
+}
 declare const ConfigMigrationError_base: Schema.Class<ConfigMigrationError, Schema.TaggedStruct<"ConfigMigrationError", {
   /** The target version of the step that failed. `0` when reading the version failed. */
   readonly version: Schema.Number;

package/index.js

@@ -2,10 +2,11 @@ import { ConfigCodecError } from "./ConfigCodec.js";
 import { ConfigEvent, ConfigEventPayload, ConfigEvents, ConfigSourceRef } from "./ConfigEvent.js";
 import { ConfigResolver } from "./ConfigResolver.js";
 import { ConfigDefaultPathMissingError, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigValidationError } from "./ConfigFile.js";
+import { ConfigMerge } from "./ConfigMerge.js";
 import { ConfigMigration, ConfigMigrationError, VersionAccess } from "./ConfigMigration.js";
 import { asConfigProvider, layerConfigProvider } from "./ConfigProvider.js";
 import { ConfigEncryptionError, EncryptedCodec, EncryptedCodecKey } from "./EncryptedCodec.js";
 import { JsonCodec } from "./JsonCodec.js";
 import { MergeStrategy } from "./MergeStrategy.js";
 
-export { ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigMigration, ConfigMigrationError, ConfigResolver, ConfigSourceRef, ConfigValidationError, EncryptedCodec, EncryptedCodecKey, JsonCodec, MergeStrategy, VersionAccess, asConfigProvider, layerConfigProvider };
+export { ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, ConfigFile, ConfigFileNotFoundError, ConfigFileReadError, ConfigFileWriteError, ConfigMerge, ConfigMigration, ConfigMigrationError, ConfigResolver, ConfigSourceRef, ConfigValidationError, EncryptedCodec, EncryptedCodecKey, JsonCodec, MergeStrategy, VersionAccess, asConfigProvider, layerConfigProvider };

package/internal/deepMerge.js

@@ -9,6 +9,8 @@
 * instance loses its prototype, so `instanceof` fails and its getters vanish.
 * Recursion is gated on this predicate so nested values of those kinds stay
 * atomic — the higher-priority source wins them whole.
+*
+* @internal
 */
 const isPlainObject = (value) => {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
@@ -23,46 +25,83 @@ const isPlainObject = (value) => {
 */
 const isRecordLike = (value) => typeof value === "object" && value !== null && Object.prototype.toString.call(value) === "[object Object]";
 /**
-* Two values may be merged only if both are record-like and share a prototype.
-* Same-prototype instances merge field-wise; anything else is atomic.
+* Whether two TOP-LEVEL values merge field-wise: both plain objects (either
+* prototype, `Object.prototype` or `null`), or both record-like on one shared
+* prototype. Anything else is atomic.
 *
 * @remarks
-* Requiring an identical prototype is what keeps the merge honest: a document
-* decoded through `Schema.Class` merges with another of the same class and
-* keeps its identity, and nothing else is ever silently reshaped.
+* The shared-prototype arm is what lets a document decoded through
+* `Schema.Class` merge with another of the same class and keep its identity;
+* nothing else is ever silently reshaped. The plain arm admits a
+* null-prototype object beside an ordinary one, the same pairing every nested
+* level has always merged.
+*
+* @internal
 */
-const canMerge = (a, b) => isRecordLike(a) && isRecordLike(b) && Object.getPrototypeOf(a) === Object.getPrototypeOf(b);
+const canMerge = (a, b) => isPlainObject(a) && isPlainObject(b) || isRecordLike(a) && isRecordLike(b) && Object.getPrototypeOf(a) === Object.getPrototypeOf(b);
 const FORBIDDEN = /* @__PURE__ */ new Set([
 	"__proto__",
 	"constructor",
 	"prototype"
 ]);
 /**
-* Recursively merge `source` into `target`; keys already present on `target`
-* win. Nested plain objects merge; every other value is atomic.
+* How many nested levels merge field-wise. At this depth the override's value
+* is taken whole.
+*
+* @remarks
+* Far above the 256-level nesting cap of the kit's parsers, so a decoded
+* document never reaches it. It exists so a pathologically deep pair of inputs
+* cannot overflow the stack. Cycles do not depend on it: the per-pair memo in
+* {@link deepMerge} bounds them, because a depth cap bounds depth, not work —
+* a self-cycle through two keys recursed into both at every level, about
+* 2^depth calls, before the memo existed.
+*
+* @internal
+*/
+const MAX_MERGE_DEPTH = 1024;
+/**
+* Merge `override` over `base`. Two mergeable values ({@link canMerge}) merge
+* field-wise; otherwise `override` wins whole.
+*
+* @internal
+*/
+const deepMerge = (base, override) => canMerge(base, override) ? mergeRecords(base, override, 1, /* @__PURE__ */ new WeakMap()) : override;
+/**
+* Field-wise merge, `override`'s own keys winning. Nested plain objects merge;
+* every other value is atomic.
 *
 * @remarks
-* The result is built on `target`'s prototype rather than spread into `{}`, so
-* a decoded `Schema.Class` document survives the merge as a real instance —
+* The result is built on `override`'s prototype rather than spread into `{}`,
+* so a decoded `Schema.Class` document survives the merge as a real instance:
 * `instanceof` holds and its getters still work. Without this, `load` would
 * declare `Effect<A>` and hand back a structurally-equal plain object, and a
 * consumer calling a class method would get a `TypeError` that typechecked.
 *
-* Only own enumerable keys are consulted (`Object.hasOwn`), so a prototype
-* getter on `target` never shadows a real key on `source`.
+* Only own enumerable string keys are consulted (`Object.keys`, `Object.hasOwn`),
+* so a prototype getter on `override` never shadows a real key on `base`.
+* Presence decides, not value: an own key on `override` wins even when it holds
+* `undefined`.
 */
-const deepMerge = (target, source) => {
-	const result = Object.create(Object.getPrototypeOf(target));
-	for (const key of Object.keys(target)) {
-		if (FORBIDDEN.has(key)) continue;
-		define(result, key, target[key]);
+const mergeRecords = (base, override, depth, memo) => {
+	const seen = memo.get(base)?.get(override);
+	if (seen !== void 0) return seen;
+	const result = Object.create(Object.getPrototypeOf(override));
+	let byOverride = memo.get(base);
+	if (byOverride === void 0) {
+		byOverride = /* @__PURE__ */ new WeakMap();
+		memo.set(base, byOverride);
 	}
-	for (const key of Object.keys(source)) {
+	byOverride.set(override, result);
+	for (const key of Object.keys(override)) {
 		if (FORBIDDEN.has(key)) continue;
-		const sourceValue = source[key];
-		const targetValue = result[key];
-		if (Object.hasOwn(result, key) && isPlainObject(targetValue) && isPlainObject(sourceValue)) define(result, key, deepMerge(targetValue, sourceValue));
-		else if (!Object.hasOwn(result, key)) define(result, key, sourceValue);
+		const overrideValue = override[key];
+		const baseValue = Object.hasOwn(base, key) ? base[key] : void 0;
+		if (depth < 1024 && isPlainObject(baseValue) && isPlainObject(overrideValue)) define(result, key, mergeRecords(baseValue, overrideValue, depth + 1, memo));
+		else define(result, key, overrideValue);
+	}
+	for (const key of Object.keys(base)) {
+		if (FORBIDDEN.has(key) || Object.hasOwn(result, key)) continue;
+		define(result, key, base[key]);
 	}
 	return result;
 };
@@ -76,4 +115,4 @@ const define = (target, key, value) => {
 	});
 };
 
-export { canMerge, deepMerge, isPlainObject };
+export { MAX_MERGE_DEPTH, canMerge, deepMerge, isPlainObject };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.20.1",
+	"version": "0.22.0",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [
@@ -58,11 +58,11 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/glob": "^0.14.0",
-		"@effected/jsonc": "^0.20.0",
-		"@effected/toml": "^0.16.0",
-		"@effected/walker": "^0.20.1",
-		"@effected/yaml": "^0.25.1",
+		"@effected/glob": "^0.16.0",
+		"@effected/jsonc": "^0.21.0",
+		"@effected/toml": "^0.17.0",
+		"@effected/walker": "^0.22.0",
+		"@effected/yaml": "^0.26.0",
 		"effect": "^4.0.0"
 	},
 	"peerDependenciesMeta": {