effect 4.0.0-beta.30 → 4.0.0-beta.32

package/dist/Schema.js

@@ -1,4 +1,86 @@
 /**
+ * Define data shapes, validate unknown input, and transform values between formats.
+ *
+ * ## Mental model
+ *
+ * - **Schema** — a description of a data shape. Every schema carries a decoded
+ *   *Type* (the value you work with) and an *Encoded* representation (the
+ *   serialized form, e.g. JSON).
+ * - **Decoding** — turning unknown external data (API responses, form
+ *   submissions, config files) into typed, validated values.
+ * - **Encoding** — turning typed values back into a serializable format.
+ * - **Codec** — a schema that tracks both Type and Encoded, so it can decode
+ *   *and* encode. Most concrete schemas are Codecs.
+ * - **Check / Filter** — a constraint attached to a schema (e.g. `isMinLength`,
+ *   `isGreaterThan`). Attach them with `.check(...)`.
+ * - **Transformation** — a pair of functions (decode + encode) that convert
+ *   values between two schemas. Created with {@link decodeTo} / {@link encodeTo}.
+ * - **Annotation** — metadata attached to a schema (title, description, custom
+ *   keys). Attach with `.annotate(...)`.
+ *
+ * ## Common tasks
+ *
+ * - Define a struct: {@link Struct}
+ * - Define a union: {@link Union}, {@link TaggedUnion}, {@link Literals}
+ * - Define an array: {@link Array}, {@link NonEmptyArray}
+ * - Define a record: {@link Record}
+ * - Define a tuple: {@link Tuple}, {@link TupleWithRest}
+ * - Validate unknown data synchronously: {@link decodeUnknownSync}
+ * - Validate unknown data (Effect): {@link decodeUnknownEffect}
+ * - Encode a value: {@link encodeUnknownSync}, {@link encodeUnknownEffect}
+ * - Type guard: {@link is}
+ * - Assertion: {@link asserts}
+ * - Add constraints: `.check(...)` with filters like {@link isMinLength},
+ *   {@link isGreaterThan}, {@link isPattern}, {@link isUUID}
+ * - Transform between schemas: {@link decodeTo}, {@link encodeTo}
+ * - Add a default for missing keys: {@link withDecodingDefault}, {@link withDecodingDefaultKey}
+ * - Create branded types: {@link brand}
+ * - Define classes with validation: {@link Class}, {@link TaggedClass}
+ * - Define error classes: {@link ErrorClass}, {@link TaggedErrorClass}
+ * - Generate JSON Schema: {@link toJsonSchemaDocument}
+ * - Generate test data: {@link toArbitrary}
+ * - Derive equivalence: {@link toEquivalence}
+ *
+ * ## Gotchas
+ *
+ * - `Schema.optional` creates `T | undefined` (key can be missing *or*
+ *   `undefined`). Use `Schema.optionalKey` for exact optional properties.
+ * - `decodeTo` is curried: use `from.pipe(Schema.decodeTo(to, ...))`.
+ * - `decodeUnknownSync` throws on failure. Use `decodeUnknownExit` or
+ *   `decodeUnknownOption` for non-throwing alternatives.
+ * - Filters do not change the TypeScript type. Use {@link refine} or
+ *   {@link brand} to narrow the type.
+ * - Recursive schemas require {@link suspend} to avoid infinite loops.
+ *
+ * ## Quickstart
+ *
+ * **Example** (Validate a user object)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const User = Schema.Struct({
+ *   name: Schema.String.check(Schema.isMinLength(1)),
+ *   age: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0)),
+ *   email: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * // Decode unknown input — throws on failure
+ * const user = Schema.decodeUnknownSync(User)({
+ *   name: "Alice",
+ *   age: 30
+ * })
+ *
+ * console.log(user)
+ * // { name: "Alice", age: 30 }
+ * ```
+ *
+ * @see {@link Schema} — type-level view tracking only the decoded Type
+ * @see {@link Codec} — type-level view tracking both Type and Encoded
+ * @see {@link Struct} — define object shapes
+ * @see {@link decodeUnknownSync} — synchronous validation
+ * @see {@link decodeTo} — schema transformations
+ *
  * @since 4.0.0
  */
 import * as Arr from "./Array.js";
@@ -45,9 +127,51 @@ import * as Struct_ from "./Struct.js";
 import * as FastCheck from "./testing/FastCheck.js";
 const TypeId = InternalSchema.TypeId;
 /**
- * An API for creating schemas for parametric types.
+ * Creates a schema for a **parametric** type (a generic container such as
+ * `Array<A>`, `Option<A>`, etc.) by accepting a list of type-parameter schemas
+ * and a decoder factory.
+ *
+ * The outer call `declareConstructor<T, E, Iso>()` fixes the decoded type `T`,
+ * the encoded type `E`, and the optional iso type. The inner call receives:
+ * - `typeParameters` — the concrete schemas for each type variable
+ * - `run` — a factory that, given resolved codecs for each type parameter,
+ *   returns a parsing function `(u, ast, options) => Effect<T, Issue>`
+ * - `annotations` — optional metadata
+ *
+ * @see {@link declare} for creating schemas for non-parametric types.
+ *
+ * **Example** (Schema for a parametric `Box<A>` type)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import * as SchemaParser from "effect/SchemaParser"
+ * import * as Issue from "effect/SchemaIssue"
+ * import * as Option from "effect/Option"
+ *
+ * interface Box<A> {
+ *   readonly value: A
+ * }
  *
- * @see {@link declare} for creating schemas for non parametric types.
+ * const isBox = (u: unknown): u is Box<unknown> =>
+ *   typeof u === "object" && u !== null && "value" in u
+ *
+ * const Box = <A extends Schema.Top>(item: A) =>
+ *   Schema.declareConstructor<Box<A["Type"]>, Box<A["Encoded"]>>()(
+ *     [item],
+ *     ([itemCodec]) =>
+ *       (u, ast, options) => {
+ *         if (!isBox(u)) {
+ *           return Effect.fail(new Issue.InvalidType(ast, Option.some(u)))
+ *         }
+ *         return Effect.map(
+ *           SchemaParser.decodeUnknownEffect(itemCodec)(u.value, options),
+ *           (value) => ({ value })
+ *         )
+ *       }
+ *   )
+ *
+ * const schema = Box(Schema.Number)
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
@@ -58,18 +182,60 @@ export function declareConstructor() {
   };
 }
 /**
- * An API for creating schemas for non parametric types.
+ * Creates a schema for a **non-parametric** opaque type using a type-guard
+ * function. The schema accepts any unknown value and succeeds when `is` returns
+ * `true`, failing with an `InvalidType` issue otherwise.
+ *
+ * Use this when the type has no type parameters. For parametric types such as
+ * `Option<A>` or `Array<A>`, use {@link declareConstructor} instead.
+ *
+ * **Example** (Schema for a custom `UserId` branded type)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * type UserId = string & { readonly _tag: "UserId" }
+ *
+ * const isUserId = (u: unknown): u is UserId =>
+ *   typeof u === "string" && u.startsWith("user_")
+ *
+ * const UserId = Schema.declare<UserId>(isUserId, {
+ *   title: "UserId",
+ *   description: "A user identifier starting with 'user_'"
+ * })
+ * ```
  *
  * @see {@link declareConstructor} for creating schemas for parametric types.
  *
+ * @category Constructors
  * @since 4.0.0
  */
 export function declare(is, annotations) {
   return declareConstructor()([], () => (input, ast) => is(input) ? Effect.succeed(input) : Effect.fail(new Issue.InvalidType(ast, Option_.some(input))), annotations);
 }
 /**
- * Reveals the complete Bottom interface type of a schema, exposing all 14 type
- * parameters.
+ * Widens a schema's type to the fully-parameterized {@link Bottom} interface,
+ * making all 14 type parameters visible to TypeScript.
+ *
+ * Normally, concrete schema interfaces (e.g. `Schema<string>`) hide most type
+ * parameters. `revealBottom` is useful when writing generic utilities that need
+ * to inspect or propagate the complete set of type parameters.
+ *
+ * **Example** (Inspecting all type parameters of a schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.String
+ *
+ * // Widen to Bottom to access all 14 type parameters
+ * const bottom = Schema.revealBottom(schema)
+ *
+ * // `bottom` now exposes Type, Encoded, DecodingServices, EncodingServices,
+ * // ast, ~rebuild.out, ~type.make.in, Iso, ~type.parameters, etc.
+ * type T = typeof bottom["Type"]     // string
+ * type E = typeof bottom["Encoded"]  // string
+ * ```
  *
  * @since 4.0.0
  */
