effect 4.0.0-beta.69 → 4.0.0-beta.70

package/dist/SchemaAST.d.ts

@@ -81,6 +81,8 @@ import * as Transformation from "./SchemaTransformation.ts";
 /**
  * Discriminated union of all AST node types.
  *
+ * **Details**
+ *
  * Every `Schema` has an `.ast` property of this type. Use the guard functions
  * ({@link isString}, {@link isObjects}, etc.) to narrow to a specific variant,
  * then access variant-specific fields.
@@ -91,7 +93,6 @@ import * as Transformation from "./SchemaTransformation.ts";
  *
  * @see {@link Base}
  * @see {@link isAST}
- *
  * @category models
  * @since 3.10.0
  */
@@ -99,11 +100,12 @@ export type AST = Declaration | Null | Undefined | Void | Never | Unknown | Any
 /**
  * Returns `true` if the value is an {@link AST} node (any variant).
  *
+ * **Details**
+ *
  * Uses the internal `TypeId` brand to distinguish AST nodes from arbitrary
  * objects.
  *
  * @see {@link AST}
- *
  * @category guards
  * @since 4.0.0
  */
@@ -256,9 +258,12 @@ export declare const isUnion: (ast: AST) => ast is Union<AST>;
  */
 export declare const isSuspend: (ast: AST) => ast is Suspend;
 /**
- * A single step in an {@link Encoding} chain, pairing a target {@link AST}
- * with a `Transformation` or `Middleware` that converts values between the
- * current node and the target.
+ * A single step in an {@link Encoding} chain.
+ *
+ * **Details**
+ *
+ * A link pairs a target {@link AST} with a `Transformation` or `Middleware`
+ * that converts values between the current node and the target.
  *
  * - `to` — the AST node on the other side of this transformation step.
  * - `transformation` — the bidirectional conversion logic (decode/encode).
@@ -268,7 +273,6 @@ export declare const isSuspend: (ast: AST) => ast is Suspend;
  *
  * @see {@link Encoding}
  * @see {@link decodeTo}
- *
  * @category models
  * @since 4.0.0
  */
