effect 4.0.0-beta.83 → 4.0.0-beta.84

package/src/Combiner.ts

@@ -24,7 +24,7 @@ import type * as Order from "./Order.ts"
  * `Struct.makeCombiner` or `Option.makeCombinerFailFast`, or define the
  * combining step for a `Reducer`.
  *
- * **Example** (number addition combiner)
+ * **Example** (Combining numbers with addition)
  *
  * ```ts
  * import { Combiner } from "effect"
@@ -63,7 +63,7 @@ export interface Combiner<A> {
  * The returned combiner's `combine` method delegates to the provided function.
  * Any purity, associativity, or mutation behavior comes from that function.
  *
- * **Example** (multiplying numbers)
+ * **Example** (Multiplying numbers)
  *
  * ```ts
  * import { Combiner } from "effect"
@@ -95,7 +95,7 @@ export function make<A>(combine: (self: A, that: A) => A): Combiner<A> {
  * Returns a new `Combiner` where `combine(self, that)` calls the original
  * combiner as `combine(that, self)`.
  *
- * **Example** (reversing string concatenation)
+ * **Example** (Reversing string concatenation)
  *
  * ```ts
  * import { Combiner, String } from "effect"
@@ -128,7 +128,7 @@ export function flip<A>(combiner: Combiner<A>): Combiner<A> {
  * The combiner compares values using the given `Order`. When values are equal,
  * it returns `that` (the second argument).
  *
- * **Example** (minimum of two numbers)
+ * **Example** (Selecting the minimum of two numbers)
  *
  * ```ts
  * import { Combiner, Number } from "effect"
@@ -164,7 +164,7 @@ export function min<A>(order: Order.Order<A>): Combiner<A> {
  * The combiner compares values using the given `Order`. When values are equal,
  * it returns `that` (the second argument).
  *
- * **Example** (maximum of two numbers)
+ * **Example** (Selecting the maximum of two numbers)
  *
  * ```ts
  * import { Combiner, Number } from "effect"
@@ -197,7 +197,7 @@ export function max<A>(order: Order.Order<A>): Combiner<A> {
  *
  * `combine(self, that)` returns `self` and ignores `that`.
  *
- * **Example** (keeping the first value)
+ * **Example** (Keeping the first value)
  *
  * ```ts
  * import { Combiner } from "effect"
@@ -227,7 +227,7 @@ export function first<A>(): Combiner<A> {
  *
  * `combine(self, that)` returns `that` and ignores `self`.
  *
- * **Example** (keeping the last value)
+ * **Example** (Keeping the last value)
  *
  * ```ts
  * import { Combiner } from "effect"
@@ -259,7 +259,7 @@ export function last<A>(): Combiner<A> {
  *
  * `combine(self, that)` returns the constant `a` and ignores both arguments.
  *
- * **Example** (always returning zero)
+ * **Example** (Always returning zero)
  *
  * ```ts
  * import { Combiner } from "effect"
@@ -295,7 +295,7 @@ export function constant<A>(a: A): Combiner<A> {
  * `combiner.combine(self, combiner.combine(middle, that))`. This function is
  * curried: first provide the separator, then the base combiner.
  *
- * **Example** (joining strings with a separator)
+ * **Example** (Joining strings with a separator)
  *
  * ```ts
  * import { Combiner, String } from "effect"

package/src/Config.ts

@@ -33,7 +33,7 @@ const TypeId = "~effect/Config"
  * Use when you need to distinguish a `Config` from an unknown value before
  * calling `.parse` or {@link unwrap}.
  *
- * **Example** (Type guard)
+ * **Example** (Checking Config values)
  *
  * ```ts
  * import { Config } from "effect"
@@ -93,21 +93,24 @@ export class ConfigError {
  * **Details**
  *
  * Key members:
- * - `parse(provider)` – runs the config against a specific provider,
- *   returning `Effect<T, ConfigError>`.
+ * - `parse(provider, pathPrefix?)` – runs the config against a specific provider.
+ *   The optional path prefix is the logical scope accumulated from outer
+ *   `Config.nested` calls.
  * - Yieldable – can be yielded inside `Effect.gen`, which automatically
  *   resolves the current `ConfigProvider` from the context.
  * - Pipeable – supports `.pipe(Config.map(...))` etc.
  *
  * @see {@link schema} – the main way to create a Config
- * @see {@link make} – low-level constructor
  *
  * @category models
  * @since 2.0.0
  */
 export interface Config<out T> extends Effect.Effect<T, ConfigError> {
   readonly [TypeId]: typeof TypeId
-  readonly parse: (provider: ConfigProvider.ConfigProvider) => Effect.Effect<T, ConfigError>
+  readonly parse: (
+    provider: ConfigProvider.ConfigProvider,
+    pathPrefix?: Path
+  ) => Effect.Effect<T, ConfigError>
 }
 
 const Proto = {
@@ -125,46 +128,11 @@ const Proto = {
   }
 }
 
-/**
- * Creates a `Config` from a raw parsing function.
- *
- * **When to use**
- *
- * Use to build a custom config that cannot be expressed with {@link schema} or
- * convenience constructors, or compose configs programmatically.
- *
- * **Details**
- *
- * The `parse` callback receives a `ConfigProvider` and must return
- * `Effect<T, ConfigError>`.
- *
- * **Example** (Custom config that reads two keys)
- *
- * ```ts
- * import { Config, ConfigProvider, Effect } from "effect"
- *
- * const hostPort = Config.make((provider) =>
- *   Effect.all({
- *     host: Config.string("host").parse(provider),
- *     port: Config.number("port").parse(provider)
- *   })
- * )
- *
- * const provider = ConfigProvider.fromUnknown({ host: "localhost", port: 3000 })
- * // Effect.runSync(hostPort.parse(provider))
- * // { host: "localhost", port: 3000 }
- * ```
- *
- * @see {@link schema} – higher-level constructor using Schema codecs
- *
- * @category constructors
- * @since 4.0.0
- */
-export function make<T>(
-  parse: (provider: ConfigProvider.ConfigProvider) => Effect.Effect<T, ConfigError>
+function make<T>(
+  parse: (provider: ConfigProvider.ConfigProvider, pathPrefix: Path) => Effect.Effect<T, ConfigError>
 ): Config<T> {
   const self = Object.create(Proto)
-  self.parse = parse
+  self.parse = (provider: ConfigProvider.ConfigProvider, pathPrefix: Path = []) => parse(provider, pathPrefix)
   return self
 }
 
@@ -176,10 +144,6 @@ export function make<T>(
  * Use when you need to transform a parsed config value with a function that
  * cannot fail.
  *
- * **Details**
- *
- * Supports both data-last and data-first calling conventions.
- *
  * **Example** (Uppercasing a string config)
  *
  * ```ts
@@ -207,10 +171,6 @@ export const map: {
    * Use when you need to transform a parsed config value with a function that
    * cannot fail.
    *
-   * **Details**
-   *
-   * Supports both data-last and data-first calling conventions.
-   *
    * **Example** (Uppercasing a string config)
    *
    * ```ts
@@ -238,10 +198,6 @@ export const map: {
    * Use when you need to transform a parsed config value with a function that
    * cannot fail.
    *
-   * **Details**
-   *
-   * Supports both data-last and data-first calling conventions.
-   *
    * **Example** (Uppercasing a string config)
    *
    * ```ts
@@ -262,7 +218,7 @@ export const map: {
    */
   <A, B>(self: Config<A>, f: (a: A) => B): Config<B>
 } = dual(2, <A, B>(self: Config<A>, f: (a: A) => B): Config<B> => {
-  return make((provider) => Effect.map(self.parse(provider), f))
+  return make((provider, pathPrefix) => Effect.map(self.parse(provider, pathPrefix), f))
 })
 
 /**
@@ -273,10 +229,6 @@ export const map: {
  * Use when you need to transform a parsed config value with a function that can
  * produce a `ConfigError` (e.g. parsing a URL, checking a range).
  *
- * **Details**
- *
- * Supports both data-last and data-first calling conventions.
- *
  * **Example** (Wrapping a value in an effectful transformation)
  *
  * ```ts
@@ -301,10 +253,6 @@ export const mapOrFail: {
    * Use when you need to transform a parsed config value with a function that can
    * produce a `ConfigError` (e.g. parsing a URL, checking a range).
    *
-   * **Details**
-   *
-   * Supports both data-last and data-first calling conventions.
-   *
    * **Example** (Wrapping a value in an effectful transformation)
    *
    * ```ts
@@ -329,10 +277,6 @@ export const mapOrFail: {
    * Use when you need to transform a parsed config value with a function that can
    * produce a `ConfigError` (e.g. parsing a URL, checking a range).
    *
-   * **Details**
-   *
-   * Supports both data-last and data-first calling conventions.
-   *
    * **Example** (Wrapping a value in an effectful transformation)
    *
    * ```ts
@@ -350,7 +294,7 @@ export const mapOrFail: {
    */
   <A, B>(self: Config<A>, f: (a: A) => Effect.Effect<B, ConfigError>): Config<B>
 } = dual(2, <A, B>(self: Config<A>, f: (a: A) => Effect.Effect<B, ConfigError>): Config<B> => {
-  return make((provider) => Effect.flatMap(self.parse(provider), f))
+  return make((provider, pathPrefix) => Effect.flatMap(self.parse(provider, pathPrefix), f))
 })
 
 /**
@@ -367,8 +311,6 @@ export const mapOrFail: {
  * missing data). The fallback function receives the error and returns a new
  * `Config`.
  *
- * Supports both data-last and data-first calling conventions.
- *
  * **Example** (Falling back to a literal)
  *
  * ```ts
@@ -399,8 +341,6 @@ export const orElse: {
    * missing data). The fallback function receives the error and returns a new
    * `Config`.
    *
-   * Supports both data-last and data-first calling conventions.
-   *
    * **Example** (Falling back to a literal)
    *
    * ```ts
@@ -431,8 +371,6 @@ export const orElse: {
    * missing data). The fallback function receives the error and returns a new
    * `Config`.
    *
-   * Supports both data-last and data-first calling conventions.
-   *
    * **Example** (Falling back to a literal)
    *
    * ```ts
@@ -450,7 +388,9 @@ export const orElse: {
    */
   <A, A2>(self: Config<A>, that: (error: ConfigError) => Config<A2>): Config<A | A2>
 } = dual(2, <A, A2>(self: Config<A>, that: (error: ConfigError) => Config<A2>): Config<A | A2> => {
-  return make((provider) => Effect.catch(self.parse(provider), (error) => that(error).parse(provider)))
+  return make((provider, pathPrefix) =>
+    Effect.catch(self.parse(provider, pathPrefix), (error) => that(error).parse(provider, pathPrefix))
+  )
 })
 
 /**
@@ -501,9 +441,13 @@ export function all<const Arg extends Iterable<Config<any>> | Record<string, Con
     ? [...arg as any]
     : arg
   if (Array.isArray(configs)) {
-    return make((provider) => Effect.all(configs.map((config) => config.parse(provider)))) as any
+    return make((provider, pathPrefix) =>
+      Effect.all(configs.map((config) => config.parse(provider, pathPrefix)))
+    ) as any
   } else {
-    return make((provider) => Effect.all(Rec.map(configs, (config) => config.parse(provider)))) as any
+    return make((provider, pathPrefix) =>
+      Effect.all(Rec.map(configs, (config) => config.parse(provider, pathPrefix)))
+    ) as any
   }
 }
 
@@ -543,11 +487,6 @@ function isMissingDataOnly(issue: SchemaIssue.Issue): boolean {
  *
  * Use when you need to make a config key optional with a sensible default.
  *
- * **Details**
- *
- * The default is lazily evaluated. Supports both data-last and data-first
- * calling conventions.
- *
  * **Gotchas**
  *
  * Only applies when the error is a `SchemaError` caused exclusively by
@@ -579,11 +518,6 @@ export const withDefault: {
    *
    * Use when you need to make a config key optional with a sensible default.
    *
-   * **Details**
-   *
-   * The default is lazily evaluated. Supports both data-last and data-first
-   * calling conventions.
-   *
    * **Gotchas**
    *
    * Only applies when the error is a `SchemaError` caused exclusively by
@@ -615,11 +549,6 @@ export const withDefault: {
    *
    * Use when you need to make a config key optional with a sensible default.
    *
-   * **Details**
-   *
-   * The default is lazily evaluated. Supports both data-last and data-first
-   * calling conventions.
-   *
    * **Gotchas**
    *
    * Only applies when the error is a `SchemaError` caused exclusively by
@@ -669,7 +598,7 @@ export const withDefault: {
  * Like {@link withDefault}, only missing-data errors produce `None`.
  * Validation errors still propagate.
  *
- * **Example** (Optional config)
+ * **Example** (Reading optional config)
  *
  * ```ts
  * import { Config, ConfigProvider, Effect } from "effect"
@@ -765,10 +694,10 @@ type IsPlainObject<A> = [A] extends [Record<string, any>]
  */
 export const unwrap = <T>(wrapped: Wrap<T>): Config<T> => {
   if (isConfig(wrapped)) return wrapped
-  return make((provider) => {
+  return make((provider, pathPrefix) => {
     const entries = Object.entries(wrapped)
     const configs = entries.map(([key, config]) =>
-      unwrap(config as any).parse(provider).pipe(Effect.map((value) => [key, value] as const))
+      unwrap(config as any).parse(provider, pathPrefix).pipe(Effect.map((value) => [key, value] as const))
     )
     return Effect.all(configs).pipe(Effect.map(Object.fromEntries))
   })
@@ -879,8 +808,10 @@ const recur: (
  *
  * **Details**
  *
- * The optional `path` sets the root path segment(s) for the config lookup.
- * Pass a single string for a flat key or an array for nested paths.
+ * The optional `path` sets the local path segment(s) for the config lookup.
+ * It is appended to the logical path prefix accumulated from outer
+ * {@link nested} calls. Pass a single string for a flat key or an array for
+ * nested paths.
  *
  * Convenience constructors such as `string`, `number`, and `boolean` delegate
  * to this API.
@@ -919,14 +850,14 @@ export function schema<T, E>(codec: Schema.Codec<T, E>, path?: string | ConfigPr
   const codecStringTree = Schema.toCodecStringTree(codec)
   const decodeUnknownEffect = SchemaParser.decodeUnknownEffect(codecStringTree)
   const codecStringTreeEncoded = SchemaAST.toEncoded(codecStringTree.ast)
-  const defaultPath = typeof path === "string" ? [path] : path ?? []
-  return make((provider) => {
-    const path = provider.prefix ? [...provider.prefix, ...defaultPath] : defaultPath
-    return recur(codecStringTreeEncoded, provider, defaultPath).pipe(
+  const localPath = typeof path === "string" ? [path] : path ?? []
+  return make((provider, pathPrefix) => {
+    const fullPath = [...pathPrefix, ...localPath]
+    return recur(codecStringTreeEncoded, provider, fullPath).pipe(
       Effect.flatMapEager((tree) =>
         decodeUnknownEffect(tree).pipe(
           Effect.mapErrorEager((issue) =>
-            new Schema.SchemaError(path.length > 0 ? new SchemaIssue.Pointer(path, issue) : issue)
+            new Schema.SchemaError(fullPath.length > 0 ? new SchemaIssue.Pointer(fullPath, issue) : issue)
           )
         )
       ),
@@ -1132,7 +1063,7 @@ export function fail(err: SourceError | Schema.SchemaError) {
  * Use when you need a hardcoded config value, such as inside {@link orElse} or
  * tests.
  *
- * **Example** (Constant fallback)
+ * **Example** (Returning a constant fallback)
  *
  * ```ts
  * import { Config } from "effect"
@@ -1672,7 +1603,7 @@ export function date(name?: string) {
  * // { host: "localhost", port: 5432 }
  * ```
  *
- * **Example** (Env vars with nested prefix)
+ * **Example** (Reading env vars with a nested prefix)
  *
  * ```ts
  * import { Config, ConfigProvider, Effect } from "effect"
@@ -1725,7 +1656,7 @@ export const nested: {
    * // { host: "localhost", port: 5432 }
    * ```
    *
-   * **Example** (Env vars with nested prefix)
+   * **Example** (Reading env vars with a nested prefix)
    *
    * ```ts
    * import { Config, ConfigProvider, Effect } from "effect"
@@ -1778,7 +1709,7 @@ export const nested: {
    * // { host: "localhost", port: 5432 }
    * ```
    *
-   * **Example** (Env vars with nested prefix)
+   * **Example** (Reading env vars with a nested prefix)
    *
    * ```ts
    * import { Config, ConfigProvider, Effect } from "effect"
@@ -1800,5 +1731,6 @@ export const nested: {
   <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)))
+  <A>(self: Config<A>, name: string): Config<A> =>
+    make((provider, pathPrefix) => self.parse(provider, [...pathPrefix, name]))
 )