@@ -78,8 +244,24 @@ export function revealBottom(bottom) {
 }
 /**
  * Adds metadata annotations to a schema without changing its runtime behavior.
- * Annotations are used to provide additional context for documentation,
- * JSON schema generation, error formatting, and other tooling.
+ * This is the pipeable (curried) counterpart of the `.annotate` method.
+ *
+ * Annotations provide extra context used by documentation generators, JSON
+ * Schema converters, error formatters, and other tooling. Common keys include
+ * `title`, `description`, `examples`, `message`, and `identifier`.
+ *
+ * **Example** (Adding a title and description)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Age = Schema.Number.pipe(
+ *   Schema.annotate({
+ *     title: "Age",
+ *     description: "A non-negative integer representing age in years"
+ *   })
+ * )
+ * ```
  *
  * @category Annotations
  * @since 4.0.0
@@ -90,9 +272,29 @@ export function annotate(annotations) {
   };
 }
 /**
- * Adds key-specific annotations to a schema field. This is useful for providing
- * custom error messages and documentation for individual fields within
- * structures.
+ * Adds key-level annotations to a schema field. This is the pipeable
+ * (curried) counterpart of the `.annotateKey` method.
+ *
+ * Key annotations apply to a field's position inside a `Struct` or `Tuple`
+ * rather than to the field's value type. They can carry a
+ * `messageMissingKey` to customise the error shown when the field is absent,
+ * as well as standard documentation fields such as `title`, `description`,
+ * and `examples`.
+ *
+ * **Example** (Custom missing-key message for a required field)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Struct({
+ *   username: Schema.String.pipe(
+ *     Schema.annotateKey({
+ *       description: "The username used to log in",
+ *       messageMissingKey: "Username is required"
+ *     })
+ *   )
+ * })
+ * ```
  *
  * @category Annotations
  * @since 4.0.0
@@ -103,6 +305,25 @@ export function annotateKey(annotations) {
   };
 }
 /**
+ * Identity function that widens a value to the full {@link Codec} interface,
+ * prompting TypeScript to infer all four type parameters (`T`, `E`, `RD`, `RE`).
+ *
+ * When a schema is stored in a variable typed as `Schema<T>` or `Top`, the
+ * encoded type and service requirements are erased. Passing the value through
+ * `revealCodec` recovers those parameters without any runtime cost.
+ *
+ * **Example** (Recovering encoded type from a schema variable)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema: Schema.Schema<number> = Schema.NumberFromString
+ *
+ * // Without revealCodec, Encoded is unknown
+ * const codec = Schema.revealCodec(schema)
+ * type Enc = typeof codec["Encoded"] // string
+ * ```
+ *
  * @since 4.0.0
  */
 export function revealCodec(codec) {
@@ -110,12 +331,30 @@ export function revealCodec(codec) {
 }
 const SchemaErrorTypeId = "~effect/Schema/SchemaError";
 /**
- * A `SchemaError` is returned when schema decoding or encoding fails.
+ * Error thrown (or returned as the error channel value) when schema decoding
+ * or encoding fails.
+ *
+ * The `issue` field contains a structured {@link Issue.Issue} tree describing
+ * every validation failure, including the path to the problematic value,
+ * expected types, and actual values received. `message` renders the issue tree
+ * as a human-readable string.
+ *
+ * Use {@link isSchemaError} to narrow an unknown value to `SchemaError`.
+ *
+ * **Example** (Catching a SchemaError)
  *
- * This error extends `Data.TaggedError` and contains detailed information about
- * what went wrong during schema processing. The error includes an `issue` field
- * that provides comprehensive details about the validation failure, including
- * the path to the problematic data, expected types, and actual values.
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * try {
+ *   Schema.decodeUnknownSync(Schema.Number)("not a number")
+ * } catch (err) {
+ *   if (Schema.isSchemaError(err)) {
+ *     console.log(err.message)
+ *     // Expected number, actual "not a number"
+ *   }
+ * }
+ * ```
  *
  * @since 4.0.0
  */
@@ -135,6 +374,22 @@ export class SchemaError {
   }
 }
 /**
+ * Returns `true` if `u` is a {@link SchemaError}.
+ *
+ * **Example** (Type guard in a catch block)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * try {
+ *   Schema.decodeUnknownSync(Schema.Number)("oops")
+ * } catch (err) {
+ *   if (Schema.isSchemaError(err)) {
+ *     console.log(err._tag) // "SchemaError"
+ *   }
+ * }
+ * ```
+ *
  * @since 4.0.0
  */
 export function isSchemaError(u) {
@@ -225,7 +480,7 @@ export function toStandardSchemaV1(self, options) {
     }), {
       scheduler
     });
-    scheduler.flush();
+    fiber.currentDispatcher?.flush();
     const exit = fiber.pollUnsafe();
     if (exit) {
       return makeStandardResult(exit);
@@ -374,6 +629,11 @@ export const is = Parser.is;
  */
 export const asserts = Parser.asserts;
 /**
+ * Decodes an `unknown` input against a schema, returning an `Effect` that
+ * succeeds with the decoded value or fails with a {@link SchemaError}. Use this
+ * when the input type is not statically known. Prefer {@link decodeEffect} when
+ * the input is already typed as the schema's `Encoded` type.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -384,11 +644,22 @@ export function decodeUnknownEffect(schema) {
   };
 }
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning an `Effect` that succeeds with the decoded value or fails with a
+ * {@link SchemaError}. Use this when the input is already typed; for `unknown`
+ * input use {@link decodeUnknownEffect}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeEffect = decodeUnknownEffect;
 /**
+ * Decodes an `unknown` input against a schema synchronously, returning an
+ * `Exit` that is either a `Success` with the decoded value or a `Failure` with
+ * a {@link SchemaError}. Only usable with schemas that have no
+ * `DecodingServices` requirement. Prefer {@link decodeExit} when the input is
+ * already typed as the schema's `Encoded` type.
+ *
  * @category Decoding
  * @since 4.0.0
  */
@@ -399,41 +670,110 @@ export function decodeUnknownExit(schema) {
   };
 }
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema
+ * synchronously, returning an `Exit` that is either a `Success` with the
+ * decoded value or a `Failure` with a {@link SchemaError}. Only usable with
+ * schemas that have no `DecodingServices` requirement. For `unknown` input use
+ * {@link decodeUnknownExit}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeExit = decodeUnknownExit;
 /**
+ * Decodes an `unknown` input against a schema, returning an `Option` that is
+ * `Some` with the decoded value on success or `None` on failure. Prefer this
+ * over {@link decodeUnknownExit} or {@link decodeUnknownEffect} when you only
+ * need to know whether decoding succeeded and don't need error details. For
+ * typed input use {@link decodeOption}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeUnknownOption = Parser.decodeUnknownOption;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning an `Option` that is `Some` with the decoded value on success or
+ * `None` on failure. For `unknown` input use {@link decodeUnknownOption}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeOption = Parser.decodeOption;
 /**
+ * Decodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the decoded value or rejects with a {@link SchemaError}. Useful
+ * for integrating with Promise-based APIs. For typed input use
+ * {@link decodePromise}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeUnknownPromise = Parser.decodeUnknownPromise;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema,
+ * returning a `Promise` that resolves with the decoded value or rejects with a
+ * {@link SchemaError}. For `unknown` input use {@link decodeUnknownPromise}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodePromise = Parser.decodePromise;
 /**
+ * Decodes an `unknown` input against a schema synchronously, throwing a
+ * {@link SchemaError} on failure. Use this when you want to validate data at a
+ * boundary and treat a schema mismatch as an unrecoverable error. For
+ * non-throwing alternatives see {@link decodeUnknownOption},
+ * {@link decodeUnknownExit}, or {@link decodeUnknownEffect}. For typed input
+ * use {@link decodeSync}.
+ *
+ * **Example** (Decoding with a transformation schema)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const NumberFromString = Schema.NumberFromString
+ *
+ * console.log(Schema.decodeUnknownSync(NumberFromString)("42"))
+ * // Output: 42
+ *
+ * Schema.decodeUnknownSync(NumberFromString)("not a number")
+ * // throws SchemaError: NumberFromString
+ * //   └─ Encoded side transformation failure
+ * //      └─ NumberFromString
+ * //         └─ Expected a numeric string, actual "not a number"
+ * ```
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeUnknownSync = Parser.decodeUnknownSync;
 /**
+ * Decodes a typed input (the schema's `Encoded` type) against a schema
+ * synchronously, throwing a {@link SchemaError} on failure. For `unknown` input
+ * use {@link decodeUnknownSync}.
+ *
  * @category Decoding
  * @since 4.0.0
  */
 export const decodeSync = Parser.decodeSync;
 /**
+ * Encodes an `unknown` input against a schema, returning an `Effect` that
+ * succeeds with the encoded value or fails with a {@link SchemaError}. Use this
+ * when the input type is not statically known. Prefer {@link encodeEffect} when
+ * the input is already typed as the schema's `Type`.
+ *
+ * **Example** (Encoding a value to a string)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const NumberFromString = Schema.NumberFromString
+ *
+ * Effect.runPromise(Schema.encodeUnknownEffect(NumberFromString)(42)).then(console.log)
+ * // Output: "42"
+ * ```
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -444,11 +784,22 @@ export function encodeUnknownEffect(schema) {
   };
 }
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning an
+ * `Effect` that succeeds with the encoded value or fails with a
+ * {@link SchemaError}. Use this when the input is already typed; for `unknown`
+ * input use {@link encodeUnknownEffect}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeEffect = encodeUnknownEffect;
 /**
+ * Encodes an `unknown` input against a schema synchronously, returning an
+ * `Exit` that is either a `Success` with the encoded value or a `Failure` with
+ * a {@link SchemaError}. Only usable with schemas that have no
+ * `EncodingServices` requirement. Prefer {@link encodeExit} when the input is
+ * already typed as the schema's `Type`.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -459,36 +810,72 @@ export function encodeUnknownExit(schema) {
   };
 }
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema synchronously,
+ * returning an `Exit` that is either a `Success` with the encoded value or a
+ * `Failure` with a {@link SchemaError}. Only usable with schemas that have no
+ * `EncodingServices` requirement. For `unknown` input use
+ * {@link encodeUnknownExit}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeExit = encodeUnknownExit;
 /**
+ * Encodes an `unknown` input against a schema, returning an `Option` that is
+ * `Some` with the encoded value on success or `None` on failure. Prefer this
+ * over {@link encodeUnknownExit} or {@link encodeUnknownEffect} when you only
+ * need to know whether encoding succeeded and don't need error details. For
+ * typed input use {@link encodeOption}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeUnknownOption = Parser.encodeUnknownOption;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning an
+ * `Option` that is `Some` with the encoded value on success or `None` on
+ * failure. For `unknown` input use {@link encodeUnknownOption}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeOption = Parser.encodeOption;
 /**
+ * Encodes an `unknown` input against a schema, returning a `Promise` that
+ * resolves with the encoded value or rejects with a {@link SchemaError}. Useful
+ * for integrating with Promise-based APIs. For typed input use
+ * {@link encodePromise}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeUnknownPromise = Parser.encodeUnknownPromise;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema, returning a
+ * `Promise` that resolves with the encoded value or rejects with a
+ * {@link SchemaError}. For `unknown` input use {@link encodeUnknownPromise}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodePromise = Parser.encodePromise;
 /**
+ * Encodes an `unknown` input against a schema synchronously, throwing a
+ * {@link SchemaError} on failure. Use this when you want to serialize data at a
+ * boundary and treat a schema mismatch as an unrecoverable error. For
+ * non-throwing alternatives see {@link encodeUnknownOption},
+ * {@link encodeUnknownExit}, or {@link encodeUnknownEffect}. For typed input
+ * use {@link encodeSync}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
 export const encodeUnknownSync = Parser.encodeUnknownSync;
 /**
+ * Encodes a typed input (the schema's `Type`) against a schema synchronously,
+ * throwing a {@link SchemaError} on failure. For `unknown` input use
+ * {@link encodeUnknownSync}.
+ *
  * @category Encoding
  * @since 4.0.0
  */
