effect 4.0.0-beta.2 → 4.0.0-beta.21

package/src/Combiner.ts

@@ -1,16 +1,92 @@
 /**
+ * A module for combining two values of the same type into one.
+ *
+ * A `Combiner<A>` wraps a single binary function `(self: A, that: A) => A`.
+ * It describes *how* two values merge but carries no initial/empty value
+ * (for that, see {@link Reducer} which extends `Combiner` with an
+ * `initialValue`).
+ *
+ * ## Mental model
+ *
+ * - **Combiner** – an object with a `combine(self, that)` method that returns
+ *   a value of the same type.
+ * - **Argument order** – `self` is the "left" / accumulator side, `that` is
+ *   the "right" / incoming side.
+ * - **No identity element** – unlike a monoid, a `Combiner` does not require
+ *   a neutral element. Use {@link Reducer} when you need one.
+ * - **Purity** – all combiners produced by this module are pure; they never
+ *   mutate their arguments.
+ * - **Composability** – combiners can be lifted into `Option`, `Struct`,
+ *   `Tuple`, and other container types via helpers in those modules.
+ *
+ * ## Common tasks
+ *
+ * - Create a combiner from any binary function → {@link make}
+ * - Swap argument order → {@link flip}
+ * - Pick the smaller / larger of two values → {@link min} / {@link max}
+ * - Always keep the first or last value → {@link first} / {@link last}
+ * - Ignore both values and return a fixed result → {@link constant}
+ * - Insert a separator between combined values → {@link intercalate}
+ *
+ * ## Gotchas
+ *
+ * - `min` and `max` require an `Order<A>`, not a raw comparator. Import from
+ *   e.g. `Number.Order` or `String.Order`.
+ * - `intercalate` is curried: call it with the separator first, then pass the
+ *   base combiner.
+ * - A `Reducer` (which adds `initialValue`) is also a valid `Combiner` — you
+ *   can pass a `Reducer` anywhere a `Combiner` is expected.
+ *
+ * ## Quickstart
+ *
+ * **Example** (combining strings with a separator)
+ *
+ * ```ts
+ * import { Combiner, String } from "effect"
+ *
+ * const csv = Combiner.intercalate(",")(String.ReducerConcat)
+ *
+ * console.log(csv.combine("a", "b"))
+ * // Output: "a,b"
+ *
+ * console.log(csv.combine(csv.combine("a", "b"), "c"))
+ * // Output: "a,b,c"
+ * ```
+ *
+ * ## See also
+ *
+ * - {@link make} – the primary constructor
+ * - {@link Combiner} – the core interface
+ *
  * @since 4.0.0
  */
 import type * as Order from "./Order.ts"
 
 /**
- * A `Combiner` represents any type of value that can be combined
- * with another value of the same type to produce a new value.
+ * Represents a strategy for combining two values of the same type `A`.
+ *
+ * A `Combiner` contains a single `combine` method that takes two values and
+ * returns a merged result. It does not include an identity/empty value; use
+ * `Reducer` when you need one.
+ *
+ * When to use:
+ * - You need to describe how two values of the same type merge.
+ * - You want to pass a reusable combining strategy to library functions like
+ *   `Struct.makeCombiner` or `Option.makeCombinerFailFast`.
+ * - You are building a `Reducer` and need to define the combining step first.
+ *
+ * **Example** (number addition combiner)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const Sum = Combiner.make<number>((self, that) => self + that)
  *
- * Examples:
- * - numbers with addition
- * - strings with concatenation
- * - arrays with merging
+ * console.log(Sum.combine(3, 4))
+ * // Output: 7
+ * ```
+ *
+ * @see {@link make} – create a `Combiner` from a function
  *
  * @category model
  * @since 4.0.0
@@ -23,7 +99,29 @@ export interface Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` from a `combine` function.
+ * Creates a `Combiner` from a binary function.
+ *
+ * When to use:
+ * - You have a custom combining operation that is not covered by the built-in
+ *   constructors (`min`, `max`, `first`, `last`, `constant`).
+ *
+ * Behavior:
+ * - Returns a new `Combiner` whose `combine` method delegates to the provided
+ *   function.
+ * - Pure – the returned combiner does not mutate its arguments.
+ *
+ * **Example** (multiplying numbers)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const Product = Combiner.make<number>((self, that) => self * that)
+ *
+ * console.log(Product.combine(3, 5))
+ * // Output: 15
+ * ```
+ *
+ * @see {@link Combiner} – the interface this creates
  *
  * @since 4.0.0
  */
