effect 4.0.0-beta.65 → 4.0.0-beta.67

package/dist/Schema.js

@@ -650,12 +650,14 @@ export const asserts = Parser.asserts;
  * succeeds with the decoded value or fails with a {@link SchemaError}. Use this
  * when the input type is not statically known. Prefer {@link decodeEffect} when
  * the input is already typed as the schema's `Encoded` type.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
  */
-export function decodeUnknownEffect(schema) {
-  const parser = Parser.decodeUnknownEffect(schema);
+export function decodeUnknownEffect(schema, options) {
+  const parser = Parser.decodeUnknownEffect(schema, options);
   return (input, options) => {
     return Effect.mapErrorEager(parser(input, options), issue => new SchemaError(issue));
   };
@@ -665,6 +667,8 @@ export function decodeUnknownEffect(schema) {
  * returning an `Effect` that succeeds with the decoded value or fails with a
  * {@link SchemaError}. Use this when the input is already typed; for `unknown`
  * input use {@link decodeUnknownEffect}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
@@ -676,12 +680,14 @@ export const decodeEffect = decodeUnknownEffect;
  * a {@link SchemaError}. Only usable with schemas that have no
  * `DecodingServices` requirement. Prefer {@link decodeExit} when the input is
  * already typed as the schema's `Encoded` type.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
  */
-export function decodeUnknownExit(schema) {
-  const parser = Parser.decodeUnknownExit(schema);
+export function decodeUnknownExit(schema, options) {
+  const parser = Parser.decodeUnknownExit(schema, options);
   return (input, options) => {
     return Exit_.mapError(parser(input, options), issue => new SchemaError(issue));
   };
@@ -692,6 +698,8 @@ export function decodeUnknownExit(schema) {
  * decoded value or a `Failure` with a {@link SchemaError}. Only usable with
  * schemas that have no `DecodingServices` requirement. For `unknown` input use
  * {@link decodeUnknownExit}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
@@ -703,6 +711,8 @@ export const decodeExit = decodeUnknownExit;
  * over {@link decodeUnknownExit} or {@link decodeUnknownEffect} when you only
  * need to know whether decoding succeeded and don't need error details. For
  * typed input use {@link decodeOption}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
@@ -712,27 +722,43 @@ export const decodeUnknownOption = Parser.decodeUnknownOption;
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning an `Option` that is `Some` with the decoded value on success or
  * `None` on failure. For `unknown` input use {@link decodeUnknownOption}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeOption = Parser.decodeOption;
 /**
- * Decodes an `unknown` input against a schema, returning a `Promise` that
- * resolves with the decoded value or rejects with a {@link SchemaError}. Useful
- * for integrating with Promise-based APIs. For typed input use
- * {@link decodePromise}.
+ * Decodes an `unknown` input against a schema, returning a `Result` that
+ * succeeds with the decoded value or fails with a schema issue. For typed input
+ * use {@link decodeResult}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeUnknownResult = Parser.decodeUnknownResult;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning a `Result` that succeeds with the decoded value or fails with a
+ * schema issue. For `unknown` input use {@link decodeUnknownResult}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeResult = Parser.decodeResult;
 /**
+ * Decodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the decoded value or rejects with a schema issue. Useful for
+ * integrating with Promise-based APIs. For typed input use
+ * {@link decodePromise}.
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -740,19 +766,27 @@ export const decodeUnknownPromise = Parser.decodeUnknownPromise;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema,
  * returning a `Promise` that resolves with the decoded value or rejects with a
- * {@link SchemaError}. For `unknown` input use {@link decodeUnknownPromise}.
+ * schema issue. For `unknown` input use `decodeUnknownPromise`.
+ *
+ * **Details**
+ * Options may be provided either when creating the decoder or when applying it;
+ * application options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodePromise = Parser.decodePromise;
 /**
- * Decodes an `unknown` input against a schema synchronously, throwing a
- * {@link SchemaError} on failure. Use this when you want to validate data at a
- * boundary and treat a schema mismatch as an unrecoverable error. For
- * non-throwing alternatives see {@link decodeUnknownOption},
- * {@link decodeUnknownExit}, or {@link decodeUnknownEffect}. For typed input
- * use {@link decodeSync}.
+ * Decodes an `unknown` input against a schema synchronously, returning the
+ * decoded value or throwing an `Error` whose cause contains the schema issue.
+ * Use this when you want to validate data at a boundary and treat a schema
+ * mismatch as an exception. For typed input use `decodeSync`.
+ *
+ * **Details**
+ * Only service-free schemas can be decoded synchronously. For non-throwing
+ * alternatives see `decodeUnknownOption`, `decodeUnknownExit`, or
+ * `decodeUnknownEffect`. Options may be provided either when creating the
+ * decoder or when applying it; application options override creation options.
  *
  * **Example** (Decoding with a transformation schema)
  *
@@ -777,8 +811,13 @@ export const decodePromise = Parser.decodePromise;
 export const decodeUnknownSync = Parser.decodeUnknownSync;
 /**
  * Decodes a typed input (the schema's `Encoded` type) against a schema
- * synchronously, throwing a {@link SchemaError} on failure. For `unknown` input
- * use {@link decodeUnknownSync}.
+ * synchronously, returning the decoded value or throwing an `Error` whose cause
+ * contains the schema issue. For `unknown` input use `decodeUnknownSync`.
+ *
+ * **Details**
+ * Only service-free schemas can be decoded synchronously. Options may be
+ * provided either when creating the decoder or when applying it; application
+ * options override creation options.
  *
  * @category Decoding
  * @since 4.0.0
@@ -789,6 +828,8 @@ export const decodeSync = Parser.decodeSync;
  * succeeds with the encoded value or fails with a {@link SchemaError}. Use this
  * when the input type is not statically known. Prefer {@link encodeEffect} when
  * the input is already typed as the schema's `Type`.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * **Example** (Encoding a value to a string)
  *
@@ -804,8 +845,8 @@ export const decodeSync = Parser.decodeSync;
  * @category Encoding
  * @since 4.0.0
  */
-export function encodeUnknownEffect(schema) {
-  const parser = Parser.encodeUnknownEffect(schema);
+export function encodeUnknownEffect(schema, options) {
+  const parser = Parser.encodeUnknownEffect(schema, options);
   return (input, options) => {
     return Effect.mapErrorEager(parser(input, options), issue => new SchemaError(issue));
   };
@@ -815,6 +856,8 @@ export function encodeUnknownEffect(schema) {
  * `Effect` that succeeds with the encoded value or fails with a
  * {@link SchemaError}. Use this when the input is already typed; for `unknown`
  * input use {@link encodeUnknownEffect}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -826,12 +869,14 @@ export const encodeEffect = encodeUnknownEffect;
  * a {@link SchemaError}. Only usable with schemas that have no
  * `EncodingServices` requirement. Prefer {@link encodeExit} when the input is
  * already typed as the schema's `Type`.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
  */
-export function encodeUnknownExit(schema) {
-  const parser = Parser.encodeUnknownExit(schema);
+export function encodeUnknownExit(schema, options) {
+  const parser = Parser.encodeUnknownExit(schema, options);
   return (input, options) => {
     return Exit_.mapError(parser(input, options), issue => new SchemaError(issue));
   };
@@ -842,6 +887,8 @@ export function encodeUnknownExit(schema) {
  * `Failure` with a {@link SchemaError}. Only usable with schemas that have no
  * `EncodingServices` requirement. For `unknown` input use
  * {@link encodeUnknownExit}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -853,6 +900,8 @@ export const encodeExit = encodeUnknownExit;
  * over {@link encodeUnknownExit} or {@link encodeUnknownEffect} when you only
  * need to know whether encoding succeeded and don't need error details. For
  * typed input use {@link encodeOption}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -862,27 +911,43 @@ export const encodeUnknownOption = Parser.encodeUnknownOption;
  * Encodes a typed input (the schema's `Type`) against a schema, returning an
  * `Option` that is `Some` with the encoded value on success or `None` on
  * failure. For `unknown` input use {@link encodeUnknownOption}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeOption = Parser.encodeOption;
 /**
- * Encodes an `unknown` input against a schema, returning a `Promise` that
- * resolves with the encoded value or rejects with a {@link SchemaError}. Useful
- * for integrating with Promise-based APIs. For typed input use
- * {@link encodePromise}.
+ * Encodes an `unknown` input against a schema, returning a `Result` that
+ * succeeds with the encoded value or fails with a schema issue. For typed input
+ * use {@link encodeResult}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeUnknownResult = Parser.encodeUnknownResult;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning a
+ * `Result` that succeeds with the encoded value or fails with a schema issue.
+ * For `unknown` input use {@link encodeUnknownResult}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeResult = Parser.encodeResult;
 /**
+ * Encodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the encoded value or rejects with a schema issue. Useful for
+ * integrating with Promise-based APIs. For typed input use
+ * {@link encodePromise}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -891,6 +956,8 @@ export const encodeUnknownPromise = Parser.encodeUnknownPromise;
  * Encodes a typed input (the schema's `Type`) against a schema, returning a
  * `Promise` that resolves with the encoded value or rejects with a
  * {@link SchemaError}. For `unknown` input use {@link encodeUnknownPromise}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -903,6 +970,8 @@ export const encodePromise = Parser.encodePromise;
  * non-throwing alternatives see {@link encodeUnknownOption},
  * {@link encodeUnknownExit}, or {@link encodeUnknownEffect}. For typed input
  * use {@link encodeSync}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -912,6 +981,8 @@ export const encodeUnknownSync = Parser.encodeUnknownSync;
  * Encodes a typed input (the schema's `Type`) against a schema synchronously,
  * throwing a {@link SchemaError} on failure. For `unknown` input use
  * {@link encodeUnknownSync}.
+ * Options may be provided either when creating the encoder or when applying it;
+ * application options override creation options.
  *
  * @category Encoding
  * @since 4.0.0
@@ -1531,9 +1602,14 @@ export function Tuple(elements) {
   return makeTuple(AST.tuple(elements), elements);
 }
 /**
- * Extends a fixed-length tuple schema with rest elements, creating a variadic
- * tuple that starts with the fixed elements and ends with zero or more rest
- * elements.
+ * Extends a fixed-length tuple schema with a variadic rest segment.
+ *
+ * **Details**
+ * The resulting tuple starts with the fixed elements from `schema`. The first
+ * schema in `rest` is the repeatable element schema, and any additional schemas
+ * in `rest` are required trailing tuple elements after the variadic segment. For
+ * example, `[Schema.Boolean, Schema.String]` represents zero or more booleans
+ * followed by a final string.
  *
  * **Example** (Tuple with rest)
  *
@@ -1609,15 +1685,16 @@ export const NonEmptyArray = /*#__PURE__*/Struct_.lambda(schema => make(new AST.
   schema
 }));
 /**
- * Decodes a single value or an array of values into an array.
+ * Creates a schema that accepts either a value decoded by `schema` or an array
+ * decoded by `Schema.Array(schema)`, then returns an array.
  *
- * Decoding:
- * - a single value is decoded as a one-element array
- * - an array is decoded as-is
+ * **Details**
+ * The single-value branch is tried before the array branch. If `schema` itself
+ * accepts arrays, an array input can be treated as one value and wrapped in a
+ * one-element array.
  *
- * Encoding:
- * - a one-element array is encoded as a single value
- * - arrays with more than one element are encoded as arrays
+ * During encoding, one-element arrays are encoded as the single element. Empty
+ * arrays and arrays with two or more elements are encoded as arrays.
  *
  * @category Arrays
  * @since 4.0.0
@@ -1795,6 +1872,12 @@ export function check(...checks) {
  * Narrows the TypeScript type of a schema's output via a type guard predicate,
  * attaching the guard as a runtime filter check.
  *
+ * The `annotations` parameter annotates the filter created by the refinement.
+ * With the default formatter, failed refinements use `message` first,
+ * `expected` second, and `<filter>` when neither is provided. `identifier`
+ * names type-level failures before the refinement runs; it does not name the
+ * failed refinement itself.
+ *
  * @category Filtering
  * @since 4.0.0
  */
@@ -2042,7 +2125,7 @@ export function withConstructorDefault(
 // `S["~type.make.in"]` instead of `S["Type"]` is intentional here because
 // it makes easier to define the default value if there are nested defaults
 defaultValue) {
-  return schema => make(AST.withConstructorDefault(schema.ast, defaultValue), {
+  return schema => make(AST.withConstructorDefault(schema.ast, Effect.mapErrorEager(defaultValue, e => e.issue)), {
     schema
   });
 }
@@ -2081,7 +2164,7 @@ export function withDecodingDefaultKey(defaultValue, options) {
   const encode = options?.encodingStrategy === "omit" ? Getter.omit() : Getter.passthrough();
   return self => {
     return optionalKey(toEncoded(self)).pipe(decodeTo(self, {
-      decode: Getter.withDefault(defaultValue),
+      decode: Getter.withDefault(Effect.mapErrorEager(defaultValue, e => e.issue)),
       encode
     }));
   };
@@ -2145,7 +2228,7 @@ export function withDecodingDefault(defaultValue, options) {
   const encode = options?.encodingStrategy === "omit" ? Getter.omit() : Getter.passthrough();
   return self => {
     return optional(toEncoded(self)).pipe(decodeTo(self, {
-      decode: Getter.withDefault(defaultValue),
+      decode: Getter.withDefault(Effect.mapErrorEager(defaultValue, e => e.issue)),
       encode
     }));
   };
@@ -2450,9 +2533,17 @@ export function link() {
 // Checks
 // -----------------------------------------------------------------------------
 /**
- * Creates a custom filter check from a predicate function. The predicate
- * receives the input value, the schema's AST, and parse options, and returns
- * a value of type {@link FilterOutput}.
+ * Creates a custom validation filter from a predicate function.
+ *
+ * **Details**
+ * The predicate receives the decoded input value, the schema AST, and parse
+ * options, and returns a `FilterOutput`. Non-success outputs are normalized into
+ * schema issues. The `annotations` parameter annotates the filter itself; with
+ * the default formatter, failures use `message` first, `expected` second, and
+ * `<filter>` when neither is provided.
+ *
+ * When `abort` is `true`, parsing stops after this filter fails instead of
+ * collecting later check failures.
  *
  * **Example** (Failure at a nested path)
  *
@@ -2575,34 +2666,29 @@ export const isPattern = AST.isPattern;
  */
 export const isStringFinite = AST.isStringFinite;
 /**
- * Validates that a string represents a valid BigInt (can be parsed as a BigInt).
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings representing BigInt values.
+ * Validates that a string is a signed base-10 integer literal for Effect's
+ * BigInt string encoding.
  *
- * **Arbitrary**
+ * **Details**
+ * The check uses the pattern `^-?\d+$`. It does not accept leading `+`, decimal
+ * points, exponent notation, separators, or non-decimal inputs such as
+ * hexadecimal strings.
  *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings match the BigInt string pattern.
+ * **JSON Schema**
+ * This check corresponds to a `pattern` constraint with the same signed
+ * base-10 integer pattern.
  *
  * @category String checks
  * @since 4.0.0
  */
 export const isStringBigInt = AST.isStringBigInt;
 /**
- * Validates that a string represents a valid Symbol (can be parsed as a Symbol).
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings representing Symbol values.
+ * Validates that a string has the `Symbol(description)` format used by Effect's
+ * symbol string encoding.
  *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings match the Symbol string pattern.
+ * **Details**
+ * The check uses the pattern `^Symbol\((.*)\)$`. It is not a general test for
+ * whether a string can be passed to JavaScript's `Symbol()` function.
  *
  * @category String checks
  * @since 4.0.0
@@ -2732,17 +2818,12 @@ export function isBase64Url(annotations) {
   });
 }
 /**
- * Validates that a string starts with the specified prefix.
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings starting with the specified prefix.
+ * Validates at runtime that a string starts with the specified literal prefix.
  *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings start with the required prefix.
+ * **Notes**
+ * The JSON Schema and arbitrary metadata are built from `^${startsWith}` without
+ * escaping regexp metacharacters. If the prefix contains regexp syntax, generated
+ * patterns may not be equivalent to the runtime `startsWith` check.
  *
  * @category String checks
  * @since 4.0.0
@@ -2765,17 +2846,12 @@ export function isStartsWith(startsWith, annotations) {
   });
 }
 /**
- * Validates that a string ends with the specified suffix.
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings ending with the specified suffix.
+ * Validates at runtime that a string ends with the specified literal suffix.
  *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings end with the required suffix.
+ * **Notes**
+ * The JSON Schema and arbitrary metadata are built from `${endsWith}$` without
+ * escaping regexp metacharacters. If the suffix contains regexp syntax, generated
+ * patterns may not be equivalent to the runtime `endsWith` check.
  *
  * @category String checks
  * @since 4.0.0
@@ -2798,17 +2874,12 @@ export function isEndsWith(endsWith, annotations) {
   });
 }
 /**
- * Validates that a string contains the specified substring.
+ * Validates at runtime that a string contains the specified literal substring.
  *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings containing the specified substring.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings contain the required substring.
+ * **Notes**
+ * The JSON Schema and arbitrary metadata use the substring as a raw regexp
+ * pattern. If the substring contains regexp syntax, generated patterns may not be
+ * equivalent to the runtime `includes` check.
  *
  * @category String checks
  * @since 4.0.0
@@ -2832,17 +2903,12 @@ export function isIncludes(includes, annotations) {
 }
 const UPPERCASED_PATTERN = "^[^a-z]*$";
 /**
- * Validates that a string contains only uppercase characters.
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with only uppercase characters.
+ * Validates that a string is unchanged by JavaScript's `toUpperCase()`.
  *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings contain only uppercase characters.
+ * **Details**
+ * This accepts empty strings and characters that do not have lowercase forms,
+ * such as digits, punctuation, and whitespace. It rejects strings that would
+ * change when uppercased.
  *
  * @category String checks
  * @since 4.0.0
@@ -2864,17 +2930,12 @@ export function isUppercased(annotations) {
 }
 const LOWERCASED_PATTERN = "^[^A-Z]*$";
 /**
- * Validates that a string contains only lowercase characters.
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with only lowercase characters.
+ * Validates that a string is unchanged by JavaScript's `toLowerCase()`.
  *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings contain only lowercase characters.
+ * **Details**
+ * This accepts empty strings and characters that do not have uppercase forms,
+ * such as digits, punctuation, and whitespace. It rejects strings that would
+ * change when lowercased.
  *
  * @category String checks
  * @since 4.0.0
@@ -2896,17 +2957,12 @@ export function isLowercased(annotations) {
 }
 const CAPITALIZED_PATTERN = "^[^a-z]?.*$";
 /**
- * Validates that a string has its first character in uppercase.
- *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with the first character in uppercase.
+ * Validates that the first character of a string is unchanged by
+ * `toUpperCase()`.
  *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings have the first character in uppercase.
+ * **Details**
+ * Empty strings pass. Strings whose first character has no lowercase form, such
+ * as a digit, punctuation mark, or whitespace, also pass.
  *
  * @category String checks
  * @since 4.0.0
@@ -2928,17 +2984,12 @@ export function isCapitalized(annotations) {
 }
 const UNCAPITALIZED_PATTERN = "^[^A-Z]?.*$";
 /**
- * Validates that a string has its first character in lowercase.
+ * Validates that the first character of a string is unchanged by
+ * `toLowerCase()`.
  *
- * **JSON Schema**
- *
- * This check corresponds to a `pattern` constraint in JSON Schema that matches
- * strings with the first character in lowercase.
- *
- * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `patterns`
- * constraint to ensure generated strings have the first character in lowercase.
+ * **Details**
+ * Empty strings pass. Strings whose first character has no uppercase form, such
+ * as a digit, punctuation mark, or whitespace, also pass.
  *
  * @category String checks
  * @since 4.0.0
@@ -3732,7 +3783,11 @@ export const isLessThanOrEqualToBigDecimal = /*#__PURE__*/makeIsLessThanOrEqualT
   formatter: bd => BigDecimal_.format(bd)
 });
 /**
- * Validates that a BigDecimal is within a specified range.
+ * Validates that a `BigDecimal` is within a specified range.
+ *
+ * **Details**
+ * The minimum and maximum boundaries are inclusive by default. Pass
+ * `exclusiveMinimum` or `exclusiveMaximum` to exclude either boundary.
  *
  * @category BigDecimal checks
  * @since 4.0.0
@@ -4105,12 +4160,16 @@ export function isPropertiesLengthBetween(minimum, maximum, annotations) {
   });
 }
 /**
- * Validates that all property names in an object satisfy the provided key
- * schema (encoded side of the schema).
+ * Validates that every own property key of an object satisfies the encoded side
+ * of the provided key schema.
  *
- * **JSON Schema**
+ * **Details**
+ * This check uses `Reflect.ownKeys`, so symbol keys are validated in addition to
+ * string property names.
  *
- * This check corresponds to the `propertyNames` constraint in JSON Schema.
+ * **JSON Schema**
+ * For string property names, this corresponds to the `propertyNames` constraint
+ * in JSON Schema.
  *
  * @category Object checks
  * @since 4.0.0
@@ -4143,18 +4202,14 @@ export function isPropertyNames(keySchema, annotations) {
   });
 }
 /**
- * Validates that all items in an array are unique according to the provided
- * equivalence function.
+ * Validates that all items in an array are unique according to Effect equality.
  *
  * **JSON Schema**
- *
  * This check corresponds to the `uniqueItems: true` constraint in JSON Schema.
  *
  * **Arbitrary**
- *
- * When generating test data with fast-check, this applies a `comparator`
- * constraint using the provided equivalence function to ensure generated arrays
- * contain only unique items.
+ * When generating test data with fast-check, this applies a comparator based on
+ * Effect equality to ensure generated arrays contain only unique items.
  *
  * @category Array checks
  * @since 4.0.0
@@ -4518,7 +4573,8 @@ export function RedactedFromValue(value, options) {
   }));
 }
 /**
- * Creates a schema for `Cause.Reason<E>`. See {@link CauseReason} for details.
+ * Creates a schema for `Cause.Reason` values using separate schemas for typed
+ * failures and unexpected defects.
  *
  * @category CauseReason
  * @since 4.0.0
@@ -4619,7 +4675,8 @@ function causeReasonToFormatter(error, defect) {
   };
 }
 /**
- * Creates a schema for `Cause<E>`. See {@link Cause} for details.
+ * Creates a schema for `Cause` values using separate schemas for typed failures
+ * and unexpected defects.
  *
  * @category Cause
  * @since 4.0.0
@@ -4680,10 +4737,12 @@ const ErrorJsonEncoded = /*#__PURE__*/Struct({
   stack: /*#__PURE__*/optionalKey(String)
 });
 /**
- * A schema that represents `Error` objects.
+ * A schema for JavaScript `Error` objects.
  *
- * The default json serializer decodes to a struct with `name` and `message`
- * properties (stack is omitted for security).
+ * **Default JSON serializer**
+ * Encodes an `Error` as an object with `message` and optional `name` properties,
+ * and decodes that object back into an `Error`. The stack trace is omitted from
+ * the encoded form for security.
  *
  * @category Schemas
  * @since 4.0.0
@@ -4701,10 +4760,12 @@ export const Error = /*#__PURE__*/instanceOf(globalThis.Error, {
   toArbitrary: () => fc => fc.string().map(message => new globalThis.Error(message))
 });
 /**
- * A schema that represents `Error` objects.
+ * A schema for JavaScript `Error` objects that preserves stack traces in the JSON
+ * encoded form.
  *
- * The default json serializer decodes to a struct with `name`, `message` and
- * `stack` properties.
+ * **Default JSON serializer**
+ * Encodes an `Error` as an object with `message`, optional `name`, and optional
+ * `stack` properties, and decodes that object back into an `Error`.
  *
  * @category Schemas
  * @since 4.0.0
@@ -4731,7 +4792,12 @@ const defectTransformation = /*#__PURE__*/new Transformation.Transformation(/*#_
   }
 }));
 /**
- * A schema that represents defects.
+ * A schema for defect values, accepting either JavaScript `Error` values encoded
+ * with `message` and optional `name`, or arbitrary unknown defect values.
+ *
+ * **Default JSON serializer**
+ * Unknown defects are serialized with `JSON.stringify` when possible and fall
+ * back to Effect's formatted representation when JSON serialization fails.
  *
  * @category Constructors
  * @since 4.0.0
@@ -4754,7 +4820,8 @@ export const DefectWithStack = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded
   toArbitrary: () => fc => fc.json()
 }), defectTransformation))]);
 /**
- * Creates a schema for `Exit<A, E>`. See {@link Exit} for details.
+ * Creates a schema for `Exit` values using schemas for the success value, typed
+ * failure, and unexpected defect channels.
  *
  * @category Exit
  * @since 4.0.0
@@ -4947,6 +5014,9 @@ export function HashMap(key, value) {
   });
 }
 /**
+ * Creates a schema that validates a `ReadonlySet` whose values conform to the
+ * provided element schema.
+ *
  * @category ReadonlySet
  * @since 4.0.0
  */
@@ -5148,8 +5218,8 @@ const URLString = /*#__PURE__*/String.annotate({
  *
  * - encodes `URL` as a `string`
  *
- * @since 4.0.0
  * @category URL
+ * @since 4.0.0
  */
 export const URL = /*#__PURE__*/instanceOf(globalThis.URL, {
   typeConstructor: {
@@ -5183,9 +5253,10 @@ const DateString = /*#__PURE__*/String.annotate({
 /**
  * A schema for JavaScript `Date` objects.
  *
- * This schema accepts any `Date` instance, including invalid dates (e.g., `new
- * Date("invalid")`). For validating only valid dates, use {@link DateValid}
- * instead. The default JSON serializer encodes `Date` as an ISO 8601 string.
+ * This schema accepts any `Date` instance, including invalid dates. For
+ * validating only valid dates, use `DateValid` instead. The default JSON
+ * serializer encodes valid dates as ISO 8601 strings; invalid dates encode as
+ * `"Invalid Date"`.
  *
  * **Example** (Date schema)
  *
@@ -5212,13 +5283,15 @@ export const Date = /*#__PURE__*/instanceOf(globalThis.Date, {
   toArbitrary: () => (fc, ctx) => fc.date(ctx?.constraints?.date)
 });
 /**
- * A transformation schema that parses an ISO 8601 string into a `Date`.
+ * A transformation schema that decodes a string into a JavaScript `Date`.
  *
- * Decoding:
- * - A `string` is decoded as a `Date`.
+ * **Decoding**
+ * The string is passed to JavaScript `Date` construction and may decode to an
+ * invalid `Date`. Compose with `DateValid` when invalid dates should be rejected.
  *
- * Encoding:
- * - A `Date` is encoded as a `string`.
+ * **Encoding**
+ * A valid `Date` is encoded as an ISO string; an invalid `Date` is encoded as
+ * `"Invalid Date"`.
  *
  * @category Date
  * @since 4.0.0
@@ -5334,13 +5407,15 @@ export const DurationFromString = /*#__PURE__*/DurationString.pipe(/*#__PURE__*/
 const bigint0 = /*#__PURE__*/globalThis.BigInt(0);
 /**
  * A transformation schema that decodes a non-negative `bigint` into a
- * `Duration`, treating the `bigint` value as the duration in nanoseconds.
+ * `Duration`, treating the bigint as nanoseconds.
  *
- * Decoding:
- * - A non-negative `bigint` representing nanoseconds is decoded as a `Duration`
+ * **Decoding**
+ * A non-negative `bigint` representing nanoseconds is decoded as a `Duration`.
  *
- * Encoding:
- * - A `Duration` is encoded to a non-negative `bigint` representing nanoseconds
+ * **Encoding**
+ * Finite durations are encoded as a non-negative `bigint` number of nanoseconds.
+ * Encoding fails when the duration cannot be represented as nanoseconds, such as
+ * `Duration.infinity`.
  *
  * @category Duration
  * @since 4.0.0
@@ -5805,13 +5880,16 @@ export const Finite = /*#__PURE__*/Number.check(/*#__PURE__*/isFinite());
  */
 export const Int = /*#__PURE__*/Number.check(/*#__PURE__*/isInt());
 /**
- * A transformation schema that parses a string into a number.
+ * A transformation schema that parses a string into a `number` using JavaScript
+ * number coercion.
  *
- * Decoding:
- * - A `string` is decoded as a finite number.
+ * **Decoding**
+ * A `string` is decoded as a number, including possible non-finite values such as
+ * `NaN`, `Infinity`, and `-Infinity`. Use `FiniteFromString` to reject non-finite
+ * numbers.
  *
- * Encoding:
- * - A number is encoded as a `string`.
+ * **Encoding**
+ * A number is encoded as a `string`.
  *
  * @category Number
  * @since 4.0.0
@@ -5950,13 +6028,19 @@ export const StringFromUriComponent = /*#__PURE__*/String.annotate({
   expected: "a URI component encoded string that will be decoded as a UTF-8 string"
 }).pipe(/*#__PURE__*/decodeTo(String, Transformation.stringFromUriComponent));
 /**
- * A union schema for JavaScript property keys: `number | symbol | string`.
+ * A union schema for property keys accepted by Effect schemas: finite `number`,
+ * `symbol`, or `string`.
  *
  * @category PropertyKey
  * @since 4.0.0
  */
 export const PropertyKey = /*#__PURE__*/Union([Finite, Symbol, String]);
 /**
+ * Schema for a Standard Schema v1 failure result.
+ *
+ * The result contains an `issues` array where each issue has a message and an
+ * optional path made of property keys or keyed path segments.
+ *
  * @category StandardSchema
  * @since 4.0.0
  */
@@ -6102,15 +6186,16 @@ export const DateTimeUtcFromDate = /*#__PURE__*/DateValid.pipe(/*#__PURE__*/deco
   encode: /*#__PURE__*/Getter.transform(DateTime.toDateUtc)
 }));
 /**
- * A transformation schema that decodes a string into a `DateTime.Utc`.
+ * A transformation schema that decodes a date-time string into a `DateTime.Utc`.
  *
  * Decoding:
- * - A `string` that can be parsed by `Date.parse` is decoded as a
- *   `DateTime.Utc`
+ *
+ * - A string accepted by `DateTime.make` is parsed and normalized to UTC. Strings
+ *   without an explicit zone are interpreted as UTC.
  *
  * Encoding:
- * - A `DateTime.Utc` is encoded as a `string` in ISO 8601 format, ignoring any
- *   time zone.
+ *
+ * - A `DateTime.Utc` is encoded as a UTC ISO 8601 string.
  *
  * @category DateTime
  * @since 4.0.0
@@ -6256,7 +6341,9 @@ const DateTimeZonedString = /*#__PURE__*/String.annotate({
  *
  * **Default JSON serializer**
  *
- * - encodes `DateTime.Zoned` as a string in the format
+ * - encodes offset zones as an ISO date-time with a numeric offset, such as
+ *   `YYYY-MM-DDTHH:mm:ss.sss+HH:MM`
+ * - encodes named zones by appending the IANA identifier in brackets, such as
  *   `YYYY-MM-DDTHH:mm:ss.sss+HH:MM[Time/Zone]`
  *
  * @category DateTime
@@ -6336,7 +6423,7 @@ function makeClass(Inherited, identifier, struct, annotations, proto) {
       return Parser.makeOption(getClassSchema(this))(input ?? {}, options);
     }
     static makeEffect(input, options) {
-      return Effect.mapErrorEager(Parser.makeEffect(getClassSchema(this))(input ?? {}, options), issue => new SchemaError(issue));
+      return getClassSchema(this).makeEffect(input ?? {}, options);
     }
     static annotate(annotations) {
       return this.rebuild(AST.annotate(this.ast, annotations));
@@ -6478,12 +6565,13 @@ export const Class = identifier => (schema, annotations) => {
  */
 export const TaggedClass = identifier => {
   return (tagValue, schema, annotations) => {
-    return Class(identifier ?? tagValue)(isStruct(schema) ? schema.mapFields(fields => ({
+    const struct = isStruct(schema) ? schema.mapFields(fields => ({
       _tag: tag(tagValue),
       ...fields
     }), {
       unsafePreserveChecks: true
-    }) : TaggedStruct(tagValue, schema), annotations);
+    }) : TaggedStruct(tagValue, schema);
+    return Class(identifier ?? tagValue)(struct, annotations);
   };
 };
 /**
@@ -6540,12 +6628,13 @@ export const ErrorClass = identifier => (schema, annotations) => {
  */
 export const TaggedErrorClass = identifier => {
   return (tagValue, schema, annotations) => {
-    return ErrorClass(identifier ?? tagValue)(isStruct(schema) ? schema.mapFields(fields => ({
+    const struct = isStruct(schema) ? schema.mapFields(fields => ({
       _tag: tag(tagValue),
       ...fields
     }), {
       unsafePreserveChecks: true
-    }) : TaggedStruct(tagValue, schema), annotations);
+    }) : TaggedStruct(tagValue, schema);
+    return ErrorClass(identifier ?? tagValue)(struct, annotations);
   };
 };
 /**
@@ -6590,10 +6679,11 @@ export function toArbitrary(schema) {
 // Formatter
 // -----------------------------------------------------------------------------
 /**
- * **Technical Note**
+ * Annotates a schema with a custom formatter used by `toFormatter`.
  *
- * This annotation cannot be added to `Annotations.Bottom` because it would make
- * the schema invariant.
+ * Use this when the formatter derived from the schema structure is not suitable.
+ * The annotation is applied through this helper because adding it directly to
+ * `Annotations.Bottom` would make schemas invariant.
  *
  * @category Formatter
  * @since 4.0.0
@@ -6800,9 +6890,11 @@ export function toRepresentation(schema) {
   return InternalStandard.fromAST(schema.ast);
 }
 /**
- * Returns a JSON Schema Document (draft-2020-12).
+ * Returns a JSON Schema document using draft 2020-12.
  *
- * You can use the `options` parameter to return a different target JSON Schema.
+ * The `options` parameter controls generation details such as additional
+ * properties and synthesized check descriptions; it does not change the draft
+ * target.
  *
  * @category JsonSchema
  * @since 4.0.0
@@ -6820,8 +6912,8 @@ export function toJsonSchemaDocument(schema, options) {
 // Canonical Codecs
 // -----------------------------------------------------------------------------
 /**
- * Derives a canonical JSON codec from a schema. The encoded form is `unknown`
- * (any JSON-compatible value), decoded to the schema's `Type`.
+ * Derives a canonical JSON codec from a schema. The encoded form is `Json`, and
+ * decoding produces the schema's `Type`.
  *
  * @category Canonical Codecs
  * @since 4.0.0
@@ -6920,9 +7012,11 @@ export function toCodecStringTree(schema, options) {
   return make(toCodecEnsureArray(options?.keepDeclarations === true ? serializerStringTreeKeepDeclarations(schema.ast) : serializerStringTree(schema.ast)));
 }
 /**
- * Derives an XML encoder from a codec. Encodes a value to an XML string by
- * first converting it through {@link toCodecStringTree}, then serializing the
- * resulting tree to XML.
+ * Derives an XML encoder from a codec.
+ *
+ * The returned function encodes a value through `toCodecStringTree` and returns
+ * an `Effect` that succeeds with the XML string or fails with `SchemaError` if
+ * codec encoding fails.
  *
  * @category Canonical Codecs
  * @since 4.0.0