@@ -543,57 +930,74 @@ export const optionalKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.option
   schema
 }));
 /**
+ * Reverses {@link optionalKey}, returning the inner required schema. Only
+ * applicable to schemas already wrapped with `optionalKey`.
+ *
  * @since 4.0.0
  */
 export const requiredKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
 /**
- * Creates an optional schema field that allows both the specified type and
+ * Marks a struct field as optional, allowing the key to be absent or
  * `undefined`.
  *
- * This is equivalent to `optionalKey(UndefinedOr(schema))`, creating a field
- * that:
- * - Can be omitted from the object entirely
- * - Can be explicitly set to `undefined`
- * - Can contain the specified schema type
+ * explicitly set to `undefined`. Equivalent to `optionalKey(UndefinedOr(S))`.
+ *
+ * Use {@link optionalKey} instead if you want exact optional semantics (absent
+ * only, not `undefined`).
  *
- * **Example** (Creating a struct with optional)
+ * **Example** (Optional field accepting undefined)
  *
  * ```ts
  * import { Schema } from "effect"
  *
  * const schema = Schema.Struct({
  *   name: Schema.String,
- *   age: Schema.optionalKey(Schema.Number)
+ *   age: Schema.optional(Schema.Number)
  * })
  *
- * // Type: { readonly name: string; readonly age?: number | undefined }
- * type Person = typeof schema["Type"]
+ * // { readonly name: string; readonly age?: number | undefined }
+ * type Person = typeof schema.Type
  * ```
  *
  * @since 4.0.0
  */
 export const optional = /*#__PURE__*/Struct_.lambda(self => optionalKey(UndefinedOr(self)));
 /**
+ * Reverses {@link optional}, returning the inner schema (unwrapping `UndefinedOr`).
+ * Only applicable to schemas already wrapped with `optional`.
+ *
  * @since 4.0.0
  */
 export const required = /*#__PURE__*/Struct_.lambda(self => self.schema.members[0]);
 /**
+ * Makes a struct field mutable (removes the `readonly` modifier on the property).
+ * Use {@link readonlyKey} to reverse.
+ *
  * @since 4.0.0
  */
 export const mutableKey = /*#__PURE__*/Struct_.lambda(schema => make(AST.mutableKey(schema.ast), {
   schema
 }));
 /**
+ * Reverses {@link mutableKey}, returning the inner schema as readonly again.
+ * Only applicable to schemas already wrapped with `mutableKey`.
+ *
  * @since 4.0.0
  */
 export const readonlyKey = /*#__PURE__*/Struct_.lambda(self => self.schema);
 /**
+ * Extracts the type-side schema: sets `Encoded` to equal the decoded `Type`,
+ * discarding the encoding transformation path.
+ *
  * @since 4.0.0
  */
 export const toType = /*#__PURE__*/Struct_.lambda(schema => make(AST.toType(schema.ast), {
   schema
 }));
 /**
+ * Extracts the encoded-side schema: sets `Type` to equal the `Encoded`,
+ * discarding the decoding transformation path.
+ *
  * @since 4.0.0
  */
 export const toEncoded = /*#__PURE__*/Struct_.lambda(schema => make(AST.toEncoded(schema.ast), {
@@ -613,6 +1017,16 @@ export function flip(schema) {
   });
 }
 /**
+ * Creates a schema for a single literal value (string, number, bigint, boolean, or null).
+ *
+ * **Example** (String literal)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Literal("hello")
+ * // Type: Schema.Literal<"hello">
+ * ```
+ *
  * @see {@link Literals} for a schema that represents a union of literals.
  * @see {@link tag} for a schema that represents a literal value that can be
  * used as a discriminator field in tagged unions and has a constructor default.
@@ -634,6 +1048,18 @@ function templateLiteralFromParts(parts) {
   return new AST.TemplateLiteral(parts.map(part => isSchema(part) ? part.ast : new AST.Literal(part)));
 }
 /**
+ * Creates a schema that validates strings matching a template literal pattern. Each part can be
+ * a literal string/number/bigint or a schema whose encoded type is a string, number, or bigint.
+ *
+ * **Example** (URL path pattern)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.TemplateLiteral(["/user/", Schema.Number])
+ * // matches strings like "/user/123", "/user/42", etc.
+ * ```
+ *
+ * @see {@link TemplateLiteralParser} for a schema that also parses matched parts into a tuple.
  * @since 4.0.0
  */
 export function TemplateLiteral(parts) {
@@ -642,6 +1068,18 @@ export function TemplateLiteral(parts) {
   });
 }
 /**
+ * Like {@link TemplateLiteral} but decodes the matched string into a readonly tuple of typed values,
+ * one element per schema part.
+ *
+ * **Example** (Parse path parameters)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.TemplateLiteralParser(["/user/", Schema.NumberFromString])
+ * // decodes "/user/42" => readonly ["/user/", 42]
+ * ```
+ *
+ * @see {@link TemplateLiteral} for a validation-only version that keeps the string encoded.
  * @since 4.0.0
  */
 export function TemplateLiteralParser(parts) {
@@ -650,6 +1088,21 @@ export function TemplateLiteralParser(parts) {
   });
 }
 /**
+ * Creates a schema from a TypeScript enum object. Validates that the input is one of the enum's values.
+ *
+ * **Example** (Direction enum)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * enum Direction {
+ *   Up = "Up",
+ *   Down = "Down"
+ * }
+ *
+ * const schema = Schema.Enum(Direction)
+ * // accepts "Up" or "Down"
+ * ```
+ *
  * @since 4.0.0
  */
 export function Enum(enums) {
@@ -658,84 +1111,102 @@ export function Enum(enums) {
   });
 }
 /**
+ * Schema for the `never` type. Always fails validation — no value satisfies it.
+ *
  * @since 4.0.0
  */
 export const Never = /*#__PURE__*/make(AST.never);
 /**
+ * Schema for the `any` type. Accepts any value without validation.
+ *
+ * @see {@link Unknown} for a safer alternative that uses `unknown`.
  * @since 4.0.0
  */
 export const Any = /*#__PURE__*/make(AST.any);
 /**
+ * Schema for the `unknown` type. Accepts any value without validation.
+ *
+ * @see {@link Any} for the `any` variant.
  * @since 4.0.0
  */
 export const Unknown = /*#__PURE__*/make(AST.unknown);
 /**
+ * Schema for the `null` literal. Validates that the input is strictly `null`.
+ *
+ * @see {@link NullOr} for a union with another schema.
  * @since 4.0.0
  */
 export const Null = /*#__PURE__*/make(AST.null);
 /**
+ * Schema for the `undefined` literal. Validates that the input is strictly `undefined`.
+ *
+ * @see {@link UndefinedOr} for a union with another schema.
  * @since 4.0.0
  */
 export const Undefined = /*#__PURE__*/make(AST.undefined);
 /**
- * A schema for all strings.
+ * Schema for `string` values. Validates that the input is `typeof` `"string"`.
  *
  * @since 4.0.0
  */
 export const String = /*#__PURE__*/make(AST.string);
 /**
- * A schema for all numbers, including `NaN`, `Infinity`, and `-Infinity`.
+ * Schema for `number` values, including `NaN`, `Infinity`, and `-Infinity`.
  *
  * **Default Json Serializer**
  *
- * - If the number is finite, it is serialized as a number.
- * - Otherwise, it is serialized as a string ("NaN", "Infinity", or "-Infinity").
+ * - Finite numbers are serialized as numbers.
+ * - Non-finite values are serialized as strings (`"NaN"`, `"Infinity"`, `"-Infinity"`).
  *
+ * @see {@link Finite} for a schema that excludes non-finite values.
  * @since 4.0.0
  */
 export const Number = /*#__PURE__*/make(AST.number);
 /**
- * A schema for all booleans.
+ * Schema for `boolean` values. Validates that the input is `typeof` `"boolean"`.
  *
  * @category Boolean
  * @since 4.0.0
  */
 export const Boolean = /*#__PURE__*/make(AST.boolean);
 /**
- * A schema for all symbols.
+ * Schema for `symbol` values. Validates that the input is `typeof` `"symbol"`.
  *
+ * @see {@link UniqueSymbol} for a schema that matches a specific symbol.
  * @since 4.0.0
  */
 export const Symbol = /*#__PURE__*/make(AST.symbol);
 /**
- * A schema for all bigints.
+ * Schema for `bigint` values. Validates that the input is `typeof` `"bigint"`.
  *
  * @since 4.0.0
  */
 export const BigInt = /*#__PURE__*/make(AST.bigInt);
 /**
- * A schema for the `void` type.
+ * Schema for the `void` type. Accepts `undefined` as the encoded value.
  *
  * @since 4.0.0
  */
 export const Void = /*#__PURE__*/make(AST.void);
 /**
- * A schema for the `object` type.
+ * Schema for the `object` type. Validates that the input is a non-null object or function
+ * (i.e. `typeof value === "object" && value !== null || typeof value === "function"`).
  *
  * @since 4.0.0
  */
 export const ObjectKeyword = /*#__PURE__*/make(AST.objectKeyword);
 /**
- * A schema for unique symbols.
- *
- * **Example**
+ * Creates a schema for a specific symbol. Only that exact symbol satisfies the schema.
  *
+ * **Example** (Specific symbol)
  * ```ts
  * import { Schema } from "effect"
  *
- * const a = Symbol.for("a")
- * const schema = Schema.UniqueSymbol(a)
+ * const mySymbol = Symbol.for("mySymbol")
+ * const schema = Schema.UniqueSymbol(mySymbol)
  * ```
+ *
+ * @see {@link Symbol} for a schema that accepts any symbol.
  * @since 4.0.0
  */
 export function UniqueSymbol(symbol) {
@@ -751,6 +1222,34 @@ function makeStruct(ast, fields) {
   });
 }
 /**
+ * Defines a struct schema from a map of field schemas.
+ *
+ * Each field value is a schema. Use {@link optionalKey} or {@link optional} to
+ * mark fields as optional, and {@link mutableKey} to mark them as mutable.
+ *
+ * The resulting schema's `Type` is a readonly object type with the fields'
+ * decoded types. The `Encoded` form mirrors the field schemas' encoded types.
+ *
+ * **Example** (Basic struct)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Person = Schema.Struct({
+ *   name: Schema.String,
+ *   age: Schema.Number,
+ *   email: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * // { readonly name: string; readonly age: number; readonly email?: string }
+ * type Person = typeof Person.Type
+ *
+ * const alice = Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 })
+ * console.log(alice)
+ * // { name: 'Alice', age: 30 }
+ * ```
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export function Struct(fields) {
@@ -778,6 +1277,26 @@ export function fieldsAssign(fields) {
   return Struct_.lambda(struct => struct.mapFields(Struct_.assign(fields)));
 }
 /**
+ * Renames struct keys in the encoded form without changing the decoded type.
+ *
+ * Takes a partial mapping `{ decodedKey: encodedKey }` and produces a
+ * transformation schema that decodes from the renamed keys and encodes back to
+ * the renamed keys. Keys not present in the mapping are left unchanged.
+ *
+ * **Example** (Rename `name` to `full_name` in the encoded form)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Person = Schema.Struct({ name: Schema.String, age: Schema.Number })
+ * const Encoded = Person.pipe(Schema.encodeKeys({ name: "full_name" }))
+ *
+ * // Decodes { full_name: "Alice", age: 30 } → { name: "Alice", age: 30 }
+ * const alice = Schema.decodeUnknownSync(Encoded)({ full_name: "Alice", age: 30 })
+ * console.log(alice)
+ * // { name: 'Alice', age: 30 }
+ * ```
+ *
  * @category Struct transformations
  * @since 4.0.0
  */