@@ -32,6 +130,31 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
 }
 
 /**
+ * Reverses the argument order of a combiner's `combine` method.
+ *
+ * When to use:
+ * - You need the "right" value to act as the accumulator side.
+ * - You want to reverse the natural direction of a non-commutative combiner
+ *   (e.g. string concatenation).
+ *
+ * Behavior:
+ * - Returns a new `Combiner` where `combine(self, that)` calls the original
+ *   combiner as `combine(that, self)`.
+ * - Does not mutate the input combiner.
+ *
+ * **Example** (reversing string concatenation)
+ *
+ * ```ts
+ * import { Combiner, String } from "effect"
+ *
+ * const Prepend = Combiner.flip(String.ReducerConcat)
+ *
+ * console.log(Prepend.combine("a", "b"))
+ * // Output: "ba"
+ * ```
+ *
+ * @see {@link make}
+ *
  * @since 4.0.0
  */
 export function flip<A>(combiner: Combiner<A>): Combiner<A> {
@@ -39,7 +162,33 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns the smaller of two values.
+ * Creates a `Combiner` that returns the smaller of two values according to
+ * the provided `Order`.
+ *
+ * When to use:
+ * - You want to accumulate the minimum value across a collection.
+ * - You are building a `Reducer` that tracks the running minimum.
+ *
+ * Behavior:
+ * - Compares using the given `Order`. When values are equal, returns `that`
+ *   (the second argument).
+ * - Pure – does not mutate either argument.
+ *
+ * **Example** (minimum of two numbers)
+ *
+ * ```ts
+ * import { Combiner, Number } from "effect"
+ *
+ * const Min = Combiner.min(Number.Order)
+ *
+ * console.log(Min.combine(3, 1))
+ * // Output: 1
+ *
+ * console.log(Min.combine(1, 3))
+ * // Output: 1
+ * ```
+ *
+ * @see {@link max}
  *
  * @since 4.0.0
  */
@@ -48,7 +197,33 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns the larger of two values.
+ * Creates a `Combiner` that returns the larger of two values according to
+ * the provided `Order`.
+ *
+ * When to use:
+ * - You want to accumulate the maximum value across a collection.
+ * - You are building a `Reducer` that tracks the running maximum.
+ *
+ * Behavior:
+ * - Compares using the given `Order`. When values are equal, returns `that`
+ *   (the second argument).
+ * - Pure – does not mutate either argument.
+ *
+ * **Example** (maximum of two numbers)
+ *
+ * ```ts
+ * import { Combiner, Number } from "effect"
+ *
+ * const Max = Combiner.max(Number.Order)
+ *
+ * console.log(Max.combine(3, 1))
+ * // Output: 3
+ *
+ * console.log(Max.combine(1, 3))
+ * // Output: 3
+ * ```
+ *
+ * @see {@link min}
  *
  * @since 4.0.0
  */
@@ -57,7 +232,29 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns the first value.
+ * Creates a `Combiner` that always returns the first (left) argument.
+ *
+ * When to use:
+ * - You want "first write wins" semantics when merging values.
+ * - You need a combiner but the combining logic should be a no-op that keeps
+ *   the existing value.
+ *
+ * Behavior:
+ * - `combine(self, that)` returns `self`, ignoring `that`.
+ * - Pure – the second argument is discarded, not mutated.
+ *
+ * **Example** (keeping the first value)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const First = Combiner.first<number>()
+ *
+ * console.log(First.combine(1, 2))
+ * // Output: 1
+ * ```
+ *
+ * @see {@link last}
  *
  * @since 4.0.0
  */
@@ -66,7 +263,28 @@ export function first<A>(): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns the last value.
+ * Creates a `Combiner` that always returns the last (right) argument.
+ *
+ * When to use:
+ * - You want "last write wins" semantics when merging values.
+ * - You need a combiner that replaces the accumulator with each new value.
+ *
+ * Behavior:
+ * - `combine(self, that)` returns `that`, ignoring `self`.
+ * - Pure – the first argument is discarded, not mutated.
+ *
+ * **Example** (keeping the last value)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const Last = Combiner.last<number>()
+ *
+ * console.log(Last.combine(1, 2))
+ * // Output: 2
+ * ```
+ *
+ * @see {@link first}
  *
  * @since 4.0.0
  */
@@ -75,7 +293,31 @@ export function last<A>(): Combiner<A> {
 }
 
 /**
- * Creates a `Combiner` that returns a constant value.
+ * Creates a `Combiner` that ignores both arguments and always returns the
+ * given constant value.
+ *
+ * When to use:
+ * - You need a combiner that produces a fixed result regardless of input.
+ * - You are providing a combiner to a generic API but the combined value is
+ *   predetermined.
+ *
+ * Behavior:
+ * - `combine(self, that)` returns the constant `a`, ignoring both arguments.
+ * - Pure – no mutation occurs.
+ *
+ * **Example** (always returning zero)
+ *
+ * ```ts
+ * import { Combiner } from "effect"
+ *
+ * const Zero = Combiner.constant(0)
+ *
+ * console.log(Zero.combine(42, 99))
+ * // Output: 0
+ * ```
+ *
+ * @see {@link first}
+ * @see {@link last}
  *
  * @since 4.0.0
  */
@@ -84,7 +326,32 @@ export function constant<A>(a: A): Combiner<A> {
 }
 
 /**
- * Between each pair of elements insert `middle`.
+ * Wraps a `Combiner` so that a separator value is inserted between every
+ * pair of combined elements.
+ *
+ * When to use:
+ * - You are building delimited strings (CSV, paths, etc.) by repeated
+ *   combination.
+ * - You need to inject a fixed separator between accumulated values.
+ *
+ * Behavior:
+ * - `intercalate(middle)(combiner).combine(self, that)` is equivalent to
+ *   `combiner.combine(self, combiner.combine(middle, that))`.
+ * - Curried: first provide the separator, then the base combiner.
+ * - Does not mutate the input combiner; returns a new one.
+ *
+ * **Example** (joining strings with a separator)
+ *
+ * ```ts
+ * import { Combiner, String } from "effect"
+ *
+ * const commaSep = Combiner.intercalate(",")(String.ReducerConcat)
+ *
+ * console.log(commaSep.combine("a", "b"))
+ * // Output: "a,b"
+ * ```
+ *
+ * @see {@link make}
  *
  * @since 4.0.0
  */

package/src/Config.ts

@@ -75,7 +75,7 @@ import type { Path, SourceError } from "./ConfigProvider.ts"
 import * as ConfigProvider from "./ConfigProvider.ts"
 import * as Duration_ from "./Duration.ts"
 import * as Effect from "./Effect.ts"
-import { dual, type LazyArg } from "./Function.ts"
+import { dual } from "./Function.ts"
 import { PipeInspectableProto, YieldableProto } from "./internal/core.ts"
 import * as LogLevel_ from "./LogLevel.ts"
 import * as Option from "./Option.ts"
@@ -569,7 +569,7 @@ function isMissingDataOnly(issue: Issue.Issue): boolean {
  * ```ts
  * import { Config, ConfigProvider, Effect } from "effect"
  *
- * const port = Config.number("port").pipe(Config.withDefault(() => 3000))
+ * const port = Config.number("port").pipe(Config.withDefault(3000))
  *
  * const provider = ConfigProvider.fromUnknown({})
  * // Effect.runSync(port.parse(provider)) // 3000
@@ -598,7 +598,7 @@ export const withDefault: {
    * ```ts
    * import { Config, ConfigProvider, Effect } from "effect"
    *
-   * const port = Config.number("port").pipe(Config.withDefault(() => 3000))
+   * const port = Config.number("port").pipe(Config.withDefault(3000))
    *
    * const provider = ConfigProvider.fromUnknown({})
    * // Effect.runSync(port.parse(provider)) // 3000
@@ -609,7 +609,7 @@ export const withDefault: {
    *
    * @since 4.0.0
    */
-  <const A2>(defaultValue: LazyArg<A2>): <A>(self: Config<A>) => Config<A2 | A>
+  <const A2>(defaultValue: A2): <A>(self: Config<A>) => Config<A2 | A>
   /**
    * Provides a fallback value when the config fails due to missing data.
    *
@@ -627,7 +627,7 @@ export const withDefault: {
    * ```ts
    * import { Config, ConfigProvider, Effect } from "effect"
    *
-   * const port = Config.number("port").pipe(Config.withDefault(() => 3000))
+   * const port = Config.number("port").pipe(Config.withDefault(3000))
    *
    * const provider = ConfigProvider.fromUnknown({})
    * // Effect.runSync(port.parse(provider)) // 3000
@@ -638,13 +638,13 @@ export const withDefault: {
    *
    * @since 4.0.0
    */
-  <A, const A2>(self: Config<A>, defaultValue: LazyArg<A2>): Config<A | A2>
-} = dual(2, <A, const A2>(self: Config<A>, defaultValue: LazyArg<A2>): Config<A | A2> => {
+  <A, const A2>(self: Config<A>, defaultValue: A2): Config<A | A2>
+} = dual(2, <A, const A2>(self: Config<A>, defaultValue: A2): Config<A | A2> => {
   return orElse(self, (err) => {
     if (Schema.isSchemaError(err.cause)) {
       const issue = err.cause.issue
       if (isMissingDataOnly(issue)) {
-        return succeed(defaultValue())
+        return succeed(defaultValue)
       }
     }
     return fail(err.cause)
@@ -678,7 +678,7 @@ export const withDefault: {
  * @since 4.0.0
  */
 export const option = <A>(self: Config<A>): Config<Option.Option<A>> =>
-  self.pipe(map(Option.some), withDefault(() => Option.none()))
+  self.pipe(map(Option.some), withDefault(Option.none()))
 
 /**
  * Utility type that recursively replaces primitives with `Config` in a nested
@@ -886,18 +886,19 @@ export function schema<T, E>(codec: Schema.Codec<T, E>, path?: string | ConfigPr
   const decodeUnknownEffect = Parser.decodeUnknownEffect(toCodecStringTree)
   const toCodecStringTreeEncoded = AST.toEncoded(toCodecStringTree.ast)
   const defaultPath = typeof path === "string" ? [path] : path ?? []
-  return make((provider) =>
-    recur(toCodecStringTreeEncoded, provider, defaultPath).pipe(
+  return make((provider) => {
+    const path = provider.prefix ? [...provider.prefix, ...defaultPath] : defaultPath
+    return recur(toCodecStringTreeEncoded, provider, defaultPath).pipe(
       Effect.flatMapEager((tree) =>
-        decodeUnknownEffect(tree).pipe(Effect.mapErrorEager((issue) =>
-          new Schema.SchemaError(defaultPath.length > 0 ? new Issue.Pointer(defaultPath, issue) : issue)
-        ))
+        decodeUnknownEffect(tree).pipe(
+          Effect.mapErrorEager((issue) =>
+            new Schema.SchemaError(path.length > 0 ? new Issue.Pointer(path, issue) : issue)
+          )
+        )
       ),
-      Effect.mapErrorEager((cause) =>
-        new ConfigError(cause)
-      )
+      Effect.mapErrorEager((cause) => new ConfigError(cause))
     )
-  )
+  })
 }
 
 /** @internal */
@@ -938,7 +939,7 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
  * - Pass to {@link schema} for custom paths, or use the {@link duration}
  *   convenience constructor.
  *
- * Accepts any string that `Duration.fromDurationInput` can parse (e.g.
+ * Accepts any string that `Duration.fromInput` can parse (e.g.
  * `"10 seconds"`, `"500 millis"`).
  *
  * @see {@link duration} – convenience constructor
@@ -948,7 +949,7 @@ export const Boolean = Schema.Literals([...TrueValues.literals, ...FalseValues.l
  */
 export const Duration = Schema.String.pipe(Schema.decodeTo(Schema.Duration, {
   decode: Getter.transformOrFail((s) => {
-    const d = Duration_.fromDurationInput(s as any)
+    const d = Duration_.fromInput(s as any)
     return d ? Effect.succeed(d) : Effect.fail(new Issue.InvalidValue(Option.some(s)))
   }),
   encode: Getter.forbidden(() => "Encoding Duration is not supported")
@@ -1235,7 +1236,7 @@ export function boolean(name?: string) {
  *
  * Shortcut for `Config.schema(Config.Duration, name)`.
  *
- * Accepts any string that `Duration.fromDurationInput` can parse (e.g.
+ * Accepts any string that `Duration.fromInput` can parse (e.g.
  * `"10 seconds"`, `"500 millis"`, `"2 minutes"`).
  *
  * **Example** (Reading a duration)
@@ -1446,3 +1447,164 @@ export function url(name?: string) {
 export function date(name?: string) {
   return schema(Schema.DateValid, name)
 }
+
+/**
+ * Scopes a config under a named prefix.
+ *
+ * When to use:
+ * - Grouping related config keys under a common namespace (e.g.
+ *   `"database"`, `"redis"`).
+ * - Building reusable config fragments that callers nest at different paths.
+ *
+ * The prefix is prepended to every key the inner config reads. With
+ * `fromUnknown` this means an extra object level; with `fromEnv` it means
+ * a `_`-separated prefix on env var names.
+ *
+ * Multiple `nested` calls compose: the outermost name becomes the
+ * outermost path segment.
+ *
+ * **Example** (Nesting a struct config under `"database"`)
+ *
+ * ```ts
+ * import { Config, ConfigProvider, Effect } from "effect"
+ *
+ * const dbConfig = Config.all({
+ *   host: Config.string("host"),
+ *   port: Config.number("port")
+ * }).pipe(Config.nested("database"))
+ *
+ * const provider = ConfigProvider.fromUnknown({
+ *   database: { host: "localhost", port: "5432" }
+ * })
+ * // Effect.runSync(dbConfig.parse(provider))
+ * // { host: "localhost", port: 5432 }
+ * ```
+ *
+ * **Example** (Env vars with nested prefix)
+ *
+ * ```ts
+ * import { Config, ConfigProvider, Effect } from "effect"
+ *
+ * const host = Config.string("host").pipe(Config.nested("database"))
+ *
+ * const provider = ConfigProvider.fromEnv({
+ *   env: { database_host: "localhost" }
+ * })
+ * // Effect.runSync(host.parse(provider)) // "localhost"
+ * ```
+ *
+ * @see {@link all} – combine multiple configs into a struct
+ * @see {@link schema} – read structured config from a schema
+ *
+ * @category Combinators
+ * @since 4.0.0
+ */
+export const nested: {
+  /**
+   * Scopes a config under a named prefix.
+   *
+   * When to use:
+   * - Grouping related config keys under a common namespace (e.g.
+   *   `"database"`, `"redis"`).
+   * - Building reusable config fragments that callers nest at different paths.
+   *
+   * The prefix is prepended to every key the inner config reads. With
+   * `fromUnknown` this means an extra object level; with `fromEnv` it means
+   * a `_`-separated prefix on env var names.
+   *
+   * Multiple `nested` calls compose: the outermost name becomes the
+   * outermost path segment.
+   *
+   * **Example** (Nesting a struct config under `"database"`)
+   *
+   * ```ts
+   * import { Config, ConfigProvider, Effect } from "effect"
+   *
+   * const dbConfig = Config.all({
+   *   host: Config.string("host"),
+   *   port: Config.number("port")
+   * }).pipe(Config.nested("database"))
+   *
+   * const provider = ConfigProvider.fromUnknown({
+   *   database: { host: "localhost", port: "5432" }
+   * })
+   * // Effect.runSync(dbConfig.parse(provider))
+   * // { host: "localhost", port: 5432 }
+   * ```
+   *
+   * **Example** (Env vars with nested prefix)
+   *
+   * ```ts
+   * import { Config, ConfigProvider, Effect } from "effect"
+   *
+   * const host = Config.string("host").pipe(Config.nested("database"))
+   *
+   * const provider = ConfigProvider.fromEnv({
+   *   env: { database_host: "localhost" }
+   * })
+   * // Effect.runSync(host.parse(provider)) // "localhost"
+   * ```
+   *
+   * @see {@link all} – combine multiple configs into a struct
+   * @see {@link schema} – read structured config from a schema
+   *
+   * @category Combinators
+   * @since 4.0.0
+   */
+  (name: string): <A>(self: Config<A>) => Config<A>
+  /**
+   * Scopes a config under a named prefix.
+   *
+   * When to use:
+   * - Grouping related config keys under a common namespace (e.g.
+   *   `"database"`, `"redis"`).
+   * - Building reusable config fragments that callers nest at different paths.
+   *
+   * The prefix is prepended to every key the inner config reads. With
+   * `fromUnknown` this means an extra object level; with `fromEnv` it means
+   * a `_`-separated prefix on env var names.
+   *
+   * Multiple `nested` calls compose: the outermost name becomes the
+   * outermost path segment.
+   *
+   * **Example** (Nesting a struct config under `"database"`)
+   *
+   * ```ts
+   * import { Config, ConfigProvider, Effect } from "effect"
+   *
+   * const dbConfig = Config.all({
+   *   host: Config.string("host"),
+   *   port: Config.number("port")
+   * }).pipe(Config.nested("database"))
+   *
+   * const provider = ConfigProvider.fromUnknown({
+   *   database: { host: "localhost", port: "5432" }
+   * })
+   * // Effect.runSync(dbConfig.parse(provider))
+   * // { host: "localhost", port: 5432 }
+   * ```
+   *
+   * **Example** (Env vars with nested prefix)
+   *
+   * ```ts
+   * import { Config, ConfigProvider, Effect } from "effect"
+   *
+   * const host = Config.string("host").pipe(Config.nested("database"))
+   *
+   * const provider = ConfigProvider.fromEnv({
+   *   env: { database_host: "localhost" }
+   * })
+   * // Effect.runSync(host.parse(provider)) // "localhost"
+   * ```
+   *
+   * @see {@link all} – combine multiple configs into a struct
+   * @see {@link schema} – read structured config from a schema
+   *
+   * @category Combinators
+   * @since 4.0.0
+   */
+  <A>(self: Config<A>, name: string): Config<A>
+} = dual(
+  2,
+  <A>(self: Config<A>, name: string): Config<A> => make((provider) => self.parse(ConfigProvider.nested(provider, name)))
+)