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

package/dist/Schema.d.ts

@@ -153,7 +153,7 @@ export type ConstructorDefault = "no-default" | "with-default";
  *
  * **When to use**
  *
- * - Pass `disableChecks: true` to skip validation when you trust the data.
+ * Use when passing `disableChecks: true` to skip validation when you trust the data.
  * - Pass `parseOptions` to control error reporting behavior.
  *
  * @see {@link Bottom.makeEffect}
@@ -179,7 +179,7 @@ export interface MakeOptions {
  *
  * **When to use**
  *
- * - You are writing advanced generic schema utilities or performing schema
+ * Use when you are writing advanced generic schema utilities or performing schema
  *   introspection.
  * - In user code, prefer {@link Schema}, {@link Codec}, {@link Decoder}, or
  *   {@link Encoder} instead.
@@ -213,10 +213,57 @@ export interface Bottom<out T, out E, out RD, out RE, out Ast extends AST.AST, o
     check(...checks: readonly [AST.Check<this["Type"]>, ...Array<AST.Check<this["Type"]>>]): this["Rebuild"];
     rebuild(ast: this["ast"]): this["Rebuild"];
     /**
-     * Constructs a value from the make input representation.
+     * Constructs a value from the make input representation synchronously.
+     *
+     * **When to use**
+     *
+     * Use when constructor input is trusted or when validation failure
+     * should abort with a thrown `Error`.
+     *
+     * **Details**
+     *
+     * Applies constructor defaults and type-side validation according to
+     * `MakeOptions`.
+     *
+     * **Gotchas**
+     *
+     * Throws an `Error` with the schema issue in its `cause` when validation
+     * fails.
+     *
+     * @see {@link Bottom.makeOption} — construct synchronously and discard validation details
+     * @see {@link Bottom.makeEffect} — construct through `Effect` when validation failure should stay in the error channel
      */
     make(input: this["~type.make.in"], options?: MakeOptions): this["Type"];
+    /**
+     * Constructs a value from the make input representation, returning `Option.none`
+     * when validation fails.
+     *
+     * **When to use**
+     *
+     * Use when you only need to know whether construction succeeds
+     * and do not need validation details.
+     *
+     * **Details**
+     *
+     * Applies constructor defaults and type-side validation according to
+     * `MakeOptions`.
+     *
+     * @see {@link Bottom.make} — construct synchronously when validation failure should throw
+     * @see {@link Bottom.makeEffect} — construct through `Effect` when validation details should stay in the error channel
+     */
     makeOption(input: this["~type.make.in"], options?: MakeOptions): Option_.Option<this["Type"]>;
+    /**
+     * Constructs a value from the make input representation, returning validation
+     * failures in the `Effect` error channel.
+     *
+     * **When to use**
+     *
+     * Use when constructor input may fail validation and you want to
+     * compose that failure with other `Effect` operations instead of throwing.
+     *
+     * @see {@link Bottom.make} — construct synchronously when validation failure should throw
+     * @see {@link Bottom.makeOption} — construct synchronously and discard validation details
+     */
     makeEffect(input: this["~type.make.in"], options?: MakeOptions): Effect.Effect<this["Type"], SchemaError>;
 }
 /**
@@ -1840,6 +1887,12 @@ export interface Boolean extends Bottom<boolean, boolean, never, never, AST.Bool
 /**
  * Schema for `boolean` values. Validates that the input is `typeof` `"boolean"`.
  *
+ * **When to use**
+ *
+ * Use to validate values that are already JavaScript booleans.
+ *
+ * @see {@link BooleanFromBit} for a schema that decodes bit literals `0` or `1` into a boolean
+ *
  * @category Boolean
  * @since 4.0.0
  */
@@ -1873,6 +1926,13 @@ export interface BigInt extends Bottom<bigint, bigint, never, never, AST.BigInt,
 /**
  * Schema for `bigint` values. Validates that the input is `typeof` `"bigint"`.
  *
+ * **When to use**
+ *
+ * Use when the input is already a bigint and the schema should validate and
+ * preserve bigint values without parsing from another representation.
+ *
+ * @see {@link BigIntFromString} for parsing string input into a bigint
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -2440,6 +2500,14 @@ export declare namespace Record {
  * Companion type for a key-value record (map) with a typed key and value schema.
  * Produced by {@link Record}.
  *
+ * **When to use**
+ *
+ * Use as the concrete schema type returned by `Record` when an API needs to
+ * accept or return a record schema with typed property keys and values.
+ *
+ * @see {@link Record} for constructing record schemas
+ * @see {@link StructWithRest} for combining fixed struct fields with record index signatures
+ *
  * @category models
  * @since 4.0.0
  */