@@ -801,6 +1320,31 @@ export function encodeKeys(mapping) {
   };
 }
 /**
+ * Adds derived fields to a struct schema during decoding.
+ *
+ * Each new field is derived from the decoded struct value via a function that
+ * returns `Option`. On encoding the derived fields are stripped. This allows
+ * computed or enriched fields to live in the decoded type without appearing in
+ * the encoded form.
+ *
+ * **Example** (Add a computed `fullName` field)
+ *
+ * ```ts
+ * import { Option, Schema } from "effect"
+ *
+ * const Person = Schema.Struct({ first: Schema.String, last: Schema.String })
+ * const Extended = Person.pipe(
+ *   Schema.extendTo(
+ *     { fullName: Schema.String },
+ *     { fullName: (p) => Option.some(`${p.first} ${p.last}`) }
+ *   )
+ * )
+ *
+ * const alice = Schema.decodeUnknownSync(Extended)({ first: "Alice", last: "Smith" })
+ * console.log(alice.fullName)
+ * // Alice Smith
+ * ```
+ *
  * @since 4.0.0
  * @experimental
  */
@@ -840,6 +1384,24 @@ derive) {
   };
 }
 /**
+ * Defines a record (dictionary) schema with typed keys and values.
+ *
+ * **Example** (String-keyed record of numbers)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Record(Schema.String, Schema.Number)
+ *
+ * // { readonly [x: string]: number }
+ * type R = typeof schema.Type
+ *
+ * const result = Schema.decodeUnknownSync(schema)({ a: 1, b: 2 })
+ * console.log(result)
+ * // { a: 1, b: 2 }
+ * ```
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export function Record(key, value, options) {
@@ -850,6 +1412,24 @@ export function Record(key, value, options) {
   });
 }
 /**
+ * Extends a struct schema with one or more record (index-signature) schemas,
+ * producing a schema whose decoded type intersects the struct and all records.
+ *
+ * **Example** (Struct with string-indexed extra keys)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.StructWithRest(
+ *   Schema.Struct({ id: Schema.Number }),
+ *   [Schema.Record(Schema.String, Schema.String)]
+ * )
+ *
+ * // { readonly id: number } & { readonly [x: string]: string }
+ * type T = typeof schema.Type
+ * ```
+ *
+ * @category Constructors
  * @since 4.0.0
  */
 export function StructWithRest(schema, records) {
@@ -868,6 +1448,20 @@ function makeTuple(ast, elements) {
   });
 }
 /**
+ * Defines a fixed-length tuple schema from an array of element schemas.
+ *
+ * **Example** (Pair of string and number)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Tuple([Schema.String, Schema.Number])
+ *
+ * const pair = Schema.decodeUnknownSync(schema)(["hello", 42])
+ * console.log(pair)
+ * // [ 'hello', 42 ]
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -875,6 +1469,26 @@ export function Tuple(elements) {
   return makeTuple(AST.tuple(elements), elements);
 }
 /**
+ * Extends a fixed-length tuple schema with rest elements, creating a variadic
+ * tuple that starts with the fixed elements and ends with zero or more rest
+ * elements.
+ *
+ * **Example** (Tuple with rest)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * // [string, number, ...boolean[]]
+ * const schema = Schema.TupleWithRest(
+ *   Schema.Tuple([Schema.String, Schema.Number]),
+ *   [Schema.Boolean]
+ * )
+ *
+ * const result = Schema.decodeUnknownSync(schema)(["hello", 1, true, false])
+ * console.log(result)
+ * // [ 'hello', 1, true, false ]
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -885,6 +1499,20 @@ export function TupleWithRest(schema, rest) {
   });
 }
 /**
+ * Defines a `ReadonlyArray` schema for a given element schema.
+ *
+ * **Example** (Array of strings)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Array(Schema.String)
+ *
+ * const result = Schema.decodeUnknownSync(schema)(["a", "b", "c"])
+ * console.log(result)
+ * // [ 'a', 'b', 'c' ]
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -892,6 +1520,20 @@ export const Array = /*#__PURE__*/Struct_.lambda(schema => make(new AST.Arrays(f
   schema
 }));
 /**
+ * Defines a non-empty `ReadonlyArray` schema — at least one element required.
+ * Type is `readonly [T, ...T[]]`.
+ *
+ * **Example** (Non-empty array of numbers)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.NonEmptyArray(Schema.Number)
+ *
+ * Schema.decodeUnknownSync(schema)([1, 2, 3])  // ok
+ * Schema.decodeUnknownSync(schema)([])          // throws
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -911,7 +1553,18 @@ export function UniqueArray(item) {
   return Array(item).check(isUnique());
 }
 /**
- * Makes arrays or tuples mutable.
+ * Makes an array or tuple schema mutable, removing the `readonly` modifier.
+ *
+ * **Example** (Mutable array)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.mutable(Schema.Array(Schema.Number))
+ *
+ * // number[]   (mutable)
+ * type T = typeof schema.Type
+ * ```
  *
  * @since 4.0.0
  */
