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

package/src/SchemaAST.ts

@@ -158,6 +158,13 @@ export function isAST(u: unknown): u is AST {
 /**
  * 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
  */
@@ -166,6 +173,15 @@ export const isDeclaration = 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
  */
@@ -174,6 +190,13 @@ export const isNull = 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
  */
@@ -182,6 +205,13 @@ export const isUndefined = 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
  */
@@ -190,6 +220,14 @@ export const isVoid = 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
  */
@@ -198,6 +236,13 @@ export const isNever = 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
  */
@@ -206,6 +251,13 @@ export const isUnknown = 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
  */
@@ -214,6 +266,15 @@ export const isAny = 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
  */
@@ -222,6 +283,11 @@ export const isString = 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
  */
@@ -230,6 +296,14 @@ export const isNumber = 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
  */
@@ -238,6 +312,13 @@ export const isBoolean = 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
  */
@@ -246,6 +327,13 @@ export const isBigInt = 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
  */
@@ -254,6 +342,13 @@ export const isSymbol = 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
  */
@@ -270,6 +365,15 @@ export const isUniqueSymbol = 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
  */
@@ -278,6 +382,13 @@ export const isObjectKeyword = 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
  */
@@ -294,6 +405,13 @@ export const isTemplateLiteral = 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
  */
@@ -639,7 +757,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
@@ -722,7 +840,7 @@ export {
  * 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
@@ -748,6 +866,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
    */
@@ -782,6 +909,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
  */
@@ -811,6 +946,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
  */
@@ -844,6 +986,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
  */
@@ -874,6 +1023,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
  */
@@ -1180,6 +1337,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
  */
@@ -1245,6 +1409,14 @@ function hasCheck(checks: ReadonlyArray<Check<unknown>>, tag: string): boolean {
 /**
  * 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
  */
@@ -1274,6 +1446,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
  */
@@ -1282,6 +1462,10 @@ export const boolean = 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
@@ -1311,6 +1495,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
  */
@@ -1348,6 +1543,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
  */