effect 4.0.0-beta.70 → 4.0.0-beta.72

package/dist/SchemaAST.js

@@ -110,6 +110,13 @@ export function isAST(u) {
 /**
  * Narrows an {@link AST} to {@link Declaration}.
  *
+ * **When to use**
+ *
+ * Use to recognize declaration AST nodes before running declaration-specific
+ * handling.
+ *
+ * @see {@link Declaration} for the AST node type narrowed by this guard
+ *
  * @category guards
  * @since 3.10.0
  */
@@ -117,6 +124,15 @@ export const isDeclaration = /*#__PURE__*/makeGuard("Declaration");
 /**
  * Narrows an {@link AST} to {@link Null}.
  *
+ * **When to use**
+ *
+ * Use to recognize an AST node that represents exactly the `null` literal when
+ * inspecting, traversing, or transforming schema ASTs.
+ *
+ * @see {@link Null} for the AST node type narrowed by this guard
+ * @see {@link null_ null} for the singleton `Null` AST instance
+ * @see {@link isLiteral} for exact primitive literal AST nodes
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -124,6 +140,13 @@ export const isNull = /*#__PURE__*/makeGuard("Null");
 /**
  * Narrows an {@link AST} to {@link Undefined}.
  *
+ * **When to use**
+ *
+ * Use to identify AST nodes that represent exactly the JavaScript `undefined`
+ * value.
+ *
+ * @see {@link isVoid} for narrowing AST nodes that represent TypeScript `void` instead of exact `undefined`
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -131,6 +154,13 @@ export const isUndefined = /*#__PURE__*/makeGuard("Undefined");
 /**
  * Narrows an {@link AST} to {@link Void}.
  *
+ * **When to use**
+ *
+ * Use to identify AST nodes that represent the TypeScript `void` type before
+ * handling `Void`-specific schema behavior.
+ *
+ * @see {@link isUndefined} for narrowing AST nodes that represent the literal `undefined` value instead of TypeScript `void`
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -138,6 +168,14 @@ export const isVoid = /*#__PURE__*/makeGuard("Void");
 /**
  * Narrows an {@link AST} to {@link Never}.
  *
+ * **When to use**
+ *
+ * Use to detect the AST node for a schema that can never match before handling
+ * other schema variants.
+ *
+ * @see {@link Never} for the AST node type narrowed by this guard
+ * @see {@link never} for the singleton `Never` AST instance
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -145,6 +183,13 @@ export const isNever = /*#__PURE__*/makeGuard("Never");
 /**
  * Narrows an {@link AST} to {@link Unknown}.
  *
+ * **When to use**
+ *
+ * Use when inspecting a schema AST and you need to handle the `Unknown` node
+ * variant specifically.
+ *
+ * @see {@link isAny} for the guard for the `Any` node, whose parsed result is typed as `any` rather than `unknown`
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -152,6 +197,13 @@ export const isUnknown = /*#__PURE__*/makeGuard("Unknown");
 /**
  * Narrows an {@link AST} to {@link Any}.
  *
+ * **When to use**
+ *
+ * Use when inspecting a schema AST and you need to handle the `Any` node
+ * variant specifically.
+ *
+ * @see {@link isUnknown} for the guard for the `Unknown` node, whose parsed result is typed as `unknown` rather than `any`
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -159,6 +211,15 @@ export const isAny = /*#__PURE__*/makeGuard("Any");
 /**
  * Narrows an {@link AST} to {@link String}.
  *
+ * **When to use**
+ *
+ * Use to detect schema AST nodes that match any string value while inspecting or
+ * transforming an AST.
+ *
+ * @see {@link String} for the AST node class narrowed by this guard
+ * @see {@link string} for the singleton `String` AST instance
+ * @see {@link isLiteral} for exact primitive literal AST nodes, including exact string literals
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -166,6 +227,11 @@ export const isString = /*#__PURE__*/makeGuard("String");
 /**
  * Narrows an {@link AST} to {@link Number}.
  *
+ * **When to use**
+ *
+ * Use to detect `Number` AST nodes while inspecting, traversing, or transforming
+ * schema ASTs.
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -173,6 +239,14 @@ export const isNumber = /*#__PURE__*/makeGuard("Number");
 /**
  * Narrows an {@link AST} to {@link Boolean}.
  *
+ * **When to use**
+ *
+ * Use to identify the `Boolean` AST variant while inspecting, traversing, or
+ * transforming schema definitions.
+ *
+ * @see {@link Boolean} for the AST node type matched by this guard
+ * @see {@link boolean} for the singleton instance to use when constructing a boolean AST directly
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -180,6 +254,13 @@ export const isBoolean = /*#__PURE__*/makeGuard("Boolean");
 /**
  * Narrows an {@link AST} to {@link BigInt}.
  *
+ * **When to use**
+ *
+ * Use to identify bigint AST nodes while inspecting or transforming schema ASTs.
+ *
+ * @see {@link BigInt} for the AST node matched by this guard
+ * @see {@link bigInt} for the singleton instance; use `isBigInt` when narrowing an existing `AST` value
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -187,6 +268,13 @@ export const isBigInt = /*#__PURE__*/makeGuard("BigInt");
 /**
  * Narrows an {@link AST} to {@link Symbol}.
  *
+ * **When to use**
+ *
+ * Use to narrow an `AST` node before handling the `Symbol` variant for schemas
+ * that accept any JavaScript symbol value.
+ *
+ * @see {@link isUniqueSymbol} for the sibling guard that narrows the `UniqueSymbol` variant for one exact symbol value
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -194,6 +282,13 @@ export const isSymbol = /*#__PURE__*/makeGuard("Symbol");
 /**
  * Narrows an {@link AST} to {@link Literal}.
  *
+ * **When to use**
+ *
+ * Use to recognize exact string, number, boolean, or bigint literal AST nodes.
+ *
+ * @see {@link Literal} for the AST node type narrowed by this guard
+ * @see {@link LiteralValue} for the values stored by literal nodes
+ *
  * @category guards
  * @since 3.10.0
  */
@@ -208,6 +303,15 @@ export const isUniqueSymbol = /*#__PURE__*/makeGuard("UniqueSymbol");
 /**
  * Narrows an {@link AST} to {@link ObjectKeyword}.
  *
+ * **When to use**
+ *
+ * Use to identify the AST node for the TypeScript `object` keyword when
+ * inspecting or transforming a schema AST.
+ *
+ * @see {@link ObjectKeyword} for the AST node matched by this guard
+ * @see {@link objectKeyword} for the singleton `ObjectKeyword` AST instance
+ * @see {@link isObjects} for struct and record AST nodes
+ *
  * @category guards
  * @since 3.10.0
  */
@@ -215,6 +319,13 @@ export const isObjectKeyword = /*#__PURE__*/makeGuard("ObjectKeyword");
 /**
  * Narrows an {@link AST} to {@link Enum}.
  *
+ * **When to use**
+ *
+ * Use to recognize enum AST nodes before reading enum cases or running
+ * enum-specific handling.
+ *
+ * @see {@link Enum} for the AST node type narrowed by this guard
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -229,6 +340,13 @@ export const isTemplateLiteral = /*#__PURE__*/makeGuard("TemplateLiteral");
 /**
  * Narrows an {@link AST} to {@link Arrays}.
  *
+ * **When to use**
+ *
+ * Use to recognize array-like AST nodes before reading their element, rest, or
+ * mutability metadata.
+ *
+ * @see {@link Arrays} for the AST node type narrowed by this guard
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -255,7 +373,7 @@ export const isUnion = /*#__PURE__*/makeGuard("Union");
  */
 export const isSuspend = /*#__PURE__*/makeGuard("Suspend");
 /**
- * A single step in an {@link Encoding} chain.
+ * Represents a single step in an {@link Encoding} chain.
  *
  * **Details**
  *
@@ -284,7 +402,7 @@ export class Link {
 /** @internal */
 export const defaultParseOptions = {};
 /**
- * Per-property metadata attached to AST nodes via {@link Base.context}.
+ * Represents per-property metadata attached to AST nodes via {@link Base.context}.
  *
  * **Details**
  *
@@ -320,7 +438,7 @@ export class Context {
 }
 const TypeId = "~effect/Schema";
 /**
- * Abstract base class for all {@link AST} node variants.
+ * Represents the abstract base class for all {@link AST} node variants.
  *
  * **Details**
  *
@@ -409,7 +527,7 @@ export class Declaration extends Base {
  *
  * Parsing succeeds only when the input is exactly `null`.
  *
- * @see {@link null}
+ * @see {@link null_ null}
  * @see {@link isNull}
  * @category models
  * @since 4.0.0
@@ -428,9 +546,14 @@ export class Null extends Base {
 const null_ = /*#__PURE__*/new Null();
 export {
 /**
- * Singleton {@link Null} AST instance.
+ * Provides the singleton {@link Null} AST instance.
  *
- * @category constructors
+ * **When to use**
+ *
+ * Use when you need the shared AST node for exact null values while inspecting
+ * or constructing schema ASTs.
+ *
+ * @category constants
  * @since 4.0.0
  */
 null_ as null };
@@ -465,9 +588,14 @@ const undefinedToNull = /*#__PURE__*/new Link(null_, /*#__PURE__*/new Transforma
 const undefined_ = /*#__PURE__*/new Undefined();
 export {
 /**
- * Singleton {@link Undefined} AST instance.
+ * Provides the singleton {@link Undefined} AST instance.
  *
- * @category constructors
+ * **When to use**
+ *
+ * Use when you need the shared AST node for exact undefined values while
+ * inspecting or constructing schema ASTs.
+ *
+ * @category constants
  * @since 4.0.0
  */
 undefined_ as undefined };
@@ -479,7 +607,7 @@ undefined_ as undefined };
  * Behaves like {@link Undefined} for parsing but represents the TypeScript
  * `void` type semantically.
  *
- * @see {@link void}
+ * @see {@link void_ void}
  * @see {@link isVoid}
  * @category models
  * @since 4.0.0
@@ -502,7 +630,16 @@ export class Void extends Base {
 const void_ = /*#__PURE__*/new Void();
 export {
 /**
- * Singleton {@link Void} AST instance.
+ * Provides the singleton {@link Void} AST instance.
+ *
+ * **When to use**
+ *
+ * Use when constructing or comparing AST nodes that represent the TypeScript
+ * `void` type and accept `undefined` at runtime.
+ *
+ * @see {@link Void} for the AST node class
+ * @see {@link undefined} for the sibling AST singleton that matches exactly `undefined`
+ * @see {@link isVoid} for narrowing an AST to a `Void` node
  *
  * @category constructors
  * @since 4.0.0
@@ -533,7 +670,15 @@ export class Never extends Base {
   }
 }
 /**
- * Singleton {@link Never} AST instance.
+ * Provides the singleton {@link Never} AST instance.
+ *
+ * **When to use**
+ *
+ * Use to reuse the canonical bottom-type AST node when constructing,
+ * comparing, or returning ASTs.
+ *
+ * @see {@link Never} for the AST node class
+ * @see {@link isNever} for narrowing an AST to a `Never` node
  *
  * @category constructors
  * @since 4.0.0
@@ -560,7 +705,14 @@ export class Any extends Base {
   }
 }
 /**
- * Singleton {@link Any} AST instance.
+ * Provides the singleton {@link Any} AST instance.
+ *
+ * **When to use**
+ *
+ * Use when you need the singleton AST node for the TypeScript `any` type and
+ * intentionally want parsing to accept every input value.
+ *
+ * @see {@link unknown} for the sibling AST singleton that also accepts every value while preserving the safer `unknown` type
  *
  * @category constructors
  * @since 4.0.0
@@ -591,7 +743,14 @@ export class Unknown extends Base {
   }
 }
 /**
- * Singleton {@link Unknown} AST instance.
+ * Provides the singleton {@link Unknown} AST instance.
+ *
+ * **When to use**
+ *
+ * Use when you need the reusable AST singleton for a schema node that accepts
+ * every value while keeping parsed values opaque.
+ *
+ * @see {@link any} for the singleton that accepts every value as `any`
  *
  * @category constructors
  * @since 4.0.0
@@ -619,7 +778,15 @@ export class ObjectKeyword extends Base {
   }
 }
 /**
- * Singleton {@link ObjectKeyword} AST instance.
+ * Provides the singleton {@link ObjectKeyword} AST instance.
+ *
+ * **When to use**
+ *
+ * Use to reuse the canonical AST node for the TypeScript `object` keyword when
+ * building or comparing `SchemaAST` values directly.
+ *
+ * @see {@link ObjectKeyword} for the AST node class
+ * @see {@link isObjectKeyword} for narrowing an AST to an `ObjectKeyword` node
  *
  * @category constructors
  * @since 3.10.0
@@ -842,7 +1009,14 @@ export class String extends Base {
   }
 }
 /**
- * Singleton {@link String} AST instance.
+ * Provides the singleton {@link String} AST instance.
+ *
+ * **When to use**
+ *
+ * Use as the shared `SchemaAST` node for unconstrained JavaScript strings.
+ *
+ * @see {@link String} for the AST node class
+ * @see {@link isString} for narrowing an AST to a string node
  *
  * @category constructors
  * @since 4.0.0
@@ -904,7 +1078,15 @@ function hasCheck(checks, tag) {
   });
 }
 /**
- * Singleton {@link Number} AST instance.
+ * Provides the singleton {@link Number} AST instance.
+ *
+ * **When to use**
+ *
+ * Use when you need the canonical `SchemaAST` node for schemas that accept any
+ * JavaScript number value.
+ *
+ * @see {@link Number} for the AST node class and serialization behavior
+ * @see {@link Literal} for exact finite numeric literal AST nodes
  *
  * @category constructors
  * @since 4.0.0
@@ -931,7 +1113,15 @@ export class Boolean extends Base {
   }
 }
 /**
- * Singleton {@link Boolean} AST instance.
+ * Provides the singleton {@link Boolean} AST instance.
+ *
+ * **When to use**
+ *
+ * Use to reuse the standard AST node that accepts either `true` or `false` when
+ * constructing schema ASTs directly.
+ *
+ * @see {@link Boolean} for the AST node class
+ * @see {@link Literal} for exact boolean literal AST nodes
  *
  * @category constructors
  * @since 4.0.0
@@ -940,6 +1130,11 @@ export const boolean = /*#__PURE__*/new Boolean();
 /**
  * AST node matching any `symbol` value.
  *
+ * **When to use**
+ *
+ * Use when defining or inspecting the AST node class for schemas that match any
+ * JavaScript symbol value.
+ *
  * **Details**
  *
  * When serialized to a string-based codec, symbols are converted via
@@ -966,7 +1161,19 @@ export class Symbol extends Base {
   }
 }
 /**
- * Singleton {@link Symbol} AST instance.
+ * Provides the singleton {@link Symbol} AST instance.
+ *
+ * **When to use**
+ *
+ * Use to reuse the singleton AST node for schemas that match any JavaScript
+ * symbol value.
+ *
+ * **Gotchas**
+ *
+ * String-based codecs can encode only symbols registered with `Symbol.for`,
+ * because the implementation uses `Symbol.keyFor`.
+ *
+ * @see {@link UniqueSymbol} for an AST node that matches one specific symbol
  *
  * @category constructors
  * @since 4.0.0
@@ -1001,7 +1208,15 @@ export class BigInt extends Base {
   }
 }
 /**
- * Singleton {@link BigInt} AST instance.
+ * Provides the singleton {@link BigInt} AST instance.
+ *
+ * **When to use**
+ *
+ * Use to reuse the canonical `BigInt` AST node when constructing, inspecting,
+ * or transforming schemas at the AST level.
+ *
+ * @see {@link BigInt} for the AST node class and string-codec behavior
+ * @see {@link isBigInt} for narrowing an AST to a `BigInt` node
  *
  * @category constructors
  * @since 4.0.0
@@ -1218,7 +1433,7 @@ export function getIndexSignatureKeys(input, parameter) {
   }
 }
 /**
- * A named property within an {@link Objects} node.
+ * Represents a named property within an {@link Objects} node.
  *
  * **Details**
  *
@@ -1239,7 +1454,7 @@ export class PropertySignature {
   }
 }
 /**
- * Bidirectional merge strategy for index signature key-value pairs.
+ * Represents a bidirectional merge strategy for index signature key-value pairs.
  *
  * **Details**
  *
@@ -1265,7 +1480,7 @@ export class KeyValueCombiner {
   }
 }
 /**
- * An index signature entry within an {@link Objects} node.
+ * Represents an index signature entry within an {@link Objects} node.
  *
  * **Details**
  *
@@ -1939,7 +2154,7 @@ export class Suspend extends Base {
 // Checks
 // -----------------------------------------------------------------------------
 /**
- * A single validation check attached to an AST node.
+ * Represents a single validation check attached to an AST node.
  *
  * **Details**
  *
@@ -1991,7 +2206,7 @@ export class Filter extends Pipeable.Class {
   }
 }
 /**
- * A composite validation check grouping multiple {@link Check} values.
+ * Represents a composite validation check grouping multiple {@link Check} values.
  *
  * **Details**
  *
@@ -2225,7 +2440,6 @@ export function withConstructorDefault(ast, defaultValue) {
  * `Schema.transformOrFail`. It appends a {@link Link} to the `to` node's
  * encoding chain.
  *
- * - Does not mutate either input.
  * - Returns a new AST with the same type as `to`.
  *
  * @see {@link Link}
@@ -2316,7 +2530,6 @@ export function isMutable(ast) {
  * - Memoized: same input reference → same output reference.
  * - Recursively walks into composite nodes ({@link Arrays}, {@link Objects},
  *   {@link Union}, {@link Suspend}).
- * - Does not mutate the input.
  *
  * **Example** (Getting the type AST)
  *
@@ -2350,7 +2563,6 @@ export const toType = /*#__PURE__*/memoize(ast => {
  * the shape of the serialized/encoded data.
  *
  * - Memoized: same input reference → same output reference.
- * - Does not mutate the input.
  *
  * **Example** (Getting the encoded AST)
  *
@@ -2396,7 +2608,6 @@ function flipEncoding(ast, encoding) {
  *
  * - Memoized: same input reference → same output reference.
  * - Recursively walks composite nodes.
- * - Does not mutate the input.
  *
  * @see {@link toType}
  * @see {@link toEncoded}