effect 4.0.0-beta.70 → 4.0.0-beta.71

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
  */
@@ -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
@@ -479,7 +597,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
@@ -504,6 +622,15 @@ export {
 /**
  * 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
  */
@@ -535,6 +662,14 @@ export class Never extends Base {
 /**
  * Singleton {@link Never} AST instance.
  *
+ * **When to use**
+ *
+ * Use to reuse the canonical `Never` AST node when constructing, comparing, or
+ * returning ASTs that represent the `never` type.
+ *
+ * @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
  */
@@ -562,6 +697,13 @@ export class Any extends Base {
 /**
  * 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
  */
@@ -593,6 +735,13 @@ export class Unknown extends Base {
 /**
  * Singleton {@link Unknown} AST instance.
  *
+ * **When to use**
+ *
+ * Use when you need the reusable AST singleton for an `unknown` schema node
+ * that accepts every value while keeping the parsed type as `unknown`.
+ *
+ * @see {@link any} for the singleton that accepts every value as `any`
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -621,6 +770,14 @@ export class ObjectKeyword extends Base {
 /**
  * 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
  */
@@ -844,6 +1001,13 @@ export class String extends Base {
 /**
  * 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
  */
@@ -906,6 +1070,14 @@ function hasCheck(checks, tag) {
 /**
  * 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
  */
@@ -933,6 +1105,14 @@ export class Boolean extends Base {
 /**
  * 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 +1120,10 @@ export const boolean = /*#__PURE__*/new Boolean();
 /**
  * AST node matching any `symbol` value.
  *
+ * **When to use**
+ *
+ * Use when building an AST that should match any JavaScript symbol value.
+ *
  * **Details**
  *
  * When serialized to a string-based codec, symbols are converted via
@@ -968,6 +1152,17 @@ export class Symbol extends Base {
 /**
  * Singleton {@link Symbol} AST instance.
  *
+ * **When to use**
+ *
+ * Use when building an AST that should 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
  */
@@ -1003,6 +1198,14 @@ export class BigInt extends Base {
 /**
  * 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
  */