@@ -930,12 +1583,23 @@ function makeUnion(ast, members) {
   });
 }
 /**
- * Creates a schema that represents a union of multiple schemas. Members are checked in order, and the first match is returned.
+ * Creates a union schema from an array of member schemas. Members are tested in
+ * order; the first match is returned.
+ *
+ * Optionally, specify `mode`:
+ * - `"anyOf"` (default) — matches if any member matches.
+ * - `"oneOf"` — matches if exactly one member matches.
+ *
+ * **Example** (String or number union)
  *
- * Optionally, you can specify the `mode` to be `"anyOf"` or `"oneOf"`.
+ * ```ts
+ * import { Schema } from "effect"
  *
- * - `"anyOf"` - The union matches if any member matches.
- * - `"oneOf"` - The union matches if exactly one member matches.
+ * const schema = Schema.Union([Schema.String, Schema.Number])
+ *
+ * Schema.decodeUnknownSync(schema)("hello") // "hello"
+ * Schema.decodeUnknownSync(schema)(42)       // 42
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
@@ -944,6 +1608,16 @@ export function Union(members, options) {
   return makeUnion(AST.union(members, options?.mode ?? "anyOf", undefined), members);
 }
 /**
+ * Creates a union schema from an array of literal values.
+ *
+ * **Example** (Status codes)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.Literals(["active", "inactive", "pending"])
+ * // accepts "active", "inactive", or "pending"
+ * ```
+ *
  * @see {@link Literal} for a schema that represents a single literal.
  * @category Constructors
  * @since 4.0.0
@@ -965,16 +1639,21 @@ export function Literals(literals) {
   });
 }
 /**
+ * Creates a union schema of `S | null`.
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export const NullOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null]));
 /**
+ * Creates a union schema of `S | undefined`.
+ *
  * @category Constructors
  * @since 4.0.0
  */
 export const UndefinedOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Undefined]));
 /**
+ * Creates a union schema of `S | null | undefined`.
  * @category Constructors
  * @since 4.0.0
  */
@@ -984,6 +1663,21 @@ export const NullishOr = /*#__PURE__*/Struct_.lambda(self => Union([self, Null,
  * essential for creating recursive schemas where a schema references itself,
  * preventing infinite recursion during schema definition.
  *
+ * **Example** (Recursive tree schema)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * interface Tree {
+ *   readonly value: number
+ *   readonly children: ReadonlyArray<Tree>
+ * }
+ *
+ * const Tree = Schema.Struct({
+ *   value: Schema.Number,
+ *   children: Schema.Array(Schema.suspend((): Schema.Codec<Tree> => Tree))
+ * })
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -991,6 +1685,18 @@ export function suspend(f) {
   return make(new AST.Suspend(() => f().ast));
 }
 /**
+ * Pipeable function that attaches one or more filter checks to a schema without
+ * changing the TypeScript type.
+ *
+ * **Example** (Adding checks to a schema)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const AgeSchema = Schema.Number.pipe(
+ *   Schema.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(120))
+ * )
+ * ```
+ *
  * @category Filtering
  * @since 4.0.0
  */
@@ -998,6 +1704,9 @@ export function check(...checks) {
   return self => self.check(...checks);
 }
 /**
+ * Narrows the TypeScript type of a schema's output via a type guard predicate,
+ * attaching the guard as a runtime filter check.
+ *
  * @category Filtering
  * @since 4.0.0
  */
@@ -1007,7 +1716,8 @@ export function refine(refinement, annotations) {
   });
 }
 /**
- * Adds a brand to a schema.
+ * Adds a nominal brand to a schema, intersecting the output type with
+ * `Brand.Brand<B>` to prevent accidental mixing of structurally identical types.
  *
  * @category Branding
  * @since 4.0.0
@@ -1019,7 +1729,10 @@ export function brand(identifier) {
   });
 }
 /**
- * @category Constructors
+ * Creates a branded schema from a {@link Brand.Constructor}, applying the
+ * constructor's checks and brand tag to the underlying schema.
+ *
+ * @category Branding
  * @since 4.0.0
  */
 export function fromBrand(identifier, ctor) {
@@ -1028,6 +1741,25 @@ export function fromBrand(identifier, ctor) {
   };
 }
 /**
+ * Intercepts the decoding pipeline of a schema.
+ *
+ * The provided function receives the current decoding `Effect` and `ParseOptions`,
+ * and returns a new `Effect` — potentially adding service requirements (`RD`),
+ * recovering from errors, or augmenting the result.
+ *
+ * **Example** (Logging decode failures)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const Logged = Schema.String.pipe(
+ *   Schema.middlewareDecoding((effect) =>
+ *     Effect.tapError(effect, (issue) => Effect.log("decode failed", issue))
+ *   )
+ * )
+ * ```
+ *
+ * @see {@link catchDecoding} for a simpler error-recovery variant
  * @since 4.0.0
  */
 export function middlewareDecoding(decode) {
@@ -1036,6 +1768,25 @@ export function middlewareDecoding(decode) {
   });
 }
 /**
+ * Intercepts the encoding pipeline of a schema.
+ *
+ * The provided function receives the current encoding `Effect` and `ParseOptions`,
+ * and returns a new `Effect` — potentially adding service requirements (`RE`),
+ * recovering from errors, or augmenting the result.
+ *
+ * **Example** (Logging encode failures)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * const Logged = Schema.String.pipe(
+ *   Schema.middlewareEncoding((effect) =>
+ *     Effect.tapError(effect, (issue) => Effect.log("encode failed", issue))
+ *   )
+ * )
+ * ```
+ *
+ * @see {@link catchEncoding} for a simpler error-recovery variant
  * @since 4.0.0
  */
 export function middlewareEncoding(encode) {
@@ -1044,24 +1795,50 @@ export function middlewareEncoding(encode) {
   });
 }
 /**
+ * Recovers from a decoding error by providing a fallback value.
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either
+ * succeeds with a fallback value or re-fails with a (possibly different) issue.
+ *
+ * **Example** (Returning a default on decode failure)
+ *
+ * ```ts
+ * import { Effect, Option, Schema } from "effect"
+ *
+ * const schema = Schema.Number.pipe(
+ *   Schema.catchDecoding((_issue) => Effect.succeed(Option.some(0)))
+ * )
+ * ```
+ *
+ * @see {@link catchDecodingWithContext} to add service requirements to the handler
  * @since 4.0.0
  */
 export function catchDecoding(f) {
   return catchDecodingWithContext(f);
 }
 /**
+ * Like {@link catchDecoding}, but the handler may require Effect services (`R`).
+ *
  * @since 4.0.0
  */
 export function catchDecodingWithContext(f) {
   return self => self.pipe(middlewareDecoding(Effect.catchEager(f)));
 }
 /**
+ * Recovers from an encoding error by providing a fallback value.
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either
+ * succeeds with a fallback value or re-fails with a (possibly different) issue.
+ *
+ * @see {@link catchEncodingWithContext} to add service requirements to the handler
  * @since 4.0.0
  */
 export function catchEncoding(f) {
   return catchEncodingWithContext(f);
 }
 /**
+ * Like {@link catchEncoding}, but the handler may require Effect services (`R`).
+ *
  * @since 4.0.0
  */
 export function catchEncodingWithContext(f) {
@@ -1123,6 +1900,25 @@ export function encodeTo(to, transformation) {
   };
 }
 /**
+ * Applies a transformation to a schema's encoded type, creating a new schema where encoding/decoding
+ * operate on `S["Encoded"]` rather than `S["Type"]`.
+ *
+ * The `decode` getter maps `S["Encoded"]` → `S["Encoded"]` (applied during decoding),
+ * and the `encode` getter maps `S["Encoded"]` → `S["Encoded"]` (applied during encoding).
+ *
+ * **Example** (Upper-casing encoded strings)
+ *
+ * ```ts
+ * import { Schema, SchemaGetter } from "effect"
+ *
+ * const UpperFromLower = Schema.String.pipe(
+ *   Schema.encode({
+ *     decode: SchemaGetter.transform((s: string) => s.toLowerCase()),
+ *     encode: SchemaGetter.transform((s: string) => s.toUpperCase())
+ *   })
+ * )
+ * ```
+ *
  * @since 4.0.0
  */
 export function encode(transformation) {
@@ -1131,6 +1927,32 @@ export function encode(transformation) {
   };
 }
 /**
+ * Attaches a constructor default value to a schema field.
+ *
+ * The `defaultValue` function receives `Option.some(undefined)` when the field is
+ * explicitly set to `undefined`, or `Option.none()` when the field is absent.
+ * Return `Option.some(value)` to supply a default, or `Option.none()` to leave the
+ * field required. An `Effect` may be returned for async or service-dependent defaults.
+ *
+ * Constructor defaults are applied only during `makeUnsafe` / `make`, not during
+ * decoding or encoding.
+ *
+ * **Example** (Optional field with a static default)
+ *
+ * ```ts
+ * import { Option, Schema } from "effect"
+ *
+ * const MySchema = Schema.Struct({
+ *   name: Schema.String.pipe(
+ *     Schema.optionalKey,
+ *     Schema.withConstructorDefault(() => Option.some("anonymous"))
+ *   )
+ * })
+ *
+ * const value = MySchema.makeUnsafe({})
+ * // value: { name: "anonymous" }
+ * ```
+ *
  * @since 4.0.0
  */
 export function withConstructorDefault(defaultValue) {
@@ -1147,6 +1969,27 @@ export function withConstructorDefault(defaultValue) {
  *   - `passthrough`: (default) Pass the default value through to the output.
  *   - `omit`: Omit the value from the output.
  *
+ * Provides a default value for a missing key during decoding.
+ *
+ * When the key is absent from the input, `defaultValue()` is called to supply a value.
+ * During encoding, the behavior is controlled by `options.encodingStrategy`:
+ * - `"passthrough"` (default): include the value in the output
+ * - `"omit"`: omit the key from the output
+ *
+ * **Example** (Default for a missing struct key)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const MySchema = Schema.Struct({
+ *   name: Schema.String.pipe(Schema.withDecodingDefaultKey(() => "anonymous"))
+ * })
+ *
+ * const result = Schema.decodeUnknownSync(MySchema)({})
+ * // result: { name: "anonymous" }
+ * ```
+ *
+ * @see {@link withDecodingDefault} for the `optional` (value-level) variant
  * @since 4.0.0
  */
 export function withDecodingDefaultKey(defaultValue, options) {
@@ -1165,6 +2008,30 @@ export function withDecodingDefaultKey(defaultValue, options) {
  *   - `passthrough`: (default) Pass the default value through to the output.
  *   - `omit`: Omit the value from the output.
  *
+ * Provides a default value for an `optional` field during decoding.
+ *
+ * Similar to {@link withDecodingDefaultKey} but works on `optional` (value-level optional)
+ * rather than `optionalKey` (key-level optional).
+ *
+ * When the value is `undefined` or absent, `defaultValue()` is called to supply a value.
+ * During encoding, the behavior is controlled by `options.encodingStrategy`:
+ * - `"passthrough"` (default): include the value in the output
+ * - `"omit"`: omit the value from the output
+ *
+ * **Example** (Default for an optional field value)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const MySchema = Schema.Struct({
+ *   name: Schema.String.pipe(Schema.optional, Schema.withDecodingDefault(() => "anonymous"))
+ * })
+ *
+ * const result = Schema.decodeUnknownSync(MySchema)({ name: undefined })
+ * // result: { name: "anonymous" }
+ * ```
+ *
+ * @see {@link withDecodingDefaultKey} for the key-level variant
  * @since 4.0.0
  */
 export function withDecodingDefault(defaultValue, options) {
@@ -1177,23 +2044,50 @@ export function withDecodingDefault(defaultValue, options) {
   };
 }
 /**
- * Creates a schema for a literal value and automatically provides itself as a
- * default.
+ * Combines a {@link Literal} schema with {@link withConstructorDefault}, making it ideal
+ * for discriminator fields in tagged unions. When constructing via `makeUnsafe`, the
+ * `_tag` field can be omitted and will be filled automatically.
+ *
+ * **Example** (Discriminated union tag)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const A = Schema.Struct({ _tag: Schema.tag("A"), value: Schema.Number })
  *
- * The `tag` function combines a literal schema with a constructor default,
- * making it perfect for discriminated unions and tagged data structures. The
- * tag value is automatically provided when the field is missing during
- * construction.
+ * // _tag is optional in makeUnsafe, auto-filled to "A"
+ * const a = A.makeUnsafe({ value: 42 })
+ * // a: { _tag: "A", value: 42 }
+ * ```
  *
+ * @see {@link tagDefaultOmit} to also omit the tag during encoding
+ * @see {@link TaggedStruct} for a shorthand that adds `_tag` automatically
  * @since 4.0.0
  */
 export function tag(literal) {
   return Literal(literal).pipe(withConstructorDefault(() => Option_.some(literal)));
 }
 /**
- * Similar to `tag`, but provides itself as a default when decoding and omits
- * the value from the output when encoding.
+ * Like {@link tag}, but additionally omits the tag field from the encoded output.
+ * Useful when the encoded form (e.g. JSON) does not include the discriminator key,
+ * but the decoded type and constructor still need it.
+ *
+ * **Example** (Tag omitted during encoding)
  *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const A = Schema.Struct({
+ *   _tag: Schema.tagDefaultOmit("A"),
+ *   value: Schema.Number
+ * })
+ *
+ * // Encode strips the _tag field
+ * const encoded = Schema.encodeUnknownSync(A)({ _tag: "A", value: 1 })
+ * // encoded: { value: 1 }
+ * ```
+ *
+ * @see {@link tag} for the variant that keeps the tag during encoding
  * @since 4.0.0
  */
 export function tagDefaultOmit(literal) {
@@ -1250,6 +2144,26 @@ export function TaggedStruct(value, fields) {
   });
 }
 /**
+ * Augments an existing {@link Union} of tagged structs with utility methods keyed by the discriminant field.
+ *
+ * **Example** (Adding tagged-union utilities to an existing union)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const A = Schema.TaggedStruct("A", { value: Schema.Number })
+ * const B = Schema.TaggedStruct("B", { name: Schema.String })
+ *
+ * const MyUnion = Schema.Union([A, B]).pipe(Schema.toTaggedUnion("_tag"))
+ *
+ * // Pattern-match on the union
+ * const result = MyUnion.match({ _tag: "A", value: 1 }, {
+ *   A: (a) => `number: ${a.value}`,
+ *   B: (b) => `name: ${b.name}`
+ * })
+ * ```
+ *
+ * @see {@link TaggedUnion} for a shorthand that builds the union from scratch
  * @since 4.0.0
  * @experimental
  */
@@ -1295,6 +2209,28 @@ export function toTaggedUnion(tag) {
   };
 }
 /**
+ * Builds a discriminated union from a record of field sets, one per variant.
+ * Each key becomes the `_tag` literal and the value is passed to {@link TaggedStruct}.
+ * The result includes `cases`, `guards`, `isAnyOf`, and `match` utilities.
+ *
+ * **Example** (Discriminated union with pattern matching)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const Shape = Schema.TaggedUnion({
+ *   Circle: { radius: Schema.Number },
+ *   Rectangle: { width: Schema.Number, height: Schema.Number }
+ * })
+ *
+ * // Pattern-match on a decoded value
+ * const area = Shape.match({ _tag: "Circle", radius: 5 }, {
+ *   Circle: (c) => Math.PI * c.radius ** 2,
+ *   Rectangle: (r) => r.width * r.height
+ * })
+ * ```
+ *
+ * @see {@link toTaggedUnion} to augment an existing union instead
  * @category Constructors
  * @since 4.0.0
  */
