@effected/config-file 0.13.1 → 0.14.1

package/ConfigEvent.js

@@ -21,15 +21,14 @@ const ConfigSourceRef = Schema.Struct({
 * persistence.
 *
 * @remarks
-* v3's `Stringified` and `ResolutionFailed` variants were declared and never
-* emitted; they are not ported. `DiscoveryFailed` goes with them: under this
-* package's resolver-absorption contract a resolver's error channel is `never`
-* — every filesystem failure becomes `Option.none()` — so the pipeline can
-* never observe a discovery failure to report one.
+* There is no discovery-failure variant: under this package's
+* resolver-absorption contract a resolver's error channel is `never` — every
+* filesystem failure becomes `Option.none()` — so the pipeline never observes a
+* discovery failure to report.
 *
 * The failure variants carry the **structured** typed error in `error`, not a
-* `reason` string. v3 stringified them, destroying every field a subscriber
-* might branch on; a subscriber that wants prose can read `error.message`.
+* `reason` string, so every field a subscriber might branch on survives; a
+* subscriber that wants prose can read `error.message`.
 *
 * @public
 */

package/ConfigFile.js

@@ -10,7 +10,7 @@ import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PubSub, Sch
 * @remarks
 * Its own tag, so "no config anywhere" is routable with `Effect.catchTag`
 * separately from "the config I found is broken" — the single most important
-* distinction the v3 mega-error could not express.
+* distinction in the error set.
 *
 * @public
 */
@@ -40,8 +40,8 @@ var ConfigFileNotFoundError = class extends Schema.TaggedError()("ConfigFileNotF
 * Indicates that a config file could not be read from the filesystem.
 *
 * @remarks
-* `cause` preserves the underlying filesystem failure structurally. v3 flattened
-* it to `reason: String(e)`.
+* `cause` preserves the underlying filesystem failure structurally rather than
+* flattening it to a string.
 *
 * @public
 */
@@ -75,13 +75,12 @@ var ConfigFileWriteError = class extends Schema.TaggedError()("ConfigFileWriteEr
 * was called on a service configured without a `defaultPath`.
 *
 * @remarks
-* v3 reported this as a generic `ConfigError` carrying `operation: "save"` and
-* `reason: "no default path configured"` — indistinguishable by tag from a real
-* write failure.
+* It is distinct by tag from a real {@link ConfigFileWriteError}, so a caller
+* can tell "no destination was configured" from "the write failed".
 *
 * It carries no `path` field on purpose. The whole point of this failure is
 * that there is no path; a {@link ConfigFileWriteError} with a fabricated path
-* would be a lie, and lying error payloads are what this port exists to undo.
+* would be a lie.
 *
 * @public
 */
@@ -96,10 +95,9 @@ var ConfigDefaultPathMissingError = class extends Schema.TaggedError()("ConfigDe
 *
 * @remarks
 * `issue` carries the **structured** schema failure — at runtime a
-* `SchemaIssue.Issue` tree, reachable through `_tag` and nested `issues`. v3
-* flattened this to `String(ParseError)`, destroying every field a caller might
-* branch on. It is typed `unknown` because v4 exposes no `Schema` for `Issue`;
-* narrow it with the `SchemaIssue` module.
+* `SchemaIssue.Issue` tree, reachable through `_tag` and nested `issues`, so
+* every field a caller might branch on survives. It is typed `unknown` because
+* there is no `Schema` for `Issue`; narrow it with the `SchemaIssue` module.
 *
 * @public
 */
@@ -244,10 +242,10 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	const searched = options.resolvers.map((r) => r.name);
 	/**
 	* Merge the discovered sources and announce the result. Shared by `load` and
-	* `loadOrDefault`, which in v3 each re-inlined it and drifted apart.
+	* `loadOrDefault`, so the two cannot drift apart.
 	*
-	* Both events carry EVERY contributing source. v3 reported `sources[0].path`,
-	* which is wrong under `layeredMerge`, where all of them contributed.
+	* Both events carry EVERY contributing source, because under `layeredMerge`
+	* all of them contributed.
 	*/
 	const mergeAndEmit = (sources) => Effect.gen(function* () {
 		const value = yield* options.strategy.resolve(sources);
@@ -331,10 +329,10 @@ const makeImpl = (options, fs, path, resolverEnv) => {
 	* Resolve `defaultPath`, `mkdir -p` its parent and write. Shared by `save`
 	* and `update`, and — crucially — emits nothing.
 	*
-	* v3's `update` called the public `save`, so a single `update` published
-	* `Written` + `Saved` + `Updated`; v3 documented this as a known smell. Event
-	* granularity is per-operation, so the emitting boundary must sit in the
-	* public method, never in the shared internals it delegates to.
+	* `update` must not call the public `save`, or one `update` would publish
+	* `Saved` as well as `Updated`. Event granularity is per-operation, so the
+	* 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;
@@ -459,14 +457,38 @@ var ConfigFile = class {
 	* Build the live layer for a config service class.
 	*
 	* @remarks
-	* Resolver requirements flow into the layer's `R` type. v3 cast them away with
-	* `as Effect.Effect<Option<string>>`, making `Layer<Service, never, FileSystem>`
-	* a claim rather than a proof.
+	* Resolver requirements flow into the layer's `R` type: the result is
+	* `Layer<Self, never, FileSystem | Path | RR>`, so the platform services and
+	* every resolver's needs are visible at the provide site.
 	*
 	* `ConfigFile.layer` is a layer-RETURNING function, not a layer: calling it
 	* twice builds two independent service instances. Bind its result to a const
-	* and provide that const, per the memoization discipline — do not call
-	* `ConfigFile.layer(...)` inline at each provide site.
+	* and provide that const — do not call `ConfigFile.layer(...)` inline at each
+	* provide site.
+	*
+	* `tag` is a {@link ConfigFile.Service} key — its service type
+	* `ConfigFileShape<A>` for the schema's `A`. A key whose shape adds members
+	* (`ConfigFileShape<A> & { … }`) is a compile error, reported as an argument
+	* "not assignable to parameter of type 'never'", because this layer could not
+	* supply them. The check cannot see through method-syntax parameter
+	* bivariance: a member redeclared as a method with a wider parameter still
+	* compiles.
+	*
+	* @example
+	* ```ts
+	* import { ConfigFile, ConfigResolver, JsonCodec, MergeStrategy } from "@effected/config-file";
+	* import { Schema } from "effect";
+	*
+	* const AppShape = Schema.Struct({ port: Schema.Number });
+	* class AppConfig extends ConfigFile.Service<AppConfig, typeof AppShape.Type>()("app/Config") {}
+	*
+	* const AppConfigLive = ConfigFile.layer(AppConfig, {
+	* 	schema: AppShape,
+	* 	codec: JsonCodec,
+	* 	resolvers: [ConfigResolver.explicitPath("./app.config.json")],
+	* 	strategy: MergeStrategy.firstMatch<typeof AppShape.Type>(),
+	* });
+	* ```
 	*/
 	static layer = layer;
 	/**
@@ -485,10 +507,12 @@ var ConfigFile = class {
 	* directory is created through `FileSystem.makeTempDirectory` rather than
 	* `node:fs`.
 	*
-	* `Layer.scoped` does not exist in v4. `Layer.effect` types its layer as
-	* `Layer<I, E, Exclude<R, Scope>>`, so an `Effect.addFinalizer` inside it binds
-	* to the layer's own scope and runs on release without surfacing `Scope` in the
-	* layer's requirements.
+	* The temp directory is removed by a finalizer bound to the layer's own scope,
+	* so cleanup runs on release without surfacing `Scope` in the layer's
+	* requirements.
+	*
+	* `tag` takes the same `ConfigFileShape<A>` key as {@link ConfigFile.layer},
+	* with the same check: a shape that adds members is a compile error.
 	*
 	* @example
 	* ```ts
@@ -524,10 +548,17 @@ var ConfigFile = class {
 	* @example
 	* ```ts
 	* import { ConfigFile, JsonCodec } from "@effected/config-file";
+	* import { Effect, Schema } from "effect";
+	*
+	* const MyConfig = Schema.Struct({ port: Schema.Number });
 	*
-	* const config = yield* ConfigFile.read(inputs.configFile, {
-	*   schema: MyConfig,
-	*   codec: JsonCodec,
+	* // Requires `FileSystem` in `R`; provide it from a platform layer.
+	* const program = Effect.gen(function* () {
+	* 	const config = yield* ConfigFile.read("./app.config.json", {
+	* 		schema: MyConfig,
+	* 		codec: JsonCodec,
+	* 	});
+	* 	return config.port;
 	* });
 	* ```
 	*/

package/ConfigMigration.js

@@ -7,8 +7,7 @@ import { Effect, Schema } from "effect";
 * @remarks
 * `phase` says where: reading the current version, applying a step, or writing
 * the new version back. `cause` preserves the underlying failure by identity
-* when the failing step signals recoverable failure with `Effect.fail`. v3
-* assembled all three into a prose `reason` string.
+* when the failing step signals recoverable failure with `Effect.fail`.
 *
 * @public
 */
@@ -90,6 +89,23 @@ var ConfigMigration = class {
 	* {@link ConfigMigrationError} rather than flattening migration failures into
 	* the inner codec's error — the reason the {@link (ConfigCodec:interface)} seam is generic
 	* in its error type.
+	*
+	* @example
+	* ```ts
+	* import { ConfigMigration, JsonCodec } from "@effected/config-file";
+	* import { Effect } from "effect";
+	*
+	* const codec = ConfigMigration.make({
+	* 	codec: JsonCodec,
+	* 	migrations: [
+	* 		{
+	* 			version: 2,
+	* 			name: "rename-host",
+	* 			up: (raw) => Effect.succeed({ ...(raw as object), host: (raw as { hostname?: string }).hostname }),
+	* 		},
+	* 	],
+	* });
+	* ```
 	*/
 	static make = make;
 };

package/ConfigProvider.js

@@ -2,22 +2,21 @@ import { ConfigProvider, Effect } from "effect";
 
 //#region src/ConfigProvider.ts
 /**
-* Expose a loaded, merged, schema-validated document as a v4 `ConfigProvider`,
+* Expose a loaded, merged, schema-validated document as a `ConfigProvider`,
 * so it can be read through `Config.String("port")` and layered beneath other
 * providers.
 *
 * @remarks
 * Strictly additive, and deliberately in its own module so it never becomes a
 * required import. The schema-validated whole-document
-* {@link ConfigFileShape.load} remains the primary API: v4's `Config` has no
+* {@link ConfigFileShape.load} remains the primary API: `Config` has no
 * whole-document story, and this function is the bridge, not a replacement.
 *
 * Three properties, in order of how easy they are to lose:
 *
 * 1. **A missing file is a failure, not an empty provider.** The
 *    {@link ConfigFileNotFoundError} propagates. Handing back an empty provider
-*    would silently turn every subsequent `Config` read into "not found", which
-*    is the exact class of lie this port exists to undo.
+*    would silently turn every subsequent `Config` read into "not found".
 * 2. **Nested keys are structural, not dotted.** `fromUnknown` descends one path
 *    segment at a time, so `{ db: { host } }` is reached with
 *    `Config.nested(Config.String("host"), "db")` — never `Config.String("db.host")`,
@@ -45,8 +44,14 @@ import { ConfigProvider, Effect } from "effect";
 *
 * @example
 * ```ts
-* const fileProvider = yield* asConfigProvider(cfg);
-* const provider = ConfigProvider.orElse(ConfigProvider.fromEnv(), fileProvider);
+* import { asConfigProvider } from "@effected/config-file";
+* import { ConfigProvider, Effect } from "effect";
+*
+* const program = Effect.gen(function* () {
+* 	const cfg = yield* AppConfig; // a ConfigFile.Service class
+* 	const fileProvider = yield* asConfigProvider(cfg);
+* 	return ConfigProvider.orElse(ConfigProvider.fromEnv(), fileProvider);
+* });
 * ```
 *
 * @public
@@ -57,9 +62,8 @@ const asConfigProvider = (service) => Effect.map(service.load, (value) => Config
 * `ConfigProvider`, so `Config` accessors read env first and the file second.
 *
 * @remarks
-* This is the composition the v3 library could not express. This layer
-* composes beneath the **ambient** `ConfigProvider`, v4's `Context.Reference`
-* for it, so a consumer supplying `ConfigProvider.layer(...)` controls
+* This layer composes beneath the **ambient** `ConfigProvider` (a
+* `Context.Reference`), so a consumer supplying `ConfigProvider.layer(...)` controls
 * precedence explicitly: whatever that provider resolves wins, and the config
 * file supplies whatever it lacks. That reference's own default is
 * `ConfigProvider.fromEnv()`, which is what most applications want; this

package/EncryptedCodec.js

@@ -7,10 +7,9 @@ import { Duration, Effect, Exit, Schema } from "effect";
 * failed.
 *
 * @remarks
-* Its own error rather than v3's `"key-derivation"` value on the generic
-* `ConfigCodecError.operation` union — an encryption-only concern was leaking
-* into every codec's error type. `cause` preserves the underlying host failure
-* structurally; v3 assembled it into a prose `reason` string.
+* Its own error rather than a value on the generic `ConfigCodecError.operation`
+* union, so an encryption-only concern does not leak into every codec's error
+* type. `cause` preserves the underlying host failure structurally.
 *
 * @public
 */
@@ -88,6 +87,14 @@ const keyEffect = (keySource) => keySource._tag === "CryptoKey" ? keySource.key
 * flattening — the inner codec's failures stay distinguishable from
 * cryptographic ones.
 *
+* @example
+* ```ts
+* import { EncryptedCodec, EncryptedCodecKey, JsonCodec } from "@effected/config-file";
+*
+* const salt = new Uint8Array(16); // use a stored, random per-deployment salt
+* const codec = EncryptedCodec(JsonCodec, EncryptedCodecKey.fromPassphrase("correct horse", salt));
+* ```
+*
 * @public
 */
 function EncryptedCodec(inner, keySource) {

package/MergeStrategy.js

@@ -36,11 +36,19 @@ const layeredMerge = () => ({
 	}
 });
 /**
-* Built-in merge strategies.
+* Built-in merge strategies: `firstMatch` (the highest-priority source wins
+* whole) and `layeredMerge` (every source deep-merged, higher priority winning).
 *
 * @remarks
-* Renamed from v3's `ConfigWalkStrategy`, which never walked anything — the
-* thing that walks is the `upwardWalk` resolver.
+* Strategies only combine sources; the walk up the directory tree belongs to
+* the `upwardWalk` resolver.
+*
+* @example
+* ```ts
+* import { MergeStrategy } from "@effected/config-file";
+*
+* const strategy = MergeStrategy.layeredMerge<{ port: number }>();
+* ```
 *
 * @public
 */

package/README.md

@@ -7,10 +7,10 @@
 
 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".
 
-> **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
-> development against a single pinned Effect v4 prerelease. Packages graduate to
-> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
-> exactly the ones the kit is built and tested against, install
+> **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
+> makes a kit `1.0.0` possible, not automatic. To keep your `effect` and
+> `@effect/*` versions on the line the kit is built and tested against, install
 > [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
 >
 > **Stability: unstable.** This package's API surface is not yet considered

package/index.d.ts

@@ -60,8 +60,11 @@ export declare class ConfigCodecError extends ConfigCodecError_base {
  * @public
  */
 interface ConfigCodec<E = ConfigCodecError> {
+  /** The codec's name, e.g. `"json"`; recorded on {@link ConfigCodecError} and in events. */
   readonly name: string;
+  /** Turn file content into an unknown document. */
   readonly parse: (raw: string) => Effect.Effect<unknown, E>;
+  /** Turn a document back into file content. */
   readonly stringify: (value: unknown) => Effect.Effect<string, E>;
 }
 //#endregion
@@ -86,15 +89,14 @@ export declare const ConfigSourceRef: Schema.Struct<{
  * persistence.
  *
  * @remarks
- * v3's `Stringified` and `ResolutionFailed` variants were declared and never
- * emitted; they are not ported. `DiscoveryFailed` goes with them: under this
- * package's resolver-absorption contract a resolver's error channel is `never`
- * — every filesystem failure becomes `Option.none()` — so the pipeline can
- * never observe a discovery failure to report one.
+ * There is no discovery-failure variant: under this package's
+ * resolver-absorption contract a resolver's error channel is `never` — every
+ * filesystem failure becomes `Option.none()` — so the pipeline never observes a
+ * discovery failure to report.
  *
  * The failure variants carry the **structured** typed error in `error`, not a
- * `reason` string. v3 stringified them, destroying every field a subscriber
- * might branch on; a subscriber that wants prose can read `error.message`.
+ * `reason` string, so every field a subscriber might branch on survives; a
+ * subscriber that wants prose can read `error.message`.
  *
  * @public
  */
@@ -260,7 +262,9 @@ export declare class ConfigEvents extends ConfigEvents_base {
  * @public
  */
 export interface ConfigResolver<R = never> {
+  /** The resolver's name, reported in `searched` lists, events and `ConfigSource.resolver`. */
   readonly name: string;
+  /** Look up the config file's path: `Option.some(path)` when found, `Option.none()` otherwise. */
   readonly resolve: Effect.Effect<Option.Option<string>, never, R>;
   /**
    * The same lookup, reporting **how** the file was found rather than only
@@ -511,15 +515,25 @@ type NonEmptySources<A> = readonly [ConfigSource<A>, ...ConfigSource<A>[]];
  * @public
  */
 export interface MergeStrategy<A> {
+  /** The strategy's name, reported on the `Resolved` event. */
   readonly name: string;
+  /** Combine the sources, highest priority first, into one value. */
   readonly resolve: (sources: NonEmptySources<A>) => Effect.Effect<A>;
 }
 /**
- * Built-in merge strategies.
+ * Built-in merge strategies: `firstMatch` (the highest-priority source wins
+ * whole) and `layeredMerge` (every source deep-merged, higher priority winning).
  *
  * @remarks
- * Renamed from v3's `ConfigWalkStrategy`, which never walked anything — the
- * thing that walks is the `upwardWalk` resolver.
+ * Strategies only combine sources; the walk up the directory tree belongs to
+ * the `upwardWalk` resolver.
+ *
+ * @example
+ * ```ts
+ * import { MergeStrategy } from "@effected/config-file";
+ *
+ * const strategy = MergeStrategy.layeredMerge<{ port: number }>();
+ * ```
  *
  * @public
  */
@@ -551,7 +565,7 @@ declare const ConfigFileNotFoundError_base: Schema.Class<ConfigFileNotFoundError
  * @remarks
  * Its own tag, so "no config anywhere" is routable with `Effect.catchTag`
  * separately from "the config I found is broken" — the single most important
- * distinction the v3 mega-error could not express.
+ * distinction in the error set.
  *
  * @public
  */
@@ -568,8 +582,8 @@ declare const ConfigFileReadError_base: Schema.Class<ConfigFileReadError, Schema
  * Indicates that a config file could not be read from the filesystem.
  *
  * @remarks
- * `cause` preserves the underlying filesystem failure structurally. v3 flattened
- * it to `reason: String(e)`.
+ * `cause` preserves the underlying filesystem failure structurally rather than
+ * flattening it to a string.
  *
  * @public
  */
@@ -596,13 +610,12 @@ declare const ConfigDefaultPathMissingError_base: Schema.Class<ConfigDefaultPath
  * was called on a service configured without a `defaultPath`.
  *
  * @remarks
- * v3 reported this as a generic `ConfigError` carrying `operation: "save"` and
- * `reason: "no default path configured"` — indistinguishable by tag from a real
- * write failure.
+ * It is distinct by tag from a real {@link ConfigFileWriteError}, so a caller
+ * can tell "no destination was configured" from "the write failed".
  *
  * It carries no `path` field on purpose. The whole point of this failure is
  * that there is no path; a {@link ConfigFileWriteError} with a fabricated path
- * would be a lie, and lying error payloads are what this port exists to undo.
+ * would be a lie.
  *
  * @public
  */
@@ -621,10 +634,9 @@ declare const ConfigValidationError_base: Schema.Class<ConfigValidationError, Sc
  *
  * @remarks
  * `issue` carries the **structured** schema failure — at runtime a
- * `SchemaIssue.Issue` tree, reachable through `_tag` and nested `issues`. v3
- * flattened this to `String(ParseError)`, destroying every field a caller might
- * branch on. It is typed `unknown` because v4 exposes no `Schema` for `Issue`;
- * narrow it with the `SchemaIssue` module.
+ * `SchemaIssue.Issue` tree, reachable through `_tag` and nested `issues`, so
+ * every field a caller might branch on survives. It is typed `unknown` because
+ * there is no `Schema` for `Issue`; narrow it with the `SchemaIssue` module.
  *
  * @public
  */
@@ -723,7 +735,7 @@ interface ConfigFileShape<A> {
    * @remarks
    * A found-but-corrupt source ABORTS discovery with a typed error rather than
    * being silently skipped: silently skipping a corrupt file would mean running
-   * on the wrong config. This is deliberate, and is parity with v3.
+   * on the wrong config. This is deliberate.
    */
   readonly discover: Effect.Effect<ReadonlyArray<ConfigSource<A>>, ConfigReadError>;
   /**
@@ -786,7 +798,7 @@ interface ConfigFileOptions<A, I, RR> {
    * The schema every discovered document is decoded through.
    *
    * @remarks
-   * `Schema.Codec<A, I>` rather than v4's one-parameter `Schema.Schema<A>`,
+   * `Schema.Codec<A, I>` rather than the one-parameter `Schema.Schema<A>`,
    * because the encoded form `I` matters on the write path. Its decoding and
    * encoding service channels default to `never`, keeping `decode` free of
    * requirements.
@@ -830,8 +842,6 @@ interface ConfigFileOptions<A, I, RR> {
    *
    * @remarks
    * Its requirements join the resolvers' in `RR` and flow into the layer's `R`.
-   * v3 typed this `Effect<string, ConfigError, any>` and cast the requirements
-   * away at the call site.
    *
    * When absent, `save` and `update` fail with
    * {@link ConfigDefaultPathMissingError}.
@@ -931,16 +941,40 @@ export declare class ConfigFile {
    * Build the live layer for a config service class.
    *
    * @remarks
-   * Resolver requirements flow into the layer's `R` type. v3 cast them away with
-   * `as Effect.Effect<Option<string>>`, making `Layer<Service, never, FileSystem>`
-   * a claim rather than a proof.
+   * Resolver requirements flow into the layer's `R` type: the result is
+   * `Layer<Self, never, FileSystem | Path | RR>`, so the platform services and
+   * every resolver's needs are visible at the provide site.
    *
    * `ConfigFile.layer` is a layer-RETURNING function, not a layer: calling it
    * twice builds two independent service instances. Bind its result to a const
-   * and provide that const, per the memoization discipline — do not call
-   * `ConfigFile.layer(...)` inline at each provide site.
+   * and provide that const — do not call `ConfigFile.layer(...)` inline at each
+   * provide site.
+   *
+   * `tag` is a {@link ConfigFile.Service} key — its service type
+   * `ConfigFileShape<A>` for the schema's `A`. A key whose shape adds members
+   * (`ConfigFileShape<A> & { … }`) is a compile error, reported as an argument
+   * "not assignable to parameter of type 'never'", because this layer could not
+   * supply them. The check cannot see through method-syntax parameter
+   * bivariance: a member redeclared as a method with a wider parameter still
+   * compiles.
+   *
+   * @example
+   * ```ts
+   * import { ConfigFile, ConfigResolver, JsonCodec, MergeStrategy } from "@effected/config-file";
+   * import { Schema } from "effect";
+   *
+   * const AppShape = Schema.Struct({ port: Schema.Number });
+   * class AppConfig extends ConfigFile.Service<AppConfig, typeof AppShape.Type>()("app/Config") {}
+   *
+   * const AppConfigLive = ConfigFile.layer(AppConfig, {
+   * 	schema: AppShape,
+   * 	codec: JsonCodec,
+   * 	resolvers: [ConfigResolver.explicitPath("./app.config.json")],
+   * 	strategy: MergeStrategy.firstMatch<typeof AppShape.Type>(),
+   * });
+   * ```
    */
-  static readonly layer: <Self, A, I, RR = never>(tag: Context.Key<Self, ConfigFileShape<A>>, options: ConfigFileOptions<A, I, RR>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | RR>;
+  static readonly layer: <Self, A, I, RR = never, S extends ConfigFileShape<A> = ConfigFileShape<A>>(tag: Context.Key<Self, S> & ([ConfigFileShape<A>] extends [S] ? unknown : never), options: ConfigFileOptions<A, I, RR>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path | RR>;
   /**
    * A scoped layer that seeds `files` into a temp directory, wires the **real**
    * live implementation over them, and removes the directory when the scope
@@ -957,10 +991,12 @@ export declare class ConfigFile {
    * directory is created through `FileSystem.makeTempDirectory` rather than
    * `node:fs`.
    *
-   * `Layer.scoped` does not exist in v4. `Layer.effect` types its layer as
-   * `Layer<I, E, Exclude<R, Scope>>`, so an `Effect.addFinalizer` inside it binds
-   * to the layer's own scope and runs on release without surfacing `Scope` in the
-   * layer's requirements.
+   * The temp directory is removed by a finalizer bound to the layer's own scope,
+   * so cleanup runs on release without surfacing `Scope` in the layer's
+   * requirements.
+   *
+   * `tag` takes the same `ConfigFileShape<A>` key as {@link ConfigFile.layer},
+   * with the same check: a shape that adds members is a compile error.
    *
    * @example
    * ```ts
@@ -972,7 +1008,7 @@ export declare class ConfigFile {
    * }).pipe(Layer.provide(NodeServices.layer));
    * ```
    */
-  static readonly testLayer: <Self, A, I>(tag: Context.Key<Self, ConfigFileShape<A>>, options: ConfigFileTestOptions<A, I>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path>;
+  static readonly testLayer: <Self, A, I, S extends ConfigFileShape<A> = ConfigFileShape<A>>(tag: Context.Key<Self, S> & ([ConfigFileShape<A>] extends [S] ? unknown : never), options: ConfigFileTestOptions<A, I>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path>;
   /**
    * Read, decode and validate one explicit path — no service, no layer, no tag.
    *
@@ -996,10 +1032,17 @@ export declare class ConfigFile {
    * @example
    * ```ts
    * import { ConfigFile, JsonCodec } from "@effected/config-file";
+   * import { Effect, Schema } from "effect";
    *
-   * const config = yield* ConfigFile.read(inputs.configFile, {
-   *   schema: MyConfig,
-   *   codec: JsonCodec,
+   * const MyConfig = Schema.Struct({ port: Schema.Number });
+   *
+   * // Requires `FileSystem` in `R`; provide it from a platform layer.
+   * const program = Effect.gen(function* () {
+   * 	const config = yield* ConfigFile.read("./app.config.json", {
+   * 		schema: MyConfig,
+   * 		codec: JsonCodec,
+   * 	});
+   * 	return config.port;
    * });
    * ```
    */
@@ -1023,8 +1066,7 @@ declare const ConfigMigrationError_base: Schema.Class<ConfigMigrationError, Sche
  * @remarks
  * `phase` says where: reading the current version, applying a step, or writing
  * the new version back. `cause` preserves the underlying failure by identity
- * when the failing step signals recoverable failure with `Effect.fail`. v3
- * assembled all three into a prose `reason` string.
+ * when the failing step signals recoverable failure with `Effect.fail`.
  *
  * @public
  */
@@ -1035,13 +1077,14 @@ export declare class ConfigMigrationError extends ConfigMigrationError_base {
  * A single versioned migration step.
  *
  * @remarks
- * v3 also declared a `down` reverse migration. It was never invoked anywhere in
- * the codebase, so it is not ported.
+ * Steps are forward-only: there is no reverse (`down`) migration.
  *
  * @public
  */
 interface ConfigFileMigration {
+  /** The version this step migrates the config to. Steps run in ascending order. */
   readonly version: number;
+  /** A label for the step, carried on {@link ConfigMigrationError} when it fails. */
   readonly name: string;
   /**
    * Transforms the parsed config. Signal recoverable failure with `Effect.fail`;
@@ -1051,7 +1094,9 @@ interface ConfigFileMigration {
 }
 /** How the version number is read from and written to the parsed config. @public */
 export interface VersionAccess {
+  /** Read the current version from the parsed config. */
   readonly get: (raw: unknown) => Effect.Effect<number, unknown>;
+  /** Return the config with `version` written back. */
   readonly set: (raw: unknown, version: number) => Effect.Effect<unknown, unknown>;
 }
 /** Reads and writes a top-level `version` field. @public */
@@ -1060,8 +1105,11 @@ export declare const VersionAccess: {
 };
 /** Options for {@link ConfigMigration.make}. @public */
 interface ConfigMigrationOptions {
+  /** The codec being wrapped. */
   readonly codec: ConfigCodec;
+  /** The migration steps; they run in ascending `version` order. */
   readonly migrations: ReadonlyArray<ConfigFileMigration>;
+  /** How the version is read and written; defaults to {@link (VersionAccess:variable).default}, a top-level `version` field. */
   readonly versionAccess?: VersionAccess;
 }
 /** Versioned migration support for config codecs. @public */
@@ -1075,28 +1123,44 @@ export declare class ConfigMigration {
    * {@link ConfigMigrationError} rather than flattening migration failures into
    * the inner codec's error — the reason the {@link (ConfigCodec:interface)} seam is generic
    * in its error type.
+   *
+   * @example
+   * ```ts
+   * import { ConfigMigration, JsonCodec } from "@effected/config-file";
+   * import { Effect } from "effect";
+   *
+   * const codec = ConfigMigration.make({
+   * 	codec: JsonCodec,
+   * 	migrations: [
+   * 		{
+   * 			version: 2,
+   * 			name: "rename-host",
+   * 			up: (raw) => Effect.succeed({ ...(raw as object), host: (raw as { hostname?: string }).hostname }),
+   * 		},
+   * 	],
+   * });
+   * ```
    */
   static readonly make: (options: ConfigMigrationOptions) => ConfigCodec<ConfigCodecError | ConfigMigrationError>;
 }
 //#endregion
 //#region src/ConfigProvider.d.ts
 /**
- * Expose a loaded, merged, schema-validated document as a v4 `ConfigProvider`,
+ * Expose a loaded, merged, schema-validated document as a `ConfigProvider`,
  * so it can be read through `Config.String("port")` and layered beneath other
  * providers.
  *
  * @remarks
  * Strictly additive, and deliberately in its own module so it never becomes a
  * required import. The schema-validated whole-document
- * {@link ConfigFileShape.load} remains the primary API: v4's `Config` has no
+ * {@link ConfigFileShape.load} remains the primary API: `Config` has no
  * whole-document story, and this function is the bridge, not a replacement.
  *
  * Three properties, in order of how easy they are to lose:
  *
  * 1. **A missing file is a failure, not an empty provider.** The
  *    {@link ConfigFileNotFoundError} propagates. Handing back an empty provider
- *    would silently turn every subsequent `Config` read into "not found", which
- *    is the exact class of lie this port exists to undo.
+ *    would silently turn every subsequent `Config` read into "not found".
  * 2. **Nested keys are structural, not dotted.** `fromUnknown` descends one path
  *    segment at a time, so `{ db: { host } }` is reached with
  *    `Config.nested(Config.String("host"), "db")` — never `Config.String("db.host")`,
@@ -1124,8 +1188,14 @@ export declare class ConfigMigration {
  *
  * @example
  * ```ts
- * const fileProvider = yield* asConfigProvider(cfg);
- * const provider = ConfigProvider.orElse(ConfigProvider.fromEnv(), fileProvider);
+ * import { asConfigProvider } from "@effected/config-file";
+ * import { ConfigProvider, Effect } from "effect";
+ *
+ * const program = Effect.gen(function* () {
+ * 	const cfg = yield* AppConfig; // a ConfigFile.Service class
+ * 	const fileProvider = yield* asConfigProvider(cfg);
+ * 	return ConfigProvider.orElse(ConfigProvider.fromEnv(), fileProvider);
+ * });
  * ```
  *
  * @public
@@ -1152,9 +1222,8 @@ interface LayerConfigProviderOptions {
  * `ConfigProvider`, so `Config` accessors read env first and the file second.
  *
  * @remarks
- * This is the composition the v3 library could not express. This layer
- * composes beneath the **ambient** `ConfigProvider`, v4's `Context.Reference`
- * for it, so a consumer supplying `ConfigProvider.layer(...)` controls
+ * This layer composes beneath the **ambient** `ConfigProvider` (a
+ * `Context.Reference`), so a consumer supplying `ConfigProvider.layer(...)` controls
  * precedence explicitly: whatever that provider resolves wins, and the config
  * file supplies whatever it lacks. That reference's own default is
  * `ConfigProvider.fromEnv()`, which is what most applications want; this
@@ -1187,10 +1256,9 @@ declare const ConfigEncryptionError_base: Schema.Class<ConfigEncryptionError, Sc
  * failed.
  *
  * @remarks
- * Its own error rather than v3's `"key-derivation"` value on the generic
- * `ConfigCodecError.operation` union — an encryption-only concern was leaking
- * into every codec's error type. `cause` preserves the underlying host failure
- * structurally; v3 assembled it into a prose `reason` string.
+ * Its own error rather than a value on the generic `ConfigCodecError.operation`
+ * union, so an encryption-only concern does not leak into every codec's error
+ * type. `cause` preserves the underlying host failure structurally.
  *
  * @public
  */
@@ -1260,6 +1328,14 @@ export declare const EncryptedCodecKey: {
  * flattening — the inner codec's failures stay distinguishable from
  * cryptographic ones.
  *
+ * @example
+ * ```ts
+ * import { EncryptedCodec, EncryptedCodecKey, JsonCodec } from "@effected/config-file";
+ *
+ * const salt = new Uint8Array(16); // use a stored, random per-deployment salt
+ * const codec = EncryptedCodec(JsonCodec, EncryptedCodecKey.fromPassphrase("correct horse", salt));
+ * ```
+ *
  * @public
  */
 export declare function EncryptedCodec<E>(inner: ConfigCodec<E>, keySource: EncryptedCodecKey): ConfigCodec<E | ConfigEncryptionError>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/config-file",
-	"version": "0.13.1",
+	"version": "0.14.1",
 	"private": false,
 	"description": "Composable config file loading for Effect: JSON, JSONC, YAML and TOML codecs, resolution strategies, and merge behaviors.",
 	"keywords": [
@@ -43,11 +43,12 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/jsonc": "^0.14.0",
-		"@effected/toml": "^0.10.0",
-		"@effected/walker": "^0.14.0",
-		"@effected/yaml": "^0.18.0",
-		"effect": "4.0.0-rc.118"
+		"@effected/glob": "^0.10.0",
+		"@effected/jsonc": "^0.15.0",
+		"@effected/toml": "^0.11.0",
+		"@effected/walker": "^0.15.0",
+		"@effected/yaml": "^0.19.0",
+		"effect": "^4.0.0"
 	},
 	"engines": {
 		"node": ">=24.11.0"