effect 4.0.0-beta.99 → 4.0.0-rc.108

package/dist/Config.d.ts

@@ -7,7 +7,7 @@
  *
  * @since 4.0.0
  */
-import type { Path, SourceError } from "./ConfigProvider.ts";
+import type { SourceError } from "./ConfigProvider.ts";
 import * as ConfigProvider from "./ConfigProvider.ts";
 import * as Effect from "./Effect.ts";
 import * as LogLevel_ from "./LogLevel.ts";
@@ -25,11 +25,11 @@ declare const TypeId = "~effect/Config";
  *
  * **Example** (Checking Config values)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config } from "effect"
  *
- * console.log(Config.isConfig(Config.string("HOST"))) // true
- * console.log(Config.isConfig("not a config"))        // false
+ * Config.isConfig(Config.string("HOST")) // => true
+ * Config.isConfig("not a config") // => false
  * ```
  *
  * @category guards
@@ -51,7 +51,7 @@ export declare const isConfig: (u: unknown) => u is Config<unknown>;
  *   (wrong type, out of range, missing key, etc.).
  *
  * @see {@link orElse} – recover from a ConfigError
- * @see {@link withDefault} – provide a fallback for missing-data errors
+ * @see {@link withDefault} – provide a fallback when relevant input is absent
  *
  * @category errors
  * @since 4.0.0
@@ -75,9 +75,7 @@ export declare class ConfigError {
  * **Details**
  *
  * Key members:
- * - `parse(provider, pathPrefix?)` – runs the config against a specific provider.
- *   The optional path prefix is the logical scope accumulated from outer
- *   `Config.nested` calls.
+ * - `parse(provider)` – runs the config against a specific provider.
  * - Yieldable – can be yielded inside `Effect.gen`, which automatically
  *   resolves the current `ConfigProvider` from the context.
  * - Pipeable – supports `.pipe(Config.map(...))` etc.
@@ -89,7 +87,7 @@ export declare class ConfigError {
  */
 export interface Config<out T> extends Effect.Effect<T, ConfigError> {
     readonly [TypeId]: typeof TypeId;
-    readonly parse: (provider: ConfigProvider.ConfigProvider, pathPrefix?: Path) => Effect.Effect<T, ConfigError>;
+    readonly parse: (provider: ConfigProvider.ConfigProvider) => Effect.Effect<T, ConfigError>;
 }
 /**
  * Transforms the parsed value of a config with a pure function.
@@ -101,7 +99,7 @@ export interface Config<out T> extends Effect.Effect<T, ConfigError> {
  *
  * **Example** (Uppercasing a string config)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const upper = Config.string("name").pipe(
@@ -109,7 +107,7 @@ export interface Config<out T> extends Effect.Effect<T, ConfigError> {
  * )
  *
  * const provider = ConfigProvider.fromUnknown({ name: "alice" })
- * // Effect.runSync(upper.parse(provider)) // "ALICE"
+ * Effect.runSync(upper.parse(provider)) // => "ALICE"
  * ```
  *
  * @see {@link mapOrFail} – when the transformation can fail