@@ -1318,6 +2254,23 @@ export function TaggedUnion(casesByTag) {
   });
 }
 /**
+ * Wraps a schema so that its decoded `Type` becomes a nominally distinct type `Self`.
+ * Useful for creating opaque types that are structurally identical to a base schema
+ * but type-incompatible with it.
+ *
+ * **Example** (Opaque user ID)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * type UserId = string & { readonly _tag: "UserId" }
+ * const UserId = Schema.Opaque<UserId>()(Schema.String)
+ *
+ * // Decoded value is UserId, not plain string
+ * const id = Schema.decodeUnknownSync(UserId)("abc")
+ * // id: UserId
+ * ```
+ *
  * @since 4.0.0
  */
 export function Opaque() {
@@ -1329,7 +2282,19 @@ export function Opaque() {
   };
 }
 /**
- * Creates a schema that validates an instance of a specific class constructor.
+ * Creates a schema that validates values using `instanceof`.
+ * Decoding and encoding pass the value through unchanged.
+ *
+ * **Example** (Schema for a built-in class)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const DateSchema = Schema.instanceOf(Date)
+ *
+ * const decoded = Schema.decodeUnknownSync(DateSchema)(new Date("2024-01-01"))
+ * // decoded: Date
+ * ```
  *
  * @category Constructors
  * @since 4.0.0
@@ -1338,6 +2303,9 @@ export function instanceOf(constructor, annotations) {
   return declare(u => u instanceof constructor, annotations);
 }
 /**
+ * Constructs an `AST.Link` that describes how a value of type `T` encodes to and decodes from a `To` schema.
+ * Used when building low-level AST transformations that bridge two schema types.
+ *
  * @since 4.0.0
  * @experimental
  */
@@ -1350,11 +2318,30 @@ export function link() {
 // Checks
 // -----------------------------------------------------------------------------
 /**
+ * Creates a custom filter check from a predicate function. The predicate
+ * receives the input value, the schema's AST, and parse options, and returns
+ * `true`/`undefined` on success or a failure description on error.
+ *
+ * **Example** (Custom filter check)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * // Check that a number is even
+ * const isEven = Schema.makeFilter(
+ *   (n: number) => n % 2 === 0 || "expected an even number"
+ * )
+ *
+ * const EvenNumber = Schema.Number.check(isEven)
+ * ```
+ *
  * @category Checks Constructors
  * @since 4.0.0
  */
 export const makeFilter = AST.makeFilter;
 /**
+ * Groups multiple checks into a single {@link AST.FilterGroup}, applying
+ * optional shared annotations to the group as a whole.
+ *
  * @category Checks Constructors
  * @since 4.0.0
  */
@@ -1842,6 +2829,9 @@ export function isFinite(annotations) {
   });
 }
 /**
+ * Generic factory for creating a "greater than" (`>`) check for any ordered
+ * type by supplying an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1857,6 +2847,9 @@ export function makeIsGreaterThan(options) {
   };
 }
 /**
+ * Generic factory for creating a ">=" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1872,6 +2865,9 @@ export function makeIsGreaterThanOrEqualTo(options) {
   };
 }
 /**
+ * Generic factory for creating a "<" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1887,6 +2883,9 @@ export function makeIsLessThan(options) {
   };
 }
 /**
+ * Generic factory for creating a "<=" check for any ordered type by supplying
+ * an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1902,6 +2901,9 @@ export function makeIsLessThanOrEqualTo(options) {
   };
 }
 /**
+ * Generic factory for creating an inclusive/exclusive range check for any
+ * ordered type by supplying an {@link Order.Order} instance.
+ *
  * @category Order checks
  * @since 4.0.0
  */
