effect 4.0.0-beta.82 → 4.0.0-beta.84

package/src/ConfigProvider.ts

@@ -176,7 +176,7 @@ export function makeArray(length: number, value?: string): Node {
  * **Gotchas**
  *
  * Do not use `SourceError` for "key not found". That case is represented by
- * returning `undefined` from `load` or `get`.
+ * returning `undefined` from `load`.
  *
  * **Example** (Failing with a SourceError)
  *
@@ -190,8 +190,8 @@ export function makeArray(length: number, value?: string): Node {
  * )
  * ```
  *
- * @see {@link ConfigProvider} – the interface whose `load`/`get` may fail
- *   with this error
+ * @see {@link ConfigProvider} – the interface whose `load` may fail with this
+ *   error
  *
  * @category models
  * @since 4.0.0
@@ -234,13 +234,10 @@ export type Path = ReadonlyArray<string | number>
  *
  * **Details**
  *
- * `load(path)` resolves `mapInput` and `prefix` transformations, then
- * delegates to `get`. This is what the `Config` module calls. `get(path)` is
- * raw access to the underlying store without path transformations.
- * `mapInput` and `prefix` are optional path transformations set by
- * {@link mapInput} and {@link nested}. All methods return
- * `Effect<Node | undefined, SourceError>`: `undefined` means "not found" and
- * `SourceError` means the source itself failed.
+ * `load(path)` is the semantic lookup operation used by the `Config` module.
+ * It applies provider transformations and composition before consulting the
+ * underlying source. `undefined` means "not found" and `SourceError` means the
+ * source itself failed.
  *
  * @see {@link make} – construct a provider from a lookup function
  * @see {@link orElse} – compose providers with fallback
@@ -260,33 +257,8 @@ export interface ConfigProvider extends Pipeable {
    */
   readonly load: (path: Path) => Effect.Effect<Node | undefined, SourceError>
 
-  /**
-   * Raw access to the underlying source.
-   *
-   * **When to use**
-   *
-   * Use to read from the backing source without applying this provider's path
-   * transformations.
-   */
-  readonly get: (path: Path) => Effect.Effect<Node | undefined, SourceError>
-
-  /**
-   * Function to map the input path.
-   *
-   * **When to use**
-   *
-   * Use to store the path transformation applied before raw provider lookup.
-   */
-  readonly mapInput: ((path: Path) => Path) | undefined
-
-  /**
-   * Prefix to add to the input path.
-   *
-   * **When to use**
-   *
-   * Use to store the path prefix applied before raw provider lookup.
-   */
-  readonly prefix: Path | undefined
+  /** @internal */
+  readonly state: ProviderState
 }
 
 /**
@@ -335,6 +307,57 @@ const Proto = {
   }
 }
 
+type SourceState = {
+  readonly _tag: "Source"
+  readonly get: (path: Path) => Effect.Effect<Node | undefined, SourceError>
+  readonly transform: (path: Path) => Path
+}
+
+type OrElseState = {
+  readonly _tag: "OrElse"
+  readonly first: ConfigProvider
+  readonly second: ConfigProvider
+}
+
+type ProviderState = SourceState | OrElseState
+
+const identityPath = (path: Path): Path => path
+
+function makeProvider(
+  state: ProviderState,
+  load: (path: Path) => Effect.Effect<Node | undefined, SourceError>
+): ConfigProvider {
+  const self = Object.create(Proto)
+  self.state = state
+  self.load = load
+  return self
+}
+
+function makeSource(
+  get: (path: Path) => Effect.Effect<Node | undefined, SourceError>,
+  transform: (path: Path) => Path
+): ConfigProvider {
+  const state: SourceState = {
+    _tag: "Source",
+    get,
+    transform
+  }
+  return makeProvider(state, (path) => state.get(state.transform(path)))
+}
+
+function makeOrElse(first: ConfigProvider, second: ConfigProvider): ConfigProvider {
+  const state: OrElseState = {
+    _tag: "OrElse",
+    first,
+    second
+  }
+  return makeProvider(state, (path) =>
+    Effect.flatMap(
+      state.first.load(path),
+      (node) => node ? Effect.succeed(node) : state.second.load(path)
+    ))
+}
+
 /**
  * Creates a `ConfigProvider` from a raw lookup function.
  *
@@ -349,11 +372,7 @@ const Proto = {
  * `Effect<Node | undefined, SourceError>`. Return `undefined` when the path
  * does not exist; fail with `SourceError` only for actual I/O errors.
  *
- * The optional `mapInput` and `prefix` parameters are wired into the
- * resulting `load` method so that combinators like {@link mapInput} and
- * {@link nested} can compose without wrapping `get`.
- *
- * **Example** (A simple in-memory provider)
+ * **Example** (Creating a simple in-memory provider)
  *
  * ```ts
  * import { ConfigProvider, Effect } from "effect"
@@ -378,21 +397,8 @@ const Proto = {
  * @category constructors
  * @since 2.0.0
  */
-export function make(
-  get: (path: Path) => Effect.Effect<Node | undefined, SourceError>,
-  mapInput?: (path: Path) => Path,
-  prefix?: Path
-): ConfigProvider {
-  const self = Object.create(Proto)
-  self.get = get
-  self.mapInput = mapInput
-  self.prefix = prefix
-  self.load = (path: Path) => {
-    if (mapInput) path = mapInput(path)
-    if (prefix) path = [...prefix, ...path]
-    return get(path)
-  }
-  return self
+export function make(get: (path: Path) => Effect.Effect<Node | undefined, SourceError>): ConfigProvider {
+  return makeSource(get, identityPath)
 }
 
 /**
@@ -406,7 +412,9 @@ export function make(
  *
  * **Details**
  *
- * Supports both data-last and data-first calling conventions.
+ * Each provider keeps its own path transformations. If the combined provider
+ * is later transformed with {@link mapInput} or {@link nested}, the
+ * transformation is applied to both sides.
  *
  * **Gotchas**
  *
@@ -443,7 +451,9 @@ export const orElse: {
    *
    * **Details**
    *
-   * Supports both data-last and data-first calling conventions.
+   * Each provider keeps its own path transformations. If the combined provider
+   * is later transformed with {@link mapInput} or {@link nested}, the
+   * transformation is applied to both sides.
    *
    * **Gotchas**
    *
@@ -480,7 +490,9 @@ export const orElse: {
    *
    * **Details**
    *
-   * Supports both data-last and data-first calling conventions.
+   * Each provider keeps its own path transformations. If the combined provider
+   * is later transformed with {@link mapInput} or {@link nested}, the
+   * transformation is applied to both sides.
    *
    * **Gotchas**
    *
@@ -508,8 +520,7 @@ export const orElse: {
   (self: ConfigProvider, that: ConfigProvider): ConfigProvider
 } = dual(
   2,
-  (self: ConfigProvider, that: ConfigProvider): ConfigProvider =>
-    make((path) => Effect.flatMap(self.get(path), (node) => node ? Effect.succeed(node) : that.get(path)))
+  (self: ConfigProvider, that: ConfigProvider): ConfigProvider => makeOrElse(self, that)
 )
 
 /**
@@ -522,10 +533,11 @@ export const orElse: {
  *
  * **Details**
  *
- * The function `f` receives the full path and must return a new path. If the
- * provider already has a `mapInput`, the functions compose: the existing
- * mapping runs first, then `f`. Supports both data-last and data-first calling
- * conventions.
+ * The function `f` receives the whole path produced by earlier provider
+ * transformations and must return a new path. Lookup path transformations
+ * compose in application order: the existing transformation runs first, then
+ * `f` runs. For providers composed with {@link orElse}, the transformation is
+ * applied to each operand.
  *
  * **Example** (Uppercasing path segments)
  *
@@ -560,10 +572,11 @@ export const mapInput: {
    *
    * **Details**
    *
-   * The function `f` receives the full path and must return a new path. If the
-   * provider already has a `mapInput`, the functions compose: the existing
-   * mapping runs first, then `f`. Supports both data-last and data-first calling
-   * conventions.
+   * The function `f` receives the whole path produced by earlier provider
+   * transformations and must return a new path. Lookup path transformations
+   * compose in application order: the existing transformation runs first, then
+   * `f` runs. For providers composed with {@link orElse}, the transformation is
+   * applied to each operand.
    *
    * **Example** (Uppercasing path segments)
    *
@@ -598,10 +611,11 @@ export const mapInput: {
    *
    * **Details**
    *
-   * The function `f` receives the full path and must return a new path. If the
-   * provider already has a `mapInput`, the functions compose: the existing
-   * mapping runs first, then `f`. Supports both data-last and data-first calling
-   * conventions.
+   * The function `f` receives the whole path produced by earlier provider
+   * transformations and must return a new path. Lookup path transformations
+   * compose in application order: the existing transformation runs first, then
+   * `f` runs. For providers composed with {@link orElse}, the transformation is
+   * applied to each operand.
    *
    * **Example** (Uppercasing path segments)
    *
@@ -629,7 +643,13 @@ export const mapInput: {
 } = dual(
   2,
   (self: ConfigProvider, f: (path: Path) => Path): ConfigProvider => {
-    return make(self.get, self.mapInput ? flow(self.mapInput, f) : f, self.prefix ? f(self.prefix) : undefined)
+    const state = self.state
+    switch (state._tag) {
+      case "Source":
+        return makeSource(state.get, flow(state.transform, f))
+      case "OrElse":
+        return makeOrElse(mapInput(state.first, f), mapInput(state.second, f))
+    }
   }
 )
 
@@ -678,14 +698,16 @@ export const constantCase: (self: ConfigProvider) => ConfigProvider = mapInput((
  *
  * **Details**
  *
- * Accepts a single string or a full `Path` array. Supports both data-last and
- * data-first calling conventions.
+ * Accepts a single string or a full `Path` array. For providers composed with
+ * {@link orElse}, the prefix is applied to each operand. Supports both
+ * data-last and data-first calling conventions.
  *
  * **Gotchas**
  *
- * The prefix is prepended after any `mapInput` transformation runs, so
- * ordering matters when composing with {@link mapInput} or
- * {@link constantCase}.
+ * Ordering matters when composing with {@link mapInput} or
+ * {@link constantCase}. Later provider transformations run after earlier ones:
+ * a later `nested` becomes the outer prefix, and a later `mapInput` sees the
+ * whole path produced by previous transformations.
  *
  * **Example** (Nesting under a prefix)
  *
@@ -717,14 +739,16 @@ export const nested: {
    *
    * **Details**
    *
-   * Accepts a single string or a full `Path` array. Supports both data-last and
-   * data-first calling conventions.
+   * Accepts a single string or a full `Path` array. For providers composed with
+   * {@link orElse}, the prefix is applied to each operand. Supports both
+   * data-last and data-first calling conventions.
    *
    * **Gotchas**
    *
-   * The prefix is prepended after any `mapInput` transformation runs, so
-   * ordering matters when composing with {@link mapInput} or
-   * {@link constantCase}.
+   * Ordering matters when composing with {@link mapInput} or
+   * {@link constantCase}. Later provider transformations run after earlier ones:
+   * a later `nested` becomes the outer prefix, and a later `mapInput` sees the
+   * whole path produced by previous transformations.
    *
    * **Example** (Nesting under a prefix)
    *
@@ -756,14 +780,16 @@ export const nested: {
    *
    * **Details**
    *
-   * Accepts a single string or a full `Path` array. Supports both data-last and
-   * data-first calling conventions.
+   * Accepts a single string or a full `Path` array. For providers composed with
+   * {@link orElse}, the prefix is applied to each operand. Supports both
+   * data-last and data-first calling conventions.
    *
    * **Gotchas**
    *
-   * The prefix is prepended after any `mapInput` transformation runs, so
-   * ordering matters when composing with {@link mapInput} or
-   * {@link constantCase}.
+   * Ordering matters when composing with {@link mapInput} or
+   * {@link constantCase}. Later provider transformations run after earlier ones:
+   * a later `nested` becomes the outer prefix, and a later `mapInput` sees the
+   * whole path produced by previous transformations.
    *
    * **Example** (Nesting under a prefix)
    *
@@ -788,7 +814,13 @@ export const nested: {
   2,
   (self: ConfigProvider, prefix: string | Path): ConfigProvider => {
     const path = typeof prefix === "string" ? [prefix] : prefix
-    return make(self.get, self.mapInput, self.prefix ? [...self.prefix, ...path] : path)
+    const state = self.state
+    switch (state._tag) {
+      case "Source":
+        return makeSource(state.get, flow(state.transform, (input) => [...path, ...input]))
+      case "OrElse":
+        return makeOrElse(nested(state.first, path), nested(state.second, path))
+    }
   }
 )
 
@@ -805,7 +837,7 @@ export const nested: {
  * Accepts either a plain `ConfigProvider` or an `Effect` that produces one.
  * When given an Effect, it is evaluated once when the layer is built.
  *
- * **Example** (Using a JSON object as the config source)
+ * **Example** (Reading config from a JSON object)
  *
  * ```ts
  * import { Config, ConfigProvider, Effect, Layer } from "effect"
@@ -1286,8 +1318,9 @@ export const fromDotEnv: (options?: {
  *
  * Resolution tries a regular file first and returns a `Value` node with
  * trimmed file contents. If the file read fails, it tries a directory and
- * returns a `Record` node with immediate child names as keys. If both fail, it
- * returns `SourceError`.
+ * returns a `Record` node with immediate child names as keys. If both fail with
+ * `NotFound`, it returns `undefined`. Other platform failures return
+ * `SourceError`.
  *
  * Requires `Path` and `FileSystem` in the Effect context. Defaults to root
  * path `/`; override with `{ rootPath: "/etc/config" }`.
@@ -1332,15 +1365,19 @@ export const fromDir: (options?: {
 
     // If not a file, try reading as a *directory*
     const asDirectory = fs.readDirectory(fullPath).pipe(
-      Effect.map((entries: ReadonlyArray<any>) => {
-        // Support both string paths and DirEntry-like objects
-        const keys = entries.map((e) => typeof e === "string" ? platformPath.basename(e) : format(e?.name ?? ""))
-        return makeRecord(new Set(keys))
-      })
+      Effect.map((entries) => makeRecord(new Set(entries.map((entry) => platformPath.basename(entry)))))
     )
 
     return asFile.pipe(
-      Effect.catch(() => asDirectory),
+      Effect.catch((fileCause) =>
+        asDirectory.pipe(
+          Effect.catch((dirCause) =>
+            isNotFound(fileCause) && isNotFound(dirCause)
+              ? Effect.succeed(undefined)
+              : Effect.fail(isNotFound(fileCause) ? dirCause : fileCause)
+          )
+        )
+      ),
       Effect.mapError((cause: PlatformError) =>
         new SourceError({
           message: `Failed to read file at ${platformPath.join(rootPath, ...path.map(String))}`,
@@ -1350,3 +1387,5 @@ export const fromDir: (options?: {
     )
   })
 })
+
+const isNotFound = (cause: PlatformError) => cause.reason._tag === "NotFound"

package/src/Console.ts

@@ -78,7 +78,7 @@ export const Console: Context.Reference<Console> = effect.ConsoleRef
 /**
  * Creates an Effect that provides access to the current console service and lets you perform operations with it within an Effect context.
  *
- * **Example** (Using the current console service)
+ * **Example** (Accessing the current console service)
  *
  * ```ts
  * import { Console, Effect } from "effect"

package/src/Data.ts

@@ -195,7 +195,7 @@ export declare namespace TaggedEnum {
    * `this["A"]`, `this["B"]`, etc. as placeholders for the generics. The
    * `Count` parameter declares how many generics are used (up to 4).
    *
-   * **Example** (Generic tagged enum)
+   * **Example** (Defining a generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -325,7 +325,7 @@ export declare namespace TaggedEnum {
    *
    * Use to select one full tagged-union variant by its `_tag` value.
    *
-   * **Example** (extracting a variant type)
+   * **Example** (Extracting a variant type)
    *
    * ```ts
    * import type { Data } from "effect"
@@ -537,7 +537,7 @@ export declare namespace TaggedEnum {
  *   on the tag being globally unique and the value being produced by your
  *   constructors. For untrusted input, validate with the `Schema` module first.
  *
- * **Example** (Basic usage)
+ * **Example** (Creating and matching tagged enum values)
  *
  * ```ts
  * import { Data } from "effect"
@@ -562,7 +562,7 @@ export declare namespace TaggedEnum {
  * console.log(msg) // "/missing not found"
  * ```
  *
- * **Example** (Generic tagged enum)
+ * **Example** (Defining a generic tagged enum)
  *
  * ```ts
  * import { Data } from "effect"
@@ -610,7 +610,7 @@ export const taggedEnum: {
    *   on the tag being globally unique and the value being produced by your
    *   constructors. For untrusted input, validate with the `Schema` module first.
    *
-   * **Example** (Basic usage)
+   * **Example** (Creating and matching tagged enum values)
    *
    * ```ts
    * import { Data } from "effect"
@@ -635,7 +635,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (Generic tagged enum)
+   * **Example** (Defining a generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -694,7 +694,7 @@ export const taggedEnum: {
    *   on the tag being globally unique and the value being produced by your
    *   constructors. For untrusted input, validate with the `Schema` module first.
    *
-   * **Example** (Basic usage)
+   * **Example** (Creating and matching tagged enum values)
    *
    * ```ts
    * import { Data } from "effect"
@@ -719,7 +719,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (Generic tagged enum)
+   * **Example** (Defining a generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -778,7 +778,7 @@ export const taggedEnum: {
    *   on the tag being globally unique and the value being produced by your
    *   constructors. For untrusted input, validate with the `Schema` module first.
    *
-   * **Example** (Basic usage)
+   * **Example** (Creating and matching tagged enum values)
    *
    * ```ts
    * import { Data } from "effect"
@@ -803,7 +803,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (Generic tagged enum)
+   * **Example** (Defining a generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -862,7 +862,7 @@ export const taggedEnum: {
    *   on the tag being globally unique and the value being produced by your
    *   constructors. For untrusted input, validate with the `Schema` module first.
    *
-   * **Example** (Basic usage)
+   * **Example** (Creating and matching tagged enum values)
    *
    * ```ts
    * import { Data } from "effect"
@@ -887,7 +887,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (Generic tagged enum)
+   * **Example** (Defining a generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -946,7 +946,7 @@ export const taggedEnum: {
    *   on the tag being globally unique and the value being produced by your
    *   constructors. For untrusted input, validate with the `Schema` module first.
    *
-   * **Example** (Basic usage)
+   * **Example** (Creating and matching tagged enum values)
    *
    * ```ts
    * import { Data } from "effect"
@@ -971,7 +971,7 @@ export const taggedEnum: {
    * console.log(msg) // "/missing not found"
    * ```
    *
-   * **Example** (Generic tagged enum)
+   * **Example** (Defining a generic tagged enum)
    *
    * ```ts
    * import { Data } from "effect"
@@ -1098,7 +1098,7 @@ export const Error: new<A extends Record<string, any> = {}>(
  * The `_tag` is excluded from the constructor argument. Yielding an instance
  * inside `Effect.gen` fails the effect with this error.
  *
- * **Example** (Tag-based error recovery)
+ * **Example** (Recovering by tag)
  *
  * ```ts
  * import { Data, Effect } from "effect"

package/src/DateTime.ts

@@ -3177,7 +3177,7 @@ export const mapEpochMillis: {
  * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
  * receive the UTC instant.
  *
- * **Example** (Using time zone adjusted Dates)
+ * **Example** (Applying time zone adjusted Dates)
  *
  * ```ts
  * import { DateTime } from "effect"
@@ -3202,7 +3202,7 @@ export const withDate: {
    * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
    * receive the UTC instant.
    *
-   * **Example** (Using time zone adjusted Dates)
+   * **Example** (Applying time zone adjusted Dates)
    *
    * ```ts
    * import { DateTime } from "effect"
@@ -3227,7 +3227,7 @@ export const withDate: {
    * `DateTime.Zoned` values. Use `DateTime.withDateUtc` when the callback should
    * receive the UTC instant.
    *
-   * **Example** (Using time zone adjusted Dates)
+   * **Example** (Applying time zone adjusted Dates)
    *
    * ```ts
    * import { DateTime } from "effect"
@@ -3253,7 +3253,7 @@ export const withDate: {
  * This ignores any associated time zone. Use `DateTime.withDate` when the
  * callback should receive the time-zone-adjusted wall-clock date.
  *
- * **Example** (Using UTC Dates)
+ * **Example** (Applying UTC Dates)
  *
  * ```ts
  * import { DateTime } from "effect"
@@ -3277,7 +3277,7 @@ export const withDateUtc: {
    * This ignores any associated time zone. Use `DateTime.withDate` when the
    * callback should receive the time-zone-adjusted wall-clock date.
    *
-   * **Example** (Using UTC Dates)
+   * **Example** (Applying UTC Dates)
    *
    * ```ts
    * import { DateTime } from "effect"
@@ -3301,7 +3301,7 @@ export const withDateUtc: {
    * This ignores any associated time zone. Use `DateTime.withDate` when the
    * callback should receive the time-zone-adjusted wall-clock date.
    *
-   * **Example** (Using UTC Dates)
+   * **Example** (Applying UTC Dates)
    *
    * ```ts
    * import { DateTime } from "effect"

package/src/Duration.ts

@@ -573,7 +573,7 @@ export const negate = (self: Duration): Duration => {
 /**
  * A Duration representing zero time.
  *
- * **Example** (Using the zero duration)
+ * **Example** (Referencing the zero duration)
  *
  * ```ts
  * import { Duration } from "effect"
@@ -589,7 +589,7 @@ export const zero: Duration = make(0)
 /**
  * A Duration representing infinite time.
  *
- * **Example** (Using infinite duration)
+ * **Example** (Referencing infinite duration)
  *
  * ```ts
  * import { Duration } from "effect"
@@ -605,7 +605,7 @@ export const infinity: Duration = make(Infinity)
 /**
  * A Duration representing negative infinite time.
  *
- * **Example** (Using negative infinite duration)
+ * **Example** (Referencing negative infinite duration)
  *
  * ```ts
  * import { Duration } from "effect"