effect 4.0.0-beta.73 → 4.0.0-beta.75

package/dist/Option.js

@@ -119,7 +119,7 @@ export const none = () => option.none;
  *
  * **When to use**
  *
- * Use to wrap a known-present value as `Option`
+ * Use to wrap a known present value as `Option`
  * - Returning a successful result from a partial function
  *
  * **Details**
@@ -186,7 +186,7 @@ export const isOption = option.isOption;
  *
  * **When to use**
  *
- * Use when branching on absence before accessing `.value`
+ * Use when you need to branch on an absent `Option` before accessing `.value`.
  *
  * **Details**
  *
@@ -215,7 +215,7 @@ export const isNone = option.isNone;
  *
  * **When to use**
  *
- * Use when branching on presence before accessing `.value`
+ * Use when you need to branch on a present `Option` before accessing `.value`.
  *
  * **Details**
  *
@@ -244,8 +244,8 @@ export const isSome = option.isSome;
  *
  * **When to use**
  *
- * Use when exhaustively handling both branches in one expression
- * - Transforming an `Option` into a plain value
+ * Use when you need to handle both `Some` and `None` in one expression and
+ * transform an `Option` into a plain value.
  *
  * **Details**
  *
@@ -269,7 +269,7 @@ export const isSome = option.isSome;
  *
  * @see {@link getOrElse} for unwrapping with a default
  *