@@ -1922,6 +2924,9 @@ export function makeIsBetween(deriveOptions) {
   };
 }
 /**
+ * Generic factory for creating a divisibility check for any numeric type by
+ * supplying a remainder function and a zero value.
+ *
  * @category Numeric checks
  * @since 4.0.0
  */
@@ -2590,6 +3595,14 @@ export const isBetweenBigDecimal = /*#__PURE__*/makeIsBetween({
  * constraint to ensure generated strings or arrays have at least the required
  * length.
  *
+ * **Example** (Minimum length check)
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const NonEmptyStringSchema = Schema.String.check(Schema.isMinLength(1))
+ * const NonEmptyArraySchema = Schema.Array(Schema.Number).check(Schema.isMinLength(1))
+ * ```
+ *
  * @category Length checks
  * @since 4.0.0
  */
@@ -2982,6 +3995,7 @@ export function isPropertyNames(keySchema, annotations) {
  * constraint using the provided equivalence function to ensure generated arrays
  * contain only unique items.
  *
+ * @category Array checks
  * @since 4.0.0
  */
 export function isUnique(annotations) {
@@ -3016,6 +4030,8 @@ export const NonEmptyString = /*#__PURE__*/String.check(/*#__PURE__*/isNonEmpty(
  */
 export const Char = /*#__PURE__*/String.check(/*#__PURE__*/isLengthBetween(1, 1));
 /**
+ * Creates a schema for `Option<A>`. See {@link Option} for details.
+ *
  * @category Option
  * @since 4.0.0
  */
@@ -3159,6 +4175,35 @@ export function OptionFromOptional(schema) {
   return optional(schema).pipe(decodeTo(Option(toType(schema)), Transformation.optionFromOptional()));
 }
 /**
+ * Decodes an optional or `null` or `undefined` value `A` to a required `Option<A>`
+ * value.
+ *
+ * Decoding:
+ * - a missing key is decoded as `None`
+ * - a present key with an `undefined` value is decoded as `None`
+ * - a present key with a `null` value is decoded as `None`
+ * - all other values are decoded as `Some`
+ *
+ * Encoding (controlled by `options.onNoneEncoding`):
+ * - `"omit"` (default): `None` is encoded as a missing key
+ * - `null`: `None` is encoded as `null`
+ * - `undefined`: `None` is encoded as `undefined`
+ * - `Some` is always encoded as the value
+ *
+ * @category Option
+ * @since 4.0.0
+ */
+export function OptionFromOptionalNullOr(schema, options) {
+  const onNoneEncoding = options === undefined ? "omit" : options.onNoneEncoding;
+  const noneValue = onNoneEncoding === null ? null : undefined;
+  return optional(NullOr(schema)).pipe(decodeTo(Option(toType(schema)), Transformation.transformOptional({
+    decode: oe => oe.pipe(Option_.filter(Predicate.isNotNullish), Option_.some),
+    encode: onNoneEncoding === "omit" ? Option_.flatten : ot => Option_.some(Option_.getOrElse(Option_.flatten(ot), () => noneValue))
+  })));
+}
+/**
+ * Creates a schema for `Result<A, E>`. See {@link Result} for details.
+ *
  * @category Result
  * @since 4.0.0
  */
@@ -3287,6 +4332,9 @@ export function Redacted(value, options) {
   });
 }
 /**
+ * Middleware that wraps decoded errors in `Redacted`, preventing sensitive
+ * schema details from leaking in error messages.
+ *
  * @category Redacted
  * @since 4.0.0
  */
@@ -3294,6 +4342,10 @@ export function redact(schema) {
   return schema.pipe(middlewareDecoding(Effect.mapErrorEager(Issue.redact)));
 }
 /**
+ * Decodes a value and wraps it in `Redacted<A>`. Unlike {@link Redacted} which
+ * expects the input to already be a `Redacted` instance, this schema decodes
+ * the raw value and wraps it.
+ *
  * @category Redacted
  * @since 4.0.0
  */
@@ -3306,6 +4358,8 @@ export function RedactedFromValue(value, options) {
   }));
 }
 /**
+ * Creates a schema for `Cause.Reason<E>`. See {@link CauseReason} for details.
+ *
  * @category CauseReason
  * @since 4.0.0
  */
@@ -3405,6 +4459,8 @@ function causeReasonToFormatter(error, defect) {
   };
 }
 /**
+ * Creates a schema for `Cause<E>`. See {@link Cause} for details.
+ *
  * @category Cause
  * @since 4.0.0
  */
@@ -3538,6 +4594,8 @@ export const DefectWithStack = /*#__PURE__*/Union([/*#__PURE__*/ErrorJsonEncoded
   toArbitrary: () => fc => fc.json()
 }), defectTransformation))]);
 /**
+ * Creates a schema for `Exit<A, E>`. See {@link Exit} for details.
+ *
  * @category Exit
  * @since 4.0.0
  */
@@ -3882,6 +4940,11 @@ export function Chunk(value) {
   });
 }
 /**
+ * Schema for JavaScript `RegExp` objects.
+ *
+ * The default JSON serializer encodes a `RegExp` as `{ source, flags }`.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const RegExp = /*#__PURE__*/instanceOf(globalThis.RegExp, {
@@ -3959,8 +5022,19 @@ export const URLFromString = /*#__PURE__*/String.annotate({
  * A schema for JavaScript `Date` objects.
  *
  * This schema accepts any `Date` instance, including invalid dates (e.g., `new
- * Date("invalid")`). For validating only valid dates, use `ValidDate` instead.
+ * Date("invalid")`). For validating only valid dates, use {@link DateValid}
+ * instead. The default JSON serializer encodes `Date` as an ISO 8601 string.
+ *
+ * **Example** (Date schema)
  *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * Schema.decodeUnknownSync(Schema.Date)(new Date("2024-01-01"))
+ * // => Date { 2024-01-01T00:00:00.000Z }
+ * ```
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const Date = /*#__PURE__*/instanceOf(globalThis.Date, {
@@ -3992,9 +5066,20 @@ export const DateValid = /*#__PURE__*/Date.check(/*#__PURE__*/isDateValid());
 /**
  * A schema for `Duration` values.
  *
- * **Default JSON serializer**
+ * The default JSON serializer encodes `Duration` as a tagged object with the
+ * duration type and value.
+ *
+ * **Example** (Duration schema)
  *
- * - encodes `Duration` as a `string`
+ * ```ts
+ * import { Schema } from "effect"
+ * import { Duration } from "effect"
+ *
+ * Schema.decodeUnknownSync(Schema.Duration)(Duration.seconds(5))
+ * // => Duration(5s)
+ * ```
+ *
+ * @category Duration
  *
  * @since 4.0.0
  */
@@ -4212,6 +5297,12 @@ export function fromJsonString(schema) {
   }).pipe(decodeTo(schema, Transformation.fromJsonString));
 }
 /**
+ * Schema for JavaScript `File` objects.
+ *
+ * The default JSON serializer encodes a `File` as `{ data, type, name, lastModified }`
+ * where `data` is base64-encoded.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const File = /*#__PURE__*/instanceOf(globalThis.File, {
@@ -4258,6 +5349,12 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
   }))
 });
 /**
+ * Schema for JavaScript `FormData` objects.
+ *
+ * The default JSON serializer encodes a `FormData` as an array of `[key, entry]`
+ * pairs where each entry is tagged as `"String"` or `"File"`.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
@@ -4387,6 +5484,11 @@ export function fromFormData(schema) {
   return FormData.pipe(decodeTo(schema, Transformation.fromFormData));
 }
 /**
+ * Schema for JavaScript `URLSearchParams` objects.
+ *
+ * The default JSON serializer encodes a `URLSearchParams` as a query string.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const URLSearchParams = /*#__PURE__*/instanceOf(globalThis.URLSearchParams, {
@@ -4544,6 +5646,9 @@ export const Trim = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a trimmed string"
 }).pipe(/*#__PURE__*/decodeTo(Trimmed, /*#__PURE__*/Transformation.trim()));
 /**
+ * A union schema for JavaScript property keys: `number | symbol | string`.
+ *
+ * @category Schemas
  * @since 4.0.0
  */
 export const PropertyKey = /*#__PURE__*/Union([Finite, Symbol, String]);
@@ -4948,6 +6053,46 @@ function isStruct(schema) {
   return isSchema(schema);
 }
 /**
+ * Creates a schema-backed class whose constructor validates input against a
+ * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
+ * input (unless `disableValidation` is set in the options).
+ *
+ * Pass the desired class type as the first type parameter. The second optional
+ * type parameter can be used to add nominal brands.
+ *
+ * **Example** (Basic class)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * class Person extends Schema.Class<Person>("Person")({
+ *   name: Schema.String,
+ *   age: Schema.Number
+ * }) {}
+ *
+ * const alice = new Person({ name: "Alice", age: 30 })
+ * console.log(alice.name) // "Alice"
+ * console.log(`${alice}`) // "Person({ name: Alice, age: 30 })"
+ * ```
+ *
+ * **Example** (Extending a class)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * class Animal extends Schema.Class<Animal>("Animal")({
+ *   name: Schema.String
+ * }) {}
+ *
+ * class Dog extends Animal.extend<Dog>("Dog")({
+ *   breed: Schema.String
+ * }) {}
+ *
+ * const dog = new Dog({ name: "Rex", breed: "Labrador" })
+ * console.log(dog.name) // "Rex"
+ * console.log(dog.breed) // "Labrador"
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -4956,6 +6101,27 @@ export const Class = identifier => (schema, annotations) => {
   return makeClass(Data.Class, identifier, struct, annotations);
 };
 /**
+ * Like {@link Class} but automatically adds a `_tag` literal field set to the
+ * given `tag` value. This makes instances compatible with tagged union
+ * discrimination patterns.
+ *
+ * The optional `identifier` parameter overrides the schema identifier;
+ * it defaults to the `tag` value.
+ *
+ * **Example** (Tagged class)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * class Circle extends Schema.TaggedClass<Circle>()("Circle", {
+ *   radius: Schema.Number
+ * }) {}
+ *
+ * const c = new Circle({ radius: 5 })
+ * console.log(c._tag) // "Circle"
+ * console.log(c.radius) // 5
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -4970,6 +6136,25 @@ export const TaggedClass = identifier => {
   };
 };
 /**
+ * Creates a schema-backed error class that can be used as a typed,
+ * yieldable error in Effect programs. Combines {@link Class} validation with
+ * the `YieldableError` interface so instances can be yielded directly inside
+ * `Effect.gen`.
+ *
+ * **Example** (Schema-backed error)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * class NotFound extends Schema.ErrorClass<NotFound>("NotFound")({
+ *   id: Schema.Number
+ * }) {}
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* new NotFound({ id: 1 })
+ * })
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -4980,6 +6165,24 @@ export const ErrorClass = identifier => (schema, annotations) => {
   return self;
 };
 /**
+ * Like {@link ErrorClass} but automatically adds a `_tag` literal field. The
+ * resulting class is both a schema-validated, yieldable error and a tagged
+ * union member.
+ *
+ * **Example** (Tagged error class)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ *
+ * class NotFound extends Schema.TaggedErrorClass<NotFound>()("NotFound", {
+ *   id: Schema.Number
+ * }) {}
+ *
+ * const program = Effect.gen(function*() {
+ *   yield* new NotFound({ id: 42 })
+ * })
+ * ```
+ *
  * @category Constructors
  * @since 4.0.0
  */
@@ -4994,6 +6197,11 @@ export const TaggedErrorClass = identifier => {
   };
 };
 /**
+ * Derives a {@link LazyArbitrary} from a schema. The result is memoized so
+ * repeated calls with the same schema are cheap.
+ *
+ * Prefer {@link toArbitrary} when you just need the arbitrary directly.
+ *
  * @category Arbitrary
  * @since 4.0.0
  */
