effect 4.0.0-beta.83 → 4.0.0-beta.84

package/src/Iterable.ts

@@ -3233,7 +3233,7 @@ export const map: {
 /**
  * Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
  *
- * **Example** (FlatMapping iterables)
+ * **Example** (Flat mapping iterables)
  *
  * ```ts
  * import { Iterable } from "effect"
@@ -3272,7 +3272,7 @@ export const flatMap: {
   /**
    * Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
    *
-   * **Example** (FlatMapping iterables)
+   * **Example** (Flat mapping iterables)
    *
    * ```ts
    * import { Iterable } from "effect"
@@ -3311,7 +3311,7 @@ export const flatMap: {
   /**
    * Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
    *
-   * **Example** (FlatMapping iterables)
+   * **Example** (Flat mapping iterables)
    *
    * ```ts
    * import { Iterable } from "effect"
@@ -4089,7 +4089,7 @@ export const filter: {
  * Use when working with APIs or functions that return nullable values,
  * providing a clean way to filter out null or undefined while transforming.
  *
- * **Example** (FlatMapping nullable results)
+ * **Example** (Flat mapping nullable results)
  *
  * ```ts
  * import { Iterable } from "effect"
@@ -4135,7 +4135,7 @@ export const flatMapNullishOr: {
    * Use when working with APIs or functions that return nullable values,
    * providing a clean way to filter out null or undefined while transforming.
    *
-   * **Example** (FlatMapping nullable results)
+   * **Example** (Flat mapping nullable results)
    *
    * ```ts
    * import { Iterable } from "effect"
@@ -4181,7 +4181,7 @@ export const flatMapNullishOr: {
    * Use when working with APIs or functions that return nullable values,
    * providing a clean way to filter out null or undefined while transforming.
    *
-   * **Example** (FlatMapping nullable results)
+   * **Example** (Flat mapping nullable results)
    *
    * ```ts
    * import { Iterable } from "effect"

package/src/JsonPatch.ts

@@ -29,7 +29,7 @@ import type * as Schema from "./Schema.ts"
  * discriminated by the `op` field, and the optional `description` field can be
  * used for documentation.
  *
- * **Example** (All operation types)
+ * **Example** (Defining all operation types)
  *
  * ```ts
  * import { JsonPatch } from "effect"
@@ -113,7 +113,7 @@ export type JsonPatchOperation =
  * operations observe the document state produced by earlier operations. An empty
  * array represents a no-op patch and returns the original document.
  *
- * **Example** (Multi-operation patch)
+ * **Example** (Defining a multi-operation patch)
  *
  * ```ts
  * import { JsonPatch } from "effect"

package/src/Layer.ts

@@ -4259,7 +4259,7 @@ export const span = (
  * that are built with this layer. This API does not create, end, or close the
  * span; the caller remains responsible for the span's lifetime.
  *
- * **Example** (Using an existing parent span)
+ * **Example** (Referencing an existing parent span)
  *
  * ```ts
  * import { Console, Context, Effect, Layer, Tracer } from "effect"

package/src/Logger.ts

@@ -547,7 +547,7 @@ export const make: <Message, Output>(
 /**
  * The default logging implementation used by the Effect runtime.
  *
- * **Example** (Using the default logger)
+ * **Example** (Referencing the default logger)
  *
  * ```ts
  * import { Effect, Logger } from "effect"

package/src/Match.ts

@@ -601,7 +601,7 @@ export const typeTags: {
  * **Important:** This function must be the first step in the matcher pipeline.
  * If used later, TypeScript will not enforce type consistency correctly.
  *
- * **Example** (Validating Return Type Consistency)
+ * **Example** (Validating return type consistency)
  *
  * ```ts
  * import { Match } from "effect"
@@ -641,7 +641,7 @@ export const withReturnType: <Ret>() => <I, F, R, A, Pr, _>(
  * pattern matches, the associated function is executed and the matched input is
  * removed from the remaining cases tracked by the matcher.
  *
- * **Example** (Matching with Values and Predicates)
+ * **Example** (Matching with values and predicates)
  *
  * ```ts
  * import { Match } from "effect"
@@ -1055,7 +1055,7 @@ export const discriminatorsExhaustive: <D extends string>(
  * `"_tag"` as their discriminator field. Use {@link discriminator} for a
  * different discriminator field.
  *
- * **Example** (Matching a Discriminated Union by Tag)
+ * **Example** (Matching a discriminated union by tag)
  *
  * ```ts
  * import { Match } from "effect"
@@ -1268,7 +1268,7 @@ export const tagsExhaustive: <
  * Any excluded value bypasses the provided function and continues matching
  * through later cases.
  *
- * **Example** (Ignoring a Specific Value)
+ * **Example** (Ignoring a specific value)
  *
  * ```ts
  * import { Match } from "effect"
@@ -1945,7 +1945,7 @@ export const instanceOfUnsafe: <A extends abstract new(...args: any) => any>(
  * `default` clause in a `switch` statement or the final `else` in an `if-else`
  * chain.
  *
- * **Example** (Providing a Default Value When No Patterns Match)
+ * **Example** (Providing a default value when no patterns match)
  *
  * ```ts
  * import { Match } from "effect"
@@ -2041,7 +2041,7 @@ export const orElseAbsurd: <I, R, RA, A, Pr, Ret>(
  * unmatched case should be explicitly handled rather than returning a default
  * value or throwing an error.
  *
- * **Example** (Extracting a User Role with `Match.result`)
+ * **Example** (Extracting a user role with `Match.result`)
  *
  * ```ts
  * import { Match } from "effect"
@@ -2087,7 +2087,7 @@ export const result: <I, F, R, A, Pr, Ret>(
  * handled explicitly rather than throwing an error or returning a default
  * value.
  *
- * **Example** (Extracting a User Role with `Match.option`)
+ * **Example** (Extracting a user role with `Match.option`)
  *
  * ```ts
  * import { Match } from "effect"
@@ -2131,7 +2131,7 @@ export const option: <I, F, R, A, Pr, Ret>(
  * If any case is still unmatched, the matcher does not type-check as
  * exhaustive.
  *
- * **Example** (Ensuring All Cases Are Covered)
+ * **Example** (Ensuring all cases are covered)
  *
  * ```ts
  * import { Match } from "effect"

package/src/Metric.ts

@@ -1586,7 +1586,7 @@ export declare namespace Metric {
 /**
  * Service key for the current metric attributes context.
  *
- * **Example** (Using the current attributes key)
+ * **Example** (Accessing the current metric attributes key)
  *
  * ```ts
  * import { Data, Effect, Metric } from "effect"
@@ -4634,7 +4634,7 @@ const fiberFailures = counter("child_fiber_failures", {
 /**
  * Service key for the fiber runtime metrics service.
  *
- * **Example** (Using the fiber runtime metrics key)
+ * **Example** (Accessing the fiber runtime metrics key)
  *
  * ```ts
  * import { Data, Effect, Layer, Metric } from "effect"
@@ -4781,7 +4781,7 @@ export const FiberRuntimeMetrics = Context.Reference<FiberRuntimeMetricsService
 /**
  * Default implementation of the fiber runtime metrics service.
  *
- * **Example** (Using the default fiber metrics implementation)
+ * **Example** (Accessing the default fiber metrics implementation)
  *
  * ```ts
  * import { Data, Effect, Layer, Metric } from "effect"

package/src/Optic.ts

@@ -39,7 +39,7 @@ import type { IsUnion } from "./Types.ts"
  * - `get(set(a)) === a` and `set(get(s))` equals `s` (round-trip laws).
  * - Extends both {@link Lens} and {@link Prism}.
  *
- * **Example** (Celsius ↔ Fahrenheit)
+ * **Example** (Converting between Celsius and Fahrenheit)
  *
  * ```ts
  * import { Optic } from "effect"
@@ -77,7 +77,7 @@ export interface Iso<in out S, in out A> extends Lens<S, A>, Prism<S, A> {}
  *
  * The returned optic can be composed with any other optic.
  *
- * **Example** (wrapping/unwrapping a branded type)
+ * **Example** (Wrapping and unwrapping a branded type)
  *
  * ```ts
  * import { Optic } from "effect"
@@ -121,7 +121,7 @@ export function makeIso<S, A>(get: (s: S) => A, set: (a: A) => S): Iso<S, A> {
  * - Composing a Lens with a {@link Prism} or {@link Optional} produces an
  *   {@link Optional}.
  *
- * **Example** (focusing on a struct field)
+ * **Example** (Focusing on a struct field)
  *
  * ```ts
  * import { Optic } from "effect"
@@ -158,7 +158,7 @@ export interface Lens<in out S, in out A> extends Optional<S, A> {
  * - `replace(a, s)` should return a structurally new `S` with `a` in place
  *   of the old focus.
  *
- * **Example** (lens into the first element of a pair)
+ * **Example** (Focusing on the first element of a pair)
  *
  * ```ts
  * import { Optic } from "effect"
@@ -204,7 +204,7 @@ export function makeLens<S, A>(get: (s: S) => A, replace: (a: A, s: S) => S): Le
  * - Composing two Prisms produces a Prism; composing a Prism with a
  *   {@link Lens} produces an {@link Optional}.
  *
- * **Example** (narrowing a tagged union)
+ * **Example** (Narrowing a tagged union)
  *
  * ```ts
  * import { Optic, Result } from "effect"
@@ -245,7 +245,7 @@ export interface Prism<in out S, in out A> extends Optional<S, A> {
  *
  * - `getResult` should return `Result.fail(message)` on mismatch.
  *
- * **Example** (parsing a string to a number)
+ * **Example** (Parsing a string to a number)
  *
  * ```ts
  * import { Optic, Result } from "effect"
@@ -290,7 +290,7 @@ export function makePrism<S, A>(getResult: (s: S) => Result.Result<A, string>, s
  *   any check fails.
  * - `set` is identity — the value passes through unchanged.
  *
- * **Example** (positive integer prism)
+ * **Example** (Creating a positive integer prism)
  *
  * ```ts
  * import { Optic, Result, Schema } from "effect"
@@ -473,7 +473,7 @@ type ForbidUnion<A, Message extends string> = IsUnion<A> extends true ? [Message
  * - `modify(f)` returns the original `s` on failure (never throws).
  * - All operations are pure; inputs are never mutated.
  *
- * **Example** (record key that may be absent)
+ * **Example** (Focusing on an optional record key)
  *
  * ```ts
  * import { Optic, Result } from "effect"
@@ -521,7 +521,7 @@ export interface Optional<in out S, in out A> {
    * Composes this optic with another. The result type is the weakest of
    * the two: Iso + Iso = Iso, Lens + Prism = Optional, etc.
    *
-   * **Example** (composing a lens with a prism)
+   * **Example** (Composing a lens with a prism)
    *
    * ```ts
    * import { Optic, Option } from "effect"
@@ -543,7 +543,7 @@ export interface Optional<in out S, in out A> {
    * Returns a function `(s: S) => S` that applies `f` to the focused value.
    * If the optic cannot focus, the original `s` is returned unchanged.
    *
-   * **Example** (incrementing a nested field)
+   * **Example** (Incrementing a nested field)
    *
    * ```ts
    * import { Optic } from "effect"
@@ -567,7 +567,7 @@ export interface Optional<in out S, in out A> {
    * - On an {@link Optional}, returns an Optional.
    * - Does **not** work on union types (compile error).
    *
-   * **Example** (drilling into nested structs)
+   * **Example** (Drilling into nested structs)
    *
    * ```ts
    * import { Optic } from "effect"
@@ -599,7 +599,7 @@ export interface Optional<in out S, in out A> {
    * - The focus type becomes `A[Key] | undefined`.
    * - Does **not** work on union types (compile error).
    *
-   * **Example** (deleting an optional key)
+   * **Example** (Deleting an optional key)
    *
    * ```ts
    * import { Optic } from "effect"
@@ -634,7 +634,7 @@ export interface Optional<in out S, in out A> {
    * - On a {@link Prism}, returns a Prism.
    * - On an {@link Optional}, returns an Optional.
    *
-   * **Example** (only focus positive numbers)
+   * **Example** (Focusing only on positive numbers)
    *
    * ```ts
    * import { Optic, Result, Schema } from "effect"
@@ -665,7 +665,7 @@ export interface Optional<in out S, in out A> {
    * - On an {@link Optional}, returns an Optional.
    * - Pass optional `annotations` to customize the error message.
    *
-   * **Example** (narrowing a union)
+   * **Example** (Narrowing a union)
    *
    * ```ts
    * import { Optic, Result } from "effect"
@@ -705,7 +705,7 @@ export interface Optional<in out S, in out A> {
    * - On an {@link Optional}, returns an Optional.
    * - Shorthand for `.refine(s => s._tag === tag)`.
    *
-   * **Example** (focusing a tagged variant)
+   * **Example** (Focusing a tagged variant)
    *
    * ```ts
    * import { Optic, Result } from "effect"
@@ -746,7 +746,7 @@ export interface Optional<in out S, in out A> {
    * - Always returns an {@link Optional}.
    * - Does **not** work on union types (compile error).
    *
-   * **Example** (safe record access)
+   * **Example** (Accessing records safely)
    *
    * ```ts
    * import { Optic, Result } from "effect"
@@ -778,7 +778,7 @@ export interface Optional<in out S, in out A> {
    * - On an {@link Optional}, returns an Optional.
    * - Does **not** work on union types (compile error).
    *
-   * **Example** (picking keys)
+   * **Example** (Picking keys)
    *
    * ```ts
    * import { Optic } from "effect"
@@ -813,7 +813,7 @@ export interface Optional<in out S, in out A> {
    * - On an {@link Optional}, returns an Optional.
    * - Does **not** work on union types (compile error).
    *
-   * **Example** (omitting keys)
+   * **Example** (Omitting keys)
    *
    * ```ts
    * import { Optic } from "effect"
@@ -845,7 +845,7 @@ export interface Optional<in out S, in out A> {
    * Filters out `undefined` from the focus, producing a {@link Prism}.
    * `getResult` fails when the focus is `undefined`.
    *
-   * **Example** (filtering undefined)
+   * **Example** (Filtering undefined values)
    *
    * ```ts
    * import { Optic, Result } from "effect"
@@ -879,7 +879,7 @@ export interface Optional<in out S, in out A> {
    *   `getResult` and writes them back in order. Fails with a
    *   length-mismatch error if counts differ.
    *
-   * **Example** (incrementing liked posts)
+   * **Example** (Incrementing liked posts)
    *
    * ```ts
    * import { Optic, Schema } from "effect"
@@ -918,7 +918,7 @@ export interface Optional<in out S, in out A> {
    * Unlike `.modify()`, which operates on the whole array, `modifyAll`
    * maps `f` over each individual element.
    *
-   * **Example** (doubling all focused values)
+   * **Example** (Doubling all focused values)
    *
    * ```ts
    * import { Optic, Schema } from "effect"
@@ -955,7 +955,7 @@ export interface Optional<in out S, in out A> {
  * - `set` should return `Result.fail(message)` when the update cannot be
  *   applied.
  *
- * **Example** (safe record key access)
+ * **Example** (Accessing record keys safely)
  *
  * ```ts
  * import { Optic, Result } from "effect"
@@ -1007,7 +1007,7 @@ export function makeOptional<S, A>(
  * - Use `.modifyAll(f)` to map a function over every focused element.
  * - Use {@link getAll} to extract all focused elements as a plain array.
  *
- * **Example** (traversing array elements with a filter)
+ * **Example** (Traversing array elements with a filter)
  *
  * ```ts
  * import { Optic, Schema } from "effect"
@@ -1397,7 +1397,7 @@ function getCompositionTag(a: Op["_tag"], b: Op["_tag"]): Op["_tag"] {
  * - Returns an empty array when the traversal cannot focus.
  * - Always returns a fresh array (safe to mutate).
  *
- * **Example** (collecting positive numbers)
+ * **Example** (Collecting positive numbers)
  *
  * ```ts
  * import { Optic, Schema } from "effect"
@@ -1449,7 +1449,7 @@ const identityIso = make(identityNode)
  * - `set(a)` returns `a`.
  * - Singleton — every call returns the same instance.
  *
- * **Example** (starting an optic chain)
+ * **Example** (Starting an optic chain)
  *
  * ```ts
  * import { Optic } from "effect"
@@ -1486,7 +1486,7 @@ export function id<S>(): Iso<S, S> {
  * - `set` uses `Object.fromEntries`.
  * - Round-trip is lossless for `Record<string, A>`.
  *
- * **Example** (traversing record values)
+ * **Example** (Traversing record values)
  *
  * ```ts
  * import { Optic, Schema } from "effect"
@@ -1523,7 +1523,7 @@ export function entries<A>(): Iso<Record<string, A>, ReadonlyArray<readonly [str
  * - `getResult` fails with an error message when the option is `None`.
  * - `set(a)` wraps `a` in `Option.some(a)`.
  *
- * **Example** (accessing Some value)
+ * **Example** (Accessing Some value)
  *
  * ```ts
  * import { Optic, Option, Result } from "effect"
@@ -1571,7 +1571,7 @@ export function some<A>(): Prism<Option.Option<A>, A> {
  * - `getResult` fails when the option is `Some`.
  * - `set(undefined)` produces `Option.none()`.
  *
- * **Example** (matching None)
+ * **Example** (Matching None)
  *
  * ```ts
  * import { Optic, Option, Result } from "effect"
@@ -1616,7 +1616,7 @@ export function none<A>(): Prism<Option.Option<A>, undefined> {
  * - `getResult` fails when the result is a `Failure`.
  * - `set(a)` produces `Result.succeed(a)`.
  *
- * **Example** (accessing success)
+ * **Example** (Accessing success)
  *
  * ```ts
  * import { Optic, Result } from "effect"
@@ -1661,7 +1661,7 @@ export function success<A, E>(): Prism<Result.Result<A, E>, A> {
  * - `getResult` fails when the result is a `Success`.
  * - `set(e)` produces `Result.fail(e)`.
  *
- * **Example** (accessing failure)
+ * **Example** (Accessing failure)
  *
  * ```ts
  * import { Optic, Result } from "effect"

package/src/Option.ts

@@ -1119,7 +1119,7 @@ export const firstSomeOf = <T, C extends Iterable<Option<T>> = Iterable<Option<T
  * - `null` or `undefined` → `None`
  * - Any other value → `Some` (typed as `NonNullable<A>`)
  *
- * **Example** (From nullable values)
+ * **Example** (Converting nullable values to an Option)
  *
  * ```ts
  * import { Option } from "effect"
@@ -1159,7 +1159,7 @@ export const fromNullishOr = <A>(
  * - `undefined` → `None`
  * - Any other value (including `null`) → `Some`
  *
- * **Example** (From possibly-undefined values)
+ * **Example** (Converting possibly undefined values to an Option)
  *
  * ```ts
  * import { Option } from "effect"
@@ -1198,7 +1198,7 @@ export const fromUndefinedOr = <A>(
  * - `null` → `None`
  * - Any other value (including `undefined`) → `Some`
  *
- * **Example** (From possibly-null values)
+ * **Example** (Converting possibly null values to an Option)
  *
  * ```ts
  * import { Option } from "effect"
@@ -1733,7 +1733,7 @@ export {
    *
    * Use to return a "success with no meaningful value" from an `Option`-returning function
    *
-   * **Example** (Using Option.void)
+   * **Example** (Referencing Option.void)
    *
    * ```ts
    * import { Option } from "effect"
@@ -3995,7 +3995,7 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
  * - `Some` where `isEquivalent(value, a)` is `true` → `true`
  * - `Some` where not equivalent, or `None` → `false`
  *
- * **Example** (Custom equivalence check)
+ * **Example** (Checking with custom equivalence)
  *
  * ```ts
  * import { Equivalence, Option } from "effect"
@@ -4595,7 +4595,7 @@ export const bind: {
  * Use when you need to start an `Option` do notation pipeline before adding
  * bindings.
  *
- * **Example** (Do notation pipeline)
+ * **Example** (Building Option pipelines with do notation)
  *
  * ```ts
  * import { Option, pipe } from "effect"
@@ -4635,7 +4635,7 @@ export const Do: Option<{}> = some({})
  * - The return value is wrapped in `Some`
  * - No `Effect` runtime is needed
  *
- * **Example** (Generator syntax)
+ * **Example** (Sequencing Option computations with generator syntax)
  *
  * ```ts
  * import { Option } from "effect"