@@ -281,12 +285,13 @@ export declare class Link {
  * A non-empty chain of {@link Link} values representing the transformation
  * steps between a schema's decoded (type) form and its encoded (wire) form.
  *
+ * **Details**
+ *
  * Stored on {@link Base.encoding}. When `undefined`, the node has no
  * encoding transformation (type and encoded forms are identical).
  *
  * @see {@link Link}
  * @see {@link toEncoded}
- *
  * @category models
  * @since 4.0.0
  */
@@ -294,6 +299,8 @@ export type Encoding = readonly [Link, ...Array<Link>];
 /**
  * Options that control schema parsing, validation, transformation, and output behavior.
  *
+ * **Details**
+ *
  * Pass to `Schema.decodeUnknown`, `Schema.encode`, and related APIs to customize
  * error reporting, excess property handling, output key ordering, check
  * execution, and asynchronous parser concurrency.
@@ -314,30 +321,27 @@ export type Encoding = readonly [Link, ...Array<Link>];
  */
 export interface ParseOptions {
     /**
-     * The `errors` option allows you to receive all parsing errors when
-     * attempting to parse a value using a schema. By default only the first error
-     * is returned, but by setting the `errors` option to `"all"`, you can receive
-     * all errors that occurred during the parsing process. This can be useful for
-     * debugging or for providing more comprehensive error messages to the user.
+     * Controls how many parsing errors are reported.
+     *
+     * **Details**
+     *
+     * The default, `"first"`, stops at the first error. Set the option to `"all"`
+     * to collect every parsing error, which can help with debugging or with
+     * presenting more complete error messages to a user.
      *
-     * default: "first"
+     * @default "first"
      */
     readonly errors?: "first" | "all" | undefined;
     /**
-     * When using a `Objects` to parse a value, by default any properties that
-     * are not specified in the schema will be stripped out from the output. This
-     * is because the `Objects` is expecting a specific shape for the parsed
-     * value, and any excess properties do not conform to that shape.
+     * Controls how object parsing handles keys that are not declared by the schema.
      *
-     * However, you can use the `onExcessProperty` option (default value:
-     * `"ignore"`) to trigger a parsing error. This can be particularly useful in
-     * cases where you need to detect and handle potential errors or unexpected
-     * values.
+     * **Details**
      *
-     * If you want to allow excess properties to remain, you can use
-     * `onExcessProperty` set to `"preserve"`.
+     * The default, `"ignore"`, strips unspecified properties from the output. Use
+     * `"error"` to fail when an excess property is present, or `"preserve"` to
+     * keep excess properties in the output.
      *
-     * default: "ignore"
+     * @default "ignore"
      */
     readonly onExcessProperty?: "ignore" | "error" | "preserve" | undefined;
     /**
@@ -346,16 +350,20 @@ export interface ParseOptions {
      * important for the consuming processes or when maintaining the input order
      * enhances readability and usability.
      *
+     * **Details**
+     *
      * By default, the `propertyOrder` option is set to `"none"`. This means that
      * the internal system decides the order of keys to optimize parsing speed.
-     * The order of keys in this mode should not be considered stable, and it's
-     * recommended not to rely on key ordering as it may change in future updates
-     * without notice.
      *
      * Setting `propertyOrder` to `"original"` ensures that the keys are ordered
      * as they appear in the input during the decoding/encoding process.
      *
-     * default: "none"
+     * **Gotchas**
+     *
+     * The key order for `"none"` should not be considered stable and may change
+     * in future updates without notice.
+     *
+     * @default "none"
      */
     readonly propertyOrder?: "none" | "original" | undefined;
     /**
@@ -366,13 +374,15 @@ export interface ParseOptions {
     /**
      * The maximum number of async effects to run concurrently.
      *
-     * Defaults to 1.
+     * @default 1
      */
     readonly concurrency?: number | "unbounded" | undefined;
 }
 /**
  * Per-property metadata attached to AST nodes via {@link Base.context}.
  *
+ * **Details**
+ *
  * Tracks whether a property key is optional, mutable, has a constructor
  * default, or carries key-level annotations. Typically set by helpers like
  * {@link optionalKey} and `Schema.mutableKey`.
@@ -386,7 +396,6 @@ export interface ParseOptions {
  *
  * @see {@link optionalKey}
  * @see {@link isOptional}
- *
  * @category models
  * @since 4.0.0
  */
@@ -404,13 +413,14 @@ export declare class Context {
  * Non-empty array of validation {@link Check} values attached to an AST node
  * via {@link Base.checks}.
  *
+ * **Details**
+ *
  * Checks are run after basic type matching succeeds. They represent
  * refinements like `minLength`, `pattern`, `int`, etc.
  *
  * @see {@link Check}
  * @see {@link Filter}
  * @see {@link FilterGroup}
- *
  * @category models
  * @since 4.0.0
  */
@@ -419,6 +429,8 @@ declare const TypeId = "~effect/Schema";
 /**
  * Abstract base class for all {@link AST} node variants.
  *
+ * **Details**
+ *
  * Every AST node extends `Base` and inherits these fields:
  *
  * - `annotations` — user-supplied metadata (identifier, title, description,
@@ -431,7 +443,6 @@ declare const TypeId = "~effect/Schema";
  * Subclasses add a `_tag` discriminant and variant-specific data.
  *
  * @see {@link AST}
- *
  * @category models
  * @since 4.0.0
  */
@@ -448,15 +459,18 @@ export declare abstract class Base {
 /**
  * AST node for user-defined opaque types with custom parsing logic.
  *
+ * **When to use**
+ *
  * Use when none of the built-in AST nodes fit. The `run` function receives
  * `typeParameters` and returns a parser that validates/transforms raw input.
  *
+ * **Details**
+ *
  * - `typeParameters` — inner schemas this declaration is parameterized over
  *   (e.g. the element type for a custom collection).
  * - `run` — factory producing the actual parse function.
  *
  * @see {@link isDeclaration}
- *
  * @category models
  * @since 3.10.0
  */
@@ -469,11 +483,12 @@ export declare class Declaration extends Base {
 /**
  * AST node matching the `null` literal value.
  *
+ * **Details**
+ *
  * Parsing succeeds only when the input is exactly `null`.
  *
  * @see {@link null}
  * @see {@link isNull}
- *
  * @category models
  * @since 4.0.0
  */
@@ -485,17 +500,19 @@ export {
 /**
  * Singleton {@link Null} AST instance.
  *
+ * @category constructors
  * @since 4.0.0
  */
 null_ as null };
 /**
  * AST node matching the `undefined` value.
  *
+ * **Details**
+ *
  * Parsing succeeds only when the input is exactly `undefined`.
  *
  * @see {@link undefined}
  * @see {@link isUndefined}
- *
  * @category models
  * @since 4.0.0
  */
@@ -507,18 +524,20 @@ export {
 /**
  * Singleton {@link Undefined} AST instance.
  *
+ * @category constructors
  * @since 4.0.0
  */
 undefined_ as undefined };
 /**
  * AST node matching the `void` type (accepts `undefined` at runtime).
  *
+ * **Details**
+ *
  * Behaves like {@link Undefined} for parsing but represents the TypeScript
  * `void` type semantically.
  *
  * @see {@link void}
  * @see {@link isVoid}
- *
  * @category models
  * @since 4.0.0
  */
@@ -530,18 +549,20 @@ export {
 /**
  * Singleton {@link Void} AST instance.
  *
+ * @category constructors
  * @since 4.0.0
  */
 void_ as void };
 /**
  * AST node representing the `never` type — no value matches.
  *
+ * **Details**
+ *
  * Parsing always fails. Useful as a placeholder in unions or as the result
  * of narrowing that eliminates all options.
  *
  * @see {@link never}
  * @see {@link isNever}
- *
  * @category models
  * @since 4.0.0
  */
@@ -577,12 +598,13 @@ export declare const any: Any;
 /**
  * AST node representing the `unknown` type — every value matches.
  *
+ * **Details**
+ *
  * Unlike {@link Any}, this is type-safe: the parsed result is typed as
  * `unknown` rather than `any`.
  *
  * @see {@link unknown}
  * @see {@link isUnknown}
- *
  * @category models
  * @since 4.0.0
  */
@@ -619,11 +641,12 @@ export declare const objectKeyword: ObjectKeyword;
 /**
  * AST node representing a TypeScript `enum`.
  *
+ * **Details**
+ *
  * Holds `enums` as an array of `[name, value]` pairs where values are
  * `string | number`. Parsing succeeds when the input matches any enum value.
  *
  * @see {@link isEnum}
- *
  * @category models
  * @since 4.0.0
  */
@@ -636,12 +659,13 @@ export declare class Enum extends Base {
  * AST node representing a TypeScript template literal type
  * (e.g. `` `user_${string}` ``).
  *
+ * **Details**
+ *
  * `parts` is an array of AST nodes; each part contributes to the
  * template literal pattern. A regex is derived from the parts to validate
  * strings at runtime.
  *
  * @see {@link isTemplateLiteral}
- *
  * @category models
  * @since 3.10.0
  */
@@ -653,11 +677,12 @@ export declare class TemplateLiteral extends Base {
 /**
  * AST node matching a specific `unique symbol` value.
  *
+ * **Details**
+ *
  * Parsing succeeds only when the input is reference-equal to the stored
  * `symbol`.
  *
  * @see {@link isUniqueSymbol}
- *
  * @category models
  * @since 3.10.0
  */
@@ -679,6 +704,8 @@ export type LiteralValue = string | number | boolean | bigint;
  * AST node matching an exact primitive value (string, number, boolean, or
  * bigint).
  *
+ * **Details**
+ *
  * Parsing succeeds only when the input is strictly equal (`===`) to the
  * stored `literal`. Numeric literals must be finite — `Infinity`, `-Infinity`,
  * and `NaN` are rejected at construction time.
@@ -694,7 +721,6 @@ export type LiteralValue = string | number | boolean | bigint;
  *
  * @see {@link LiteralValue}
  * @see {@link isLiteral}
- *
  * @category models
  * @since 3.10.0
  */
@@ -726,7 +752,10 @@ export declare const string: String;
  * AST node matching any `number` value (including `NaN`, `Infinity`,
  * `-Infinity`).
  *
+ * **Details**
+ *
  * Default JSON serialization:
+ *
  * - Finite numbers are serialized as JSON numbers.
  * - `Infinity`, `-Infinity`, and `NaN` are serialized as JSON strings.
  *
@@ -735,7 +764,6 @@ export declare const string: String;
  *
  * @see {@link number}
  * @see {@link isNumber}
- *
  * @category models
  * @since 4.0.0
  */
@@ -771,12 +799,13 @@ export declare const boolean: Boolean;
 /**
  * AST node matching any `symbol` value.
  *
+ * **Details**
+ *
  * When serialized to a string-based codec, symbols are converted via
  * `Symbol.keyFor` and must be registered with `Symbol.for`.
  *
  * @see {@link symbol}
  * @see {@link isSymbol}
- *
  * @category models
  * @since 4.0.0
  */
@@ -793,12 +822,13 @@ export declare const symbol: Symbol;
 /**
  * AST node matching any `bigint` value.
  *
+ * **Details**
+ *
  * When serialized to a string-based codec, bigints are converted to/from
  * their decimal string representation.
  *
  * @see {@link bigInt}
  * @see {@link isBigInt}
- *
  * @category models
  * @since 4.0.0
  */
@@ -815,6 +845,8 @@ export declare const bigInt: BigInt;
 /**
  * AST node for array-like types — both tuples and arrays.
  *
+ * **Details**
+ *
  * - `elements` — positional element types (tuple elements). An element is
  *   optional if its {@link Context.isOptional} is `true`.
  * - `rest` — the rest/variadic element types. When non-empty, the first
@@ -823,6 +855,8 @@ export declare const bigInt: BigInt;
  * - `isMutable` — whether the resulting array is `readonly` (`false`) or
  *   mutable (`true`).
  *
+ * **Gotchas**
+ *
  * Construction enforces TypeScript ordering rules: a required element
  * cannot follow an optional one, and an optional element cannot follow a
  * rest element.
@@ -843,7 +877,6 @@ export declare const bigInt: BigInt;
  *
  * @see {@link isArrays}
  * @see {@link Objects}
- *
  * @category models
  * @since 4.0.0
  */
@@ -857,12 +890,13 @@ export declare class Arrays extends Base {
 /**
  * A named property within an {@link Objects} node.
  *
+ * **Details**
+ *
  * Pairs a `name` (any `PropertyKey`) with a `type` ({@link AST}). The
  * property's optionality and mutability are determined by the `type`'s
  * {@link Context}.
  *
  * @see {@link Objects}
- *
  * @category models
  * @since 3.10.0
  */
@@ -874,13 +908,14 @@ export declare class PropertySignature {
 /**
  * Bidirectional merge strategy for index signature key-value pairs.
  *
+ * **Details**
+ *
  * Used by {@link IndexSignature} when the same key appears multiple times
  * (e.g. from `Schema.extend` or overlapping records). Provides separate
  * `decode` and `encode` combiners that determine how duplicate entries are
  * merged.
  *
  * @see {@link IndexSignature}
- *
  * @category models
  * @since 4.0.0
  */
@@ -892,17 +927,20 @@ export declare class KeyValueCombiner {
 /**
  * An index signature entry within an {@link Objects} node.
  *
+ * **Details**
+ *
  * - `parameter` — the key type AST (e.g. {@link String} for `string` keys,
  *   {@link TemplateLiteral} for patterned keys).
  * - `type` — the value type AST.
  * - `merge` — optional {@link KeyValueCombiner} for handling duplicate keys.
  *
+ * **Gotchas**
+ *
  * Using `Schema.optionalKey` on the value type is not allowed for index
  * signatures (throws at construction); use `Schema.optional` instead.
  *
  * @see {@link Objects}
  * @see {@link PropertySignature}
- *
  * @category models
  * @since 3.10.0
  */
@@ -915,6 +953,8 @@ export declare class IndexSignature {
 /**
  * AST node for object-like schemas, including structs and records.
  *
+ * **Details**
+ *
  * - `propertySignatures` — named properties with their types (struct fields).
  * - `indexSignatures` — index signature entries (record patterns), each with
  *   a `parameter` AST for matching keys and a `type` AST for values.
@@ -923,6 +963,8 @@ export declare class IndexSignature {
  * non-nullish check: it accepts any value except `null` and `undefined`,
  * including primitive values.
  *
+ * **Gotchas**
+ *
  * Duplicate property names throw at construction time.
  *
  * **Example** (Inspecting a struct AST)
@@ -945,7 +987,6 @@ export declare class IndexSignature {
  * @see {@link PropertySignature}
  * @see {@link IndexSignature}
  * @see {@link Arrays}
- *
  * @category models
  * @since 4.0.0
  */
@@ -959,6 +1000,8 @@ export declare class Objects extends Base {
 /**
  * AST node representing a union of schemas.
  *
+ * **Details**
+ *
  * - `types` — the member AST nodes.
  * - `mode` — `"anyOf"` succeeds on the first match (like TypeScript unions);
  *   `"oneOf"` requires exactly one member to match (fails if multiple do).
@@ -982,7 +1025,6 @@ export declare class Objects extends Base {
  * ```
  *
  * @see {@link isUnion}
- *
  * @category models
  * @since 3.10.0
  */
@@ -995,6 +1037,8 @@ export declare class Union<A extends AST = AST> extends Base {
 /**
  * AST node for lazy/recursive schemas.
  *
+ * **Details**
+ *
  * Wraps a thunk (`() => AST`) that is memoized on first call. Use this to
  * define recursive or mutually recursive schemas without infinite loops at
  * construction time.
@@ -1018,7 +1062,6 @@ export declare class Union<A extends AST = AST> extends Base {
  * ```
  *
  * @see {@link isSuspend}
- *
  * @category models
  * @since 3.10.0
  */
@@ -1030,6 +1073,8 @@ export declare class Suspend extends Base {
 /**
  * A single validation check attached to an AST node.
  *
+ * **Details**
+ *
  * - `run` — the validation function. Returns `undefined` on success, or an
  *   `Issue` on failure.
  * - `annotations` — optional filter-level metadata (expected message, meta
@@ -1043,7 +1088,6 @@ export declare class Suspend extends Base {
  * @see {@link FilterGroup}
  * @see {@link Check}
  * @see {@link isPattern}
- *
  * @category models
  * @since 4.0.0
  */
@@ -1067,13 +1111,14 @@ export declare class Filter<in E> extends Pipeable.Class {
 /**
  * A composite validation check grouping multiple {@link Check} values.
  *
+ * **Details**
+ *
  * Created by calling `.and()` on a {@link Filter} or another `FilterGroup`.
  * All inner checks are run; failures from aborted filters still stop
  * evaluation.
  *
  * @see {@link Filter}
  * @see {@link Check}
- *
  * @category models
  * @since 4.0.0
  */
@@ -1089,11 +1134,12 @@ export declare class FilterGroup<in E> extends Pipeable.Class {
  * A validation check — either a single {@link Filter} or a composite
  * {@link FilterGroup}.
  *
+ * **Details**
+ *
  * Stored in the {@link Checks} array on {@link Base.checks}.
  *
  * @see {@link Filter}
  * @see {@link FilterGroup}
- *
  * @category models
  * @since 4.0.0
  */
@@ -1101,10 +1147,14 @@ export type Check<T> = Filter<T> | FilterGroup<T>;
 /**
  * Creates a {@link Filter} that validates strings by running `RegExp.test`.
  *
+ * **Details**
+ *
  * The filter can be used with `Schema.filter` or attached directly to a
  * `String` AST node through checks. The regular expression source is stored in
  * annotations for serialization and arbitrary generation.
  *
+ * **Gotchas**
+ *
  * Use a non-global, non-sticky regular expression, or reset `lastIndex`
  * yourself, because `RegExp.test` is stateful for expressions with the `g` or
  * `y` flag.
@@ -1118,7 +1168,6 @@ export type Check<T> = Filter<T> | FilterGroup<T>;
  * ```
  *
  * @see {@link Filter}
- *
  * @category constructors
  * @since 4.0.0
  */
@@ -1128,12 +1177,13 @@ export declare function mapOrSame<A>(as: ReadonlyArray<A>, f: (a: A) => A): Read
  * Marks an AST node's property key as optional by setting
  * {@link Context.isOptional} to `true`.
  *
+ * **Details**
+ *
  * Also propagates the optional flag through the last link of the encoding
  * chain if present.
  *
  * @see {@link isOptional}
  * @see {@link Context}
- *
  * @category transforming
  * @since 4.0.0
  */
@@ -1142,6 +1192,8 @@ export declare function optionalKey<A extends AST>(ast: A): A;
  * Attaches a `Transformation` to the `to` AST, making it decode from the
  * `from` AST and encode back to it.
  *
+ * **Details**
+ *
  * This is the low-level primitive behind `Schema.transform` and
  * `Schema.transformOrFail`. It appends a {@link Link} to the `to` node's
  * encoding chain.
@@ -1152,7 +1204,6 @@ export declare function optionalKey<A extends AST>(ast: A): A;
  * @see {@link Link}
  * @see {@link Encoding}
  * @see {@link flip}
- *
  * @category transforming
  * @since 4.0.0
  */
@@ -1160,12 +1211,13 @@ export declare function decodeTo<A extends AST>(from: AST, to: A, transformation
 /**
  * Returns `true` if the AST node represents an optional property.
  *
+ * **Details**
+ *
  * Checks `ast.context?.isOptional`. Defaults to `false` when no
  * {@link Context} is set.
  *
  * @see {@link optionalKey}
  * @see {@link Context}
- *
  * @category predicates
  * @since 4.0.0
  */
@@ -1174,6 +1226,8 @@ export declare function isOptional(ast: AST): boolean;
  * Strips all encoding transformations from an AST, returning the decoded
  * (type-level) representation.
  *
+ * **Details**
+ *
  * - Memoized: same input reference → same output reference.
  * - Recursively walks into composite nodes ({@link Arrays}, {@link Objects},
  *   {@link Union}, {@link Suspend}).
@@ -1191,7 +1245,6 @@ export declare function isOptional(ast: AST): boolean;
  *
  * @see {@link toEncoded}
  * @see {@link flip}
- *
  * @category transforming
  * @since 4.0.0
  */
@@ -1200,6 +1253,8 @@ export declare const toType: <A extends AST>(ast: A) => A;
  * Returns the encoded (wire-format) AST by flipping and then stripping
  * encodings.
  *
+ * **Details**
+ *
  * Equivalent to `toType(flip(ast))`. This gives you the AST that describes
  * the shape of the serialized/encoded data.
  *
@@ -1218,7 +1273,6 @@ export declare const toType: <A extends AST>(ast: A) => A;
  *
  * @see {@link toType}
  * @see {@link flip}
- *
  * @category transforming
  * @since 4.0.0
  */
@@ -1226,6 +1280,8 @@ export declare const toEncoded: (ast: AST) => AST;
 /**
  * Swaps the decode and encode directions of an AST's {@link Encoding} chain.
  *
+ * **Details**
+ *
  * After flipping, what was decoding becomes encoding and vice versa. This is
  * the core operation behind `Schema.encode` — encoding a value is decoding
  * with a flipped AST.
@@ -1236,7 +1292,6 @@ export declare const toEncoded: (ast: AST) => AST;
  *
  * @see {@link toType}
  * @see {@link toEncoded}
- *
  * @category transforming
  * @since 4.0.0
  */
@@ -1244,6 +1299,8 @@ export declare const flip: (ast: AST) => AST;
 /**
  * Returns all annotations from the AST node.
  *
+ * **Details**
+ *
  * If the node has {@link Checks}, returns annotations from the last check
  * (which is where user-supplied annotations end up after `.pipe(Schema.annotations(...))`).
  * Otherwise returns `Base.annotations` directly.
@@ -1262,7 +1319,6 @@ export declare const flip: (ast: AST) => AST;
  * @see {@link resolveIdentifier}
  * @see {@link resolveTitle}
  * @see {@link resolveDescription}
- *
  * @category annotations
  * @since 4.0.0
  */
@@ -1270,11 +1326,12 @@ export declare const resolve: (ast: AST) => Schema.Annotations.Annotations | und
 /**
  * Returns a single annotation value by key from the AST node.
  *
+ * **Details**
+ *
  * Like {@link resolve}, reads from the last check's annotations when checks
  * are present. Returns `undefined` if the key is not found.
  *
  * @see {@link resolve}
- *
  * @category annotations
  * @since 4.0.0
  */
@@ -1282,12 +1339,13 @@ export declare const resolveAt: <A>(key: string) => (ast: AST) => A | undefined;
 /**
  * Returns the `identifier` annotation from the AST node, if set.
  *
+ * **Details**
+ *
  * The identifier is typically set by `Schema.annotations({ identifier: "..." })`
  * and is used for error messages and schema identification.
  *
  * @see {@link resolve}
  * @see {@link resolveTitle}
- *
  * @category annotations
  * @since 4.0.0
  */