@effected/config-file 0.1.0

package/index.d.ts

@@ -0,0 +1,932 @@
+import { ConfigProvider, Context, Effect, FileSystem, Layer, Option, Path, PubSub, Schema } from "effect";
+//#region src/ConfigCodec.d.ts
+declare const ConfigCodecError_base: Schema.Class<ConfigCodecError, Schema.TaggedStruct<"ConfigCodecError", {
+  /** The codec that failed, e.g. `"json"`. */
+  readonly codec: Schema.String;
+  /** Which direction failed. */
+  readonly operation: Schema.Literals<readonly ["parse", "stringify"]>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a codec failed to parse or stringify configuration content.
+ *
+ * @remarks
+ * The underlying failure is preserved structurally in `cause` — it is never
+ * stringified. Route on the `"ConfigCodecError"` tag with `Effect.catchTag`.
+ *
+ * @public
+ */
+declare class ConfigCodecError extends ConfigCodecError_base {
+  get message(): string;
+}
+/**
+ * A pluggable configuration file codec: how to turn file content into a value
+ * and back.
+ *
+ * @remarks
+ * `E` is the codec's error channel. It defaults to {@link ConfigCodecError};
+ * decorator codecs such as `EncryptedCodec` and `ConfigMigration.make` widen it
+ * rather than flattening their own failures into a string.
+ *
+ * The four built-in codecs — `JsonCodec`, `JsoncCodec`, `YamlCodec` and
+ * `TomlCodec` — are free-standing named exports, one per module, and are
+ * deliberately never collected into a namespace object. Collecting them would
+ * make this module a dispatch table: referencing it at all would reach every
+ * codec, and every codec would reach its parsing engine, so importing the JSON
+ * codec alone would drag the JSONC, YAML and TOML engines into the bundle.
+ * Name the one codec you use and a bundler drops the rest.
+ *
+ * @public
+ */
+interface ConfigCodec<E = ConfigCodecError> {
+  readonly name: string;
+  readonly parse: (raw: string) => Effect.Effect<unknown, E>;
+  readonly stringify: (value: unknown) => Effect.Effect<string, E>;
+}
+//#endregion
+//#region src/ConfigEvent.d.ts
+/**
+ * A reference to one configuration source that contributed to a load.
+ *
+ * @remarks
+ * Carries the resolver's name alongside the path so a subscriber can tell
+ * `/etc/app/.apprc` found by `systemEtc` from the same path passed explicitly.
+ *
+ * @public
+ */
+declare const ConfigSourceRef: Schema.Struct<{
+  /** The filesystem path the value was read from. */
+  readonly path: Schema.String;
+  /** The name of the resolver that found it. */
+  readonly resolver: Schema.String;
+}>;
+/**
+ * Every event published during config discovery, parsing, validation and
+ * 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.
+ *
+ * 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`.
+ *
+ * @public
+ */
+declare const ConfigEventPayload: Schema.Union<readonly [Schema.TaggedStruct<"Discovered", {
+  readonly path: Schema.String;
+  readonly resolver: Schema.String;
+}>, Schema.TaggedStruct<"NotFound", {}>, Schema.TaggedStruct<"Parsed", {
+  readonly path: Schema.String;
+  readonly codec: Schema.String;
+}>, Schema.TaggedStruct<"ParseFailed", {
+  readonly path: Schema.String;
+  readonly codec: Schema.String;
+  readonly error: Schema.Defect;
+}>, Schema.TaggedStruct<"Validated", {
+  readonly path: Schema.String;
+}>, Schema.TaggedStruct<"ValidationFailed", {
+  readonly path: Schema.String;
+  readonly error: Schema.Defect;
+}>, Schema.TaggedStruct<"Resolved", {
+  readonly sources: Schema.$Array<Schema.Struct<{
+    /** The filesystem path the value was read from. */
+    readonly path: Schema.String;
+    /** The name of the resolver that found it. */
+    readonly resolver: Schema.String;
+  }>>;
+  readonly strategy: Schema.String;
+}>, Schema.TaggedStruct<"Loaded", {
+  readonly sources: Schema.$Array<Schema.Struct<{
+    /** The filesystem path the value was read from. */
+    readonly path: Schema.String;
+    /** The name of the resolver that found it. */
+    readonly resolver: Schema.String;
+  }>>;
+}>, Schema.TaggedStruct<"StringifyFailed", {
+  readonly codec: Schema.String;
+  readonly error: Schema.Defect;
+}>, Schema.TaggedStruct<"Written", {
+  readonly path: Schema.String;
+}>, Schema.TaggedStruct<"Saved", {
+  readonly path: Schema.String;
+}>, Schema.TaggedStruct<"Updated", {
+  readonly path: Schema.String;
+}>]>;
+/**
+ * The decoded form of {@link (ConfigEventPayload:variable)}: a tagged union a subscriber
+ * narrows with `switch (payload._tag)`.
+ *
+ * @public
+ */
+type ConfigEventPayload = typeof ConfigEventPayload.Type;
+declare const ConfigEvent_base: Schema.Class<ConfigEvent, Schema.Struct<{
+  /** When the event occurred. */
+  readonly timestamp: Schema.DateTimeUtc;
+  /** What happened. */
+  readonly event: Schema.Union<readonly [Schema.TaggedStruct<"Discovered", {
+    readonly path: Schema.String;
+    readonly resolver: Schema.String;
+  }>, Schema.TaggedStruct<"NotFound", {}>, Schema.TaggedStruct<"Parsed", {
+    readonly path: Schema.String;
+    readonly codec: Schema.String;
+  }>, Schema.TaggedStruct<"ParseFailed", {
+    readonly path: Schema.String;
+    readonly codec: Schema.String;
+    readonly error: Schema.Defect;
+  }>, Schema.TaggedStruct<"Validated", {
+    readonly path: Schema.String;
+  }>, Schema.TaggedStruct<"ValidationFailed", {
+    readonly path: Schema.String;
+    readonly error: Schema.Defect;
+  }>, Schema.TaggedStruct<"Resolved", {
+    readonly sources: Schema.$Array<Schema.Struct<{
+      /** The filesystem path the value was read from. */
+      readonly path: Schema.String;
+      /** The name of the resolver that found it. */
+      readonly resolver: Schema.String;
+    }>>;
+    readonly strategy: Schema.String;
+  }>, Schema.TaggedStruct<"Loaded", {
+    readonly sources: Schema.$Array<Schema.Struct<{
+      /** The filesystem path the value was read from. */
+      readonly path: Schema.String;
+      /** The name of the resolver that found it. */
+      readonly resolver: Schema.String;
+    }>>;
+  }>, Schema.TaggedStruct<"StringifyFailed", {
+    readonly codec: Schema.String;
+    readonly error: Schema.Defect;
+  }>, Schema.TaggedStruct<"Written", {
+    readonly path: Schema.String;
+  }>, Schema.TaggedStruct<"Saved", {
+    readonly path: Schema.String;
+  }>, Schema.TaggedStruct<"Updated", {
+    readonly path: Schema.String;
+  }>]>;
+}>, {}>;
+/**
+ * A published event: the payload plus the instant it occurred.
+ *
+ * @public
+ */
+declare class ConfigEvent extends ConfigEvent_base {}
+/**
+ * The service shape {@link ConfigEvents} provides.
+ *
+ * @public
+ */
+interface ConfigEventsShape {
+  /** The hub every {@link ConfigEvent} is published to. */
+  readonly events: PubSub.PubSub<ConfigEvent>;
+}
+declare const ConfigEvents_base: Context.ServiceClass<ConfigEvents, "@effected/config-file/ConfigEvents", ConfigEventsShape>;
+/**
+ * The opt-in event hook: a PubSub of {@link ConfigEvent} that consumers
+ * subscribe to.
+ *
+ * @remarks
+ * Opt-in and honestly zero-cost: when `ConfigFileOptions.events` is omitted the
+ * pipeline's `emit` is `Effect.void` and never even looks the service up.
+ *
+ * Events are a **consumer-facing hook**, not the package's observability
+ * channel — every public fallible method is also an `Effect.fn` named span, and
+ * the library stays telemetry-agnostic.
+ *
+ * @example
+ * ```ts
+ * const events = ConfigEvents.layer;
+ * const AppLayer = Layer.mergeAll(
+ * 	events,
+ * 	ConfigFile.layer(AppConfig, { schema, codec, resolvers, strategy, events: ConfigEvents }),
+ * );
+ * ```
+ *
+ * @public
+ */
+declare class ConfigEvents extends ConfigEvents_base {
+  /**
+   * An unbounded PubSub of config events.
+   *
+   * @remarks
+   * Unbounded on purpose: a slow subscriber must never apply backpressure to a
+   * config load. Bind this to a const and provide that const — building it
+   * twice mints two hubs, and the subscriber would watch the one `emit` does
+   * not publish to.
+   */
+  static readonly layer: Layer.Layer<ConfigEvents>;
+}
+//#endregion
+//#region src/ConfigResolver.d.ts
+/**
+ * A composable config file resolver: one lookup strategy.
+ *
+ * @remarks
+ * `resolve` yields `Option.some(path)` when a config file is found and
+ * `Option.none()` when it is not. **Its error channel is `never` by contract**:
+ * every filesystem failure — permission denied, ENOTDIR, a broken symlink — is
+ * absorbed into `Option.none()`, so a failure on one tier never aborts the
+ * chain. This is deliberate: discovery is best-effort.
+ *
+ * `R` carries the resolver's requirements. The built-ins require
+ * `FileSystem.FileSystem | Path.Path`, satisfied once by the consumer's
+ * platform layer at the edge.
+ *
+ * @public
+ */
+interface ConfigResolver<R = never> {
+  readonly name: string;
+  readonly resolve: Effect.Effect<Option.Option<string>, never, R>;
+}
+/**
+ * Built-in resolvers, in the order a typical chain uses them.
+ *
+ * @public
+ */
+declare const ConfigResolver: {
+  readonly explicitPath: (target: string) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
+  readonly staticDir: (options: {
+    readonly dir: string;
+    readonly filename: string;
+  }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
+  readonly upwardWalk: (options: {
+    readonly filename: string;
+    readonly cwd?: string;
+    readonly stopAt?: string;
+    readonly subpaths?: ReadonlyArray<string>;
+  }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
+  readonly workspaceRoot: (options: {
+    readonly filename: string;
+    readonly cwd?: string;
+    readonly subpaths?: ReadonlyArray<string>;
+  }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
+  readonly gitRoot: (options: {
+    readonly filename: string;
+    readonly cwd?: string;
+    readonly subpaths?: ReadonlyArray<string>;
+  }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
+  readonly systemEtc: (options: {
+    readonly app: string;
+    readonly filename: string;
+    /**
+     * System config root. Defaults to `/etc`. Overridable primarily so tests
+     * can point at a writable temp directory — the real `/etc` is not writable
+     * in test environments — and as an escape hatch for non-standard layouts.
+     */
+    readonly dir?: string;
+  }) => ConfigResolver<FileSystem.FileSystem | Path.Path>;
+};
+//#endregion
+//#region src/MergeStrategy.d.ts
+/**
+ * A single configuration source discovered during a resolver-chain pass.
+ *
+ * @public
+ */
+interface ConfigSource<A> {
+  /** The filesystem path the value was read from. */
+  readonly path: string;
+  /** The name of the resolver that found it. */
+  readonly resolver: string;
+  /** The decoded, validated configuration value. */
+  readonly value: A;
+}
+/** A source list guaranteed non-empty by the caller. @public */
+type NonEmptySources<A> = readonly [ConfigSource<A>, ...ConfigSource<A>[]];
+/**
+ * Strategy for combining several {@link ConfigSource} entries into one value.
+ *
+ * @remarks
+ * Sources arrive in priority order, highest first. The list is non-empty by
+ * construction — the empty case is the pipeline's concern and raises
+ * `ConfigFileNotFoundError` before a strategy is ever consulted — so a strategy
+ * cannot fail.
+ *
+ * @public
+ */
+interface MergeStrategy<A> {
+  readonly name: string;
+  readonly resolve: (sources: NonEmptySources<A>) => Effect.Effect<A>;
+}
+/**
+ * Built-in merge strategies.
+ *
+ * @remarks
+ * Renamed from v3's `ConfigWalkStrategy`, which never walked anything — the
+ * thing that walks is the `upwardWalk` resolver.
+ *
+ * @public
+ */
+declare const MergeStrategy: {
+  readonly firstMatch: <A>() => MergeStrategy<A>;
+  readonly layeredMerge: <A>() => MergeStrategy<A>;
+};
+//#endregion
+//#region src/ConfigFile.d.ts
+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>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that the resolver chain produced no configuration source.
+ *
+ * @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.
+ *
+ * @public
+ */
+declare class ConfigFileNotFoundError extends ConfigFileNotFoundError_base {
+  get message(): string;
+}
+declare const ConfigFileReadError_base: Schema.Class<ConfigFileReadError, Schema.TaggedStruct<"ConfigFileReadError", {
+  /** The path that could not be read. */
+  readonly path: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * 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)`.
+ *
+ * @public
+ */
+declare class ConfigFileReadError extends ConfigFileReadError_base {
+  get message(): string;
+}
+declare const ConfigFileWriteError_base: Schema.Class<ConfigFileWriteError, Schema.TaggedStruct<"ConfigFileWriteError", {
+  /** The path that could not be written. */
+  readonly path: Schema.String;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a config file could not be written to the filesystem.
+ *
+ * @public
+ */
+declare class ConfigFileWriteError extends ConfigFileWriteError_base {
+  get message(): string;
+}
+declare const ConfigDefaultPathMissingError_base: Schema.Class<ConfigDefaultPathMissingError, Schema.TaggedStruct<"ConfigDefaultPathMissingError", {}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that {@link ConfigFileShape.save} or {@link ConfigFileShape.update}
+ * 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 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.
+ *
+ * @public
+ */
+declare class ConfigDefaultPathMissingError extends ConfigDefaultPathMissingError_base {
+  get message(): string;
+}
+declare const ConfigValidationError_base: Schema.Class<ConfigValidationError, Schema.TaggedStruct<"ConfigValidationError", {
+  /** The offending file, absent when `validate` was called on an in-memory value. */
+  readonly path: Schema.Option<Schema.String>;
+  /** The structured schema issue. Never a string. */
+  readonly issue: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that parsed config content did not satisfy the schema, or that a
+ * caller-supplied `validate` rejected it.
+ *
+ * @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.
+ *
+ * @public
+ */
+declare class ConfigValidationError extends ConfigValidationError_base {
+  get message(): string;
+}
+/**
+ * The failure modes of the full discovery-and-load path.
+ *
+ * @public
+ */
+type ConfigLoadError = ConfigFileNotFoundError | ConfigFileReadError | ConfigCodecError | ConfigValidationError;
+/**
+ * The failure modes of reading one known path.
+ *
+ * @remarks
+ * Deliberately excludes {@link ConfigFileNotFoundError}: every method typed with
+ * this union either takes an explicit path or treats "nothing found" as success.
+ *
+ * @public
+ */
+type ConfigReadError = ConfigFileReadError | ConfigCodecError | ConfigValidationError;
+/**
+ * The failure modes of encoding and writing one known path.
+ *
+ * @remarks
+ * Deliberately excludes {@link ConfigFileNotFoundError} — the path is explicit,
+ * so there is nothing to discover — and {@link ConfigDefaultPathMissingError},
+ * because no default path is consulted.
+ *
+ * @public
+ */
+type ConfigWriteError = ConfigFileWriteError | ConfigCodecError | ConfigValidationError;
+/**
+ * The failure modes of {@link ConfigFileShape.save}.
+ *
+ * @public
+ */
+type ConfigSaveError = ConfigWriteError | ConfigDefaultPathMissingError;
+/**
+ * The failure modes of {@link ConfigFileShape.update}, which loads and then saves.
+ *
+ * @public
+ */
+type ConfigUpdateError = ConfigLoadError | ConfigFileWriteError | ConfigDefaultPathMissingError;
+/**
+ * The config file service, generic over the decoded config type `A`.
+ *
+ * @remarks
+ * Error unions are narrowed per method: `loadOrDefault` cannot fail with
+ * {@link ConfigFileNotFoundError} because that is the branch it handles, and
+ * `discover` treats an empty result as success.
+ *
+ * @public
+ */
+interface ConfigFileShape<A> {
+  /** Discover, decode and merge the highest-priority config source. */
+  readonly load: Effect.Effect<A, ConfigLoadError>;
+  /** Read, decode and validate one explicit path. */
+  readonly loadFrom: (path: string) => Effect.Effect<A, ConfigReadError>;
+  /**
+   * Every source the resolver chain found, in priority order. Empty is success.
+   *
+   * @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.
+   */
+  readonly discover: Effect.Effect<ReadonlyArray<ConfigSource<A>>, ConfigReadError>;
+  /**
+   * Like {@link ConfigFileShape.load}, but yields `defaultValue` when nothing is found.
+   *
+   * @remarks
+   * `defaultValue` is returned as-is: neither the schema nor `options.validate`
+   * is applied to it. It is trusted caller input, not a discovered document.
+   */
+  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` 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.
+   */
+  readonly write: (value: A, path: string) => Effect.Effect<void, ConfigWriteError>;
+  /**
+   * Resolve `defaultPath`, `mkdir -p` its parent, encode `value` into it, and
+   * return the path written.
+   */
+  readonly save: (value: A) => Effect.Effect<string, ConfigSaveError>;
+  /**
+   * Load the current value, apply `fn`, {@link ConfigFileShape.save} the result
+   * and return it.
+   *
+   * @remarks
+   * With `defaultValue` the load cannot fail with
+   * {@link ConfigFileNotFoundError}; without it, it can.
+   */
+  readonly update: (fn: (current: A) => A, defaultValue?: A) => Effect.Effect<A, ConfigUpdateError>;
+}
+/**
+ * Options for {@link ConfigFile.layer}.
+ *
+ * @remarks
+ * `RR` is the union of the resolvers' requirements. It flows into the layer's
+ * `R` rather than being cast away.
+ *
+ * @public
+ */
+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>`,
+   * because the encoded form `I` matters on the write path. Its decoding and
+   * encoding service channels default to `never`, keeping `decode` free of
+   * requirements.
+   */
+  readonly schema: Schema.Codec<A, I>;
+  /** How file content becomes an unknown document, and back. */
+  readonly codec: ConfigCodec;
+  /** The resolver chain, in priority order. */
+  readonly resolvers: ReadonlyArray<ConfigResolver<RR>>;
+  /** How several discovered sources become one value. */
+  readonly strategy: MergeStrategy<A>;
+  /** An optional caller-supplied check run after schema decoding. */
+  readonly validate?: (value: A) => Effect.Effect<A, ConfigValidationError>;
+  /**
+   * Where {@link ConfigFileShape.save} writes when given no explicit path.
+   *
+   * @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}.
+   */
+  readonly defaultPath?: Effect.Effect<string, never, RR>;
+  /**
+   * The opt-in event hook. Pass the `ConfigEvents` class itself.
+   *
+   * @remarks
+   * A **key**, not an instance: the service is looked up in the ambient context
+   * at call time with `Effect.serviceOption`, so it never enters the layer's
+   * `R`. When this is omitted, `emit` is `Effect.void` — it does not even
+   * perform the lookup. That is what "zero-cost when absent" means here.
+   */
+  readonly events?: Context.Key<ConfigEvents, ConfigEventsShape>;
+}
+/**
+ * Options for {@link ConfigFile.testLayer}.
+ *
+ * @remarks
+ * Deliberately has no `resolvers`: `testLayer` synthesizes one
+ * {@link (ConfigResolver:variable).staticDir} per seeded file, in `files`
+ * insertion order, so the first key wins under
+ * {@link (MergeStrategy:variable).firstMatch}.
+ *
+ * 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.
+ *
+ * @public
+ */
+interface ConfigFileTestOptions<A, I> {
+  /** The schema every seeded document is decoded through. */
+  readonly schema: Schema.Codec<A, I>;
+  /** How file content becomes an unknown document, and back. */
+  readonly codec: ConfigCodec;
+  /** How several discovered sources become one value. */
+  readonly strategy: MergeStrategy<A>;
+  /**
+   * Filenames (relative to the temp dir) mapped to their raw contents.
+   *
+   * @remarks
+   * A name may contain separators (`"nested/.apprc"`); the parent directory is
+   * created for you.
+   */
+  readonly files: Record<string, string>;
+  /** An optional caller-supplied check run after schema decoding. */
+  readonly validate?: (value: A) => Effect.Effect<A, ConfigValidationError>;
+}
+/**
+ * The config file service: a per-schema service factory and its layers.
+ *
+ * @public
+ */
+declare const ConfigFile: {
+  readonly Service: <Self, A>() => <const Id extends string>(id: Id) => Context.ServiceClass<Self, Id, ConfigFileShape<A>>;
+  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>;
+  readonly testLayer: <Self, A, I>(tag: Context.Key<Self, ConfigFileShape<A>>, options: ConfigFileTestOptions<A, I>) => Layer.Layer<Self, never, FileSystem.FileSystem | Path.Path>;
+};
+//#endregion
+//#region src/ConfigMigration.d.ts
+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;
+  /** The name of the step that failed; empty when reading the version failed. */
+  readonly name: Schema.String;
+  /** Which stage of a migration step failed. */
+  readonly phase: Schema.Literals<readonly ["read-version", "apply", "write-version"]>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that a versioned config migration failed.
+ *
+ * @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.
+ *
+ * @public
+ */
+declare class ConfigMigrationError extends ConfigMigrationError_base {
+  get message(): string;
+}
+/**
+ * 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.
+ *
+ * @public
+ */
+interface ConfigFileMigration {
+  readonly version: number;
+  readonly name: string;
+  /**
+   * Transforms the parsed config. Signal recoverable failure with `Effect.fail`;
+   * a synchronous `throw` is treated as a defect, not a `ConfigMigrationError`.
+   */
+  readonly up: (raw: unknown) => Effect.Effect<unknown, unknown>;
+}
+/** How the version number is read from and written to the parsed config. @public */
+interface VersionAccess {
+  readonly get: (raw: unknown) => Effect.Effect<number, unknown>;
+  readonly set: (raw: unknown, version: number) => Effect.Effect<unknown, unknown>;
+}
+/** Reads and writes a top-level `version` field. @public */
+declare const VersionAccess: {
+  readonly default: VersionAccess;
+};
+/** Options for {@link ConfigMigration.make}. @public */
+interface ConfigMigrationOptions {
+  readonly codec: ConfigCodec;
+  readonly migrations: ReadonlyArray<ConfigFileMigration>;
+  readonly versionAccess?: VersionAccess;
+}
+/** Versioned migration support for config codecs. @public */
+declare const ConfigMigration: {
+  readonly make: (options: ConfigMigrationOptions) => ConfigCodec<ConfigCodecError | ConfigMigrationError>;
+};
+//#endregion
+//#region src/ConfigProvider.d.ts
+/**
+ * Expose a loaded, merged, schema-validated document as a v4 `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
+ * 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.
+ * 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")`,
+ *    which is looked up as a single literal key and fails. No flattening happens
+ *    here, because none is needed.
+ * 3. **The decoded value is handed over as-is.** `fromUnknown` descends with
+ *    `Object.hasOwn`, and a `Schema.Class` instance carries its fields as own
+ *    properties, so no encoding step is required. The corollary: leaves are read
+ *    in their **decoded** form, and a field whose decoded type is not a JSON
+ *    primitive is exposed **structurally**, not turned into a value — with no
+ *    two decoded types exposed the same way. A `Date` has no own enumerable
+ *    properties, so it descends as an empty record and any nested read finds
+ *    nothing. Such a field reports the same `ConfigError` as a missing key —
+ *    `Expected string, got undefined` — so a `Config` read of a present `Date`
+ *    field looks exactly like a typo in the key name. An `Option.some`
+ *    descends as a record carrying Effect's internal `value` own-property, so
+ *    `Config.nested(Config.string("value"), "field")` happens to read the
+ *    wrapped value straight through — an internal representation, not a
+ *    supported spelling. An `Option.none` has no own keys and so reads as
+ *    absent, making `Some` and `None` asymmetric. None of this is a supported
+ *    way to read such a field: `load` is the API that was designed to carry it.
+ *
+ * Descent by own property is also why a prototype getter and `__proto__` are
+ * both unreachable through the returned provider.
+ *
+ * @example
+ * ```ts
+ * const fileProvider = yield* asConfigProvider(cfg);
+ * const provider = ConfigProvider.orElse(ConfigProvider.fromEnv(), fileProvider);
+ * ```
+ *
+ * @public
+ */
+declare const asConfigProvider: <A>(service: ConfigFileShape<A>) => Effect.Effect<ConfigProvider.ConfigProvider, ConfigLoadError>;
+/**
+ * Options for {@link layerConfigProvider}.
+ *
+ * @public
+ */
+interface LayerConfigProviderOptions {
+  /**
+   * Make the config file the primary source, consulted before the ambient
+   * provider rather than after it.
+   *
+   * @remarks
+   * Defaults to `false`, which is the precedence almost every application
+   * wants: an environment variable overrides the file it was deployed with.
+   */
+  readonly asPrimary?: boolean;
+}
+/**
+ * Install a loaded config document as a fallback beneath the **ambient**
+ * `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
+ * 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
+ * module composes beneath whichever provider is ambient rather than pinning
+ * that default itself, so verify the precedence you need with the provider
+ * you actually wire in.
+ *
+ * The load happens when the layer is built, and a {@link ConfigFileNotFoundError}
+ * surfaces in the layer's error channel rather than degrading to an empty
+ * provider — the same honesty {@link asConfigProvider} keeps.
+ *
+ * @example
+ * ```ts
+ * const stack = layerConfigProvider(AppConfig).pipe(Layer.provide(AppConfigLive));
+ * ```
+ *
+ * @public
+ */
+declare const layerConfigProvider: <Self, A>(tag: Context.Key<Self, ConfigFileShape<A>>, options?: LayerConfigProviderOptions) => Layer.Layer<never, ConfigLoadError, Self>;
+//#endregion
+//#region src/EncryptedCodec.d.ts
+declare const ConfigEncryptionError_base: Schema.Class<ConfigEncryptionError, Schema.TaggedStruct<"ConfigEncryptionError", {
+  /** Which cryptographic stage failed. */
+  readonly phase: Schema.Literals<readonly ["key-derivation", "encrypt", "decrypt", "encoding"]>;
+  /** The underlying failure, preserved structurally. */
+  readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Indicates that an encryption, decryption, key-derivation or base64 step
+ * 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.
+ *
+ * @public
+ */
+declare class ConfigEncryptionError extends ConfigEncryptionError_base {
+  get message(): string;
+}
+/**
+ * Key source union for {@link EncryptedCodec}.
+ *
+ * @remarks
+ * Use {@link (EncryptedCodecKey:variable).fromCryptoKey} to supply a pre-derived
+ * `CryptoKey`, or {@link (EncryptedCodecKey:variable).fromPassphrase} to derive
+ * one via PBKDF2 at first use.
+ *
+ * @public
+ */
+type EncryptedCodecKey = {
+  readonly _tag: "CryptoKey";
+  readonly key: Effect.Effect<CryptoKey, ConfigEncryptionError>;
+} | {
+  readonly _tag: "Passphrase";
+  readonly passphrase: string;
+  readonly salt: Uint8Array;
+};
+/**
+ * Convenience constructors for {@link (EncryptedCodecKey:type)}.
+ *
+ * @public
+ */
+declare const EncryptedCodecKey: {
+  /**
+   * Use a pre-derived `CryptoKey` effect directly.
+   *
+   * @remarks
+   * The effect is resolved once per codec instance and its **success** is
+   * reused for every encrypt/decrypt operation. A failure or an interruption
+   * is not cached — the next operation resolves it again. Supply your own
+   * `Effect.retry` inside this effect to bound retries; wrap it in
+   * `Effect.cached` yourself if you want a failure to be terminal.
+   *
+   * A `throw` from it is a programmer bug and stays a defect; signal
+   * recoverable failure with `Effect.fail`.
+   */
+  readonly fromCryptoKey: (key: Effect.Effect<CryptoKey, ConfigEncryptionError>) => EncryptedCodecKey;
+  /**
+   * Derive a `CryptoKey` from a passphrase and salt via PBKDF2.
+   *
+   * @remarks
+   * Derivation runs lazily on the first encrypt/decrypt call. It is resolved
+   * once per codec instance and its **success** is reused for subsequent
+   * operations on that instance. A failure or an interruption is not cached —
+   * the next operation derives again.
+   */
+  readonly fromPassphrase: (passphrase: string, salt: Uint8Array) => EncryptedCodecKey;
+};
+/**
+ * Wrap any {@link (ConfigCodec:interface)} with AES-GCM encryption.
+ *
+ * @remarks
+ * `stringify` serializes with the inner codec, generates a random 12-byte IV,
+ * encrypts, prepends the IV to the ciphertext and base64-encodes the result.
+ * `parse` reverses that: the first 12 bytes of the decoded envelope are the IV,
+ * the remainder is the ciphertext, and the plaintext is handed to the inner
+ * codec's `parse`.
+ *
+ * The error channel **widens** to `E | ConfigEncryptionError` rather than
+ * flattening — the inner codec's failures stay distinguishable from
+ * cryptographic ones.
+ *
+ * @public
+ */
+declare function EncryptedCodec<E>(inner: ConfigCodec<E>, keySource: EncryptedCodecKey): ConfigCodec<E | ConfigEncryptionError>;
+//#endregion
+//#region src/JsonCodec.d.ts
+/**
+ * A `ConfigCodec` backed by the host `JSON` global: plain JSON as
+ * configuration file content.
+ *
+ * @remarks
+ * The only codec that reaches no parsing engine at all — it is why this
+ * package can be depended on for JSON config alone without pulling a parser
+ * into the bundle. Both directions preserve the underlying failure
+ * structurally in `cause` — never stringified.
+ *
+ * @public
+ */
+declare const JsonCodec: ConfigCodec;
+//#endregion
+//#region src/JsoncCodec.d.ts
+/**
+ * A `ConfigCodec` backed by `@effected/jsonc`: JSON with comments and
+ * trailing commas.
+ *
+ * @remarks
+ * `@effected/jsonc` does not expose a `stringify` — its schema layer's encode
+ * direction is `JSON.stringify` (comments never survive a round-trip encode;
+ * see `Jsonc.fromString`'s remarks), so `stringify` here calls `JSON.stringify`
+ * directly and wraps a thrown defect the same way `JsonCodec` does.
+ * Both directions preserve the underlying failure structurally in `cause` —
+ * never stringified.
+ *
+ * @public
+ */
+declare const JsoncCodec: ConfigCodec;
+//#endregion
+//#region src/TomlCodec.d.ts
+/**
+ * A `ConfigCodec` backed by `@effected/toml`.
+ *
+ * @remarks
+ * `@effected/toml`'s input hardening — a nesting-depth cap on arrays and
+ * inline tables, enforced independently on both the parse and stringify
+ * sides — fails through the typed error channel, so a hostile config file
+ * surfaces as a `ConfigCodecError` rather than crashing the process. Both
+ * directions preserve the underlying failure structurally in `cause` —
+ * never stringified.
+ *
+ * Stringify is genuinely fallible beyond hostile input: TOML has no null,
+ * so a document carrying `null` (or any other unrepresentable value, an
+ * out-of-int64-range `bigint`, a circular reference) fails with a
+ * `ConfigCodecError` whose `cause` is the structured `TomlStringifyError`.
+ *
+ * @public
+ */
+declare const TomlCodec: ConfigCodec;
+//#endregion
+//#region src/YamlCodec.d.ts
+/**
+ * A `ConfigCodec` backed by `@effected/yaml`.
+ *
+ * @remarks
+ * `@effected/yaml`'s input hardening — an alias-expansion budget guarding
+ * against "billion laughs" alias bombs, and a collection-nesting depth cap —
+ * fails through the typed error channel, so a hostile config file surfaces
+ * as a `ConfigCodecError` rather than crashing the process. Both directions
+ * preserve the underlying failure structurally in `cause` — never
+ * stringified.
+ *
+ * @public
+ */
+declare const YamlCodec: ConfigCodec;
+//#endregion
+export { type ConfigCodec, ConfigCodecError, ConfigDefaultPathMissingError, ConfigEncryptionError, ConfigEvent, ConfigEventPayload, ConfigEvents, type ConfigEventsShape, ConfigFile, type ConfigFileMigration, ConfigFileNotFoundError, type ConfigFileOptions, ConfigFileReadError, type ConfigFileShape, type ConfigFileTestOptions, ConfigFileWriteError, type ConfigLoadError, ConfigMigration, ConfigMigrationError, type ConfigMigrationOptions, type ConfigReadError, ConfigResolver, type ConfigSaveError, type ConfigSource, ConfigSourceRef, type ConfigUpdateError, ConfigValidationError, type ConfigWriteError, EncryptedCodec, EncryptedCodecKey, JsonCodec, JsoncCodec, type LayerConfigProviderOptions, MergeStrategy, type NonEmptySources, TomlCodec, VersionAccess, YamlCodec, asConfigProvider, layerConfigProvider };
+//# sourceMappingURL=index.d.ts.map