@@ -5002,6 +6210,24 @@ export function toArbitraryLazy(schema) {
   return fc => lawc(fc, {});
 }
 /**
+ * Derives a `fast-check` `Arbitrary` from a schema for property-based
+ * testing. The derived arbitrary generates values that satisfy the schema.
+ *
+ * **Example** (Generating arbitrary values)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import * as FastCheck from "fast-check"
+ *
+ * const PersonArb = Schema.toArbitrary(
+ *   Schema.Struct({ name: Schema.String, age: Schema.Number })
+ * )
+ *
+ * // Sample a random value
+ * const sample = FastCheck.sample(PersonArb, 1)[0]
+ * console.log(typeof sample.name) // "string"
+ * ```
+ *
  * @category Arbitrary
  * @since 4.0.0
  */
@@ -5028,6 +6254,13 @@ export function overrideToFormatter(toFormatter) {
   };
 }
 /**
+ * Derives a string formatter function from a schema. The formatter converts
+ * a value to its human-readable string representation, recursing into structs,
+ * arrays, and unions.
+ *
+ * The optional `onBefore` hook lets you intercept specific AST nodes before
+ * the default formatting logic runs.
+ *
  * @category Formatter
  * @since 4.0.0
  */
@@ -5166,10 +6399,9 @@ export function toFormatter(schema, options) {
 // Equivalence
 // -----------------------------------------------------------------------------
 /**
- * **Technical Note**
- *
- * This annotation cannot be added to `Annotations.Bottom` because it would make
- * the schema invariant.
+ * Overrides the equivalence derivation for a schema by supplying a custom
+ * `Equivalence`. Use this when the default structural equivalence derived by
+ * {@link toEquivalence} is not appropriate for a type.
  *
  * @category Equivalence
  * @since 4.0.0
@@ -5180,6 +6412,21 @@ export function overrideToEquivalence(toEquivalence) {
   });
 }
 /**
+ * Derives an `Equivalence` from a schema. Two values are considered equal when
+ * every field (and nested field) compares equal according to the schema
+ * structure.
+ *
+ * **Example** (Struct equivalence)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const eq = Schema.toEquivalence(Schema.Struct({ id: Schema.Number, name: Schema.String }))
+ *
+ * console.log(eq({ id: 1, name: "Alice" }, { id: 1, name: "Alice" })) // true
+ * console.log(eq({ id: 1, name: "Alice" }, { id: 2, name: "Alice" })) // false
+ * ```
+ *
  * @category Equivalence
  * @since 4.0.0
  */
@@ -5190,6 +6437,10 @@ export function toEquivalence(schema) {
 // Representation
 // -----------------------------------------------------------------------------
 /**
+ * Derives an intermediate `SchemaRepresentation.Document` from a schema. This
+ * document is used internally by {@link toJsonSchemaDocument} and related
+ * functions to produce JSON Schema output.
+ *
  * @category Representation
  * @since 4.0.0
  */
@@ -5217,6 +6468,9 @@ export function toJsonSchemaDocument(schema, options) {
 // Canonical Codecs
 // -----------------------------------------------------------------------------
 /**
+ * Derives a canonical JSON codec from a schema. The encoded form is `unknown`
+ * (any JSON-compatible value), decoded to the schema's `Type`.
+ *
  * @category Canonical Codecs
  * @since 4.0.0
  */
@@ -5224,6 +6478,9 @@ export function toCodecJson(schema) {
   return make(InternalToCodec.toCodecJson(schema.ast));
 }
 /**
+ * Derives an isomorphism codec from a schema. The encoded form is the
+ * schema's `Iso` type — the intermediate representation used for round-tripping.
+ *
  * @category Canonical Codecs
  * @since 4.0.0
  */
@@ -5238,6 +6495,10 @@ export function toCodecStringTree(schema, options) {
   }
 }
 /**
+ * Derives an XML encoder from a codec. Encodes a value to an XML string by
+ * first converting it through {@link toCodecStringTree}, then serializing the
+ * resulting tree to XML.
+ *
  * @category Canonical Codecs
  * @since 4.0.0
  */
@@ -5450,6 +6711,9 @@ function onSerializerEnsureArray(ast) {
 // Optic APIs
 // -----------------------------------------------------------------------------
 /**
+ * Derives an `Iso` optic from a schema that isomorphically converts between
+ * the schema's `Type` and its `Iso` (intermediate / serialized form).
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -5458,6 +6722,8 @@ export function toIso(schema) {
   return Optic_.makeIso(Parser.encodeSync(serializer), Parser.decodeSync(serializer));
 }
 /**
+ * Returns an identity `Iso` over the schema's source (`Type`) side.
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -5465,6 +6731,8 @@ export function toIsoSource(_) {
   return Optic_.id();
 }
 /**
+ * Returns an identity `Iso` over the schema's focus (`Iso`) side.
+ *
  * @category Optic
  * @since 4.0.0
  */
@@ -5472,10 +6740,11 @@ export function toIsoFocus(_) {
   return Optic_.id();
 }
 /**
- * **Technical Note**
- *
- * This annotation cannot be added to `Annotations.Bottom` because it changes
- * the schema type.
+ * Overrides the ISO codec derivation for a schema by providing a target codec
+ * and explicit `decode`/`encode` getters. The resulting schema carries a
+ * custom `Iso` type, which changes the schema's type parameter — use
+ * {@link overrideToCodecIso} when the default ISO transformation is not
+ * appropriate.
  *
  * @category Optic
  * @since 4.0.0
@@ -5493,11 +6762,15 @@ export function overrideToCodecIso(to, transformation) {
 // Differ APIs
 // -----------------------------------------------------------------------------
 /**
+ * Derives a JSON Patch differ from a codec. Serializes values to JSON (via
+ * {@link toCodecJson}), computes RFC 6902 JSON Patch operations between old
+ * and new values, and can apply patches back to the typed value.
+ *
  * @category JsonPatch
  * @since 4.0.0
  */
 export function toDifferJsonPatch(schema) {
-  const serializer = toCodecJson(schema); // TODO: remove this cast
+  const serializer = toCodecJson(schema);
   const get = Parser.encodeSync(serializer);
   const set = Parser.decodeSync(serializer);
   return {
@@ -5512,6 +6785,10 @@ export function toDifferJsonPatch(schema) {
   };
 }
 /**
+ * Creates a recursive schema for a {@link Tree} of values described by `node`.
+ * The resulting schema accepts a single node value, an array of trees, or an
+ * object whose values are trees.
+ *
  * @category Tree
  * @since 4.0.0
  */
@@ -5521,11 +6798,25 @@ export function Tree(node) {
   return Tree;
 }
 /**
+ * Schema that accepts and validates any immutable JSON-compatible value.
+ *
+ * **Example** (Validating a JSON value)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const result = Schema.decodeUnknownOption(Schema.Json)({ key: [1, true, null] })
+ * console.log(result._tag) // "Some"
+ * ```
+ *
  * @category JSON
  * @since 4.0.0
  */
 export const Json = /*#__PURE__*/make(AST.Json);
 /**
+ * Schema that accepts any mutable JSON-compatible value. See {@link Json} for
+ * the immutable variant.
+ *
  * @category JSON
  * @since 4.0.0
  */