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

package/dist/Config.js

@@ -1,11 +1,13 @@
 import * as ConfigProvider from "./ConfigProvider.js";
 import * as Effect from "./Effect.js";
 import * as Effectable from "./Effectable.js";
-import { dual } from "./Function.js";
+import { dual, memoize } from "./Function.js";
+import * as InternalRecord from "./internal/record.js";
 import * as LogLevel_ from "./LogLevel.js";
 import * as Option from "./Option.js";
 import * as Predicate from "./Predicate.js";
 import * as Rec from "./Record.js";
+import * as Result from "./Result.js";
 import * as Schema from "./Schema.js";
 import * as SchemaAST from "./SchemaAST.js";
 import * as SchemaGetter from "./SchemaGetter.js";
@@ -23,11 +25,11 @@ 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
@@ -49,7 +51,7 @@ export const isConfig = u => Predicate.hasProperty(u, TypeId);
  *   (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
@@ -82,11 +84,32 @@ const Proto = {
     };
   }
 };
-function make(parse) {
+function make(evaluator) {
   const self = Object.create(Proto);
-  self.parse = (provider, pathPrefix = []) => parse(provider, pathPrefix);
+  self.evaluator = evaluator;
+  self.parse = provider => evaluator(provider, []).pipe(Effect.mapErrorEager(failure => failure.error), Effect.flatMapEager(resolution => resolution._tag === "Resolved" ? Effect.succeed(resolution.value) : Effect.fail(resolution.error)));
   return self;
 }
+const evaluateAt = (self, provider, pathPrefix) => self.evaluator(provider, pathPrefix);
+const resolved = (value, hasInput) => ({
+  _tag: "Resolved",
+  value,
+  hasInput
+});
+const absent = error => ({
+  _tag: "Absent",
+  error
+});
+const evaluationFailure = (error, hasInput) => ({
+  error,
+  hasInput
+});
+const isSourceError = u => Predicate.isTagged(u, "SourceError");
+const catchSourceError = (self, hasInput) => self.pipe(Effect.catchDefect(defect => isSourceError(defect) ? Effect.fail(evaluationFailure(new ConfigError(defect), hasInput)) : Effect.die(defect)));
+const preserveInputEvidence = (self, hasInput) => {
+  if (!hasInput) return self;
+  return self.pipe(Effect.mapErrorEager(failure => evaluationFailure(failure.error, true)), Effect.flatMapEager(resolution => resolution._tag === "Resolved" ? Effect.succeed(resolved(resolution.value, true)) : Effect.fail(evaluationFailure(resolution.error, true))));
+};
 /**
  * Transforms the parsed value of a config with a pure function.
  *
@@ -97,7 +120,7 @@ function make(parse) {
  *
  * **Example** (Uppercasing a string config)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const upper = Config.string("name").pipe(
@@ -105,7 +128,7 @@ function make(parse) {
  * )
  *
  * 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
@@ -114,7 +137,7 @@ function make(parse) {
  * @since 2.0.0
  */
 export const map = /*#__PURE__*/dual(2, (self, f) => {
-  return make((provider, pathPrefix) => Effect.map(self.parse(provider, pathPrefix), f));
+  return make((provider, pathPrefix) => Effect.map(evaluateAt(self, provider, pathPrefix), resolution => resolution._tag === "Resolved" ? resolved(f(resolution.value), resolution.hasInput) : resolution));
 });
 /**
  * Transforms the parsed value with a function that may fail.
@@ -126,12 +149,14 @@ export const map = /*#__PURE__*/dual(2, (self, f) => {
  *
  * **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
@@ -140,7 +165,7 @@ export const map = /*#__PURE__*/dual(2, (self, f) => {
  * @since 2.0.0
  */
 export const mapOrFail = /*#__PURE__*/dual(2, (self, f) => {
-  return make((provider, pathPrefix) => Effect.flatMap(self.parse(provider, pathPrefix), f));
+  return make((provider, pathPrefix) => Effect.flatMap(evaluateAt(self, provider, pathPrefix), resolution => resolution._tag === "Resolved" ? f(resolution.value).pipe(Effect.mapEager(value => resolved(value, resolution.hasInput)), Effect.mapErrorEager(error => evaluationFailure(error, resolution.hasInput))) : Effect.succeed(resolution)));
 });
 /**
  * Provides a fallback config when parsing fails with a `ConfigError`.
@@ -152,27 +177,39 @@ export const mapOrFail = /*#__PURE__*/dual(2, (self, f) => {
  *
  * **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
  */
 export const orElse = /*#__PURE__*/dual(2, (self, that) => {
-  return make((provider, pathPrefix) => Effect.catch(self.parse(provider, pathPrefix), error => that(error).parse(provider, pathPrefix)));
+  return make((provider, pathPrefix) => Effect.matchEffect(evaluateAt(self, provider, pathPrefix), {
+    onFailure: failure => preserveInputEvidence(evaluateAt(that(failure.error), provider, pathPrefix), failure.hasInput),
+    onSuccess: resolution => resolution._tag === "Absent" ? evaluateAt(that(resolution.error), provider, pathPrefix) : Effect.succeed(resolution)
+  }));
 });
 /**
  * Combines multiple configs into a single config that parses all of them.
@@ -186,9 +223,19 @@ export const orElse = /*#__PURE__*/dual(2, (self, that) => {
  * 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({
@@ -197,8 +244,7 @@ export const orElse = /*#__PURE__*/dual(2, (self, that) => {
  * })
  *
  * 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
@@ -207,39 +253,69 @@ export const orElse = /*#__PURE__*/dual(2, (self, that) => {
 export function all(arg) {
   const configs = Array.isArray(arg) ? arg : Symbol.iterator in arg ? [...arg] : arg;
   if (Array.isArray(configs)) {
-    return make((provider, pathPrefix) => Effect.all(configs.map(config => config.parse(provider, pathPrefix))));
+    return make((provider, pathPrefix) => Effect.flatMapEager(Effect.all(configs.map(config => Effect.result(evaluateAt(config, provider, pathPrefix)))), resolveArray));
   } else {
-    return make((provider, pathPrefix) => Effect.all(Rec.map(configs, config => config.parse(provider, pathPrefix))));
+    return make((provider, pathPrefix) => Effect.flatMapEager(Effect.all(Rec.map(configs, config => Effect.result(evaluateAt(config, provider, pathPrefix)))), resolveRecord));
   }
 }
-function isMissingDataOnly(issue) {
-  switch (issue._tag) {
-    case "MissingKey":
-      return true;
-    case "InvalidType":
-    case "InvalidValue":
-      return Option.isNone(issue.actual) || Option.isSome(issue.actual) && issue.actual.value === undefined;
-    case "OneOf":
-      return issue.actual === undefined;
-    case "Encoding":
-      return Option.isNone(issue.actual) || Option.isSome(issue.actual) && issue.actual.value === undefined ? true : isMissingDataOnly(issue.issue);
-    case "Pointer":
-      return isMissingDataOnly(issue.issue);
-    case "Filter":
-    case "UnexpectedKey":
-    case "Forbidden":
-      return false;
-    case "Composite":
-      return issue.issues.every(isMissingDataOnly);
-    case "AnyOf":
-      if (issue.issues.length === 0) {
-        return issue.actual === undefined;
-      }
-      return issue.issues.every(isMissingDataOnly);
+const resolveArray = results => {
+  const values = [];
+  let firstFailure;
+  let firstAbsent;
+  let hasInput = false;
+  for (const result of results) {
+    if (Result.isFailure(result)) {
+      firstFailure ??= result.failure;
+      hasInput = hasInput || result.failure.hasInput;
+      continue;
+    }
+    const resolution = result.success;
+    if (resolution._tag === "Absent") {
+      firstAbsent ??= resolution;
+    } else {
+      values.push(resolution.value);
+      hasInput = hasInput || resolution.hasInput;
+    }
   }
-}
+  if (firstFailure !== undefined) {
+    return Effect.fail(evaluationFailure(firstFailure.error, hasInput));
+  }
+  if (firstAbsent !== undefined) {
+    return hasInput ? Effect.fail(evaluationFailure(firstAbsent.error, true)) : Effect.succeed(firstAbsent);
+  }
+  return Effect.succeed(resolved(values, hasInput));
+};
+const resolveRecord = results => {
+  const values = {};
+  let firstFailure;
+  let firstAbsent;
+  let hasInput = false;
+  for (const key in results) {
+    const result = results[key];
+    if (Result.isFailure(result)) {
+      firstFailure ??= result.failure;
+      hasInput = hasInput || result.failure.hasInput;
+      continue;
+    }
+    const resolution = result.success;
+    if (resolution._tag === "Absent") {
+      firstAbsent ??= resolution;
+    } else {
+      InternalRecord.assignProperty(values, key, resolution.value);
+      hasInput = hasInput || resolution.hasInput;
+    }
+  }
+  if (firstFailure !== undefined) {
+    return Effect.fail(evaluationFailure(firstFailure.error, hasInput));
+  }
+  if (firstAbsent !== undefined) {
+    return hasInput ? Effect.fail(evaluationFailure(firstAbsent.error, true)) : Effect.succeed(firstAbsent);
+  }
+  return Effect.succeed(resolved(values, hasInput));
+};
 /**
- * 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**
  *
@@ -247,41 +323,35 @@ function isMissingDataOnly(issue) {
  *
  * **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 const withDefault = /*#__PURE__*/dual(2, (self, defaultValue) => {
-  return orElse(self, err => {
-    if (Schema.isSchemaError(err.cause)) {
-      const issue = err.cause.issue;
-      if (isMissingDataOnly(issue)) {
-        return succeed(defaultValue);
-      }
-    }
-    return fail(err.cause);
-  });
+  return make((provider, pathPrefix) => Effect.mapEager(evaluateAt(self, provider, pathPrefix), resolution => resolution._tag === "Absent" ? resolved(defaultValue, false) : resolution));
 });
 /**
- * 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**
  *
@@ -289,18 +359,21 @@ export const withDefault = /*#__PURE__*/dual(2, (self, defaultValue) => {
  *
  * **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
@@ -324,8 +397,8 @@ export const option = self => self.pipe(map(Option.some), withDefault(Option.non
  *
  * **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
@@ -333,115 +406,124 @@ export const option = self => self.pipe(map(Option.some), withDefault(Option.non
  *
  * 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 const unwrap = wrapped => {
   if (isConfig(wrapped)) return wrapped;
-  return make((provider, pathPrefix) => {
-    const entries = Object.entries(wrapped);
-    const configs = entries.map(([key, config]) => unwrap(config).parse(provider, pathPrefix).pipe(Effect.map(value => [key, value])));
-    return Effect.all(configs).pipe(Effect.map(Object.fromEntries));
-  });
+  return all(Rec.map(wrapped, config => unwrap(config)));
 };
-// -----------------------------------------------------------------------------
-// schema
-// -----------------------------------------------------------------------------
-const dump = /*#__PURE__*/Effect.fnUntraced(function* (provider, path) {
-  const stat = yield* provider.load(path);
-  if (stat === undefined) return undefined;
-  switch (stat._tag) {
-    case "Value":
-      return stat.value;
-    case "Record":
-      {
-        if (stat.value !== undefined) return stat.value;
-        const out = {};
-        for (const key of stat.keys) {
-          const child = yield* dump(provider, [...path, key]);
-          if (child !== undefined) out[key] = child;
-        }
-        return out;
-      }
-    case "Array":
-      {
-        if (stat.value !== undefined) return stat.value;
-        const out = [];
-        for (let i = 0; i < stat.length; i++) {
-          out.push(yield* dump(provider, [...path, i]));
-        }
-        return out;
-      }
+const cursorToString = () => "<configuration>";
+const loadCursor = (provider, path) => provider.load(path).pipe(Effect.orDie, Effect.mapEager(node => ({
+  provider,
+  path,
+  node,
+  toString: cursorToString
+})));
+const loadChildCursor = (cursor, segment) => loadCursor(cursor.provider, [...cursor.path, segment]);
+const getScalar = node => node?.value;
+const decodeFromCursor = (ast, decode) => SchemaAST.decodeTo(SchemaAST.unknown, ast, new SchemaTransformation.Transformation(SchemaGetter.transformOrFail(input => decode(input)), SchemaGetter.passthrough()));
+const isScalarInput = ast => {
+  switch (ast._tag) {
+    case "Union":
+      return ast.types.every(isScalarInput);
+    case "Objects":
+    case "Arrays":
+    case "Suspend":
+      return false;
+    default:
+      return true;
   }
-});
-const recur = /*#__PURE__*/Effect.fnUntraced(function* (ast, provider, path) {
+};
+const hasProviderInput = (ast, node) => {
   switch (ast._tag) {
     case "Objects":
-      {
-        const stat = yield* provider.load(path);
-        if (stat === undefined && path.length > 0) return undefined;
-        const out = {};
-        for (const ps of ast.propertySignatures) {
-          const name = ps.name;
-          if (typeof name === "string") {
-            const value = yield* recur(ps.type, provider, [...path, name]);
-            if (value !== undefined) out[name] = value;
-          }
-        }
-        if (ast.indexSignatures.length > 0) {
-          if (stat && stat._tag === "Record") {
-            for (const is of ast.indexSignatures) {
-              const matches = SchemaParser._is(is.parameter);
-              for (const key of stat.keys) {
-                if (!Object.hasOwn(out, key) && matches(key)) {
-                  const value = yield* recur(is.type, provider, [...path, key]);
-                  if (value !== undefined) out[key] = value;
-                }
-              }
-            }
-          }
-        }
-        return out;
-      }
+      return node?._tag === "Record";
     case "Arrays":
-      {
-        const stat = yield* provider.load(path);
-        if (stat === undefined) return undefined;
-        if (stat && stat._tag === "Value") return stat.value === "" ? [] : stat.value.split(",");
-        if (stat && stat._tag === "Array" && stat.value !== undefined) {
-          return stat.value === "" ? [] : stat.value.split(",");
-        }
-        const out = [];
-        const length = stat && stat._tag === "Array" ? stat.length : ast.elements.length;
-        for (let i = 0; i < length; i++) {
-          const element = ast.elements[i] ?? ast.rest[0];
-          if (element !== undefined) {
-            out.push(yield* recur(element, provider, [...path, i]));
-          }
-        }
-        return out;
-      }
+      return node?._tag === "Array";
     case "Union":
-      // Let downstream decoding decide; dump can return a string, object, or array.
-      return yield* dump(provider, path);
+      return ast.types.some(ast => hasProviderInput(ast, node));
     case "Suspend":
-      return yield* recur(ast.thunk(), provider, path);
+      return hasProviderInput(ast.thunk(), node);
     default:
-      {
-        // Base primitives / string-like encoded nodes.
-        const stat = yield* provider.load(path);
-        if (stat === undefined) return undefined;
-        if (stat._tag === "Value") return stat.value;
-        if (stat._tag === "Record" && stat.value !== undefined) return stat.value;
-        if (stat._tag === "Array" && stat.value !== undefined) return stat.value;
-        // Container without a co-located value cannot satisfy a scalar request.
-        return undefined;
-      }
+      return getScalar(node) !== undefined;
   }
+};
+const toConfigCursorAST = /*#__PURE__*/memoize(root => {
+  const seen = new WeakSet();
+  const recur = SchemaAST.applyToSelfOrLastLinkEncoding(ast => {
+    seen.add(ast);
+    switch (ast._tag) {
+      case "Objects":
+        {
+          const matchesIndex = ast.indexSignatures.map(is => SchemaParser._is(is.parameter));
+          const materialize = Effect.fnUntraced(function* (cursor) {
+            if (cursor.node?._tag !== "Record") {
+              return undefined;
+            }
+            const node = cursor.node;
+            const keys = new Set();
+            for (const property of ast.propertySignatures) {
+              if (typeof property.name === "string") keys.add(property.name);
+            }
+            if (matchesIndex.length > 0) {
+              for (const key of node.keys) {
+                if (matchesIndex.some(matches => matches(key))) keys.add(key);
+              }
+            }
+            const out = {};
+            for (const key of keys) {
+              const child = yield* loadChildCursor(cursor, key);
+              if (child.node !== undefined) InternalRecord.assignProperty(out, key, child);
+            }
+            return out;
+          });
+          return decodeFromCursor(ast.recur(recur, ast => ast), materialize);
+        }
+      case "Arrays":
+        {
+          const materialize = Effect.fnUntraced(function* (cursor) {
+            if (cursor.node?._tag !== "Array") {
+              return undefined;
+            }
+            const out = [];
+            for (let i = 0; i < cursor.node.length; i++) {
+              out.push(yield* loadChildCursor(cursor, i));
+            }
+            return out;
+          });
+          return decodeFromCursor(ast.recur(recur), materialize);
+        }
+      case "Union":
+        for (const member of ast.types) {
+          recur(member);
+        }
+        return isScalarInput(ast) ? decodeFromCursor(ast, cursor => Effect.succeed(getScalar(cursor.node))) : ast.recur(recur);
+      case "Suspend":
+        {
+          const target = ast.thunk();
+          // Force new branches so opaque encodings fail when the Config is constructed.
+          if (!seen.has(target)) recur(target);
+          return ast.recur(recur);
+        }
+      case "Declaration":
+      case "Any":
+        throw new globalThis.Error("Config.schema does not support opaque StringTree encodings", {
+          cause: ast
+        });
+      default:
+        return decodeFromCursor(ast, cursor => Effect.succeed(getScalar(cursor.node)));
+    }
+  });
+  return recur(root);
 });
 /**
  * Creates a `Config<T>` from a `Schema.Codec`.
@@ -460,12 +542,47 @@ const recur = /*#__PURE__*/Effect.fnUntraced(function* (ast, provider, path) {
  * 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(
@@ -480,8 +597,7 @@ const recur = /*#__PURE__*/Effect.fnUntraced(function* (ast, provider, path) {
  *   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
@@ -492,12 +608,18 @@ const recur = /*#__PURE__*/Effect.fnUntraced(function* (ast, provider, path) {
  */
 export function schema(codec, path) {
   const codecStringTree = Schema.toCodecStringTree(codec);
-  const decodeUnknownEffect = SchemaParser.decodeUnknownEffect(codecStringTree);
-  const codecStringTreeEncoded = SchemaAST.toEncoded(codecStringTree.ast);
+  const encodedAst = SchemaAST.toEncoded(codecStringTree.ast);
+  const decodeCursor = SchemaParser.decodeUnknownEffect(Schema.make(toConfigCursorAST(codecStringTree.ast)));
   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(fullPath.length > 0 ? new SchemaIssue.Pointer(fullPath, issue) : issue)))), Effect.mapErrorEager(cause => new ConfigError(cause)));
+    return catchSourceError(loadCursor(provider, fullPath), false).pipe(Effect.flatMapEager(cursor => {
+      const hasInput = hasProviderInput(encodedAst, cursor.node);
+      return catchSourceError(decodeCursor(cursor).pipe(Effect.mapEager(value => resolved(value, hasInput)), Effect.catchEager(issue => {
+        const error = new ConfigError(new Schema.SchemaError(fullPath.length > 0 ? new SchemaIssue.Pointer(fullPath, issue) : issue));
+        return hasInput ? Effect.fail(evaluationFailure(error, true)) : Effect.succeed(absent(error));
+      })), hasInput);
+    }));
   });
 }
 /** @internal */
@@ -579,7 +701,7 @@ export const LogLevel = /*#__PURE__*/Schema.Literals(LogLevel_.values);
  *
  * **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)
@@ -592,33 +714,37 @@ export const LogLevel = /*#__PURE__*/Schema.Literals(LogLevel_.values);
  *   }
  * })
  *
- * 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 const Record = (key, value, options) => {
   const record = Schema.Record(key, value);
-  const recordString = Schema.String.pipe(Schema.decodeTo(Schema.Record(Schema.String, Schema.String), SchemaTransformation.splitKeyValue(options)), Schema.decodeTo(record));
+  const split = SchemaTransformation.splitKeyValue(options);
+  const recordString = Schema.String.pipe(Schema.decodeTo(Schema.toCodecStringTree(record), {
+    decode: split.decode,
+    encode: SchemaGetter.passthrough({
+      strict: false
+    }).compose(split.encode)
+  }));
   return Schema.Union([record, recordString]);
 };
-/**
- * @category schemas
- * @since 4.0.0
- */
 const ArrayConfig = (value, options) => {
   const array = Schema.Array(value);
   const separator = options?.separator ?? ",";
-  const arrayString = Schema.String.pipe(Schema.decodeTo(Schema.Array(Schema.String), {
+  const arrayString = Schema.String.pipe(Schema.decodeTo(Schema.toCodecStringTree(array), {
     decode: SchemaGetter.split(options),
-    encode: SchemaGetter.transform(input => input.join(separator))
-  }), Schema.decodeTo(array));
+    encode: SchemaGetter.passthrough({
+      strict: false
+    }).compose(SchemaGetter.transform(input => input.join(separator)))
+  }));
   return Schema.Union([arrayString, array]);
 };
 export {
@@ -635,6 +761,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
  */
@@ -654,7 +782,7 @@ ArrayConfig as Array };
  * @since 2.0.0
  */
 export function fail(err) {
-  return make(() => Effect.fail(new ConfigError(err)));
+  return make(() => Effect.fail(evaluationFailure(new ConfigError(err), false)));
 }
 /**
  * Creates a config that always succeeds with the given value, ignoring the
@@ -667,19 +795,21 @@ export function fail(err) {
  *
  * **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
  * @since 2.0.0
  */
 export function succeed(value) {
-  return make(() => Effect.succeed(value));
+  return make(() => Effect.succeed(resolved(value, false)));
 }
 /**
  * Creates a config for a single string value.
@@ -694,13 +824,13 @@ export function succeed(value) {
  *
  * **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
@@ -806,10 +936,12 @@ export function int(name) {
  *
  * **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
@@ -832,10 +964,12 @@ export function literal(literal, name) {
  *
  * **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
@@ -863,13 +997,10 @@ export function literals(literals, name) {
  *
  * **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: {
@@ -879,8 +1010,7 @@ export function literals(literals, name) {
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output: true
+ * ) // => true
  * ```
  *
  * @see {@link Boolean} for the underlying boolean codec
@@ -908,13 +1038,10 @@ export function boolean(name) {
  *
  * **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: {
@@ -924,8 +1051,7 @@ export function boolean(name) {
  *
  * 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
@@ -949,13 +1075,10 @@ export function duration(name) {
  *
  * **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: {
@@ -965,8 +1088,7 @@ export function duration(name) {
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output: 8080
+ * ) // => 8080
  * ```
  *
  * @see {@link int} for integer config values outside the port range
@@ -994,13 +1116,10 @@ export function port(name) {
  *
  * **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: {
@@ -1010,8 +1129,7 @@ export function port(name) {
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output: "Info"
+ * ) // => "Info"
  * ```
  *
  * @see {@link LogLevel} for the underlying log-level codec
@@ -1037,13 +1155,10 @@ export function logLevel(name) {
  *
  * **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: {
@@ -1053,8 +1168,7 @@ export function logLevel(name) {
  *
  * Effect.runSync(
  *   program.pipe(Effect.provideService(ConfigProvider.ConfigProvider, provider))
- * )
- * // Output: <redacted>
+ * ) // => "<redacted>"
  * ```
  *
  * @see {@link string} for non-secret string settings
@@ -1082,13 +1196,10 @@ export function redacted(name) {
  *
  * **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: {
@@ -1098,22 +1209,7 @@ export function redacted(name) {
  *
  * 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
@@ -1133,7 +1229,7 @@ export function url(name) {
  *
  * **Details**
  *
- * Shortcut for `Config.schema(Schema.DateValid, name)`.
+ * Shortcut for `Config.schema(Schema.Date, name)`.
  *
  * **Gotchas**
  *
@@ -1141,21 +1237,20 @@ export function url(name) {
  *
  * **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
  * @since 2.0.0
  */
 export function date(name) {
-  return schema(Schema.DateValid, name);
+  return schema(Schema.Date, name);
 }
 /**
  * Scopes a config under a named prefix.
@@ -1175,7 +1270,7 @@ export function date(name) {
  *
  * **Example** (Nesting a struct config under `"database"`)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Config, ConfigProvider, Effect } from "effect"
  *
  * const dbConfig = Config.all({
@@ -1186,13 +1281,12 @@ export function date(name) {
  * 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"))
@@ -1200,7 +1294,7 @@ export function date(name) {
  * 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
@@ -1209,5 +1303,5 @@ export function date(name) {
  * @category combinators
  * @since 2.0.0
  */
-export const nested = /*#__PURE__*/dual(2, (self, name) => make((provider, pathPrefix) => self.parse(provider, [...pathPrefix, name])));
+export const nested = /*#__PURE__*/dual(2, (self, name) => make((provider, pathPrefix) => evaluateAt(self, provider, [...pathPrefix, name])));
 //# sourceMappingURL=Config.js.map