effect 4.0.0-beta.4 → 4.0.0-beta.41

package/src/index.ts

@@ -10,7 +10,7 @@ export {
   /**
    * @since 2.0.0
    */
-  coerceUnsafe,
+  cast,
   /**
    * @since 2.0.0
    */
@@ -444,6 +444,65 @@ export * as Chunk from "./Chunk.ts"
 export * as Clock from "./Clock.ts"
 
 /**
+ * A module for combining two values of the same type into one.
+ *
+ * A `Combiner<A>` wraps a single binary function `(self: A, that: A) => A`.
+ * It describes *how* two values merge but carries no initial/empty value
+ * (for that, see {@link Reducer} which extends `Combiner` with an
+ * `initialValue`).
+ *
+ * ## Mental model
+ *
+ * - **Combiner** – an object with a `combine(self, that)` method that returns
+ *   a value of the same type.
+ * - **Argument order** – `self` is the "left" / accumulator side, `that` is
+ *   the "right" / incoming side.
+ * - **No identity element** – unlike a monoid, a `Combiner` does not require
+ *   a neutral element. Use {@link Reducer} when you need one.
+ * - **Purity** – all combiners produced by this module are pure; they never
+ *   mutate their arguments.
+ * - **Composability** – combiners can be lifted into `Option`, `Struct`,
+ *   `Tuple`, and other container types via helpers in those modules.
+ *
+ * ## Common tasks
+ *
+ * - Create a combiner from any binary function → {@link make}
+ * - Swap argument order → {@link flip}
+ * - Pick the smaller / larger of two values → {@link min} / {@link max}
+ * - Always keep the first or last value → {@link first} / {@link last}
+ * - Ignore both values and return a fixed result → {@link constant}
+ * - Insert a separator between combined values → {@link intercalate}
+ *
+ * ## Gotchas
+ *
+ * - `min` and `max` require an `Order<A>`, not a raw comparator. Import from
+ *   e.g. `Number.Order` or `String.Order`.
+ * - `intercalate` is curried: call it with the separator first, then pass the
+ *   base combiner.
+ * - A `Reducer` (which adds `initialValue`) is also a valid `Combiner` — you
+ *   can pass a `Reducer` anywhere a `Combiner` is expected.
+ *
+ * ## Quickstart
+ *
+ * **Example** (combining strings with a separator)
+ *
+ * ```ts
+ * import { Combiner, String } from "effect"
+ *
+ * const csv = Combiner.intercalate(",")(String.ReducerConcat)
+ *
+ * console.log(csv.combine("a", "b"))
+ * // Output: "a,b"
+ *
+ * console.log(csv.combine(csv.combine("a", "b"), "c"))
+ * // Output: "a,b,c"
+ * ```
+ *
+ * ## See also
+ *
+ * - {@link make} – the primary constructor
+ * - {@link Combiner} – the core interface
+ *
  * @since 4.0.0
  */
 export * as Combiner from "./Combiner.ts"
@@ -684,15 +743,75 @@ export * as Console from "./Console.ts"
 export * as Cron from "./Cron.ts"
 
 /**
- * This module provides utilities for creating data types with structural equality
- * semantics. Unlike regular JavaScript objects, `Data` types support value-based
- * equality comparison using the `Equal` module.
+ * Immutable data constructors with discriminated-union support.
+ *
+ * The `Data` module provides base classes and factory functions for creating
+ * immutable value types with a `_tag` field for discriminated unions.
+ * It is the recommended way to define domain models, error types, and
+ * lightweight ADTs in Effect applications.
+ *
+ * ## Mental model
+ *
+ * - **`Class`** — base class for plain immutable data. Extend it with a type
+ *   parameter to declare the fields. Instances are `Pipeable`.
+ * - **`TaggedClass`** — like `Class` but automatically adds a `readonly _tag`
+ *   string literal field. Useful for single-variant types or ad-hoc tagged
+ *   values.
+ * - **`TaggedEnum`** (type) + **`taggedEnum`** (value) — define a multi-variant
+ *   discriminated union from a simple record. `taggedEnum()` returns per-variant
+ *   constructors plus `$is` / `$match` helpers.
+ * - **`Error`** — like `Class` but extends `Cause.YieldableError`, so instances
+ *   can be yielded inside `Effect.gen` to fail the effect.
+ * - **`TaggedError`** — like `TaggedClass` but extends `Cause.YieldableError`.
+ *   Works with `Effect.catchTag` for tag-based error recovery.
+ *
+ * ## Common tasks
+ *
+ * - Define a simple value class → {@link Class}
+ * - Define a value class with a `_tag` → {@link TaggedClass}
+ * - Define a discriminated union with constructors → {@link TaggedEnum} + {@link taggedEnum}
+ * - Define a yieldable error → {@link Error}
+ * - Define a yieldable tagged error → {@link TaggedError}
+ * - Type-guard a tagged value → `$is` from {@link taggedEnum}
+ * - Pattern-match on a tagged union → `$match` from {@link taggedEnum}
+ *
+ * ## Gotchas
+ *
+ * - Variant records passed to `TaggedEnum` must **not** contain a `_tag` key;
+ *   the `_tag` is added automatically from the record key.
+ * - When a class has no fields, the constructor argument is optional (`void`).
+ * - `taggedEnum()` creates **plain objects**, not class instances. If you need
+ *   class-based variants, use `TaggedClass` or `TaggedError` instead.
+ * - `TaggedEnum.WithGenerics` supports up to 4 generic type parameters.
+ *
+ * ## Quickstart
+ *
+ * **Example** (tagged union with pattern matching)
+ *
+ * ```ts
+ * import { Data } from "effect"
  *
- * The main benefits of using `Data` types are:
- * - **Structural equality**: Two `Data` objects are equal if their contents are equal
- * - **Immutability**: `Data` types are designed to be immutable
- * - **Type safety**: Constructors ensure type safety and consistency
- * - **Effect integration**: Error types work seamlessly with Effect's error handling
+ * type Shape = Data.TaggedEnum<{
+ *   Circle: { readonly radius: number }
+ *   Rect: { readonly width: number; readonly height: number }
+ * }>
+ * const { Circle, Rect, $match } = Data.taggedEnum<Shape>()
+ *
+ * const area = $match({
+ *   Circle: ({ radius }) => Math.PI * radius ** 2,
+ *   Rect: ({ width, height }) => width * height
+ * })
+ *
+ * console.log(area(Circle({ radius: 5 })))
+ * // 78.53981633974483
+ * console.log(area(Rect({ width: 3, height: 4 })))
+ * // 12
+ * ```
+ *
+ * @see {@link Class} — plain immutable data class
+ * @see {@link TaggedEnum} — discriminated union type
+ * @see {@link taggedEnum} — discriminated union constructors
+ * @see {@link TaggedError} — yieldable tagged error class
  *
  * @since 2.0.0
  */
@@ -837,12 +956,14 @@ export * as Duration from "./Duration.ts"
  *
  * @example
  * ```ts
- * import { Effect } from "effect"
+ * import { Data, Effect } from "effect"
+ *
+ * class DiscountRateError extends Data.TaggedError("DiscountRateError")<{}> {}
  *
  * // Effect that may fail
  * const divide = (a: number, b: number) =>
  *   b === 0
- *     ? Effect.fail(new Error("Division by zero"))
+ *     ? Effect.fail(new DiscountRateError())
  *     : Effect.succeed(a / b)
  *
  * // Error handling
@@ -866,9 +987,80 @@ export * as Duration from "./Duration.ts"
 export * as Effect from "./Effect.ts"
 
 /**
- * This module provides functionality for defining and working with equality between values.
- * It includes the `Equal` interface for types that can determine equality with other values
- * of the same type, and utilities for comparing values.
+ * Encoding & decoding for Base64 (RFC4648), Base64Url, and Hex.
+ *
+ * @since 4.0.0
+ */
+export * as Encoding from "./Encoding.ts"
+
+/**
+ * Structural and custom equality for Effect values.
+ *
+ * The `Equal` module provides deep structural comparison for primitives, plain
+ * objects, arrays, Maps, Sets, Dates, and RegExps. Types that implement the
+ * {@link Equal} interface can supply their own comparison logic while staying
+ * compatible with the rest of the ecosystem (HashMap, HashSet, etc.).
+ *
+ * ## Mental model
+ *
+ * - **Structural equality** — two values are equal when their contents match,
+ *   not when they share the same reference.
+ * - **Hash-first shortcut** — before comparing fields, the module checks
+ *   {@link Hash.hash}. If the hashes differ the objects are unequal without
+ *   further traversal.
+ * - **Equal interface** — any object that implements both {@link symbol} (the
+ *   equality method) and `Hash.symbol` (the hash method) can define custom
+ *   comparison logic.
+ * - **Caching** — comparison results for object pairs are cached in a WeakMap.
+ *   This makes repeated checks fast but **requires immutability** after the
+ *   first comparison.
+ * - **By-reference opt-out** — {@link byReference} and {@link byReferenceUnsafe}
+ *   let you switch individual objects back to reference equality when you need
+ *   mutable identity semantics.
+ *
+ * ## Common tasks
+ *
+ * - Compare two values → {@link equals}
+ * - Check if a value implements `Equal` → {@link isEqual}
+ * - Use `equals` where an `Equivalence` is expected → {@link asEquivalence}
+ * - Implement custom equality on a class → implement {@link Equal} (see
+ *   example on the interface)
+ * - Opt an object out of structural equality → {@link byReference} /
+ *   {@link byReferenceUnsafe}
+ *
+ * ## Gotchas
+ *
+ * - Objects **must be treated as immutable** after their first equality check.
+ *   Results are cached; mutating an object afterwards yields stale results.
+ * - `NaN` is considered equal to `NaN` (unlike `===`).
+ * - Functions without an `Equal` implementation are compared by reference.
+ * - Map and Set comparisons are order-independent but O(n²) in size.
+ * - If only one of two objects implements `Equal`, they are never equal.
+ *
+ * ## Quickstart
+ *
+ * **Example** (basic structural comparison)
+ *
+ * ```ts
+ * import { Equal } from "effect"
+ *
+ * // Primitives
+ * console.log(Equal.equals(1, 1))       // true
+ * console.log(Equal.equals("a", "b"))   // false
+ *
+ * // Objects and arrays
+ * console.log(Equal.equals({ x: 1 }, { x: 1 })) // true
+ * console.log(Equal.equals([1, 2], [1, 2]))       // true
+ *
+ * // Curried form
+ * const is42 = Equal.equals(42)
+ * console.log(is42(42)) // true
+ * console.log(is42(0))  // false
+ * ```
+ *
+ * @see {@link equals} — the main comparison function
+ * @see {@link Equal} — the interface for custom equality
+ * @see {@link Hash} — the companion hashing module
  *
  * @since 2.0.0
  */
@@ -894,7 +1086,7 @@ export * as Equal from "./Equal.ts"
  * - Using strict equality (`===`) → {@link strictEqual}
  * - Combining multiple equivalences (AND logic) → {@link combine}, {@link combineAll}
  * - Transforming input before comparison → {@link mapInput}
- * - Creating equivalences for structured types → {@link Struct}, {@link Tuple}, {@link Array}, {@link Record}
+ * - Creating equivalences for structured types → {@link Struct}, {@link Tuple}, {@link Array_}, {@link Record}
  *
  * ## Gotchas
  *
@@ -922,13 +1114,65 @@ export * as Equal from "./Equal.ts"
  * ## See also
  *
  * - {@link Equal} - For structural equality (can convert to Equivalence)
- * - {@link Array.dedupeWith} - Remove duplicates using an equivalence
+ * - {@link Array_.dedupeWith} - Remove duplicates using an equivalence
  * - {@link Chunk} - Collections that use equivalences for operations
  *
  * @since 2.0.0
  */
 export * as Equivalence from "./Equivalence.ts"
 
+/**
+ * Pluggable error reporting for Effect programs.
+ *
+ * Reporting is triggered by `Effect.withErrorReporting`,
+ * `ErrorReporter.report`, or built-in reporting boundaries in the HTTP and
+ * RPC server modules.
+ *
+ * Each reporter receives a structured callback with the failing `Cause`, a
+ * pretty-printed `Error`, severity, and any extra attributes attached to the
+ * original error — making it straightforward to forward failures to Sentry,
+ * Datadog, or a custom logging backend.
+ *
+ * Use the annotation symbols (`ignore`, `severity`, `attributes`) on your
+ * error classes to control reporting behavior per-error.
+ *
+ * @example
+ * ```ts
+ * import { Data, Effect, ErrorReporter } from "effect"
+ *
+ * // A reporter that logs to the console
+ * const consoleReporter = ErrorReporter.make(({ error, severity }) => {
+ *   console.error(`[${severity}]`, error.message)
+ * })
+ *
+ * // An error that should be ignored by reporters
+ * class NotFoundError extends Data.TaggedError("NotFoundError")<{}> {
+ *   readonly [ErrorReporter.ignore] = true
+ * }
+ *
+ * // An error with custom severity and attributes
+ * class RateLimitError extends Data.TaggedError("RateLimitError")<{
+ *   readonly retryAfter: number
+ * }> {
+ *   readonly [ErrorReporter.severity] = "Warn" as const
+ *   readonly [ErrorReporter.attributes] = {
+ *     retryAfter: this.retryAfter
+ *   }
+ * }
+ *
+ * // Opt in to error reporting with Effect.withErrorReporting
+ * const program = Effect.gen(function*() {
+ *   return yield* new RateLimitError({ retryAfter: 60 })
+ * }).pipe(
+ *   Effect.withErrorReporting,
+ *   Effect.provide(ErrorReporter.layer([consoleReporter]))
+ * )
+ * ```
+ *
+ * @since 4.0.0
+ */
+export * as ErrorReporter from "./ErrorReporter.ts"
+
 /**
  * @since 3.16.0
  */
@@ -1130,6 +1374,57 @@ export * as FileSystem from "./FileSystem.ts"
 export * as Filter from "./Filter.ts"
 
 /**
+ * Utilities for converting arbitrary JavaScript values into human-readable
+ * strings, with support for circular references, redaction, and common JS
+ * types that `JSON.stringify` handles poorly.
+ *
+ * Mental model:
+ * - A `Formatter<Value, Format>` is a callable `(value: Value) => Format`.
+ * - {@link format} is the general-purpose pretty-printer: it handles
+ *   primitives, arrays, objects, `BigInt`, `Symbol`, `Date`, `RegExp`,
+ *   `Set`, `Map`, class instances, and circular references.
+ * - {@link formatJson} is a safe `JSON.stringify` wrapper that silently
+ *   drops circular references and applies redaction.
+ * - Both functions accept a `space` option for indentation control.
+ *
+ * Common tasks:
+ * - Pretty-print any value for debugging / logging -> {@link format}
+ * - Serialize to JSON safely (no circular throws) -> {@link formatJson}
+ * - Format a single object property key -> {@link formatPropertyKey}
+ * - Format a property path like `["a"]["b"]` -> {@link formatPath}
+ * - Format a `Date` to ISO string safely -> {@link formatDate}
+ *
+ * Gotchas:
+ * - {@link format} output is **not** valid JSON; use {@link formatJson} when
+ *   you need parseable JSON.
+ * - {@link format} calls `toString()` on objects by default; pass
+ *   `ignoreToString: true` to disable.
+ * - {@link formatJson} silently omits circular references (the key is
+ *   dropped from the output).
+ * - Values implementing the `Redactable` protocol are automatically
+ *   redacted by both {@link format} and {@link formatJson}.
+ *
+ * **Example** (Pretty-print a value)
+ *
+ * ```ts
+ * import { Formatter } from "effect"
+ *
+ * const obj = { name: "Alice", scores: [100, 97] }
+ * console.log(Formatter.format(obj))
+ * // {"name":"Alice","scores":[100,97]}
+ *
+ * console.log(Formatter.format(obj, { space: 2 }))
+ * // {
+ * //   "name": "Alice",
+ * //   "scores": [
+ * //     100,
+ * //     97
+ * //   ]
+ * // }
+ * ```
+ *
+ * See also: {@link Formatter}, {@link format}, {@link formatJson}
+ *
  * @since 4.0.0
  */
 export * as Formatter from "./Formatter.ts"
@@ -1263,7 +1558,7 @@ export * as Inspectable from "./Inspectable.ts"
  *
  * @example
  * ```ts
- * import { Iterable } from "effect"
+ * import { Iterable, Option } from "effect"
  *
  * // Create iterables
  * const numbers = Iterable.range(1, 5)
@@ -1273,7 +1568,7 @@ export * as Inspectable from "./Inspectable.ts"
  * console.log(Array.from(filtered)) // [6, 8, 10]
  *
  * // Infinite iterables
- * const fibonacci = Iterable.unfold([0, 1], ([a, b]) => [a, [b, a + b]])
+ * const fibonacci = Iterable.unfold([0, 1], ([a, b]) => Option.some([a, [b, a + b]]))
  * const first10 = Iterable.take(fibonacci, 10)
  * console.log(Array.from(first10)) // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
  * ```
@@ -1394,10 +1689,98 @@ export * as JsonPatch from "./JsonPatch.ts"
 export * as JsonPointer from "./JsonPointer.ts"
 
 /**
+ * Convert JSON Schema documents between dialects (Draft-07, Draft-2020-12,
+ * OpenAPI 3.0, OpenAPI 3.1). All dialects are normalized to an internal
+ * `Document<"draft-2020-12">` representation before optional conversion to
+ * an output dialect.
+ *
+ * ## Mental model
+ *
+ * - **JsonSchema** — a plain object with string keys; represents any single
+ *   JSON Schema node.
+ * - **Dialect** — one of `"draft-07"`, `"draft-2020-12"`, `"openapi-3.1"`,
+ *   or `"openapi-3.0"`.
+ * - **Document** — a structured container holding a root `schema`, its
+ *   companion `definitions`, and the target `dialect`. Definitions are
+ *   stored separately from the root schema so they can be relocated when
+ *   converting between dialects.
+ * - **MultiDocument** — same as `Document` but carries multiple root
+ *   schemas (at least one). Useful when generating several schemas that
+ *   share a single definitions pool.
+ * - **Definitions** — a `Record<string, JsonSchema>` keyed by definition
+ *   name. The ref pointer prefix depends on the dialect.
+ * - **`from*` functions** — parse a raw JSON Schema object into the
+ *   canonical `Document<"draft-2020-12">`.
+ * - **`to*` functions** — convert from the canonical representation to a
+ *   specific output dialect.
+ *
+ * ## Common tasks
+ *
+ * - Parse a Draft-07 schema → {@link fromSchemaDraft07}
+ * - Parse a Draft-2020-12 schema → {@link fromSchemaDraft2020_12}
+ * - Parse an OpenAPI 3.1 schema → {@link fromSchemaOpenApi3_1}
+ * - Parse an OpenAPI 3.0 schema → {@link fromSchemaOpenApi3_0}
+ * - Convert to Draft-07 output → {@link toDocumentDraft07}
+ * - Convert to OpenAPI 3.1 output → {@link toMultiDocumentOpenApi3_1}
+ * - Resolve a `$ref` against definitions → {@link resolve$ref}
+ * - Inline the root `$ref` of a document → {@link resolveTopLevel$ref}
+ *
+ * ## Gotchas
+ *
+ * - All `from*` functions normalize to `Document<"draft-2020-12">`
+ *   regardless of the input dialect.
+ * - Unsupported or unrecognized JSON Schema keywords are silently dropped
+ *   during conversion.
+ * - Draft-07 tuple syntax (`items` as array + `additionalItems`) is
+ *   converted to 2020-12 form (`prefixItems` + `items`), and vice-versa.
+ * - OpenAPI 3.0 `nullable: true` is expanded into `type` arrays or
+ *   `anyOf` unions. The `nullable` keyword is removed.
+ * - OpenAPI 3.0 singular `example` is converted to `examples` (array).
+ * - {@link resolve$ref} only looks up the last segment of the ref path in
+ *   the definitions map; it does not follow arbitrary JSON Pointer paths.
+ *
+ * ## Quickstart
+ *
+ * **Example** (Parse a Draft-07 schema and convert to Draft-07 output)
+ *
+ * ```ts
+ * import { JsonSchema } from "effect"
+ *
+ * const raw: JsonSchema.JsonSchema = {
+ *   type: "object",
+ *   properties: {
+ *     name: { type: "string" }
+ *   },
+ *   required: ["name"]
+ * }
+ *
+ * // Parse into canonical form
+ * const doc = JsonSchema.fromSchemaDraft07(raw)
+ *
+ * // Convert back to Draft-07
+ * const draft07 = JsonSchema.toDocumentDraft07(doc)
+ *
+ * console.log(draft07.dialect) // "draft-07"
+ * console.log(draft07.schema) // { type: "object", properties: { name: { type: "string" } }, required: ["name"] }
+ * ```
+ *
+ * ## See also
+ *
+ * - {@link Document}
+ * - {@link MultiDocument}
+ * - {@link fromSchemaDraft07}
+ * - {@link toDocumentDraft07}
+ * - {@link resolve$ref}
+ *
  * @since 4.0.0
  */
 export * as JsonSchema from "./JsonSchema.ts"
 
+/**
+ * @since 3.8.0
+ */
+export * as Latch from "./Latch.ts"
+
 /**
  * A `Layer<ROut, E, RIn>` describes how to build one or more services in your
  * application. Services can be injected into effects via
@@ -1931,6 +2314,73 @@ export * as MutableList from "./MutableList.ts"
  */
 export * as MutableRef from "./MutableRef.ts"
 
+/**
+ * Lightweight wrapper types that prevent accidental mixing of structurally
+ * identical values (e.g. `UserId` vs `OrderId`, both `string` at runtime).
+ *
+ * **Mental model**
+ *
+ * - **Newtype** — a compile-time wrapper around a **carrier** type (the
+ *   underlying primitive or object). At runtime the value is unchanged; the
+ *   tag exists only in the type system.
+ * - **Key** — a unique string literal that distinguishes one newtype from
+ *   another (e.g. `"Label"`, `"UserId"`).
+ * - **Carrier** — the underlying type the newtype wraps (e.g. `string`,
+ *   `number`).
+ * - **Iso** — a lossless two-way conversion between a newtype and its carrier,
+ *   created with {@link makeIso}. Use `iso.set(carrier)` to wrap and
+ *   `iso.get(newtype)` to unwrap.
+ *
+ * **Common tasks**
+ *
+ * - Define a newtype → declare an `interface` extending
+ *   `Newtype.Newtype<Key, Carrier>`
+ * - Wrap / unwrap values → {@link makeIso} (returns an `Optic.Iso`)
+ * - Unwrap only → {@link value}
+ * - Lift an `Equivalence` → {@link makeEquivalence}
+ * - Lift an `Order` → {@link makeOrder}
+ * - Lift a `Combiner` → {@link makeCombiner}
+ * - Lift a `Reducer` → {@link makeReducer}
+ *
+ * **Gotchas**
+ *
+ * - Newtypes are **purely compile-time**. There is zero runtime overhead;
+ *   `value` and `makeIso` use identity casts.
+ * - Two newtypes sharing the same key string will be assignable to each other.
+ *   Choose unique key strings.
+ * - A newtype value is **not** assignable to its carrier type without
+ *   explicitly unwrapping via {@link value} or an iso.
+ *
+ * **Quickstart**
+ *
+ * **Example** (defining and using a newtype)
+ *
+ * ```ts
+ * import { Newtype } from "effect"
+ *
+ * // 1. Define a newtype
+ * interface Label extends Newtype.Newtype<"Label", string> {}
+ *
+ * // 2. Create an iso for wrapping/unwrapping
+ * const labelIso = Newtype.makeIso<Label>()
+ *
+ * // 3. Wrap a raw string
+ * const myLabel: Label = labelIso.set("hello")
+ *
+ * // 4. Unwrap back to string
+ * const raw: string = labelIso.get(myLabel) // "hello"
+ * ```
+ *
+ * **See also**
+ *
+ * - {@link Newtype} (the tagged interface)
+ * - {@link makeIso} (wrap and unwrap)
+ * - {@link value} (unwrap only)
+ *
+ * @since 4.0.0
+ */
+export * as Newtype from "./Newtype.ts"
+
 /**
  * @since 2.0.0
  *
@@ -2063,37 +2513,6 @@ export * as MutableRef from "./MutableRef.ts"
  */
 export * as NonEmptyIterable from "./NonEmptyIterable.ts"
 
-/**
- * This module provides small, allocation-free utilities for working with values of type
- * `A | null`, where `null` means "no value".
- *
- * Why not `Option<A>`?
- * In TypeScript, `Option<A>` is often unnecessary. If `null` already models absence
- * in your domain, using `A | null` keeps types simple, avoids extra wrappers, and
- * reduces overhead. The key is that `A` itself must not include `null`; in this
- * module `null` is reserved to mean "no value".
- *
- * When to use `A | null`:
- * - Absence can be represented by `null` in your domain model.
- * - You do not need to distinguish between "no value" and "value is null".
- * - You want straightforward ergonomics and zero extra allocations.
- *
- * When to prefer `Option<A>`:
- * - You must distinguish `None` from `Some(null)` (that is, `null` is a valid
- *   payload and carries meaning on its own).
- * - You need a tagged representation for serialization or pattern matching across
- *   boundaries where `null` would be ambiguous.
- * - You want the richer `Option` API and are comfortable with the extra wrapper.
- *
- * Lawfulness note:
- * All helpers treat `null` as absence. Do not use these utilities with payloads
- * where `A` can itself be `null`, or you will lose information. If you need to
- * carry `null` as a valid payload, use `Option<A>` instead.
- *
- * @since 4.0.0
- */
-export * as NullOr from "./NullOr.ts"
-
 /**
  * This module provides utility functions and type class instances for working with the `number` type in TypeScript.
  * It includes functions for basic arithmetic operations.
@@ -2103,11 +2522,100 @@ export * as NullOr from "./NullOr.ts"
 export * as Number from "./Number.ts"
 
 /**
- * Design: "pretty good" persistency.
- * Real updates copy only the path; unrelated branches keep referential identity.
- * No-op updates may still allocate a new root/parents — callers must not rely on identity for no-ops.
+ * Composable, immutable accessors for reading and updating nested data
+ * structures without mutation.
+ *
+ * **Mental model**
+ *
+ * - **Optic** — a first-class reference to a piece inside a larger structure.
+ *   Compose optics to reach deeply nested values.
+ * - **Iso** — lossless two-way conversion (`get`/`set`) between `S` and `A`.
+ *   Extends both {@link Lens} and {@link Prism}.
+ * - **Lens** — focuses on exactly one part of `S`. `get` always succeeds;
+ *   `replace` needs the original `S` to produce the updated whole.
+ * - **Prism** — focuses on a part that may not be present (e.g. a union
+ *   variant). `getResult` can fail; `set` builds a new `S` from `A` alone.
+ * - **Optional** — the most general optic: both reading and writing can fail.
+ * - **Traversal** — focuses on zero or more elements of an array-like
+ *   structure. Technically `Optional<S, ReadonlyArray<A>>`.
+ * - **Hierarchy** (strongest → weakest):
+ *   `Iso > Lens | Prism > Optional`. Composing a weaker optic with any other
+ *   produces the weaker kind.
+ *
+ * **Common tasks**
+ *
+ * - Start a chain → {@link id} (identity iso)
+ * - Drill into a struct key → `.key("name")` / `.optionalKey("name")`
+ * - Drill into a key that may not exist → `.at("name")`
+ * - Narrow a tagged union → `.tag("MyVariant")`
+ * - Narrow by type guard → `.refine(guard)`
+ * - Add validation → `.check(Schema.isGreaterThan(0))`
+ * - Filter out `undefined` → `.notUndefined()`
+ * - Pick/omit struct keys → `.pick(["a","b"])` / `.omit(["c"])`
+ * - Traverse array elements → `.forEach(el => el.key("field"))`
+ * - Build an iso → {@link makeIso}
+ * - Build a lens → {@link makeLens}
+ * - Build a prism → {@link makePrism}, {@link fromChecks}
+ * - Build an optional → {@link makeOptional}
+ * - Focus into `Option.Some` → {@link some}
+ * - Focus into `Result.Success`/`Failure` → {@link success}, {@link failure}
+ * - Convert record ↔ entries → {@link entries}
+ * - Extract all traversal elements → {@link getAll}
+ *
+ * **Gotchas**
+ *
+ * - Updates are structurally persistent: only nodes on the path are cloned.
+ *   Unrelated branches keep referential identity. However, **no-op updates
+ *   may still allocate** a new root — do not rely on reference identity to
+ *   detect no-ops.
+ * - `replace` silently returns the original `S` when the optic cannot focus
+ *   (e.g. wrong tag). Use `replaceResult` for explicit failure.
+ * - `modify` also returns the original `S` on focus failure — it never throws.
+ * - `.key()` and `.optionalKey()` do not work on union types (compile error).
+ * - Only plain objects (`Object.prototype` or `null` prototype) and arrays can
+ *   be cloned. Class instances cause a runtime error on `replace`/`modify`.
+ *
+ * **Quickstart**
+ *
+ * **Example** (reading and updating nested state)
+ *
+ * ```ts
+ * import { Optic } from "effect"
+ *
+ * type State = { user: { name: string; age: number } }
+ *
+ * const _age = Optic.id<State>().key("user").key("age")
+ *
+ * const s1: State = { user: { name: "Alice", age: 30 } }
+ *
+ * // Read
+ * console.log(_age.get(s1))
+ * // Output: 30
+ *
+ * // Update immutably
+ * const s2 = _age.replace(31, s1)
+ * console.log(s2)
+ * // Output: { user: { name: "Alice", age: 31 } }
+ *
+ * // Modify with a function
+ * const s3 = _age.modify((n) => n + 1)(s1)
+ * console.log(s3)
+ * // Output: { user: { name: "Alice", age: 31 } }
+ *
+ * // Referential identity is preserved for unrelated branches
+ * console.log(s2.user !== s1.user)
+ * // Output: true (on the path)
+ * ```
+ *
+ * **See also**
+ *
+ * - {@link id} — entry point for optic chains
+ * - {@link Lens} / {@link Prism} / {@link Optional} — core optic types
+ * - {@link Traversal} / {@link getAll} — multi-focus optics
+ * - {@link some} / {@link success} / {@link failure} — built-in prisms
  *
  * @since 4.0.0
+ * @module
  */
 export * as Optic from "./Optic.ts"
 
@@ -2144,7 +2652,7 @@ export * as Optic from "./Optic.ts"
  * **Gotchas**
  *
  * - `Option.some(null)` is a valid `Some`; use {@link fromNullishOr} to treat `null`/`undefined` as `None`
- * - {@link filterMap} is an alias for {@link flatMap}
+ * - {@link filterMap} uses a `Filter` callback that returns `Result`
  * - {@link getOrThrow} throws a generic `Error`; prefer {@link getOrThrowWith} for custom errors
  * - `None` is a singleton; compare with {@link isNone}, not `===`
  * - When yielded in `Effect.gen`, a `None` becomes a `NoSuchElementError` defect
@@ -2270,8 +2778,7 @@ export * as Order from "./Order.ts"
 export * as Ordering from "./Ordering.ts"
 
 /**
- * @since 3.19.4
- * @experimental
+ * @since 4.0.0
  */
 export * as PartitionedSemaphore from "./PartitionedSemaphore.ts"
 
@@ -2451,6 +2958,71 @@ export * as Redactable from "./Redactable.ts"
 export * as Redacted from "./Redacted.ts"
 
 /**
+ * A module for reducing collections of values into a single result.
+ *
+ * A `Reducer<A>` extends {@link Combiner.Combiner} by adding an
+ * `initialValue` (identity element) and a `combineAll` method that folds an
+ * entire collection. Think `Array.prototype.reduce`, but packaged as a
+ * reusable, composable value.
+ *
+ * ## Mental model
+ *
+ * - **Reducer** – a {@link Combiner.Combiner} plus an `initialValue` and a
+ *   `combineAll` method.
+ * - **initialValue** – the neutral/identity element. Combining any value with
+ *   `initialValue` should return the original value unchanged (e.g. `0` for
+ *   addition, `""` for string concatenation).
+ * - **combineAll** – folds an `Iterable<A>` starting from `initialValue`.
+ *   When omitted from {@link make}, a default left-to-right fold is used.
+ * - **Purity** – all reducers produced by this module are pure; they never
+ *   mutate their arguments.
+ * - **Composability** – reducers can be lifted into `Option`, `Struct`,
+ *   `Tuple`, `Record`, and other container types via helpers in those modules.
+ * - **Subtype of Combiner** – every `Reducer` is also a valid
+ *   `Combiner`, so you can pass a `Reducer` anywhere a `Combiner` is
+ *   expected.
+ *
+ * ## Common tasks
+ *
+ * - Create a reducer from a combine function and initial value → {@link make}
+ * - Swap argument order → {@link flip}
+ * - Combine two values without an initial value → use {@link Combiner.Combiner}
+ *   instead
+ *
+ * ## Gotchas
+ *
+ * - `combineAll` on an empty iterable returns `initialValue`, not an error.
+ * - The default `combineAll` folds left-to-right. If your `combine` is not
+ *   associative, order matters. Pass a custom `combineAll` to {@link make} if
+ *   you need different traversal or short-circuiting.
+ * - A `Reducer` is also a valid `Combiner` — but a `Combiner` is *not* a
+ *   `Reducer` (it lacks `initialValue`).
+ *
+ * ## Quickstart
+ *
+ * **Example** (summing a list of numbers)
+ *
+ * ```ts
+ * import { Reducer } from "effect"
+ *
+ * const Sum = Reducer.make<number>((a, b) => a + b, 0)
+ *
+ * console.log(Sum.combine(3, 4))
+ * // Output: 7
+ *
+ * console.log(Sum.combineAll([1, 2, 3, 4]))
+ * // Output: 10
+ *
+ * console.log(Sum.combineAll([]))
+ * // Output: 0
+ * ```
+ *
+ * ## See also
+ *
+ * - {@link make} – the primary constructor
+ * - {@link Reducer} – the core interface
+ * - {@link Combiner.Combiner} – the parent interface (no `initialValue`)
+ *
  * @since 4.0.0
  */
 export * as Reducer from "./Reducer.ts"
@@ -2650,7 +3222,7 @@ export * as Runtime from "./Runtime.ts"
  *
  * // Retry with exponential backoff
  * const retryPolicy = Schedule.exponential("100 millis", 2.0)
- *   .pipe(Schedule.compose(Schedule.recurs(3)))
+ *   .pipe(Schedule.both(Schedule.recurs(3)))
  *
  * const program = Effect.gen(function*() {
  *   // This will retry up to 3 times with exponential backoff
@@ -2675,6 +3247,88 @@ export * as Schedule from "./Schedule.ts"
 export * as Scheduler from "./Scheduler.ts"
 
 /**
+ * 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 ArraySchema}, {@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
  */
 export * as Schema from "./Schema.ts"
@@ -3137,6 +3791,11 @@ export * as ScopedCache from "./ScopedCache.ts"
  */
 export * as ScopedRef from "./ScopedRef.ts"
 
+/**
+ * @since 2.0.0
+ */
+export * as Semaphore from "./Semaphore.ts"
+
 /**
  * This module provides a data structure called `ServiceMap` that can be used
  * for dependency injection in effectful programs. It is essentially a table
@@ -3386,6 +4045,14 @@ export * as Tuple from "./Tuple.ts"
  */
 export * as TxChunk from "./TxChunk.ts"
 
+/**
+ * A transactional deferred value — a write-once cell that can be read within transactions.
+ * Readers retry until a value is set; once set, the value is immutable.
+ *
+ * @since 4.0.0
+ */
+export * as TxDeferred from "./TxDeferred.ts"
+
 /**
  * @since 2.0.0
  */
@@ -3396,6 +4063,25 @@ export * as TxHashMap from "./TxHashMap.ts"
  */
 export * as TxHashSet from "./TxHashSet.ts"
 
+/**
+ * A transactional priority queue. Elements are dequeued in order determined by the
+ * provided `Order` instance. All operations participate in the STM transaction system.
+ *
+ * @since 4.0.0
+ */
+export * as TxPriorityQueue from "./TxPriorityQueue.ts"
+
+/**
+ * TxPubSub is a transactional publish/subscribe hub that provides Software Transactional Memory
+ * (STM) semantics for message broadcasting. Publishers broadcast messages to all current
+ * subscribers, with each subscriber receiving its own copy of every published message.
+ *
+ * Supports multiple queue strategies: bounded, unbounded, dropping, and sliding.
+ *
+ * @since 4.0.0
+ */
+export * as TxPubSub from "./TxPubSub.ts"
+
 /**
  * TxQueue is a transactional queue data structure that provides Software Transactional Memory (STM)
  * semantics for queue operations. It uses TxRef for transactional state management and supports
@@ -3409,6 +4095,16 @@ export * as TxHashSet from "./TxHashSet.ts"
  */
 export * as TxQueue from "./TxQueue.ts"
 
+/**
+ * TxReentrantLock is a transactional read/write lock with reentrant semantics using Software
+ * Transactional Memory (STM). Multiple readers can hold the lock concurrently, OR a single
+ * writer can hold exclusive access. A fiber holding a write lock may acquire additional
+ * read or write locks (reentrancy).
+ *
+ * @since 4.0.0
+ */
+export * as TxReentrantLock from "./TxReentrantLock.ts"
+
 /**
  * TxRef is a transactional value, it can be read and modified within the body of a transaction.
  *
@@ -3426,6 +4122,14 @@ export * as TxRef from "./TxRef.ts"
  */
 export * as TxSemaphore from "./TxSemaphore.ts"
 
+/**
+ * TxSubscriptionRef is a TxRef that allows subscribing to all committed changes. Subscribers
+ * receive the current value followed by every subsequent update via a transactional queue.
+ *
+ * @since 4.0.0
+ */
+export * as TxSubscriptionRef from "./TxSubscriptionRef.ts"
+
 /**
  * Type-level utility types for TypeScript.
  *
@@ -3519,6 +4223,62 @@ export * as UndefinedOr from "./UndefinedOr.ts"
 export * as Unify from "./Unify.ts"
 
 /**
+ * Internal utilities for the Effect ecosystem's generator-based syntax and
+ * higher-kinded type machinery.
+ *
+ * ## Mental model
+ *
+ * - **SingleShotGen** — an `IterableIterator` wrapper that yields its value
+ *   exactly once. Used internally by `[Symbol.iterator]()` on Effect, Option,
+ *   Result, and other yieldable types so they work inside generator functions.
+ * - **Gen** — a type-level signature for generator-based monadic composition
+ *   (`gen` functions). Parametric over any `TypeLambda` so each module
+ *   (Effect, Option, Result, ...) can expose its own `gen` with correct types.
+ * - **Variance** — a type-level marker that encodes the variance (covariant,
+ *   contravariant, invariant) of a `TypeLambda`'s type parameters.
+ *   Used by {@link Gen} for type inference.
+ *
+ * ## Common tasks
+ *
+ * - Make a type yieldable in generators -> implement `[Symbol.iterator]()` returning a {@link SingleShotGen}
+ * - Define a generator-based API for a new TypeLambda -> type it as {@link Gen}`<MyTypeLambda>`
+ * - Encode variance for a higher-kinded type -> use {@link Variance}
+ *
+ * ## Gotchas
+ *
+ * - {@link SingleShotGen} yields its value only on the first `.next()` call.
+ *   Calling `.next()` again returns `{ done: true }`. Iterating the same
+ *   instance twice will skip the value on the second pass; call
+ *   `[Symbol.iterator]()` to get a fresh iterator.
+ * - {@link Gen} and {@link Variance} are pure type-level constructs — they
+ *   have no runtime representation.
+ *
+ * ## Quickstart
+ *
+ * **Example** (Using SingleShotGen to make a type yieldable)
+ *
+ * ```ts
+ * import { Utils } from "effect"
+ *
+ * class MyWrapper<A> {
+ *   constructor(readonly value: A) {}
+ *   [Symbol.iterator]() {
+ *     return new Utils.SingleShotGen<MyWrapper<A>, A>(this)
+ *   }
+ * }
+ *
+ * const w = new MyWrapper(42)
+ * const iter = w[Symbol.iterator]()
+ * console.log(iter.next(undefined as any))
+ * // { value: MyWrapper { value: 42 }, done: false }
+ * console.log(iter.next(42))
+ * // { value: 42, done: true }
+ * ```
+ *
+ * @see {@link SingleShotGen}
+ * @see {@link Gen}
+ * @see {@link Variance}
+ *
  * @since 2.0.0
  */
 export * as Utils from "./Utils.ts"