effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Optic.ts

@@ -110,7 +110,7 @@ import type { IsUnion } from "./Types.ts"
  *
  * **When to use**
  *
- * - You have a pair of functions that convert back and forth without losing
+ * Use when you have a pair of functions that convert back and forth without losing
  *   information (e.g. `Record ↔ entries`, `Celsius ↔ Fahrenheit`).
  * - You want the strongest optic that can be composed with any other.
  *
@@ -152,12 +152,11 @@ export interface Iso<in out S, in out A> extends Lens<S, A>, Prism<S, A> {}
  *
  * **When to use**
  *
- * - You have two pure functions that form a lossless round-trip between `S`
+ * Use when you have two pure functions that form a lossless round-trip between `S`
  *   and `A`.
  *
  * **Details**
  *
- * - Does not mutate inputs.
  * - The returned optic can be composed with any other optic.
  *
  * **Example** (wrapping/unwrapping a branded type)
@@ -193,7 +192,7 @@ export function makeIso<S, A>(get: (s: S) => A, set: (a: A) => S): Iso<S, A> {
  *
  * **When to use**
  *
- * - You always have a value to read (the part exists unconditionally).
+ * Use when you always have a value to read (the part exists unconditionally).
  * - You need the original `S` to produce the updated whole (unlike
  *   {@link Iso}).
  *
@@ -234,12 +233,11 @@ export interface Lens<in out S, in out A> extends Optional<S, A> {
  *
  * **When to use**
  *
- * - You can always extract `A` from `S` and produce a new `S` by
+ * Use when you can always extract `A` from `S` and produce a new `S` by
  *   substituting a new `A`.
  *
  * **Details**
  *
- * - Does not mutate inputs.
  * - `replace(a, s)` should return a structurally new `S` with `a` in place
  *   of the old focus.
  *
@@ -276,7 +274,7 @@ export function makeLens<S, A>(get: (s: S) => A, replace: (a: A, s: S) => S): Le
  *
  * **When to use**
  *
- * - The focus is conditional — reading can fail (wrong variant, failed
+ * Use when the focus is conditional — reading can fail (wrong variant, failed
  *   validation).
  * - Building a new `S` from `A` does **not** require the original `S`.
  *
@@ -323,12 +321,11 @@ export interface Prism<in out S, in out A> extends Optional<S, A> {
  *
  * **When to use**
  *
- * - Reading can fail (the part may not exist in `S`), but building `S`
+ * Use when reading can fail (the part may not exist in `S`), but building `S`
  *   from `A` always succeeds.
  *
  * **Details**
  *
- * - Does not mutate inputs.
  * - `getResult` should return `Result.fail(message)` on mismatch.
  *
  * **Example** (parsing a string to a number)
@@ -366,7 +363,7 @@ export function makePrism<S, A>(getResult: (s: S) => Result.Result<A, string>, s
  *
  * **When to use**
  *
- * - You want to narrow `T` to the subset that passes certain validation
+ * Use when you want to narrow `T` to the subset that passes certain validation
  *   rules (e.g. positive integer).
  * - You already have `Schema.isGreaterThan`, `Schema.isInt`, etc.
  *
@@ -375,7 +372,6 @@ export function makePrism<S, A>(getResult: (s: S) => Result.Result<A, string>, s
  * - `getResult` runs all checks; fails with a combined error message when
  *   any check fails.
  * - `set` is identity — the value passes through unchanged.
- * - Does not mutate inputs.
  *
  * **Example** (positive integer prism)
  *
@@ -546,10 +542,10 @@ type ForbidUnion<A, Message extends string> = IsUnion<A> extends true ? [Message
  *
  * **When to use**
  *
- * - The focus may not exist in `S` **and** writing a new `A` back may also
- *   fail (e.g. the source no longer matches the expected shape).
- * - As the base type: every optic ({@link Iso}, {@link Lens}, {@link Prism},
- *   {@link Traversal}) extends `Optional`.
+ * Use when the focus may not exist in `S` and writing a new `A` back may also
+ * fail, for example when the source no longer matches the expected shape. This
+ * is the base type extended by {@link Iso}, {@link Lens}, {@link Prism}, and
+ * {@link Traversal}.
  *
  * **Details**
  *
@@ -1030,11 +1026,10 @@ export interface Optional<in out S, in out A> {
  *
  * **When to use**
  *
- * - Both reading and writing can fail.
+ * Use when both reading and writing can fail.
  *
  * **Details**
  *
- * - Does not mutate inputs.
  * - `getResult` should return `Result.fail(message)` on mismatch.
  * - `set` should return `Result.fail(message)` when the update cannot be
  *   applied.
@@ -1079,7 +1074,7 @@ export function makeOptional<S, A>(
  *
  * **When to use**
  *
- * - You want to read/update multiple elements at once (e.g. all items in
+ * Use when you want to read/update multiple elements at once (e.g. all items in
  *   an array, or a filtered subset).
  *
  * **Details**
@@ -1473,14 +1468,13 @@ function getCompositionTag(a: Op["_tag"], b: Op["_tag"]): Op["_tag"] {
  *
  * **When to use**
  *
- * - You need the focused values as a simple `Array<A>` for further
+ * Use when you need the focused values as a simple `Array<A>` for further
  *   processing.
  *
  * **Details**
  *
  * - Returns an empty array when the traversal cannot focus.
  * - Always returns a fresh array (safe to mutate).
- * - Does not mutate the source.
  *
  * **Example** (collecting positive numbers)
  *
@@ -1522,12 +1516,11 @@ export function getAll<S, A>(traversal: Traversal<S, A>): (s: S) => Array<A> {
 const identityIso = make(identityNode)
 
 /**
- * The identity {@link Iso}. Focuses on the whole value unchanged.
+ * Iso that focuses on the whole value unchanged.
  *
  * **When to use**
  *
- * - As the starting point of an optic chain: `Optic.id<S>().key("x")...`
- * - Anywhere an `Iso<S, S>` is needed.
+ * Use when starting an optic chain with a focus on the whole value.
  *
  * **Details**
  *
@@ -1558,12 +1551,12 @@ export function id<S>(): Iso<S, S> {
 }
 
 /**
- * An {@link Iso} that converts a `Record<string, A>` to an array of
+ * Iso that converts a `Record<string, A>` to an array of
  * `[key, value]` entries and back.
  *
  * **When to use**
  *
- * - You want to traverse or manipulate record entries as an array (e.g.
+ * Use when you want to traverse or manipulate record entries as an array (e.g.
  *   with `.forEach()`).
  *
  * **Details**
@@ -1597,11 +1590,11 @@ export function entries<A>(): Iso<Record<string, A>, ReadonlyArray<readonly [str
 }
 
 /**
- * A {@link Prism} that focuses on the value inside `Option.Some`.
+ * Prism that focuses on the value inside `Option.Some`.
  *
  * **When to use**
  *
- * - You have an `Option<A>` and want to read/update the inner value only
+ * Use when you have an `Option<A>` and want to read/update the inner value only
  *   when it is `Some`.
  *
  * **Details**
@@ -1645,11 +1638,11 @@ export function some<A>(): Prism<Option.Option<A>, A> {
 }
 
 /**
- * A {@link Prism} that focuses on `Option.None`, exposing `undefined`.
+ * Prism that focuses on `Option.None`, exposing `undefined`.
  *
  * **When to use**
  *
- * - You want to match or construct `None` values within an optic chain.
+ * Use when you want to match or construct `None` values within an optic chain.
  *
  * **Details**
  *
@@ -1690,11 +1683,11 @@ export function none<A>(): Prism<Option.Option<A>, undefined> {
 }
 
 /**
- * A {@link Prism} that focuses on the success value of a `Result`.
+ * Prism that focuses on the success value of a `Result`.
  *
  * **When to use**
  *
- * - You have a `Result<A, E>` and want to read/update `A` only when it
+ * Use when you have a `Result<A, E>` and want to read/update `A` only when it
  *   is a `Success`.
  *
  * **Details**
@@ -1735,11 +1728,11 @@ export function success<A, E>(): Prism<Result.Result<A, E>, A> {
 }
 
 /**
- * A {@link Prism} that focuses on the failure value of a `Result`.
+ * Prism that focuses on the failure value of a `Result`.
  *
  * **When to use**
  *
- * - You have a `Result<A, E>` and want to read/update `E` only when it
+ * Use when you have a `Result<A, E>` and want to read/update `E` only when it
  *   is a `Failure`.
  *
  * **Details**