@@ -2570,6 +2638,14 @@ export declare namespace StructWithRest {
  * Companion type for a struct combined with one or more record schemas. Produced
  * by {@link StructWithRest}.
  *
+ * **When to use**
+ *
+ * Use as the schema type returned by `StructWithRest` when generic code needs to
+ * retain the base struct schema and all rest record schemas.
+ *
+ * @see {@link StructWithRest} for constructing this schema type
+ * @see {@link Record} for constructing record schemas used as rest index signatures
+ *
  * @category models
  * @since 4.0.0
  */
@@ -2911,17 +2987,22 @@ export declare function TupleWithRest<S extends Tuple<Tuple.Elements>, const Res
 /**
  * Schema interface produced by `Schema.Array` for readonly arrays.
  *
+ * **When to use**
+ *
+ * Use as the public companion type returned by `Schema.Array` when you need to
+ * refer to a readonly array schema built from an element schema.
+ *
  * **Details**
  *
  * The decoded type is `ReadonlyArray<S["Type"]>`, the encoded type is
  * `ReadonlyArray<S["Encoded"]>`, and the element schema is available as
- * `schema`.
+ * `value`.
  *
  * @category models
  * @since 4.0.0
  */
 export interface $Array<S extends Top> extends Bottom<ReadonlyArray<S["Type"]>, ReadonlyArray<S["Encoded"]>, S["DecodingServices"], S["EncodingServices"], AST.Arrays, $Array<S>, ReadonlyArray<S["~type.make"]>, ReadonlyArray<S["Iso"]>> {
-    readonly schema: S;
+    readonly value: S;
 }
 interface ArrayLambda extends Lambda {
     <S extends Top>(self: S): $Array<S>;
@@ -2955,11 +3036,17 @@ ArraySchema as Array };
 /**
  * Companion type for a non-empty `ReadonlyArray`. Produced by {@link NonEmptyArray}.
  *
+ * **Details**
+ *
+ * The decoded type is `readonly [S["Type"], ...Array<S["Type"]>]`, the encoded type is
+ * `readonly [S["Encoded"], ...Array<S["Encoded"]>]`, and the element schema is available as
+ * `value`.
+ *
  * @category models
  * @since 3.10.0
  */
 export interface NonEmptyArray<S extends Top> extends Bottom<readonly [S["Type"], ...Array<S["Type"]>], readonly [S["Encoded"], ...Array<S["Encoded"]>], S["DecodingServices"], S["EncodingServices"], AST.Arrays, NonEmptyArray<S>, readonly [S["~type.make"], ...Array<S["~type.make"]>], readonly [S["Iso"], ...Array<S["Iso"]>]> {
-    readonly schema: S;
+    readonly value: S;
 }
 interface NonEmptyArrayLambda extends Lambda {
     <S extends Top>(self: S): NonEmptyArray<S>;
@@ -2988,12 +3075,19 @@ export declare const NonEmptyArray: NonEmptyArrayLambda;
  * Schema interface returned by `ArrayEnsure`, which normalizes a single item or
  * an array of items into a readonly array.
  *
+ * **When to use**
+ *
+ * Use as the schema type returned by `ArrayEnsure` when generic code needs to
+ * retain the original item schema.
+ *
  * **Details**
  *
  * The schema decodes from `S` or `Schema.Array(S)` and produces
  * `ReadonlyArray<S["Type"]>`.
  *
- * @category Arrays
+ * @see {@link ArrayEnsure} for constructing this schema type
+ *
+ * @category constructors
  * @since 3.10.0
  */
 export interface ArrayEnsure<S extends Top> extends decodeTo<$Array<toType<S>>, Union<readonly [S, $Array<S>]>> {
@@ -3003,16 +3097,26 @@ export interface ArrayEnsure<S extends Top> extends decodeTo<$Array<toType<S>>,
  * Creates a schema that accepts either a value decoded by `schema` or an array
  * decoded by `Schema.Array(schema)`, then returns an array.
  *
+ * **When to use**
+ *
+ * Use to accept input that may be provided either as one item or as an array,
+ * while normalizing decoded values to a readonly array.
+ *
  * **Details**
  *
+ * During encoding, one-element arrays are encoded as the single element. Empty
+ * arrays and arrays with two or more elements are encoded as arrays.
+ *
+ * **Gotchas**
+ *
  * The single-value branch is tried before the array branch. If `schema` itself
  * accepts arrays, an array input can be treated as one value and wrapped in a
  * one-element array.
  *
- * During encoding, one-element arrays are encoded as the single element. Empty
- * arrays and arrays with two or more elements are encoded as arrays.
+ * @see {@link Array} for accepting only array input
+ * @see {@link NonEmptyArray} for requiring at least one decoded element
  *
- * @category Arrays
+ * @category constructors
  * @since 3.10.0
  */
 export declare function ArrayEnsure<S extends Top>(schema: S): ArrayEnsure<S>;
@@ -3326,6 +3430,13 @@ type DistributeBrands<B> = UnionToIntersection<B extends infer U extends string
  * The output type of {@link brand}, intersecting the schema's `Type` with one or
  * more {@link Brand.Brand} tags.
  *
+ * **When to use**
+ *
+ * Use as the schema type returned by `brand` when generic code needs to retain
+ * the wrapped schema and nominal brand type.
+ *
+ * @see {@link brand} for adding the brand tag to an existing schema
+ *
  * @category branding
  * @since 3.10.0
  */
@@ -3337,6 +3448,18 @@ export interface brand<S extends Top, B> extends Bottom<S["Type"] & DistributeBr
  * Adds a nominal brand to a schema, intersecting the output type with
  * `Brand.Brand<B>` to prevent accidental mixing of structurally identical types.
  *
+ * **When to use**
+ *
+ * Use to make values decoded by an existing schema nominally distinct when the
+ * schema already carries the runtime validation you need.
+ *
+ * **Gotchas**
+ *
+ * `brand` adds brand metadata and narrows the TypeScript output type, but it
+ * does not add runtime checks.
+ *
+ * @see {@link fromBrand} for applying a Brand constructor's checks along with the brand tag
+ *
  * @category branding
  * @since 3.10.0
  */
@@ -3459,6 +3582,19 @@ export declare function catchDecoding<S extends Top>(f: (issue: Issue.Issue) =>
 /**
  * Like {@link catchDecoding}, but the handler may require Effect services (`R`).
  *
+ * **When to use**
+ *
+ * Use when decoding fallback logic needs services from the Effect context.
+ *
+ * **Details**
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either succeeds
+ * with a fallback value or re-fails with a (possibly different) issue. The
+ * handler's services are added to the schema's decoding services.
+ *
+ * @see {@link catchDecoding} for recovery handlers that do not require services
+ * @see {@link middlewareDecoding} for intercepting or replacing the full decoding pipeline
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -3479,6 +3615,19 @@ export declare function catchEncoding<S extends Top>(f: (issue: Issue.Issue) =>
 /**
  * Like {@link catchEncoding}, but the handler may require Effect services (`R`).
  *
+ * **When to use**
+ *
+ * Use when encoding fallback logic needs services from the Effect context.
+ *
+ * **Details**
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either succeeds
+ * with a fallback encoded value or re-fails with a (possibly different) issue.
+ * The handler's services are added to the schema's encoding services.
+ *
+ * @see {@link catchEncoding} for recovery handlers that do not require services
+ * @see {@link middlewareEncoding} for intercepting or replacing the full encoding pipeline
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -4913,9 +5062,9 @@ export declare function isDateValid(annotations?: Annotations.Filter): AST.Filte
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `min` constraint
- * with `minExcluded: true` to ensure generated Date objects are greater than the
- * specified value.
+ * When generating test data with fast-check, this applies a `min` constraint of
+ * one millisecond after the specified value to ensure generated Date objects are
+ * greater than it.
  *
  * @category Date checks
  * @since 4.0.0
@@ -4949,9 +5098,9 @@ export declare const isGreaterThanOrEqualToDate: (minimum: globalThis.Date, anno
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `max` constraint
- * with `maxExcluded: true` to ensure generated Date objects are less than the
- * specified value.
+ * When generating test data with fast-check, this applies a `max` constraint of
+ * one millisecond before the specified value to ensure generated Date objects
+ * are less than it.
  *
  * @category Date checks
  * @since 4.0.0
@@ -4992,7 +5141,8 @@ export declare const isLessThanOrEqualToDate: (maximum: globalThis.Date, annotat
  * Arbitrary:
  *
  * When generating test data with fast-check, this applies `min` and `max`
- * constraints to ensure generated Date objects fall within the specified range.
+ * constraints to ensure generated Date objects fall within the specified range,
+ * shifting exclusive bounds by one millisecond.
  *
  * @category Date checks
  * @since 4.0.0
@@ -5010,8 +5160,8 @@ export declare const isBetweenDate: (options: {
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `min` constraint
- * with `minExcluded: true` to ensure generated BigInts are greater than the
+ * When generating test data with fast-check, this applies a `min` constraint of
+ * `exclusiveMinimum + 1n` to ensure generated BigInts are greater than the
  * specified value.
  *
  * @category BigInt checks
@@ -5041,8 +5191,8 @@ export declare const isGreaterThanOrEqualToBigInt: (minimum: bigint, annotations
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `max` constraint
- * with `maxExcluded: true` to ensure generated BigInts are less than the
+ * When generating test data with fast-check, this applies a `max` constraint of
+ * `exclusiveMaximum - 1n` to ensure generated BigInts are less than the
  * specified value.
  *
  * @category BigInt checks
@@ -5428,7 +5578,20 @@ export interface Char extends String {
     readonly "Rebuild": Char;
 }
 /**
- * A schema representing a single character.
+ * A schema for strings whose JavaScript `length` is exactly `1`.
+ *
+ * **When to use**
+ *
+ * Use to validate string values that must have `length === 1`.
+ *
+ * **Gotchas**
+ *
+ * This schema uses JavaScript `String.length`, so visible characters made from
+ * multiple UTF-16 code units do not satisfy `length === 1`.
+ *
+ * @see {@link String} for unconstrained string values
+ * @see {@link NonEmptyString} for strings with length greater than zero
+ * @see {@link isLengthBetween} for the underlying length check
  *
  * @category String
  * @since 3.10.0
@@ -5719,17 +5882,16 @@ export interface Redacted<S extends Top> extends declareConstructor<Redacted_.Re
  *   - The default JSON serializer will deserialize into a `Redacted` instance with the label
  *   - The arbitrary generator will produce a `Redacted` instance with the label
  *   - The formatter will return the label
- *
- * Default JSON serializer:
- *
- * The default JSON serializer will fail when attempting to serialize a `Redacted` value,
- * but it will deserialize a value into a `Redacted` instance.
+ * - `disallowJsonEncode`: When set to `true`, when attempting to encode a `Redacted` instance
+ *   into JSON, it will fail with an error. This is useful when the wrapped schema is
+ *   sensitive and should not be exposed in JSON.
  *
  * @category Redacted
  * @since 3.10.0
  */
 export declare function Redacted<S extends Top>(value: S, options?: {
     readonly label?: string | undefined;
+    readonly disallowJsonEncode?: boolean | undefined;
 }): Redacted<S>;
 /**
  * Type-level representation of a schema that decodes a raw value with the
@@ -5759,17 +5921,26 @@ export declare function redact<S extends Top>(schema: S): middlewareDecoding<S,
  */
 export declare function RedactedFromValue<S extends Top>(value: S, options?: {
     readonly label?: string | undefined;
+    readonly disallowEncode?: boolean | undefined;
 }): RedactedFromValue<S>;
 /**
  * Schema for a single `Cause.Reason`, representing one reason a fiber may fail:
  * a typed error (`Fail`), an unexpected defect (`Die`), or an interrupt
  * (`Interrupt`).
  *
+ * **When to use**
+ *
+ * Use as the schema type returned by `CauseReason` when generic code needs to
+ * retain the typed failure and defect schemas.
+ *
  * **Details**
  *
  * The `error` schema validates typed failures and the `defect` schema validates
  * unexpected defects.
  *
+ * @see {@link CauseReason} for constructing this schema type
+ * @see {@link CauseReasonIso} for the ISO shape of each cause reason
+ *
  * @category CauseReason
  * @since 4.0.0
  */
@@ -5803,6 +5974,19 @@ export type CauseReasonIso<E extends Top, D extends Top> = {
  * Creates a schema for `Cause.Reason` values using separate schemas for typed
  * failures and unexpected defects.
  *
+ * **When to use**
+ *
+ * Use to validate, transform, or serialize individual `Cause.Reason` values
+ * when typed failures and unexpected defects need separate schemas.
+ *
+ * **Details**
+ *
+ * `Fail` reasons use the `error` schema, `Die` reasons use the `defect` schema,
+ * and `Interrupt` reasons carry only an optional fiber id.
+ *
+ * @see {@link Cause} for constructing schemas for full Cause values
+ * @see {@link CauseReasonIso} for the ISO shape of each cause reason
+ *
  * @category CauseReason
  * @since 4.0.0
  */
@@ -5811,11 +5995,19 @@ export declare function CauseReason<E extends Top, D extends Top>(error: E, defe
  * Schema for `Cause` values, represented as an ordered collection of failure
  * reasons combining typed errors, defects, and interrupts.
  *
+ * **When to use**
+ *
+ * Use as the schema type returned by `Cause` when generic code needs to retain
+ * the typed failure and defect schemas.
+ *
  * **Details**
  *
  * The `error` schema validates typed failures and the `defect` schema validates
  * unexpected defects.
  *
+ * @see {@link Cause} for constructing this schema type
+ * @see {@link CauseIso} for the ordered array representation used by the schema ISO
+ *
  * @category Cause
  * @since 3.10.0
  */
@@ -5828,6 +6020,14 @@ export interface Cause<E extends Top, D extends Top> extends declareConstructor<
  * Iso representation used for `Cause` schemas: an ordered array of
  * `CauseReasonIso` values.
  *
+ * **When to use**
+ *
+ * Use when working with the ISO shape of a `Cause` schema, such as `toIso`
+ * optics or codecs that expose a cause as its ordered array of encoded reasons.
+ *
+ * @see {@link Cause} for constructing schemas for full Cause values
+ * @see {@link CauseReasonIso} for the ISO shape of each array element
+ *
  * @category Cause
  * @since 4.0.0
  */
@@ -5836,6 +6036,20 @@ export type CauseIso<E extends Top, D extends Top> = ReadonlyArray<CauseReasonIs
  * Creates a schema for `Cause` values using separate schemas for typed failures
  * and unexpected defects.
  *
+ * **When to use**
+ *
+ * Use to validate, transform, or serialize Effect failure causes when typed
+ * failures and unexpected defects need separate schemas.
+ *
+ * **Details**
+ *
+ * The `error` schema is applied to `Fail` reasons and the `defect` schema is
+ * applied to `Die` reasons. Interrupt reasons do not use either schema and
+ * carry only an optional fiber id.
+ *
+ * @see {@link CauseReason} for the schema used by each individual cause reason
+ * @see {@link CauseIso} for the ordered array representation used by the schema ISO
+ *
  * @category Cause
  * @since 3.10.0
  */
@@ -5959,6 +6173,15 @@ export declare function Exit<A extends Top, E extends Top, D extends Top>(value:
  * Type-level representation of a `ReadonlyMap` schema whose keys and values are
  * validated by the provided schemas.
  *
+ * **When to use**
+ *
+ * Use as a type annotation for a `ReadonlyMap` schema when exposing or returning
+ * the schema while preserving its key schema, value schema, and ISO
+ * representation.
+ *
+ * @see {@link ReadonlyMap} for constructing this schema type from key and value schemas
+ * @see {@link ReadonlyMapIso} for the readonly tuple-array ISO representation used by this schema
+ *
  * @category ReadonlyMap
  * @since 4.0.0
  */
@@ -6015,6 +6238,14 @@ export declare function HashMap<Key extends Top, Value extends Top>(key: Key, va
  * Type-level representation of a `ReadonlySet` schema whose values are validated
  * by the provided element schema.
  *
+ * **When to use**
+ *
+ * Use to name or constrain the schema type produced by `ReadonlySet` when
+ * generic code needs to retain the element schema type.
+ *
+ * @see {@link ReadonlySet} for constructing this schema type
+ * @see {@link ReadonlySetIso} for the array representation used by this schema's ISO
+ *
  * @category ReadonlySet
  * @since 4.0.0
  */
@@ -6080,6 +6311,13 @@ export interface Chunk<Value extends Top> extends declareConstructor<Chunk_.Chun
  * Iso representation used for `Chunk` schemas: an array of element values using
  * the element schema's `Iso` type.
  *
+ * **When to use**
+ *
+ * Use when annotating type-level helpers that work with the readonly-array ISO
+ * shape of a `Chunk` schema.
+ *
+ * @see {@link Chunk} for the schema interface and constructor that use this ISO representation
+ *
  * @category Chunk
  * @since 4.0.0
  */
@@ -6172,12 +6410,16 @@ export interface Date extends instanceOf<globalThis.Date> {
 /**
  * A schema for JavaScript `Date` objects.
  *
+ * **When to use**
+ *
+ * Use to validate in-memory values that must already be JavaScript `Date`
+ * instances.
+ *
  * **Details**
  *
- * This schema accepts any `Date` instance, including invalid dates. For
- * validating only valid dates, use `DateValid` instead. The default JSON
- * serializer encodes valid dates as ISO 8601 strings; invalid dates encode as
- * `"Invalid Date"`.
+ * This schema accepts any `Date` instance, including invalid dates. The default
+ * JSON serializer encodes valid dates as ISO 8601 strings; invalid dates encode
+ * as `"Invalid Date"`.
  *
  * **Example** (Date schema)
  *
@@ -6188,6 +6430,8 @@ export interface Date extends instanceOf<globalThis.Date> {
  * // => Date { 2024-01-01T00:00:00.000Z }
  * ```
  *
+ * @see {@link DateValid} for accepting only valid Date instances
+ *
  * @category Date
  * @since 4.0.0
  */
@@ -6205,16 +6449,27 @@ export interface DateFromString extends decodeTo<Date, String> {
 /**
  * A transformation schema that decodes a string into a JavaScript `Date`.
  *
+ * **When to use**
+ *
+ * Use to model string-encoded dates that decode to JavaScript `Date` objects
+ * and encode back to strings.
+ *
  * **Details**
  *
  * Decoding:
- * The string is passed to JavaScript `Date` construction and may decode to an
- * invalid `Date`. Compose with `DateValid` when invalid dates should be rejected.
+ * The string is passed to JavaScript `Date` construction.
  *
  * Encoding:
  * A valid `Date` is encoded as an ISO string; an invalid `Date` is encoded as
  * `"Invalid Date"`.
  *
+ * **Gotchas**
+ *
+ * Invalid date strings can decode to invalid `Date` instances.
+ *
+ * @see {@link Date} for accepting Date instances directly
+ * @see {@link DateValid} for rejecting invalid Date instances
+ *
  * @category Date
  * @since 3.10.0
  */
@@ -6367,12 +6622,19 @@ export interface BigDecimal extends declare<BigDecimal_.BigDecimal> {
 /**
  * A schema for `BigDecimal` values.
  *
+ * **When to use**
+ *
+ * Use when values are already `BigDecimal` instances and need schema validation,
+ * formatting, equivalence, and JSON string serialization.
+ *
  * **Details**
  *
  * Default JSON serializer:
  *
  * - encodes `BigDecimal` as a `string`
  *
+ * @see {@link BigDecimalFromString} for parsing string input into a BigDecimal
+ *
  * @category BigDecimal
  * @since 3.10.0
  */
@@ -6390,13 +6652,26 @@ export interface BigDecimalFromString extends decodeTo<BigDecimal, String> {
 /**
  * A transformation schema that parses a string into a `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to parse decimal or exponent-notation strings into arbitrary-precision
+ * BigDecimal values while encoding them back to strings.
+ *
  * **Details**
  *
  * Decoding:
- * - A `string` is decoded as a `BigDecimal`.
+ * - A `string` is decoded with `BigDecimal.fromString`.
  *
  * Encoding:
- * - A `BigDecimal` is encoded as a `string`.
+ * - A `BigDecimal` is encoded with `BigDecimal.format`.
+ *
+ * **Gotchas**
+ *
+ * An empty string decodes as zero.
+ *
+ * @see {@link BigDecimal} for validating values that are already BigDecimal values
+ * @see {@link BigIntFromString} for parsing base-10 integer strings into bigint values
+ * @see {@link NumberFromString} for parsing JavaScript number strings
  *
  * @category BigDecimal
  * @since 4.0.0
@@ -6865,6 +7140,11 @@ export interface BigIntFromString extends decodeTo<BigInt, String> {
 /**
  * A transformation schema that parses a string into a `bigint`.
  *
+ * **When to use**
+ *
+ * Use to parse signed base-10 integer strings into bigint values while encoding
+ * bigint values back to decimal strings.
+ *
  * **Details**
  *
  * Decoding:
@@ -6873,6 +7153,15 @@ export interface BigIntFromString extends decodeTo<BigInt, String> {
  * Encoding:
  * - A `bigint` is encoded as a `string`.
  *
+ * **Gotchas**
+ *
+ * Decoding accepts only strings matching `^-?\d+$`.
+ *
+ * @see {@link isStringBigInt} for the string predicate used by this schema
+ * @see {@link BigInt} for validating values that are already bigint values
+ * @see {@link NumberFromString} for parsing JavaScript number strings, including non-finite values
+ * @see {@link BigDecimalFromString} for parsing decimal number strings
+ *
  * @category BigInt
  * @since 4.0.0
  */
@@ -7078,6 +7367,19 @@ export interface BooleanFromBit extends decodeTo<Boolean, Literals<readonly [0,
 /**
  * A boolean parsed from 0 or 1.
  *
+ * **When to use**
+ *
+ * Use when decoding data sources that represent booleans as `0 | 1` while
+ * keeping boolean values in the decoded model.
+ *
+ * **Details**
+ *
+ * Decoding accepts only `0 | 1`, maps `1` to `true`, and maps `0` to `false`.
+ * Encoding maps `true` to `1` and `false` to `0`.
+ *
+ * @see {@link Boolean} for validating values that are already booleans
+ * @see {@link Literals} for keeping bit literals instead of decoding them
+ *
  * @category Boolean
  * @since 4.0.0
  */
@@ -7196,11 +7498,20 @@ export interface DateTimeUtc extends declare<DateTime.Utc> {
 /**
  * A schema for `DateTime.Utc` values.
  *
+ * **When to use**
+ *
+ * Use to validate existing `DateTime.Utc` schema values and use the default JSON
+ * codec that represents them as UTC ISO strings.
+ *
  * **Details**
  *
- * Default JSON serializer:
+ * The default JSON codec decodes UTC ISO strings into `DateTime.Utc` values and
+ * encodes `DateTime.Utc` values as UTC ISO strings.
  *
- * - encodes `DateTime.Utc` as a UTC ISO string
+ * @see {@link DateTimeUtcFromString} for decoding date-time strings into UTC values
+ * @see {@link DateTimeUtcFromDate} for decoding JavaScript Date values into UTC values
+ * @see {@link DateTimeUtcFromMillis} for decoding epoch milliseconds into UTC values
+ * @see {@link DateTimeZoned} for preserving zoned DateTime values
  *
  * @category DateTime
  * @since 3.10.0
@@ -7219,6 +7530,11 @@ export interface DateTimeUtcFromDate extends decodeTo<DateTimeUtc, Date> {
 /**
  * A transformation schema that decodes a `Date` into a `DateTime.Utc`.
  *
+ * **When to use**
+ *
+ * Use when a boundary provides valid JavaScript `Date` objects but the decoded
+ * model should use `DateTime.Utc`.
+ *
  * **Details**
  *
  * Decoding:
@@ -7227,6 +7543,11 @@ export interface DateTimeUtcFromDate extends decodeTo<DateTimeUtc, Date> {
  * Encoding:
  * - A `DateTime.Utc` is encoded as a `Date`
  *
+ * @see {@link DateTimeUtc} for validating values that are already `DateTime.Utc`
+ * @see {@link DateTimeUtcFromString} for decoding date-time strings into UTC values
+ * @see {@link DateTimeUtcFromMillis} for decoding epoch milliseconds into UTC values
+ * @see {@link DateValid} for validating Date instances without converting them
+ *
  * @category DateTime
  * @since 3.12.0
  */
@@ -7501,13 +7822,23 @@ type MissingSelfGeneric<Usage extends string> = `Missing \`Self\` generic - use
 /**
  * Creates a schema-backed class whose constructor validates input against a
  * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
- * input (unless `disableChecks` is set in the options).
+ * input.
+ *
+ * **When to use**
+ *
+ * Use to define a schema-backed data class when you want validated
+ * construction, schema-derived decoding/encoding, and class-style methods or
+ * inheritance.
  *
  * **Details**
  *
  * Pass the desired class type as the first type parameter. The second optional
  * type parameter can be used to add nominal brands.
  *
+ * **Gotchas**
+ *
+ * Passing `disableChecks` in the options skips constructor validation.
+ *
  * **Example** (Basic class)
  *
  * ```ts
@@ -7541,6 +7872,10 @@ type MissingSelfGeneric<Usage extends string> = `Missing \`Self\` generic - use
  * console.log(dog.breed) // "Labrador"
  * ```
  *
+ * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
+ * @see {@link ErrorClass} for defining schema-backed error classes
+ * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+ *
  * @category constructors
  * @since 3.10.0
  */
@@ -7548,13 +7883,23 @@ export declare const Class: {
     /**
      * Creates a schema-backed class whose constructor validates input against a
      * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
-     * input (unless `disableChecks` is set in the options).
+     * input.
+     *
+     * **When to use**
+     *
+     * Use to define a schema-backed data class when you want validated
+     * construction, schema-derived decoding/encoding, and class-style methods or
+     * inheritance.
      *
      * **Details**
      *
      * Pass the desired class type as the first type parameter. The second optional
      * type parameter can be used to add nominal brands.
      *
+     * **Gotchas**
+     *
+     * Passing `disableChecks` in the options skips constructor validation.
+     *
      * **Example** (Basic class)
      *
      * ```ts
@@ -7588,6 +7933,10 @@ export declare const Class: {
      * console.log(dog.breed) // "Labrador"
      * ```
      *
+     * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
+     * @see {@link ErrorClass} for defining schema-backed error classes
+     * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+     *
      * @category constructors
      * @since 3.10.0
      */
@@ -7595,13 +7944,23 @@ export declare const Class: {
         /**
          * Creates a schema-backed class whose constructor validates input against a
          * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
-         * input (unless `disableChecks` is set in the options).
+         * input.
+         *
+         * **When to use**
+         *
+         * Use to define a schema-backed data class when you want validated
+         * construction, schema-derived decoding/encoding, and class-style methods or
+         * inheritance.
          *
          * **Details**
          *
          * Pass the desired class type as the first type parameter. The second optional
          * type parameter can be used to add nominal brands.
          *
+         * **Gotchas**
+         *
+         * Passing `disableChecks` in the options skips constructor validation.
+         *
          * **Example** (Basic class)
          *
          * ```ts
@@ -7635,6 +7994,10 @@ export declare const Class: {
          * console.log(dog.breed) // "Labrador"
          * ```
          *
+         * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
+         * @see {@link ErrorClass} for defining schema-backed error classes
+         * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+         *
          * @category constructors
          * @since 3.10.0
          */
@@ -7642,13 +8005,23 @@ export declare const Class: {
         /**
          * Creates a schema-backed class whose constructor validates input against a
          * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
-         * input (unless `disableChecks` is set in the options).
+         * input.
+         *
+         * **When to use**
+         *
+         * Use to define a schema-backed data class when you want validated
+         * construction, schema-derived decoding/encoding, and class-style methods or
+         * inheritance.
          *
          * **Details**
          *
          * Pass the desired class type as the first type parameter. The second optional
          * type parameter can be used to add nominal brands.
          *
+         * **Gotchas**
+         *
+         * Passing `disableChecks` in the options skips constructor validation.
+         *
          * **Example** (Basic class)
          *
          * ```ts
@@ -7682,6 +8055,10 @@ export declare const Class: {
          * console.log(dog.breed) // "Labrador"
          * ```
          *
+         * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
+         * @see {@link ErrorClass} for defining schema-backed error classes
+         * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+         *
          * @category constructors
          * @since 3.10.0
          */
@@ -8116,7 +8493,7 @@ export declare function toRepresentation(schema: Top): SchemaRepresentation.Docu
 /**
  * Options for {@link toJsonSchemaDocument}.
  *
- * @category models
+ * @category JsonSchema
  * @since 4.0.0
  */
 export interface ToJsonSchemaOptions {
@@ -8137,6 +8514,54 @@ export interface ToJsonSchemaOptions {
      * provided them) based on the `expected` annotation of the check.
      */
     readonly generateDescriptions?: boolean | undefined;
+    /**
+     * A predicate that controls which additional annotation keys (beyond the
+     * standard JSON Schema keys) are included in the generated output.
+     *
+     * **When to use**
+     *
+     * Use when you need to include non-standard annotation keys in the generated
+     * JSON Schema, such as Monaco Editor properties (`markdownDescription`,
+     * `defaultSnippets`) or vendor extensions (`x-*`).
+     *
+     * **Details**
+     *
+     * Standard JSON Schema keys (`title`, `description`, `default`, `examples`,
+     * `readOnly`, `writeOnly`, `format`, `contentEncoding`, `contentMediaType`,
+     * `contentSchema`) are always included. This predicate is checked for any
+     * *other* annotation key.
+     *
+     * **Gotchas**
+     *
+     * Prefer whitelisting the custom annotation keys you want to emit instead of
+     * using a broad predicate such as `() => true`, because broad predicates can
+     * include Effect-specific annotations that are preserved for internal schema
+     * generation.
+     *
+     * **Example** (Including custom annotations)
+     *
+     * ```ts
+     * import { Schema } from "effect"
+     *
+     * const schema = Schema.String.annotate({
+     *   description: "A name",
+     *   markdownDescription: "The **name** field"
+     * })
+     *
+     * const doc = Schema.toJsonSchemaDocument(schema, {
+     *   includeAnnotationKey: (key) =>
+     *     key === "markdownDescription" || key.startsWith("x-")
+     * })
+     *
+     * console.log(doc.schema)
+     * // {
+     * //   type: "string",
+     * //   description: "A name",
+     * //   markdownDescription: "The **name** field"
+     * // }
+     * ```
+     */
+    readonly includeAnnotationKey?: ((key: string) => boolean) | undefined;
 }
 /**
  * Returns a JSON Schema document using draft 2020-12.