@@ -128,7 +126,7 @@ export declare const map: {
      *
      * **Example** (Uppercasing a string config)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const upper = Config.string("name").pipe(
@@ -136,7 +134,7 @@ export declare const map: {
      * )
      *
      * const provider = ConfigProvider.fromUnknown({ name: "alice" })
-     * // Effect.runSync(upper.parse(provider)) // "ALICE"
+     * Effect.runSync(upper.parse(provider)) // => "ALICE"
      * ```
      *
      * @see {@link mapOrFail} – when the transformation can fail
@@ -155,7 +153,7 @@ export declare const map: {
      *
      * **Example** (Uppercasing a string config)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const upper = Config.string("name").pipe(
@@ -163,7 +161,7 @@ export declare const map: {
      * )
      *
      * const provider = ConfigProvider.fromUnknown({ name: "alice" })
-     * // Effect.runSync(upper.parse(provider)) // "ALICE"
+     * Effect.runSync(upper.parse(provider)) // => "ALICE"
      * ```
      *
      * @see {@link mapOrFail} – when the transformation can fail
@@ -183,12 +181,14 @@ export declare const map: {
  *
  * **Example** (Wrapping a value in an effectful transformation)
  *
- * ```ts
- * import { Config, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const trimmed = Config.string("name").pipe(
  *   Config.mapOrFail((s) => Effect.succeed(s.trim()))
  * )
+ * const provider = ConfigProvider.fromUnknown({ name: " Alice " })
+ * Effect.runSync(trimmed.parse(provider)) // => "Alice"
  * ```
  *
  * @see {@link map} – when the transformation cannot fail
@@ -207,12 +207,14 @@ export declare const mapOrFail: {
      *
      * **Example** (Wrapping a value in an effectful transformation)
      *
-     * ```ts
-     * import { Config, Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const trimmed = Config.string("name").pipe(
      *   Config.mapOrFail((s) => Effect.succeed(s.trim()))
      * )
+     * const provider = ConfigProvider.fromUnknown({ name: " Alice " })
+     * Effect.runSync(trimmed.parse(provider)) // => "Alice"
      * ```
      *
      * @see {@link map} – when the transformation cannot fail
@@ -231,12 +233,14 @@ export declare const mapOrFail: {
      *
      * **Example** (Wrapping a value in an effectful transformation)
      *
-     * ```ts
-     * import { Config, Effect } from "effect"
+     * ```ts import.meta.vitest
+     * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const trimmed = Config.string("name").pipe(
      *   Config.mapOrFail((s) => Effect.succeed(s.trim()))
      * )
+     * const provider = ConfigProvider.fromUnknown({ name: " Alice " })
+     * Effect.runSync(trimmed.parse(provider)) // => "Alice"
      * ```
      *
      * @see {@link map} – when the transformation cannot fail
@@ -256,21 +260,30 @@ export declare const mapOrFail: {
  *
  * **Details**
  *
- * Unlike {@link withDefault}, this catches **all** `ConfigError`s (not just
- * missing data). The fallback function receives the error and returns a new
+ * Unlike {@link withDefault}, this handles both semantic absence and **all**
+ * `ConfigError`s. The fallback function receives the error and returns a new
  * `Config`.
  *
+ * **Gotchas**
+ *
+ * Recovery preserves whether the primary config read provider input. When the
+ * recovered config is composed with {@link all}, invalid input in the primary
+ * branch still makes the enclosing group partially supplied, so an outer
+ * {@link withDefault} or {@link option} does not replace the whole group.
+ *
  * **Example** (Falling back to a literal)
  *
- * ```ts
- * import { Config } from "effect"
+ * ```ts import.meta.vitest
+ * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const hostConfig = Config.string("HOST").pipe(
  *   Config.orElse(() => Config.succeed("localhost"))
  * )
+ * const provider = ConfigProvider.fromUnknown({})
+ * Effect.runSync(hostConfig.parse(provider)) // => "localhost"
  * ```
  *
- * @see {@link withDefault} – fallback only on missing data
+ * @see {@link withDefault} – fallback only on semantic absence
  *
  * @category combinators
  * @since 2.0.0
@@ -286,21 +299,30 @@ export declare const orElse: {
      *
      * **Details**
      *
-     * Unlike {@link withDefault}, this catches **all** `ConfigError`s (not just
-     * missing data). The fallback function receives the error and returns a new
+     * Unlike {@link withDefault}, this handles both semantic absence and **all**
+     * `ConfigError`s. The fallback function receives the error and returns a new
      * `Config`.
      *
+     * **Gotchas**
+     *
+     * Recovery preserves whether the primary config read provider input. When the
+     * recovered config is composed with {@link all}, invalid input in the primary
+     * branch still makes the enclosing group partially supplied, so an outer
+     * {@link withDefault} or {@link option} does not replace the whole group.
+     *
      * **Example** (Falling back to a literal)
      *
-     * ```ts
-     * import { Config } from "effect"
+     * ```ts import.meta.vitest
+     * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const hostConfig = Config.string("HOST").pipe(
      *   Config.orElse(() => Config.succeed("localhost"))
      * )
+     * const provider = ConfigProvider.fromUnknown({})
+     * Effect.runSync(hostConfig.parse(provider)) // => "localhost"
      * ```
      *
-     * @see {@link withDefault} – fallback only on missing data
+     * @see {@link withDefault} – fallback only on semantic absence
      *
      * @category combinators
      * @since 2.0.0
@@ -316,21 +338,30 @@ export declare const orElse: {
      *
      * **Details**
      *
-     * Unlike {@link withDefault}, this catches **all** `ConfigError`s (not just
-     * missing data). The fallback function receives the error and returns a new
+     * Unlike {@link withDefault}, this handles both semantic absence and **all**
+     * `ConfigError`s. The fallback function receives the error and returns a new
      * `Config`.
      *
+     * **Gotchas**
+     *
+     * Recovery preserves whether the primary config read provider input. When the
+     * recovered config is composed with {@link all}, invalid input in the primary
+     * branch still makes the enclosing group partially supplied, so an outer
+     * {@link withDefault} or {@link option} does not replace the whole group.
+     *
      * **Example** (Falling back to a literal)
      *
-     * ```ts
-     * import { Config } from "effect"
+     * ```ts import.meta.vitest
+     * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const hostConfig = Config.string("HOST").pipe(
      *   Config.orElse(() => Config.succeed("localhost"))
      * )
+     * const provider = ConfigProvider.fromUnknown({})
+     * Effect.runSync(hostConfig.parse(provider)) // => "localhost"
      * ```
      *
-     * @see {@link withDefault} – fallback only on missing data
+     * @see {@link withDefault} – fallback only on semantic absence
      *
      * @category combinators
      * @since 2.0.0
@@ -349,9 +380,19 @@ export declare const orElse: {
  * Accepts a tuple (preserves positions), an iterable, or a record of configs.
  * Returns a config whose parsed value mirrors the input shape.
  *
+ * A combined config is absent when at least one child cannot resolve and none
+ * of the other children read provider input. This lets {@link withDefault} and
+ * {@link option} handle a wholly absent group. Once any child reads input, a
+ * missing sibling makes the group incomplete and parsing fails. Values supplied
+ * by child defaults do not count as provider input.
+ *
+ * Unlike a `Schema.Struct` passed to {@link schema}, `all` only considers input
+ * read by its children. An explicitly present but empty parent container does
+ * not by itself make the group present.
+ *
  * **Example** (Combining configs as a struct)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const dbConfig = Config.all({
@@ -360,8 +401,7 @@ export declare const orElse: {
  * })
  *
  * const provider = ConfigProvider.fromUnknown({ host: "localhost", port: 5432 })
- * // Effect.runSync(dbConfig.parse(provider))
- * // { host: "localhost", port: 5432 }
+ * Effect.runSync(dbConfig.parse(provider)) // => { host: "localhost", port: 5432 }
  * ```
  *
  * @category combinators
@@ -375,7 +415,8 @@ export declare function all<const Arg extends Iterable<Config<any>> | Record<str
     -readonly [K in keyof Arg]: [Arg[K]] extends [Config<infer A>] ? A : never;
 } : never>;
 /**
- * Provides a fallback value when the config fails due to missing data.
+ * Provides a fallback value when the config cannot resolve because none of its
+ * relevant input is present.
  *
  * **When to use**
  *
@@ -383,30 +424,33 @@ export declare function all<const Arg extends Iterable<Config<any>> | Record<str
  *
  * **Gotchas**
  *
- * Only applies when the error is a `SchemaError` caused exclusively by
- * missing data (missing keys, undefined values). Validation errors (wrong
- * type, out of range) still propagate.
+ * Validation errors and partially supplied groups still propagate. A schema
+ * that successfully decodes absent input also keeps its decoded value instead
+ * of using the default. Schema configs first represent a missing or
+ * incompatible provider shape as `undefined`; the default is used only when
+ * the schema rejects that value and no relevant input was found.
  *
  * **Example** (Defaulting a missing port)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const port = Config.number("port").pipe(Config.withDefault(3000))
  *
  * const provider = ConfigProvider.fromUnknown({})
- * // Effect.runSync(port.parse(provider)) // 3000
+ * Effect.runSync(port.parse(provider)) // => 3000
  * ```
  *
  * @see {@link option} – returns `Option` instead of a default value
- * @see {@link orElse} – catches all errors, not just missing data
+ * @see {@link orElse} – catches all errors, not just absent input
  *
  * @category combinators
  * @since 2.0.0
  */
 export declare const withDefault: {
     /**
-     * Provides a fallback value when the config fails due to missing data.
+     * Provides a fallback value when the config cannot resolve because none of its
+     * relevant input is present.
      *
      * **When to use**
      *
@@ -414,30 +458,33 @@ export declare const withDefault: {
      *
      * **Gotchas**
      *
-     * Only applies when the error is a `SchemaError` caused exclusively by
-     * missing data (missing keys, undefined values). Validation errors (wrong
-     * type, out of range) still propagate.
+     * Validation errors and partially supplied groups still propagate. A schema
+     * that successfully decodes absent input also keeps its decoded value instead
+     * of using the default. Schema configs first represent a missing or
+     * incompatible provider shape as `undefined`; the default is used only when
+     * the schema rejects that value and no relevant input was found.
      *
      * **Example** (Defaulting a missing port)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const port = Config.number("port").pipe(Config.withDefault(3000))
      *
      * const provider = ConfigProvider.fromUnknown({})
-     * // Effect.runSync(port.parse(provider)) // 3000
+     * Effect.runSync(port.parse(provider)) // => 3000
      * ```
      *
      * @see {@link option} – returns `Option` instead of a default value
-     * @see {@link orElse} – catches all errors, not just missing data
+     * @see {@link orElse} – catches all errors, not just absent input
      *
      * @category combinators
      * @since 2.0.0
      */
     <const A2>(defaultValue: A2): <A>(self: Config<A>) => Config<A2 | A>;
     /**
-     * Provides a fallback value when the config fails due to missing data.
+     * Provides a fallback value when the config cannot resolve because none of its
+     * relevant input is present.
      *
      * **When to use**
      *
@@ -445,23 +492,25 @@ export declare const withDefault: {
      *
      * **Gotchas**
      *
-     * Only applies when the error is a `SchemaError` caused exclusively by
-     * missing data (missing keys, undefined values). Validation errors (wrong
-     * type, out of range) still propagate.
+     * Validation errors and partially supplied groups still propagate. A schema
+     * that successfully decodes absent input also keeps its decoded value instead
+     * of using the default. Schema configs first represent a missing or
+     * incompatible provider shape as `undefined`; the default is used only when
+     * the schema rejects that value and no relevant input was found.
      *
      * **Example** (Defaulting a missing port)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const port = Config.number("port").pipe(Config.withDefault(3000))
      *
      * const provider = ConfigProvider.fromUnknown({})
-     * // Effect.runSync(port.parse(provider)) // 3000
+     * Effect.runSync(port.parse(provider)) // => 3000
      * ```
      *
      * @see {@link option} – returns `Option` instead of a default value
-     * @see {@link orElse} – catches all errors, not just missing data
+     * @see {@link orElse} – catches all errors, not just absent input
      *
      * @category combinators
      * @since 2.0.0
@@ -469,8 +518,8 @@ export declare const withDefault: {
     <A, const A2>(self: Config<A>, defaultValue: A2): Config<A | A2>;
 };
 /**
- * Makes a config optional: returns `Some(value)` on success and `None` when
- * data is missing.
+ * Makes a config optional: returns `Some(value)` on success and `None` when the
+ * config cannot resolve because none of its relevant input is present.
  *
  * **When to use**
  *
@@ -478,18 +527,21 @@ export declare const withDefault: {
  *
  * **Gotchas**
  *
- * Like {@link withDefault}, only missing-data errors produce `None`.
- * Validation errors still propagate.
+ * Validation errors and partially supplied groups still propagate. Successful
+ * values are always wrapped in `Some`, including `undefined` when the schema
+ * explicitly accepts it. Schema configs first represent a missing or
+ * incompatible provider shape as `undefined`; `None` is returned only when the
+ * schema rejects that value and no relevant input was found.
  *
  * **Example** (Reading optional config)
  *
- * ```ts
- * import { Config, ConfigProvider, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Config, ConfigProvider, Effect, Option } from "effect"
  *
  * const maybePort = Config.option(Config.number("port"))
  *
  * const provider = ConfigProvider.fromUnknown({})
- * // Effect.runSync(maybePort.parse(provider)) // { _tag: "None" }
+ * Effect.runSync(maybePort.parse(provider)) // => Option.none()
  * ```
  *
  * @see {@link withDefault} – provide a concrete fallback value instead
@@ -528,7 +580,7 @@ export type Success<T> = [T] extends [Config<infer A>] ? A : never;
  *
  * @see {@link unwrap} – construct a `Config` from a `Wrap<T>`
  *
- * @category Wrap
+ * @category utility types
  * @since 2.0.0
  */
 export type Wrap<A> = [NonNullable<A>] extends [infer T] ? [IsPlainObject<T>] extends [true] ? {
@@ -550,8 +602,8 @@ type IsPlainObject<A> = [A] extends [Record<string, any>] ? [keyof A] extends [n
  *
  * **Example** (Unwrapping a record of configs)
  *
- * ```ts
- * import { Config } from "effect"
+ * ```ts import.meta.vitest
+ * import { Config, ConfigProvider, Effect } from "effect"
  *
  * interface Options {
  *   key: string
@@ -559,11 +611,15 @@ type IsPlainObject<A> = [A] extends [Record<string, any>] ? [keyof A] extends [n
  *
  * const makeConfig = (config: Config.Wrap<Options>): Config.Config<Options> =>
  *   Config.unwrap(config)
+ *
+ * const config = makeConfig({ key: Config.string("key") })
+ * const provider = ConfigProvider.fromUnknown({ key: "value" })
+ * Effect.runSync(config.parse(provider)) // => { key: "value" }
  * ```
  *
  * @see {@link Wrap} – the utility type accepted by this function
  *
- * @category Wrap
+ * @category converting
  * @since 2.0.0
  */
 export declare const unwrap: <T>(wrapped: Wrap<T>) => Config<T>;
@@ -584,12 +640,47 @@ export declare const unwrap: <T>(wrapped: Wrap<T>) => Config<T>;
  * Convenience constructors such as `string`, `number`, and `boolean` delegate
  * to this API.
  *
- * The codec is used to decode the raw `StringTree` produced by the provider
- * into `T`. Schema validation errors are wrapped in `ConfigError`.
+ * The codec is converted to its canonical `StringTree` form. Its encoded shape
+ * determines how provider data is loaded: scalar schemas read a co-located
+ * scalar value, object schemas read declared properties and matching record
+ * keys, and array schemas read indexed children. A mixed-shape union loads each
+ * member according to that member's shape before applying the union's mode and
+ * checks.
+ *
+ * At the config's lookup path, a missing node or a node that cannot provide the
+ * representation required by the schema is decoded as `undefined`. Missing
+ * object properties remain omitted so the schema's property semantics still
+ * apply. Decoding success always wins, even when no provider input was found.
+ * For example,
+ * `Schema.UndefinedOr(Schema.String)` decodes to `undefined` and is not replaced
+ * by {@link withDefault}. If decoding fails and no relevant representation was
+ * found, the config is absent. Invalid data in a relevant representation is a
+ * validation failure. Provider `SourceError`s are always failures.
+ *
+ * **Gotchas**
+ *
+ * Plain `Schema.Array` and `Schema.Record` schemas use structural provider
+ * input. Use {@link Array} or {@link Record} when a flat separated string must
+ * also be accepted.
+ *
+ * `Schema.Struct` and {@link all} describe different lookup models. An
+ * explicitly present empty object is relevant input for a struct and required
+ * fields are validated. The same empty parent container does not make an
+ * `all` group present when all of its child configs are absent.
+ *
+ * The canonical `StringTree` encoding must expose a concrete scalar, object,
+ * array, or union shape. Opaque encodings such as `Schema.Any`,
+ * `Schema.Unknown`, `Schema.ObjectKeyword`, `Schema.Json`, and
+ * `Schema.MutableJson` are rejected synchronously when this config is
+ * constructed, including when they are nested in another schema. Suspended
+ * recursive schemas remain supported when their eventual shape is concrete.
+ * Declarations such as `Schema.URL` also remain supported when their canonical
+ * encoding has a concrete shape. To read arbitrary JSON from one scalar value,
+ * use `Schema.fromJsonString(Schema.Json)`.
  *
  * **Example** (Reading a structured config)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect, Schema } from "effect"
  *
  * const DbConfig = Config.schema(
@@ -604,8 +695,7 @@ export declare const unwrap: <T>(wrapped: Wrap<T>) => Config<T>;
  *   db: { host: "localhost", port: 5432 }
  * })
  *
- * // Effect.runSync(DbConfig.parse(provider))
- * // { host: "localhost", port: 5432 }
+ * Effect.runSync(DbConfig.parse(provider)) // => { host: "localhost", port: 5432 }
  * ```
  *
  * @see {@link string} / {@link number} / {@link boolean} – shortcuts for
@@ -684,7 +774,7 @@ export declare const LogLevel: Schema.Literals<readonly LogLevel_.LogLevel[]>;
  *
  * **Example** (Parsing a comma-separated record)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect, Schema } from "effect"
  *
  * const schema = Config.Record(Schema.String, Schema.String)
@@ -697,28 +787,24 @@ export declare const LogLevel: Schema.Literals<readonly LogLevel_.LogLevel[]>;
  *   }
  * })
  *
- * console.dir(Effect.runSync(config.parse(provider)))
- * // {
- * //   'service.name': 'my-service',
- * //   'service.version': '1.0.0',
- * //   'custom.attribute': 'value'
- * // }
+ * const result = Effect.runSync(config.parse(provider))
+ * result["service.name"] // => "my-service"
+ * result["service.version"] // => "1.0.0"
+ * result["custom.attribute"] // => "value"
  * ```
  *
+ * @see {@link Array} for separated or structural array input
+ *
  * @category schemas
  * @since 4.0.0
  */
 export declare const Record: <K extends Schema.Record.Key, V extends Schema.Constraint>(key: K, value: V, options?: {
     readonly separator?: string | undefined;
     readonly keyValueSeparator?: string | undefined;
-}) => Schema.Union<readonly [Schema.$Record<K, V>, Schema.compose<Schema.$Record<K, V>, Schema.decodeTo<Schema.$Record<Schema.String, Schema.String>, Schema.String, never, never>>]>;
-/**
- * @category schemas
- * @since 4.0.0
- */
+}) => Schema.Union<readonly [Schema.$Record<K, V>, Schema.decodeTo<Schema.toCodecStringTree<Schema.$Record<K, V>>, Schema.String, never, never>]>;
 declare const ArrayConfig: <V extends Schema.Constraint>(value: V, options?: {
     readonly separator?: string | undefined;
-}) => Schema.Union<readonly [Schema.compose<Schema.$Array<V>, Schema.decodeTo<Schema.$Array<Schema.String>, Schema.String, never, never>>, Schema.$Array<V>]>;
+}) => Schema.Union<readonly [Schema.decodeTo<Schema.toCodecStringTree<Schema.$Array<V>>, Schema.String, never, never>, Schema.$Array<V>]>;
 export { 
 /**
  * Schema for array types that can also be parsed from a flat separated string.
@@ -733,6 +819,8 @@ export {
  * Accepts either a JSON-like array from the provider or a flat string like
  * `"a,b,c"`. The `separator` defaults to `","` and can be customized.
  *
+ * @see {@link Record} for separated or structural record input
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -748,7 +836,7 @@ ArrayConfig as Array };
  * @category constructors
  * @since 2.0.0
  */
-export declare function fail(err: SourceError | Schema.SchemaError): Config<never>;
+export declare function fail(err: SourceError | Schema.SchemaError): Config<unknown>;
 /**
  * Creates a config that always succeeds with the given value, ignoring the
  * provider entirely.
@@ -760,12 +848,14 @@ export declare function fail(err: SourceError | Schema.SchemaError): Config<neve
  *
  * **Example** (Returning a constant fallback)
  *
- * ```ts
- * import { Config } from "effect"
+ * ```ts import.meta.vitest
+ * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const host = Config.string("HOST").pipe(
  *   Config.orElse(() => Config.succeed("localhost"))
  * )
+ * const provider = ConfigProvider.fromUnknown({})
+ * Effect.runSync(host.parse(provider)) // => "localhost"
  * ```
  *
  * @category constructors
@@ -785,13 +875,13 @@ export declare function succeed<T>(value: T): Config<T>;
  *
  * **Example** (Reading a string config)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const host = Config.string("HOST")
  *
  * const provider = ConfigProvider.fromUnknown({ HOST: "localhost" })
- * // Effect.runSync(host.parse(provider)) // "localhost"
+ * Effect.runSync(host.parse(provider)) // => "localhost"
  * ```
  *
  * @see {@link nonEmptyString} – rejects empty strings
@@ -887,10 +977,12 @@ export declare function int(name?: string): Config<number>;
  *
  * **Example** (Restricting to a literal)
  *
- * ```ts
- * import { Config } from "effect"
+ * ```ts import.meta.vitest
+ * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const env = Config.literal("production", "ENV")
+ * const provider = ConfigProvider.fromUnknown({ ENV: "production" })
+ * Effect.runSync(env.parse(provider)) // => "production"
  * ```
  *
  * @see {@link literals} – accepts multiple literal values
@@ -911,10 +1003,12 @@ export declare function literal<L extends SchemaAST.LiteralValue>(literal: L, na
  *
  * **Example** (Restricting to a set of literals)
  *
- * ```ts
- * import { Config } from "effect"
+ * ```ts import.meta.vitest
+ * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const env = Config.literals(["development", "production"], "ENV")
+ * const provider = ConfigProvider.fromUnknown({ ENV: "development" })
+ * Effect.runSync(env.parse(provider)) // => "development"
  * ```
  *
  * @see {@link literal} for accepting one specific literal value
@@ -940,13 +1034,10 @@ export declare function literals<const L extends ReadonlyArray<SchemaAST.Literal
  *
  * **Example** (Reading a boolean flag)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   const flag = yield* Config.boolean("FEATURE_FLAG")
- *   console.log(flag)
- * })
+ * const program = Config.boolean("FEATURE_FLAG")
  *
  * const provider = ConfigProvider.fromEnv({
  *   env: {
@@ -956,8 +1047,7 @@ export declare function literals<const L extends ReadonlyArray<SchemaAST.Literal
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output: true
+ * ) // => true
  * ```
  *
  * @see {@link Boolean} for the underlying boolean codec
@@ -983,13 +1073,10 @@ export declare function boolean(name?: string): Config<boolean>;
  *
  * **Example** (Reading a duration)
  *
- * ```ts
- * import { Config, ConfigProvider, Effect } from "effect"
+ * ```ts import.meta.vitest
+ * import { Config, ConfigProvider, Duration, Effect } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   const duration = yield* Config.duration("DURATION")
- *   console.log(duration)
- * })
+ * const program = Config.duration("DURATION").pipe(Effect.map(Duration.toMillis))
  *
  * const provider = ConfigProvider.fromEnv({
  *   env: {
@@ -999,8 +1086,7 @@ export declare function boolean(name?: string): Config<boolean>;
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output: Duration { _tag: "millis", value: 10000 }
+ * ) // => 10000
  * ```
  *
  * @see {@link schema} for decoding configuration values with a custom codec
@@ -1022,13 +1108,10 @@ export declare function duration(name?: string): Config<import("./Duration.ts").
  *
  * **Example** (Reading a port)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   const port = yield* Config.port("PORT")
- *   console.log(port)
- * })
+ * const program = Config.port("PORT")
  *
  * const provider = ConfigProvider.fromEnv({
  *   env: {
@@ -1038,8 +1121,7 @@ export declare function duration(name?: string): Config<import("./Duration.ts").
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output: 8080
+ * ) // => 8080
  * ```
  *
  * @see {@link int} for integer config values outside the port range
@@ -1065,13 +1147,10 @@ export declare function port(name?: string): Config<number>;
  *
  * **Example** (Reading a log level)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   const logLevel = yield* Config.logLevel("LOG_LEVEL")
- *   console.log(logLevel)
- * })
+ * const program = Config.logLevel("LOG_LEVEL")
  *
  * const provider = ConfigProvider.fromEnv({
  *   env: {
@@ -1081,8 +1160,7 @@ export declare function port(name?: string): Config<number>;
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output: "Info"
+ * ) // => "Info"
  * ```
  *
  * @see {@link LogLevel} for the underlying log-level codec
@@ -1106,13 +1184,10 @@ export declare function logLevel(name?: string): Config<LogLevel_.LogLevel>;
  *
  * **Example** (Reading a secret)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   const apiKey = yield* Config.redacted("API_KEY")
- *   console.log(apiKey)
- * })
+ * const program = Config.redacted("API_KEY").pipe(Effect.map(String))
  *
  * const provider = ConfigProvider.fromEnv({
  *   env: {
@@ -1122,8 +1197,7 @@ export declare function logLevel(name?: string): Config<LogLevel_.LogLevel>;
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output: <redacted>
+ * ) // => "<redacted>"
  * ```
  *
  * @see {@link string} for non-secret string settings
@@ -1149,13 +1223,10 @@ export declare function redacted(name?: string): Config<import("./Redacted.ts").
  *
  * **Example** (Reading a URL)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
- * const program = Effect.gen(function*() {
- *   const url = yield* Config.url("URL")
- *   console.log(url)
- * })
+ * const program = Config.url("URL").pipe(Effect.map((url) => url.href))
  *
  * const provider = ConfigProvider.fromEnv({
  *   env: {
@@ -1165,22 +1236,7 @@ export declare function redacted(name?: string): Config<import("./Redacted.ts").
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output:
- * // URL {
- * //   href: 'https://example.com/',
- * //   origin: 'https://example.com',
- * //   protocol: 'https:',
- * //   username: '',
- * //   password: '',
- * //   host: 'example.com',
- * //   hostname: 'example.com',
- * //   port: '',
- * //   pathname: '/',
- * //   search: '',
- * //   searchParams: URLSearchParams {},
- * //   hash: ''
- * // }
+ * ) // => "https://example.com/"
  * ```
  *
  * @see {@link schema} for decoding configuration values with a custom codec
@@ -1198,7 +1254,7 @@ export declare function url(name?: string): Config<URL>;
  *
  * **Details**
  *
- * Shortcut for `Config.schema(Schema.DateValid, name)`.
+ * Shortcut for `Config.schema(Schema.Date, name)`.
  *
  * **Gotchas**
  *
@@ -1206,14 +1262,13 @@ export declare function url(name?: string): Config<URL>;
  *
  * **Example** (Reading a date)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const createdAt = Config.date("CREATED_AT")
  *
  * const provider = ConfigProvider.fromUnknown({ CREATED_AT: "2024-01-15" })
- * // Effect.runSync(createdAt.parse(provider))
- * // Date("2024-01-15T00:00:00.000Z")
+ * Effect.runSync(createdAt.parse(provider)).toISOString() // => "2024-01-15T00:00:00.000Z"
  * ```
  *
  * @category constructors
@@ -1238,7 +1293,7 @@ export declare function date(name?: string): Config<Date>;
  *
  * **Example** (Nesting a struct config under `"database"`)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const dbConfig = Config.all({
@@ -1249,13 +1304,12 @@ export declare function date(name?: string): Config<Date>;
  * const provider = ConfigProvider.fromUnknown({
  *   database: { host: "localhost", port: "5432" }
  * })
- * // Effect.runSync(dbConfig.parse(provider))
- * // { host: "localhost", port: 5432 }
+ * Effect.runSync(dbConfig.parse(provider)) // => { host: "localhost", port: 5432 }
  * ```
  *
  * **Example** (Reading env vars with a nested prefix)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const host = Config.string("host").pipe(Config.nested("database"))
@@ -1263,7 +1317,7 @@ export declare function date(name?: string): Config<Date>;
  * const provider = ConfigProvider.fromEnv({
  *   env: { database_host: "localhost" }
  * })
- * // Effect.runSync(host.parse(provider)) // "localhost"
+ * Effect.runSync(host.parse(provider)) // => "localhost"
  * ```
  *
  * @see {@link all} – combine multiple configs into a struct
@@ -1291,7 +1345,7 @@ export declare const nested: {
      *
      * **Example** (Nesting a struct config under `"database"`)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const dbConfig = Config.all({
@@ -1302,13 +1356,12 @@ export declare const nested: {
      * const provider = ConfigProvider.fromUnknown({
      *   database: { host: "localhost", port: "5432" }
      * })
-     * // Effect.runSync(dbConfig.parse(provider))
-     * // { host: "localhost", port: 5432 }
+     * Effect.runSync(dbConfig.parse(provider)) // => { host: "localhost", port: 5432 }
      * ```
      *
      * **Example** (Reading env vars with a nested prefix)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const host = Config.string("host").pipe(Config.nested("database"))
@@ -1316,7 +1369,7 @@ export declare const nested: {
      * const provider = ConfigProvider.fromEnv({
      *   env: { database_host: "localhost" }
      * })
-     * // Effect.runSync(host.parse(provider)) // "localhost"
+     * Effect.runSync(host.parse(provider)) // => "localhost"
      * ```
      *
      * @see {@link all} – combine multiple configs into a struct
@@ -1344,7 +1397,7 @@ export declare const nested: {
      *
      * **Example** (Nesting a struct config under `"database"`)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const dbConfig = Config.all({
@@ -1355,13 +1408,12 @@ export declare const nested: {
      * const provider = ConfigProvider.fromUnknown({
      *   database: { host: "localhost", port: "5432" }
      * })
-     * // Effect.runSync(dbConfig.parse(provider))
-     * // { host: "localhost", port: 5432 }
+     * Effect.runSync(dbConfig.parse(provider)) // => { host: "localhost", port: 5432 }
      * ```
      *
      * **Example** (Reading env vars with a nested prefix)
      *
-     * ```ts
+     * ```ts import.meta.vitest
      * import { Config, ConfigProvider, Effect } from "effect"
      *
      * const host = Config.string("host").pipe(Config.nested("database"))
@@ -1369,7 +1421,7 @@ export declare const nested: {
      * const provider = ConfigProvider.fromEnv({
      *   env: { database_host: "localhost" }
      * })
-     * // Effect.runSync(host.parse(provider)) // "localhost"
+     * Effect.runSync(host.parse(provider)) // => "localhost"
      * ```
      *
      * @see {@link all} – combine multiple configs into a struct