effect 4.0.0-beta.71 → 4.0.0-beta.72

package/src/SchemaAST.ts

@@ -442,7 +442,7 @@ export const isUnion = makeGuard("Union")
 export const isSuspend = makeGuard("Suspend")
 
 /**
- * A single step in an {@link Encoding} chain.
+ * Represents a single step in an {@link Encoding} chain.
  *
  * **Details**
  *
@@ -584,7 +584,7 @@ export interface ParseOptions {
 export const defaultParseOptions: ParseOptions = {}
 
 /**
- * Per-property metadata attached to AST nodes via {@link Base.context}.
+ * Represents per-property metadata attached to AST nodes via {@link Base.context}.
  *
  * **Details**
  *
@@ -645,7 +645,7 @@ export type Checks = readonly [Check<any>, ...Array<Check<any>>]
 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**
  *
@@ -777,9 +777,14 @@ export class Null extends Base {
 const null_ = 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
@@ -824,9 +829,14 @@ const undefinedToNull = new Link(
 const undefined_ = 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
@@ -864,7 +874,7 @@ export class Void extends Base {
 const void_ = new Void()
 export {
   /**
-   * Singleton {@link Void} AST instance.
+   * Provides the singleton {@link Void} AST instance.
    *
    * **When to use**
    *
@@ -907,12 +917,12 @@ 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 `Never` AST node when constructing, comparing, or
- * returning ASTs that represent the `never` type.
+ * 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
@@ -944,7 +954,7 @@ export class Any extends Base {
 }
 
 /**
- * Singleton {@link Any} AST instance.
+ * Provides the singleton {@link Any} AST instance.
  *
  * **When to use**
  *
@@ -984,12 +994,12 @@ 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 an `unknown` schema node
- * that accepts every value while keeping the parsed type as `unknown`.
+ * 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`
  *
@@ -1021,7 +1031,7 @@ export class ObjectKeyword extends Base {
 }
 
 /**
- * Singleton {@link ObjectKeyword} AST instance.
+ * Provides the singleton {@link ObjectKeyword} AST instance.
  *
  * **When to use**
  *
@@ -1335,7 +1345,7 @@ export class String extends Base {
 }
 
 /**
- * Singleton {@link String} AST instance.
+ * Provides the singleton {@link String} AST instance.
  *
  * **When to use**
  *
@@ -1407,7 +1417,7 @@ function hasCheck(checks: ReadonlyArray<Check<unknown>>, tag: string): boolean {
 }
 
 /**
- * Singleton {@link Number} AST instance.
+ * Provides the singleton {@link Number} AST instance.
  *
  * **When to use**
  *
@@ -1444,7 +1454,7 @@ export class Boolean extends Base {
 }
 
 /**
- * Singleton {@link Boolean} AST instance.
+ * Provides the singleton {@link Boolean} AST instance.
  *
  * **When to use**
  *
@@ -1464,7 +1474,8 @@ export const boolean = new Boolean()
  *
  * **When to use**
  *
- * Use when building an AST that should match any JavaScript symbol value.
+ * Use when defining or inspecting the AST node class for schemas that match any
+ * JavaScript symbol value.
  *
  * **Details**
  *
@@ -1493,11 +1504,12 @@ export class Symbol extends Base {
 }
 
 /**
- * Singleton {@link Symbol} AST instance.
+ * Provides the singleton {@link Symbol} AST instance.
  *
  * **When to use**
  *
- * Use when building an AST that should match any JavaScript symbol value.
+ * Use to reuse the singleton AST node for schemas that match any JavaScript
+ * symbol value.
  *
  * **Gotchas**
  *
@@ -1541,7 +1553,7 @@ export class BigInt extends Base {
 }
 
 /**
- * Singleton {@link BigInt} AST instance.
+ * Provides the singleton {@link BigInt} AST instance.
  *
  * **When to use**
  *
@@ -1812,7 +1824,7 @@ export function getIndexSignatureKeys(
 }
 
 /**
- * A named property within an {@link Objects} node.
+ * Represents a named property within an {@link Objects} node.
  *
  * **Details**
  *
@@ -1838,7 +1850,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**
  *
@@ -1869,7 +1881,7 @@ export class KeyValueCombiner {
 }
 
 /**
- * An index signature entry within an {@link Objects} node.
+ * Represents an index signature entry within an {@link Objects} node.
  *
  * **Details**
  *
@@ -2746,7 +2758,7 @@ export class Suspend extends Base {
 // -----------------------------------------------------------------------------
 
 /**
- * A single validation check attached to an AST node.
+ * Represents a single validation check attached to an AST node.
  *
  * **Details**
  *
@@ -2801,7 +2813,7 @@ export class Filter<in E> extends Pipeable.Class {
 }
 
 /**
- * A composite validation check grouping multiple {@link Check} values.
+ * Represents a composite validation check grouping multiple {@link Check} values.
  *
  * **Details**
  *
@@ -3131,7 +3143,6 @@ export function withConstructorDefault<A extends AST>(
  * `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}
@@ -3231,7 +3242,6 @@ export function isMutable(ast: AST): boolean {
  * - 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)
  *
@@ -3266,7 +3276,6 @@ export const toType = memoize(<A extends AST>(ast: A): A => {
  * the shape of the serialized/encoded data.
  *
  * - Memoized: same input reference → same output reference.
- * - Does not mutate the input.
  *
  * **Example** (Getting the encoded AST)
  *
@@ -3316,7 +3325,6 @@ function flipEncoding(ast: AST, encoding: Encoding): AST {
  *
  * - Memoized: same input reference → same output reference.
  * - Recursively walks composite nodes.
- * - Does not mutate the input.
  *
  * @see {@link toType}
  * @see {@link toEncoded}

package/src/SchemaGetter.ts

@@ -98,7 +98,7 @@ import * as Issue from "./SchemaIssue.ts"
 import * as Str from "./String.ts"
 
 /**
- * A composable transformation from an encoded type `E` to a decoded type `T`.
+ * Represents a composable transformation from an encoded type `E` to a decoded type `T`.
  *
  * **When to use**
  *
@@ -112,7 +112,6 @@ import * as Str from "./String.ts"
  * - Returns `Option.None` to omit the value from the decoded output.
  * - Fails with `Issue` on invalid input.
  * - May require Effect services via `R`.
- * - Immutable — constructing or composing getters does not mutate existing instances.
  * - `.map(f)` applies `f` to the decoded value (inside the `Some`), leaving `None` unchanged.
  * - `.compose(other)` chains two getters: the output of `this` feeds into `other`.
  *   Passthrough getters on either side are optimized away.
@@ -544,7 +543,6 @@ export function checkEffect<T, R = never>(
  *
  * - This is the most commonly used constructor.
  * - Transforms `Some(e)` to `Some(f(e))` and leaves `None` unchanged.
- * - Pure, does not mutate input.
  * - Skips `None` inputs — only called when a value is present.
  * - Never fails.
  *
@@ -860,7 +858,7 @@ export function Date<E extends string | number | Date>(): Getter<Date, E> {
 }
 
 /**
- * Trims whitespace from both ends of a string.
+ * Strips whitespace from both ends of a string.
  *
  * **Details**
  *
@@ -904,7 +902,7 @@ export function capitalize<E extends string>(): Getter<string, E> {
 }
 
 /**
- * Lowercases the first character of a string.
+ * Uncapitalizes the first character of a string.
  *
  * **Details**
  *
@@ -1773,7 +1771,7 @@ function bracketPathToTokens(bracketPath: string): Array<string | number> {
  * - A bracket path is a string like `"user[address][city]"` that describes nested
  *   object/array structure.
  * - Interprets bracket paths and constructs the corresponding nested object.
- * - Mutates and returns a new object (does not mutate the input array).
+ * - Builds and returns a nested object from the input entries.
  * - Supported syntax:
  *   - `"foo"` → object key `"foo"`
  *   - `"foo[bar]"` → nested `{ foo: { bar: ... } }`

package/src/SchemaIssue.ts

@@ -100,7 +100,6 @@ const TypeId = "~effect/SchemaIssue/Issue"
  *
  * **Details**
  *
- * - Pure; does not mutate input.
  * - Checks for the internal `TypeId` brand on the value.
  *
  * **Example** (Type-guarding an unknown error)
@@ -192,12 +191,11 @@ class Base {
 }
 
 /**
- * Issue produced when a schema filter (refinement check) fails.
+ * Represents a schema issue produced when a schema filter (refinement check) fails.
  *
  * **When to use**
  *
- * Use when inspect which filter rejected the value.
- * - Walk the inner `issue` for the specific validation failure.
+ * Use when you need to inspect which filter rejected the value.
  *
  * **Details**
  *
@@ -262,13 +260,12 @@ export class Filter extends Base {
 }
 
 /**
- * Issue produced when a schema transformation (encode/decode step) fails.
+ * Represents a schema issue produced when a schema transformation (encode/decode step) fails.
  *
  * **When to use**
  *
- * Use when inspect failures from `Schema.decodeTo` / `Schema.encodeTo`
+ * Use when you need to inspect failures from `Schema.decodeTo` / `Schema.encodeTo`
  *   transformations.
- * - Walk the inner `issue` for the root cause of the transformation failure.
  *
  * **Details**
  *
@@ -325,8 +322,8 @@ export class Encoding extends Base {
  *
  * **When to use**
  *
- * Use when walk the issue tree to accumulate path segments for error reporting.
- * - Match on `_tag === "Pointer"` when flattening nested issues.
+ * Use when you need to walk the issue tree to accumulate path segments for error
+ * reporting.
  *
  * **Details**
  *
@@ -369,13 +366,11 @@ export class Pointer extends Base {
 }
 
 /**
- * Issue produced when a required key or tuple index is missing from the input.
+ * Represents a schema issue produced when a required key or tuple index is missing from the input.
  *
  * **When to use**
  *
- * Use when detect absent fields in struct/tuple validation.
- * - Typically found inside a {@link Pointer} that indicates which key is
- *   missing.
+ * Use when you need to detect absent fields in struct/tuple validation.
  *
  * **Details**
  *
@@ -407,14 +402,13 @@ export class MissingKey extends Base {
 }
 
 /**
- * Issue produced when an input object or tuple contains a key/index not
+ * Represents a schema issue produced when an input object or tuple contains a key/index not
  * declared by the schema.
  *
  * **When to use**
  *
- * Use when detect excess properties during strict struct/tuple validation.
- * - Typically found inside a {@link Pointer} that indicates which key was
- *   unexpected.
+ * Use when you need to detect excess properties during strict struct/tuple
+ * validation.
  *
  * **Details**
  *
@@ -456,13 +450,12 @@ export class UnexpectedKey extends Base {
 }
 
 /**
- * Issue that groups multiple child issues under a single schema node.
+ * Represents a schema issue that groups multiple child issues under a single schema node.
  *
  * **When to use**
  *
- * Use when walk the issue tree for struct/tuple schemas that collect all field errors
- *   rather than failing on the first.
- * - Match on `_tag === "Composite"` to iterate over `issues`.
+ * Use when you need to walk the issue tree for struct/tuple schemas that collect
+ * all field errors rather than failing on the first.
  *
  * **Details**
  *
@@ -514,14 +507,13 @@ export class Composite extends Base {
 }
 
 /**
- * Issue produced when the runtime type of the input does not match the type
+ * Represents a schema issue produced when the runtime type of the input does not match the type
  * expected by the schema (e.g. got `null` when `string` was expected).
  *
  * **When to use**
  *
- * Use when detect basic type mismatches (wrong primitive, null where object expected,
- *   etc.).
- * - The most common leaf issue in typical validation failures.
+ * Use when you need to detect basic type mismatches, such as a wrong primitive
+ * or `null` where an object was expected.
  *
  * **Details**
  *
@@ -578,14 +570,13 @@ export class InvalidType extends Base {
 }
 
 /**
- * Issue produced when the input has the correct type but its value violates a
+ * Represents a schema issue produced when the input has the correct type but its value violates a
  * constraint (e.g. a string that is too short, a number out of range).
  *
  * **When to use**
  *
- * Use when detect constraint violations from `Schema.filter`, `Schema.minLength`,
- *   `Schema.greaterThan`, etc.
- * - Create custom validation errors in `Schema.makeFilter` callbacks.
+ * Use when you need to detect constraint violations from `Schema.filter`,
+ * `Schema.minLength`, `Schema.greaterThan`, or similar checks.
  *
  * **Details**
  *
@@ -642,13 +633,13 @@ export class InvalidValue extends Base {
 }
 
 /**
- * Issue produced when a forbidden operation is encountered during parsing,
+ * Represents a schema issue produced when a forbidden operation is encountered during parsing,
  * such as an asynchronous Effect running inside `Schema.decodeUnknownSync`.
  *
  * **When to use**
  *
- * Use when detect that a schema requires async execution but was run synchronously.
- * - Provide custom error messages via the `annotations.message` field.
+ * Use when you need to detect that a schema requires async execution but was run
+ * synchronously.
  *
  * **Details**
  *
@@ -703,13 +694,12 @@ export class Forbidden extends Base {
 }
 
 /**
- * Issue produced when a value does not match *any* member of a union schema.
+ * Represents a schema issue produced when a value does not match *any* member of a union schema.
  *
  * **When to use**
  *
- * Use when inspect which union members were attempted and why each failed.
- * - `issues` may be empty when the union has no members or when the input does
- *   not pass the initial type guard.
+ * Use when you need to inspect which union members were attempted and why each
+ * failed.
  *
  * **Details**
  *
@@ -761,13 +751,13 @@ export class AnyOf extends Base {
 }
 
 /**
- * Issue produced when a value matches *multiple* members of a union that is
+ * Represents a schema issue produced when a value matches *multiple* members of a union that is
  * configured to allow exactly one match (oneOf mode).
  *
  * **When to use**
  *
- * Use when detect ambiguous union matches when `oneOf` validation is enabled.
- * - Inspect `successes` to see which members matched.
+ * Use when you need to detect ambiguous union matches when `oneOf` validation is
+ * enabled.
  *
  * **Details**
  *
@@ -828,7 +818,6 @@ export class OneOf extends Base {
  *
  * **Details**
  *
- * - Pure; does not mutate the issue.
  * - Returns `Option.none()` for `Pointer` and `MissingKey` (they carry no
  *   value).
  * - Returns the existing `Option` for variants that already store `actual` as
@@ -928,8 +917,8 @@ export interface Formatter<out Format> extends FormatterI<Issue, Format> {}
  *
  * **When to use**
  *
- * Use when passing a custom `LeafHook` to {@link makeFormatterStandardSchemaV1} to
- *   override how terminal issues are rendered.
+ * Use when customizing how {@link makeFormatterStandardSchemaV1} renders
+ * terminal issues.
  *
  * @see {@link defaultLeafHook} — the built-in implementation
  * @see {@link Leaf} — the union of terminal issue types
@@ -940,7 +929,7 @@ export interface Formatter<out Format> extends FormatterI<Issue, Format> {}
 export type LeafHook = (issue: Leaf) => string
 
 /**
- * The built-in {@link LeafHook} used by default formatters.
+ * Returns the built-in {@link LeafHook} used by default formatters.
  *
  * **When to use**
  *
@@ -999,9 +988,8 @@ export const defaultLeafHook: LeafHook = (issue): string => {
  *
  * **When to use**
  *
- * Use when passing a custom `CheckHook` to
- * {@link makeFormatterStandardSchemaV1} to override how filter failures are
- * rendered.
+ * Use when customizing how {@link makeFormatterStandardSchemaV1} renders
+ * filter failures.
  *
  * **Details**
  *
@@ -1017,7 +1005,7 @@ export const defaultLeafHook: LeafHook = (issue): string => {
 export type CheckHook = (issue: Filter) => string | undefined
 
 /**
- * The built-in {@link CheckHook} used by default formatters.
+ * Returns the built-in {@link CheckHook} used by default formatters.
  *
  * **When to use**
  *

package/src/SchemaParser.ts

@@ -340,7 +340,8 @@ export function decodePromise<S extends Schema.Decoder<unknown>>(
 }
 
 /**
- * Creates a synchronous decoder for `unknown` input that returns an `Exit`.
+ * Creates a synchronous decoder for `unknown` input that reports failure safely
+ * as an `Exit`.
  *
  * **When to use**
  *
@@ -376,7 +377,7 @@ export function decodeUnknownExit<S extends Schema.Decoder<unknown>>(
 
 /**
  * Creates a synchronous decoder for input already typed as the schema's `Encoded`
- * type, returning an `Exit`.
+ * type, reporting failure safely as an `Exit`.
  *
  * **When to use**
  *
@@ -400,7 +401,7 @@ export const decodeExit: <S extends Schema.Decoder<unknown>>(
 ) => (input: S["Encoded"], options?: AST.ParseOptions) => Exit.Exit<S["Type"], Issue.Issue> = decodeUnknownExit
 
 /**
- * Creates a decoder for `unknown` input that returns an `Option`.
+ * Creates a decoder for `unknown` input that returns an `Option` safely.
  *
  * **When to use**
  *
@@ -426,7 +427,7 @@ export function decodeUnknownOption<S extends Schema.Decoder<unknown>>(
 }
 
 /**
- * Creates a decoder for input already typed as the schema's `Encoded` type,
+ * Creates a decoder safely for input already typed as the schema's `Encoded` type,
  * returning an `Option`.
  *
  * **When to use**
@@ -451,7 +452,8 @@ export const decodeOption: <S extends Schema.Decoder<unknown>>(
 ) => (input: S["Encoded"], options?: AST.ParseOptions) => Option.Option<S["Type"]> = decodeUnknownOption
 
 /**
- * Creates a decoder for `unknown` input that returns a `Result`.
+ * Creates a decoder for `unknown` input that reports failure safely as a
+ * `Result`.
  *
  * **When to use**
  *
@@ -483,7 +485,7 @@ export function decodeUnknownResult<S extends Schema.Decoder<unknown>>(
 
 /**
  * Creates a decoder for input already typed as the schema's `Encoded` type,
- * returning a `Result`.
+ * reporting failure safely as a `Result`.
  *
  * **When to use**
  *
@@ -673,7 +675,8 @@ export const encodePromise: <S extends Schema.Encoder<unknown>>(
 ) => (input: S["Type"], options?: AST.ParseOptions) => Promise<S["Encoded"]> = encodeUnknownPromise
 
 /**
- * Creates a synchronous encoder for `unknown` input that returns an `Exit`.
+ * Creates a synchronous encoder for `unknown` input that reports failure safely
+ * as an `Exit`.
  *
  * **When to use**
  *
@@ -700,7 +703,7 @@ export function encodeUnknownExit<S extends Schema.Encoder<unknown>>(
 
 /**
  * Creates a synchronous encoder for input already typed as the schema's decoded
- * `Type`, returning an `Exit`.
+ * `Type`, reporting failure safely as an `Exit`.
  *
  * **When to use**
  *
@@ -724,7 +727,7 @@ export const encodeExit: <S extends Schema.Encoder<unknown>>(
 ) => (input: S["Type"], options?: AST.ParseOptions) => Exit.Exit<S["Encoded"], Issue.Issue> = encodeUnknownExit
 
 /**
- * Creates an encoder for `unknown` input that returns an `Option`.
+ * Creates an encoder for `unknown` input that returns an `Option` safely.
  *
  * **When to use**
  *
@@ -750,7 +753,7 @@ export function encodeUnknownOption<S extends Schema.Encoder<unknown>>(
 }
 
 /**
- * Creates an encoder for input already typed as the schema's decoded `Type`,
+ * Creates an encoder safely for input already typed as the schema's decoded `Type`,
  * returning an `Option`.
  *
  * **When to use**
@@ -775,7 +778,8 @@ export const encodeOption: <S extends Schema.Encoder<unknown>>(
 ) => (input: S["Type"], options?: AST.ParseOptions) => Option.Option<S["Encoded"]> = encodeUnknownOption
 
 /**
- * Creates an encoder for `unknown` input that returns a `Result`.
+ * Creates an encoder for `unknown` input that reports failure safely as a
+ * `Result`.
  *
  * **When to use**
  *
@@ -803,7 +807,7 @@ export function encodeUnknownResult<S extends Schema.Encoder<unknown>>(
 
 /**
  * Creates an encoder for input already typed as the schema's decoded `Type`,
- * returning a `Result`.
+ * reporting failure safely as a `Result`.
  *
  * **When to use**
  *