- * @category Pattern matching
+ * @category pattern matching
  * @since 2.0.0
  */
 export const match = /*#__PURE__*/dual(2, (self, {
@@ -281,8 +281,8 @@ export const match = /*#__PURE__*/dual(2, (self, {
  *
  * **When to use**
  *
- * Use when turning a parsing function into a type-narrowing predicate
- * - Filtering arrays with `Array.prototype.filter`
+ * Use when you need to turn an `Option`-returning parser into a type-narrowing
+ * predicate, such as for `Array.prototype.filter`.
  *
  * **Details**
  *
@@ -323,8 +323,8 @@ export const toRefinement = f => a => isSome(f(a));
  *
  * **When to use**
  *
- * Use when safely extracting the head of a collection
- * - Working with generators or lazy iterables
+ * Use when you need to safely extract the head of a collection, including
+ * generators or lazy iterables.
  *
  * **Details**
  *
@@ -359,7 +359,8 @@ export const fromIterable = collection => {
  *
  * **When to use**
  *
- * Use when discarding the failure channel when you only care about success
+ * Use when you need to discard a `Result` failure and keep only the success
+ * value as an `Option`.
  *
  * **Details**
  *
@@ -389,7 +390,8 @@ export const getSuccess = result.getSuccess;
  *
  * **When to use**
  *
- * Use to extract the failure when you do not need the success value
+ * Use when you need to discard a `Result` success and keep only the failure
+ * value as an `Option`.
  *
  * **Details**
  *
@@ -453,8 +455,8 @@ export const getOrElse = /*#__PURE__*/dual(2, (self, onNone) => isNone(self) ? o
  *
  * **When to use**
  *
- * Use when chaining fallback `Option` computations
- * - Building priority chains of optional values
+ * Use when you need a lazy fallback `Option`, such as when building priority
+ * chains of optional values.
  *
  * **Details**
  *
@@ -517,8 +519,8 @@ export const orElseSome = /*#__PURE__*/dual(2, (self, onNone) => isNone(self) ?
  *
  * **When to use**
  *
- * Use when distinguishing whether a value came from the primary or fallback
- * `Option`.
+ * Use when you need to know whether a present value came from the primary or
+ * fallback `Option`.
  *
  * **Details**
  *
@@ -550,7 +552,7 @@ export const orElseResult = /*#__PURE__*/dual(2, (self, that) => isNone(self) ?
  *
  * **When to use**
  *
- * Use when searching for the first available value in a priority list
+ * Use when you need the first available `Some` value from a priority list.
  *
  * **Details**
  *
@@ -589,8 +591,8 @@ export const firstSomeOf = collection => {
  *
  * **When to use**
  *
- * Use when bridging from nullable APIs to `Option`
- * - Wrapping values that may be `null` or `undefined`
+ * Use when you need JavaScript nullish values to become absence at an API
+ * boundary while all other values, including falsy ones, remain present.
  *
  * **Details**
  *
@@ -626,7 +628,8 @@ export const fromNullishOr = a => a == null ? none() : some(a);
  *
  * **When to use**
  *
- * Use when when `null` is a meaningful value but `undefined` means absent
+ * Use when you want to treat only `undefined` as absent while preserving `null`
+ * as a meaningful value.
  *
  * **Details**
  *
@@ -661,7 +664,8 @@ export const fromUndefinedOr = a => a === undefined ? none() : some(a);
  *
  * **When to use**
  *
- * Use when when `undefined` is a meaningful value but `null` means absent
+ * Use when you want to treat only `null` as absent while preserving
+ * `undefined` as a meaningful value.
  *
  * **Details**
  *
@@ -734,7 +738,7 @@ export const liftNullishOr = f => (...a) => fromNullishOr(f(...a));
  *
  * **When to use**
  *
- * Use when interoping with APIs that use `null` for missing values
+ * Use when you need to pass absent `Option` values to APIs that expect `null`.
  *
  * **Details**
  *
@@ -765,7 +769,8 @@ export const getOrNull = /*#__PURE__*/getOrElse(constNull);
  *
  * **When to use**
  *
- * Use when interoping with APIs that use `undefined` for missing values
+ * Use when you need to pass absent `Option` values to APIs that expect
+ * `undefined`.
  *
  * **Details**
  *
@@ -834,8 +839,8 @@ export const liftThrowable = f => (...a) => {
  *
  * **When to use**
  *
- * Use when fail-fast unwrapping when absence is unexpected
- * - Providing a descriptive error for debugging
+ * Use when you need fail-fast unwrapping of an `Option` for unexpected absence
+ * and want to provide a descriptive debugging error.
  *
  * **Details**
  *
@@ -871,7 +876,8 @@ export const getOrThrowWith = /*#__PURE__*/dual(2, (self, onNone) => {
  *
  * **When to use**
  *
- * Use when quick fail-fast unwrapping when a generic error is acceptable
+ * Use when you need quick fail-fast unwrapping of an `Option` and a generic
+ * error is acceptable.
  *
  * **Details**
  *
@@ -903,8 +909,8 @@ export const getOrThrow = /*#__PURE__*/getOrThrowWith(() => new Error("getOrThro
  *
  * **When to use**
  *
- * Use to apply a pure transformation to an optional value, especially when
- * chaining transformations in a pipeline.
+ * Use to apply a pure transformation to an `Option`'s present value, especially
+ * when chaining transformations in a pipeline.
  *
  * **Details**
  *
@@ -935,12 +941,8 @@ export const map = /*#__PURE__*/dual(2, (self, f) => isNone(self) ? none() : som
  *
  * **When to use**
  *
- * Use when preserving presence/absence while discarding the original value
- *
- * **Details**
- *
- * - `Some` → `Some(b)`
- * - `None` → `None`
+ * Use when you need to replace a present `Option` value while preserving
+ * whether it was `Some` or `None`.
  *
  * **Example** (Replacing a value)
  *
@@ -967,12 +969,8 @@ export const as = /*#__PURE__*/dual(2, (self, b) => map(self, () => b));
  *
  * **When to use**
  *
- * Use when discarding the value while preserving presence/absence
- *
- * **Details**
- *
- * - `Some` → `Some(undefined)`
- * - `None` → `None`
+ * Use when you need to discard a present `Option` value while preserving
+ * whether it was `Some` or `None`.
  *
  * **Example** (Voiding the value)
  *
@@ -1022,8 +1020,8 @@ void_ as void };
  *
  * **When to use**
  *
- * Use when chaining dependent optional computations where each step may return
- * `None`.
+ * Use when you need to chain dependent `Option` computations where each step
+ * may return `None`.
  *
  * **Details**
  *
@@ -1068,8 +1066,8 @@ export const flatMap = /*#__PURE__*/dual(2, (self, f) => isNone(self) ? none() :
  *
  * **When to use**
  *
- * Use when flexible chaining where the next step may return `Option`, a plain value,
- *   or a function
+ * Use when you need to chain an `Option` with a next step that may be another
+ * `Option`, a plain value, or a function.
  *
  * **Details**
  *
@@ -1112,8 +1110,8 @@ export const andThen = /*#__PURE__*/dual(2, (self, f) => flatMap(self, a => {
  *
  * **When to use**
  *
- * Use when chaining with functions that use `null`/`undefined` instead of `Option`
- * - Navigating deeply nested optional properties
+ * Use when you need to chain optional computations that use `null` or
+ * `undefined` instead of `Option`, such as nested property access.
  *
  * **Details**
  *
@@ -1153,7 +1151,7 @@ export const flatMapNullishOr = /*#__PURE__*/dual(2, (self, f) => isNone(self) ?
  *
  * **When to use**
  *
- * Use when removing one layer of `Option` nesting
+ * Use when you need to remove one layer of nested `Option`.
  *
  * **Details**
  *
@@ -1184,7 +1182,8 @@ export const flatten = /*#__PURE__*/flatMap(identity);
  *
  * **When to use**
  *
- * Use to run a side-condition that must succeed, then using the second value
+ * Use when you need two `Option` values to both be `Some`, then keep only the
+ * second value.
  *
  * **Details**
  *
@@ -1215,7 +1214,8 @@ export const zipRight = /*#__PURE__*/dual(2, (self, that) => flatMap(self, () =>
  *
  * **When to use**
  *
- * Use to run a validation that must succeed, but keeping the original value
+ * Use when you need two `Option` values to both be `Some`, then keep only the
+ * first value.
  *
  * **Details**
  *
@@ -1247,7 +1247,8 @@ export const zipLeft = /*#__PURE__*/dual(2, (self, that) => tap(self, () => that
  *
  * **When to use**
  *
- * Use to build pipelines of partial functions (Kleisli composition)
+ * Use when you need to compose two functions that each return an `Option`, so
+ * `None` short-circuits without calling the next function.
  *
  * **Details**
  *
@@ -1287,8 +1288,8 @@ export const composeK = /*#__PURE__*/dual(2, (afb, bfc) => a => flatMap(afb(a),
  *
  * **When to use**
  *
- * Use to validate a value without transforming it
- * - Adding a side-condition check in a pipeline
+ * Use to validate an `Option`'s present value without transforming it, such as
+ * adding a side-condition check in a pipeline.
  *
  * **Details**
  *
@@ -1323,7 +1324,8 @@ export const tap = /*#__PURE__*/dual(2, (self, f) => flatMap(self, a => map(f(a)
  *
  * **When to use**
  *
- * Use when pairing two optional values together
+ * Use when you need to require two `Option` values to both be `Some` and keep
+ * both values as a tuple.
  *
  * **Details**
  *
@@ -1345,7 +1347,7 @@ export const tap = /*#__PURE__*/dual(2, (self, f) => flatMap(self, a => map(f(a)
  * @see {@link zipWith} to combine with a function instead of a tuple
  * @see {@link all} to combine many `Option`s
  *
- * @category Combining
+ * @category combining
  * @since 2.0.0
  */
 export const product = (self, that) => isSome(self) && isSome(that) ? some([self.value, that.value]) : none();
@@ -1355,7 +1357,8 @@ export const product = (self, that) => isSome(self) && isSome(that) ? some([self
  *
  * **When to use**
  *
- * Use when collecting several `Option`s of the same type into a non-empty tuple
+ * Use when you need several `Option` values of the same type to all be `Some`
+ * and return them as a non-empty tuple.
  *
  * **Details**
  *
@@ -1380,7 +1383,7 @@ export const product = (self, that) => isSome(self) && isSome(that) ? some([self
  * @see {@link product} for combining exactly two
  * @see {@link all} for tuples, structs, and iterables
  *
- * @category Combining
+ * @category combining
  * @since 2.0.0
  */
 export const productMany = (self, collection) => {
@@ -1402,8 +1405,8 @@ export const productMany = (self, collection) => {
  *
  * **When to use**
  *
- * Use when collecting multiple `Option`s into one, preserving the input shape
- * - "All or nothing" combination — any `None` makes the result `None`
+ * Use when you need to combine multiple `Option` values into one while
+ * preserving the input shape, with any `None` making the result `None`.
  *
  * **Details**
  *
@@ -1438,7 +1441,7 @@ export const productMany = (self, collection) => {
  * @see {@link product} for combining exactly two
  * @see {@link productMany} for a homogeneous collection
  *
- * @category Combining
+ * @category combining
  * @since 2.0.0
  */
 // @ts-expect-error
@@ -1468,7 +1471,8 @@ export const all = input => {
  *
  * **When to use**
  *
- * Use when merging two optional values into a computed result
+ * Use when you need to combine two present `Option` values into a computed
+ * result.
  *
  * **Details**
  *
@@ -1503,7 +1507,8 @@ export const zipWith = /*#__PURE__*/dual(3, (self, that, f) => map(product(self,
  *
  * **When to use**
  *
- * Use when aggregating values from a collection where some may be absent
+ * Use when you need to aggregate values from a collection where some may be
+ * absent.
  *
  * **Details**
  *
@@ -1522,7 +1527,7 @@ export const zipWith = /*#__PURE__*/dual(3, (self, that, f) => map(product(self,
  * // Output: 3
  * ```
  *
- * @category Reducing
+ * @category reducing
  * @since 2.0.0
  */
 export const reduceCompact = /*#__PURE__*/dual(3, (self, b, f) => {
@@ -1539,8 +1544,8 @@ export const reduceCompact = /*#__PURE__*/dual(3, (self, b, f) => {
  *
  * **When to use**
  *
- * Use when interfacing with array-based APIs
- * - Spreading optional values into collections
+ * Use when you need to pass an `Option` to array-based APIs or spread optional
+ * values into collections.
  *
  * **Details**
  *
@@ -1570,7 +1575,8 @@ export const toArray = self => isNone(self) ? [] : [self.value];
  *
  * **When to use**
  *
- * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
+ * Use when you need to split an optional value into "left" and "right"
+ * channels using a `Result`-returning function.
  *
  * **Details**
  *
@@ -1615,7 +1621,8 @@ export const partitionMap = /*#__PURE__*/dual(2, (self, f) => {
  *
  * **When to use**
  *
- * Use to transform a present value and discard it when the `Filter` fails.
+ * Use to transform an `Option`'s present value and discard it when the `Filter`
+ * fails.
  *
  * **Details**
  *
@@ -1652,8 +1659,8 @@ export const filterMap = /*#__PURE__*/dual(2, (self, f) => {
  *
  * **When to use**
  *
- * Use when discarding values that don't meet a condition
- * - Narrowing the type via a refinement predicate
+ * Use when you need to discard an `Option`'s present value when it does not
+ * meet a condition, while narrowing the type via a refinement predicate.
  *
  * **Details**
  *
@@ -1692,7 +1699,8 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => isNone(self) ? n
  *
  * **When to use**
  *
- * Use to compare two `Option` values for structural equality
+ * Use when you need equality to treat two `None` values as equal and compare
+ * two `Some` values with a supplied equality rule.
  *
  * **Details**
  *
@@ -1717,7 +1725,7 @@ export const filter = /*#__PURE__*/dual(2, (self, predicate) => isNone(self) ? n
  * // Output: true
  * ```
  *
- * @category Equivalence
+ * @category instances
  * @since 4.0.0
  */
 export const makeEquivalence = isEquivalent => Equivalence.make((x, y) => isNone(x) ? isNone(y) : isNone(y) ? false : isEquivalent(x.value, y.value));
@@ -1726,7 +1734,9 @@ export const makeEquivalence = isEquivalent => Equivalence.make((x, y) => isNone
  *
  * **When to use**
  *
- * Use to sort collections of `Option` values
+ * Use when you need to sort `Some` and `None` values, with `None` ordered
+ * before present values and present values compared by a supplied ordering
+ * rule.
  *
  * **Details**
  *
@@ -1751,7 +1761,7 @@ export const makeEquivalence = isEquivalent => Equivalence.make((x, y) => isNone
  * // Output: -1
  * ```
  *
- * @category Sorting
+ * @category sorting
  * @since 4.0.0
  */
 export const makeOrder = O => order.make((self, that) => isSome(self) ? isSome(that) ? O(self.value, that.value) : 1 : -1);
@@ -1760,7 +1770,8 @@ export const makeOrder = O => order.make((self, that) => isSome(self) ? isSome(t
  *
  * **When to use**
  *
- * Use when reusing an existing binary function in an `Option` context
+ * Use when you need to reuse an existing binary function with two `Option`
+ * values.
  *
  * **Details**
  *
@@ -1783,7 +1794,7 @@ export const makeOrder = O => order.make((self, that) => isSome(self) ? isSome(t
  *
  * @see {@link zipWith} for a non-lifted variant
  *
- * @category Lifting
+ * @category lifting
  * @since 2.0.0
  */
 export const lift2 = f => dual(2, (self, that) => zipWith(self, that, f));
@@ -1819,7 +1830,7 @@ export const lift2 = f => dual(2, (self, that) => zipWith(self, that, f));
  * @see {@link filter} to apply a predicate to an existing `Option`
  * @see {@link toRefinement} for the inverse direction
  *
- * @category Lifting
+ * @category lifting
  * @since 2.0.0
  */
 export const liftPredicate = /*#__PURE__*/dual(2, (b, predicate) => predicate(b) ? some(b) : none());
@@ -1829,7 +1840,8 @@ export const liftPredicate = /*#__PURE__*/dual(2, (b, predicate) => predicate(b)
  *
  * **When to use**
  *
- * Use when testing membership with a custom equality check
+ * Use when you need to test whether an `Option` contains a value using a
+ * custom equality check.
  *
  * **Details**
  *
@@ -1855,7 +1867,7 @@ export const liftPredicate = /*#__PURE__*/dual(2, (b, predicate) => predicate(b)
  *
  * @see {@link contains} for a version using default equality
  *
- * @category Elements
+ * @category elements
  * @since 2.0.0
  */
 export const containsWith = isEquivalent => dual(2, (self, a) => isNone(self) ? false : isEquivalent(self.value, a));
@@ -1865,7 +1877,8 @@ export const containsWith = isEquivalent => dual(2, (self, a) => isNone(self) ?
  *
  * **When to use**
  *
- * Use when quick membership test with standard equality
+ * Use when you need a quick membership test for an `Option` value using
+ * standard equality.
  *
  * **Details**
  *
@@ -1890,7 +1903,7 @@ export const containsWith = isEquivalent => dual(2, (self, a) => isNone(self) ?
  * @see {@link containsWith} for custom equality
  * @see {@link exists} to test with a predicate
  *
- * @category Elements
+ * @category elements
  * @since 2.0.0
  */
 export const contains = /*#__PURE__*/containsWith(/*#__PURE__*/Equal.asEquivalence());
@@ -1928,7 +1941,7 @@ export const contains = /*#__PURE__*/containsWith(/*#__PURE__*/Equal.asEquivalen
  * @see {@link filter} to keep or discard based on a predicate
  * @see {@link contains} to test for a specific value
  *
- * @category Elements
+ * @category elements
  * @since 2.0.0
  */
 export const exists = /*#__PURE__*/dual(2, (self, refinement) => isNone(self) ? false : refinement(self.value));
@@ -1941,7 +1954,8 @@ export const exists = /*#__PURE__*/dual(2, (self, refinement) => isNone(self) ?
  *
  * **When to use**
  *
- * Use when beginning a do notation chain by naming the first value
+ * Use when you need to start an `Option` do notation chain by naming the first
+ * value.
  *
  * **Example** (Starting do notation)
  *
@@ -1962,7 +1976,7 @@ export const exists = /*#__PURE__*/dual(2, (self, refinement) => isNone(self) ?
  * @see {@link bind} to add `Option` values
  * @see {@link let_ let} to add plain values
  *
- * @category Do notation
+ * @category do notation
  * @since 2.0.0
  */
 export const bindTo = /*#__PURE__*/doNotation.bindTo(map);
@@ -1973,7 +1987,8 @@ export {
  *
  * **When to use**
  *
- * Use when binding a derived (non-`Option`) value in a do notation pipeline
+ * Use when you need to bind a derived non-`Option` value in an `Option` do
+ * notation pipeline.
  *
  * **Example** (Adding a computed value)
  *
@@ -1994,7 +2009,7 @@ export {
  * @see {@link bind} to add `Option` values
  * @see {@link bindTo} to start by naming an existing `Option`
  *
- * @category Do notation
+ * @category do notation
  * @since 2.0.0
  */
 let_ as let };
@@ -2004,7 +2019,7 @@ let_ as let };
  *
  * **When to use**
  *
- * Use when sequencing `Option` computations in do notation
+ * Use when you need to sequence `Option` computations in do notation.
  *
  * **Example** (Binding Option values)
  *
@@ -2026,7 +2041,7 @@ let_ as let };
  * @see {@link let_ let} to add plain values
  * @see {@link bindTo} to start by naming an existing `Option`
  *
- * @category Do notation
+ * @category do notation
  * @since 2.0.0
  */
 export const bind = /*#__PURE__*/doNotation.bind(map, flatMap);
@@ -2036,7 +2051,8 @@ export const bind = /*#__PURE__*/doNotation.bind(map, flatMap);
  *
  * **When to use**
  *
- * Use when starting a do notation pipeline before adding bindings
+ * Use when you need to start an `Option` do notation pipeline before adding
+ * bindings.
  *
  * **Example** (Do notation pipeline)
  *
@@ -2058,7 +2074,7 @@ export const bind = /*#__PURE__*/doNotation.bind(map, flatMap);
  * @see {@link let_ let} to add plain values
  * @see {@link bindTo} to start by naming an existing `Option`
  *
- * @category Do notation
+ * @category do notation
  * @since 2.0.0
  */
 export const Do = /*#__PURE__*/some({});
@@ -2068,8 +2084,8 @@ export const Do = /*#__PURE__*/some({});
  *
  * **When to use**
  *
- * Use when writing imperative-style code that chains multiple `Option`s
- * - Readability when many sequential optional steps are involved
+ * Use when you need generator syntax for a sequence of `Option` steps that
+ * should short-circuit on `None`.
  *
  * **Details**
  *
@@ -2098,7 +2114,7 @@ export const Do = /*#__PURE__*/some({});
  *
  * @see {@link Do} / {@link bind} for the do notation alternative
  *
- * @category Generators
+ * @category generators
  * @since 2.0.0
  */
 export const gen = (...args) => {
@@ -2120,8 +2136,8 @@ export const gen = (...args) => {
  *
  * **When to use**
  *
- * Use to build a reducer that falls back to the first available value
- * - Combining optional values where either side may be absent
+ * Use to build an `Option` reducer that falls back to the first available value
+ * when either side may be absent.
  *
  * **Details**
  *
@@ -2159,7 +2175,8 @@ export function makeReducer(combiner) {
  *
  * **When to use**
  *
- * Use when operations that require both values to be present
+ * Use when you need an `Option` combiner that returns `None` unless both
+ * operands are `Some`.
  *
  * **Details**
  *
@@ -2197,8 +2214,8 @@ export function makeCombinerFailFast(combiner) {
  *
  * **When to use**
  *
- * Use to wrap an existing `Reducer` to work with `Option` values
- * - Reductions where any `None` should abort the entire result
+ * Use when you need to reduce `Option` values with fail-fast semantics, where
+ * any `None` aborts the entire result instead of being skipped.
  *
  * **Details**
  *