effect 4.0.0-beta.71 → 4.0.0-beta.72

package/src/Option.ts

@@ -1020,12 +1020,12 @@ export const orElseSome: {
 )
 
 /**
- * Like {@link orElse}, but wraps the result in a `Result` to indicate the
- * source of the value.
+ * Returns the first available value and marks whether it came from the fallback.
  *
  * **When to use**
  *
- * Use when distinguishing whether a value came from the primary or fallback `Option`
+ * Use when distinguishing whether a value came from the primary or fallback
+ * `Option`.
  *
  * **Details**
  *
@@ -1052,12 +1052,12 @@ export const orElseSome: {
  */
 export const orElseResult: {
   /**
-   * Like {@link orElse}, but wraps the result in a `Result` to indicate the
-   * source of the value.
+   * Returns the first available value and marks whether it came from the fallback.
    *
    * **When to use**
    *
-   * Use when distinguishing whether a value came from the primary or fallback `Option`
+   * Use when distinguishing whether a value came from the primary or fallback
+   * `Option`.
    *
    * **Details**
    *
@@ -1084,12 +1084,12 @@ export const orElseResult: {
    */
   <B>(that: LazyArg<Option<B>>): <A>(self: Option<A>) => Option<Result<B, A>>
   /**
-   * Like {@link orElse}, but wraps the result in a `Result` to indicate the
-   * source of the value.
+   * Returns the first available value and marks whether it came from the fallback.
    *
    * **When to use**
    *
-   * Use when distinguishing whether a value came from the primary or fallback `Option`
+   * Use when distinguishing whether a value came from the primary or fallback
+   * `Option`.
    *
    * **Details**
    *
@@ -1576,7 +1576,6 @@ export const getOrThrow: <A>(self: Option<A>) => A = getOrThrowWith(() => new Er
  *
  * - `Some` → applies `f` and wraps the result in a new `Some`
  * - `None` → returns `None` unchanged
- * - Does not mutate the input
  *
  * **Example** (Mapping over an Option)
  *
@@ -1610,7 +1609,6 @@ export const map: {
    *
    * - `Some` → applies `f` and wraps the result in a new `Some`
    * - `None` → returns `None` unchanged
-   * - Does not mutate the input
    *
    * **Example** (Mapping over an Option)
    *
@@ -1644,7 +1642,6 @@ export const map: {
    *
    * - `Some` → applies `f` and wraps the result in a new `Some`
    * - `None` → returns `None` unchanged
-   * - Does not mutate the input
    *
    * **Example** (Mapping over an Option)
    *
@@ -1800,7 +1797,7 @@ export const asVoid: <_>(self: Option<_>) => Option<void> = as(undefined)
 const void_: Option<void> = some(undefined)
 export {
   /**
-   * A pre-built `Some(undefined)` constant.
+   * Provides a pre-built `Some(undefined)` constant.
    *
    * **When to use**
    *
@@ -4028,7 +4025,7 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
 )
 
 /**
- * Checks if an `Option` contains a value equivalent to the given one, using a
+ * Checks whether an `Option` contains a value equivalent to the given one, using a
  * custom `Equivalence`.
  *
  * **When to use**
@@ -4068,7 +4065,7 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
 } => dual(2, (self: Option<A>, a: A): boolean => isNone(self) ? false : isEquivalent(self.value, a))
 
 /**
- * Checks if an `Option` contains a value equal to the given one, using default
+ * Checks whether an `Option` contains a value equal to the given one, using default
  * structural equality.
  *
  * **When to use**
@@ -4103,7 +4100,7 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
  */
 export const contains: {
   /**
-   * Checks if an `Option` contains a value equal to the given one, using default
+   * Checks whether an `Option` contains a value equal to the given one, using default
    * structural equality.
    *
    * **When to use**
@@ -4138,7 +4135,7 @@ export const contains: {
    */
   <A>(a: A): (self: Option<A>) => boolean
   /**
-   * Checks if an `Option` contains a value equal to the given one, using default
+   * Checks whether an `Option` contains a value equal to the given one, using default
    * structural equality.
    *
    * **When to use**
@@ -4175,7 +4172,7 @@ export const contains: {
 } = containsWith(Equal.asEquivalence())
 
 /**
- * Tests if the value in a `Some` satisfies a predicate or refinement.
+ * Checks whether the value in a `Some` satisfies a predicate or refinement.
  *
  * **When to use**
  *
@@ -4213,7 +4210,7 @@ export const contains: {
  */
 export const exists: {
   /**
-   * Tests if the value in a `Some` satisfies a predicate or refinement.
+   * Checks whether the value in a `Some` satisfies a predicate or refinement.
    *
    * **When to use**
    *
@@ -4251,7 +4248,7 @@ export const exists: {
    */
   <A, B extends A>(refinement: Refinement<NoInfer<A>, B>): (self: Option<A>) => self is Option<B>
   /**
-   * Tests if the value in a `Some` satisfies a predicate or refinement.
+   * Checks whether the value in a `Some` satisfies a predicate or refinement.
    *
    * **When to use**
    *
@@ -4289,7 +4286,7 @@ export const exists: {
    */
   <A>(predicate: Predicate<NoInfer<A>>): (self: Option<A>) => boolean
   /**
-   * Tests if the value in a `Some` satisfies a predicate or refinement.
+   * Checks whether the value in a `Some` satisfies a predicate or refinement.
    *
    * **When to use**
    *
@@ -4327,7 +4324,7 @@ export const exists: {
    */
   <A, B extends A>(self: Option<A>, refinement: Refinement<A, B>): self is Option<B>
   /**
-   * Tests if the value in a `Some` satisfies a predicate or refinement.
+   * Checks whether the value in a `Some` satisfies a predicate or refinement.
    *
    * **When to use**
    *
@@ -4625,7 +4622,7 @@ export const bind: {
 } = doNotation.bind<OptionTypeLambda>(map, flatMap)
 
 /**
- * An `Option` containing an empty record `{}`, used as the starting point for
+ * Provides an `Option` containing an empty record `{}`, used as the starting point for
  * do notation chains.
  *
  * **When to use**
@@ -4658,7 +4655,7 @@ export const bind: {
 export const Do: Option<{}> = some({})
 
 /**
- * Generator-based syntax for `Option`, similar to `async`/`await` but for
+ * Provides generator-based syntax for `Option`, similar to `async`/`await` but for
  * optional values. Yielding a `None` short-circuits the generator to `None`.
  *
  * **When to use**

package/src/Order.ts

@@ -94,7 +94,6 @@ import * as Reducer from "./Reducer.ts"
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs or have side effects
  * - Returns `-1` if the first value is less than the second
  * - Returns `0` if the values are equal according to this ordering
  * - Returns `1` if the first value is greater than the second
@@ -156,7 +155,6 @@ export interface OrderTypeLambda extends TypeLambda {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Uses reference equality (`===`) as a shortcut: if `self === that`, returns `0` without calling the comparison function
  * - The comparison function should return `-1`, `0`, or `1` based on the comparison result
  * - The returned order satisfies total ordering laws if the comparison function does
@@ -188,7 +186,7 @@ export function make<A>(
 }
 
 /**
- * An `Order` instance for strings that compares them lexicographically using JavaScript's `<` operator.
+ * Order instance for strings that compares them lexicographically using JavaScript's `<` operator.
  *
  * **When to use**
  *
@@ -198,7 +196,6 @@ export function make<A>(
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Uses lexicographic (dictionary) ordering
  * - Empty string is less than any non-empty string
  * - Comparison is case-sensitive
@@ -221,7 +218,7 @@ export function make<A>(
 export const String: Order<string> = make((self, that) => self < that ? -1 : 1)
 
 /**
- * An `Order` instance for numbers that compares them numerically.
+ * Order instance for numbers that compares them numerically.
  *
  * **When to use**
  *
@@ -231,7 +228,6 @@ export const String: Order<string> = make((self, that) => self < that ? -1 : 1)
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - `0` is considered equal to `-0`
  * - All `NaN` values are considered equal to each other
  * - Any `NaN` is considered less than any non-NaN number
@@ -263,7 +259,7 @@ export const Number: Order<number> = make((self, that) => {
 })
 
 /**
- * An `Order` instance for booleans where `false` is considered less than `true`.
+ * Order instance for booleans where `false` is considered less than `true`.
  *
  * **When to use**
  *
@@ -273,7 +269,6 @@ export const Number: Order<number> = make((self, that) => {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - `false` is less than `true`
  * - Equal values return `0`
  *
@@ -294,7 +289,7 @@ export const Number: Order<number> = make((self, that) => {
 export const Boolean: Order<boolean> = make((self, that) => self < that ? -1 : 1)
 
 /**
- * An `Order` instance for bigints that compares them numerically.
+ * Order instance for bigints that compares them numerically.
  *
  * **When to use**
  *
@@ -304,7 +299,6 @@ export const Boolean: Order<boolean> = make((self, that) => self < that ? -1 : 1
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Uses standard numeric comparison for bigint values
  * - Handles arbitrarily large integers
  *
@@ -336,7 +330,6 @@ export const BigInt: Order<bigint> = make((self, that) => self < that ? -1 : 1)
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Returns a new order that swaps the arguments before comparison
  * - If the original order returns `-1`, the flipped order returns `1`, and vice versa
  * - Equal comparisons remain `0`
@@ -373,7 +366,6 @@ export function flip<A>(O: Order<A>): Order<A> {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - First applies the first order; if the result is non-zero, returns that result
  * - If the first order returns `0` (equal), applies the second order
  * - Returns the first non-zero result, or `0` if both orders return `0`
@@ -419,7 +411,6 @@ export const combine: {
    *
    * **Details**
    *
-   * - Pure function: does not mutate inputs
    * - First applies the first order; if the result is non-zero, returns that result
    * - If the first order returns `0` (equal), applies the second order
    * - Returns the first non-zero result, or `0` if both orders return `0`
@@ -465,7 +456,6 @@ export const combine: {
    *
    * **Details**
    *
-   * - Pure function: does not mutate inputs
    * - First applies the first order; if the result is non-zero, returns that result
    * - If the first order returns `0` (equal), applies the second order
    * - Returns the first non-zero result, or `0` if both orders return `0`
@@ -519,7 +509,6 @@ export const combine: {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Always returns `0` regardless of input values
  * - Useful as a neutral element in order composition
  *
@@ -555,7 +544,6 @@ export function alwaysEqual<A>(): Order<A> {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Applies orders in iteration order
  * - Returns the first non-zero result from any order
  * - Returns `0` only if all orders return `0`
@@ -613,7 +601,6 @@ export function combineAll<A>(collection: Iterable<Order<A>>): Order<A> {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Applies the mapping function to both values before comparison
  * - The mapping function should be pure and not have side effects
  * - Preserves the ordering properties of the original order
@@ -648,7 +635,6 @@ export const mapInput: {
    *
    * **Details**
    *
-   * - Pure function: does not mutate inputs
    * - Applies the mapping function to both values before comparison
    * - The mapping function should be pure and not have side effects
    * - Preserves the ordering properties of the original order
@@ -683,7 +669,6 @@ export const mapInput: {
    *
    * **Details**
    *
-   * - Pure function: does not mutate inputs
    * - Applies the mapping function to both values before comparison
    * - The mapping function should be pure and not have side effects
    * - Preserves the ordering properties of the original order
@@ -712,7 +697,7 @@ export const mapInput: {
 )
 
 /**
- * An `Order` instance for `Date` objects that compares them chronologically by their timestamp.
+ * Order instance for `Date` objects that compares them chronologically by their timestamp.
  *
  * **When to use**
  *
@@ -722,7 +707,6 @@ export const mapInput: {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Compares dates by their underlying timestamp (milliseconds since epoch)
  * - Earlier dates are less than later dates
  * - Invalid dates are compared as if they were valid (uses `getTime()` result)
@@ -757,7 +741,6 @@ export const Date: Order<Date> = mapInput(Number, (date) => date.getTime())
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Compares tuples element-by-element using the corresponding order
  * - Stops at the first non-zero comparison result
  * - Requires tuples to have the same length as the order collection
@@ -824,7 +807,6 @@ export {
    *
    * **Details**
    *
-   * - Pure function: does not mutate inputs
    * - Compares arrays element-by-element using the provided order
    * - Stops at the first non-zero comparison result
    * - If all elements are equal, shorter arrays are less than longer arrays
@@ -861,7 +843,6 @@ export {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Compares structs field-by-field in the order of keys in the fields object
  * - Stops at the first non-zero comparison result
  * - Returns `0` only if all fields are equal
@@ -907,7 +888,7 @@ export function Struct<const R extends { readonly [x: string]: Order<any> }>(
 }
 
 /**
- * Tests whether one value is strictly less than another according to the given order.
+ * Checks whether one value is strictly less than another according to the given order.
  *
  * **When to use**
  *
@@ -917,7 +898,6 @@ export function Struct<const R extends { readonly [x: string]: Order<any> }>(
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Returns `true` if the order returns `-1` (first value is less than second)
  * - Returns `false` for equal or greater values
  * - Supports curried and uncurried call styles
@@ -945,7 +925,7 @@ export const isLessThan = <A>(O: Order<A>): {
 } => dual(2, (self: A, that: A) => O(self, that) === -1)
 
 /**
- * Tests whether one value is strictly greater than another according to the given order.
+ * Checks whether one value is strictly greater than another according to the given order.
  *
  * **When to use**
  *
@@ -955,7 +935,6 @@ export const isLessThan = <A>(O: Order<A>): {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Returns `true` if the order returns `1` (first value is greater than second)
  * - Returns `false` for equal or lesser values
  * - Supports curried and uncurried call styles
@@ -983,7 +962,7 @@ export const isGreaterThan = <A>(O: Order<A>): {
 } => dual(2, (self: A, that: A) => O(self, that) === 1)
 
 /**
- * Tests whether one value is less than or equal to another according to the given order.
+ * Checks whether one value is less than or equal to another according to the given order.
  *
  * **When to use**
  *
@@ -993,7 +972,6 @@ export const isGreaterThan = <A>(O: Order<A>): {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Returns `true` if the order returns `-1` or `0` (less than or equal)
  * - Returns `false` only if the order returns `1` (greater than)
  * - Supports curried and uncurried call styles
@@ -1021,7 +999,7 @@ export const isLessThanOrEqualTo = <A>(O: Order<A>): {
 } => dual(2, (self: A, that: A) => O(self, that) !== 1)
 
 /**
- * Tests whether one value is greater than or equal to another according to the given order.
+ * Checks whether one value is greater than or equal to another according to the given order.
  *
  * **When to use**
  *
@@ -1031,7 +1009,6 @@ export const isLessThanOrEqualTo = <A>(O: Order<A>): {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Returns `true` if the order returns `1` or `0` (greater than or equal)
  * - Returns `false` only if the order returns `-1` (less than)
  * - Supports curried and uncurried call styles
@@ -1069,7 +1046,6 @@ export const isGreaterThanOrEqualTo = <A>(O: Order<A>): {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Returns the value that compares as less than or equal to the other
  * - If values are equal, returns the first argument
  * - Supports curried and uncurried call styles
@@ -1107,7 +1083,6 @@ export const min = <A>(O: Order<A>): {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Returns the value that compares as greater than or equal to the other
  * - If values are equal, returns the first argument
  * - Supports curried and uncurried call styles
@@ -1135,7 +1110,7 @@ export const max = <A>(O: Order<A>): {
 } => dual(2, (self: A, that: A) => self === that || O(self, that) > -1 ? self : that)
 
 /**
- * Clamps a value between a minimum and a maximum according to the given order.
+ * Restricts a value between a minimum and a maximum according to the given order.
  *
  * **When to use**
  *
@@ -1145,7 +1120,6 @@ export const max = <A>(O: Order<A>): {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Returns the value if it's between minimum and maximum (inclusive)
  * - Returns minimum if the value is less than minimum
  * - Returns maximum if the value is greater than maximum
@@ -1189,7 +1163,7 @@ export const clamp = <A>(O: Order<A>): {
   )
 
 /**
- * Tests whether a value is between a minimum and a maximum (inclusive) according to the given order.
+ * Checks whether a value is between a minimum and a maximum (inclusive) according to the given order.
  *
  * **When to use**
  *
@@ -1199,7 +1173,6 @@ export const clamp = <A>(O: Order<A>): {
  *
  * **Details**
  *
- * - Pure function: does not mutate inputs
  * - Returns `true` if the value is greater than or equal to minimum and less than or equal to maximum
  * - Returns `false` if the value is outside the range
  * - Supports curried and uncurried call styles

package/src/Ordering.ts

@@ -79,7 +79,7 @@ import * as Reducer_ from "./Reducer.ts"
 export type Ordering = -1 | 0 | 1
 
 /**
- * Inverts the ordering of the input Ordering.
+ * Reverses the ordering of the input Ordering.
  * This is useful for creating descending sort orders from ascending ones.
  *
  * **When to use**
@@ -121,7 +121,7 @@ export type Ordering = -1 | 0 | 1
 export const reverse = (o: Ordering): Ordering => (o === -1 ? 1 : o === 1 ? -1 : 0)
 
 /**
- * Depending on the `Ordering` parameter given to it, returns a value produced by one of the 3 functions provided as parameters.
+ * Matches an `Ordering` value and returns the branch selected by that ordering.
  *
  * **When to use**
  *
@@ -149,7 +149,7 @@ export const reverse = (o: Ordering): Ordering => (o === -1 ? 1 : o === 1 ? -1 :
  */
 export const match: {
   /**
-   * Depending on the `Ordering` parameter given to it, returns a value produced by one of the 3 functions provided as parameters.
+   * Matches an `Ordering` value and returns the branch selected by that ordering.
    *
    * **When to use**
    *
@@ -183,7 +183,7 @@ export const match: {
     }
   ): (self: Ordering) => A | B | C
   /**
-   * Depending on the `Ordering` parameter given to it, returns a value produced by one of the 3 functions provided as parameters.
+   * Matches an `Ordering` value and returns the branch selected by that ordering.
    *
    * **When to use**
    *
@@ -227,7 +227,7 @@ export const match: {
 ): A | B | C => self === -1 ? onLessThan() : self === 0 ? onEqual() : onGreaterThan())
 
 /**
- * A `Reducer` for combining `Ordering`s.
+ * Reducer for combining `Ordering`s.
  *
  * **When to use**
  *

package/src/PartitionedSemaphore.ts

@@ -44,16 +44,12 @@ import * as Option from "./Option.ts"
  * Runtime type identifier used to mark values that implement
  * `PartitionedSemaphore`.
  *
- * **When to use**
- *
- * Use to mark and recognize `PartitionedSemaphore` values at runtime.
- *
  * **Details**
  *
- * This constant is stored on partitioned semaphore instances and can be used by
- * library code that needs to recognize the data type at runtime.
+ * This marker is part of the runtime representation of partitioned semaphore
+ * values.
  *
- * @category models
+ * @category type IDs
  * @since 4.0.0
  */
 export const PartitionedTypeId: PartitionedTypeId = "~effect/PartitionedSemaphore"
@@ -70,7 +66,7 @@ export const PartitionedTypeId: PartitionedTypeId = "~effect/PartitionedSemaphor
  * Use this type when declaring fields that must contain the exact
  * `PartitionedTypeId` marker value.
  *
- * @category models
+ * @category type IDs
  * @since 4.0.0
  */
 export type PartitionedTypeId = "~effect/PartitionedSemaphore"

package/src/Path.ts

@@ -40,14 +40,11 @@ import { BadArgument } from "./PlatformError.ts"
 /**
  * Runtime type identifier used to mark implementations of the `Path` service.
  *
- * **When to use**
- *
- * Use when implementing or inspecting a custom `Path` service value that must
- * carry the runtime marker.
- *
  * **Details**
  *
  * The marker is the exact string stored on `Path` service implementations.
+ * Most code should depend on the `Path` service instead of inspecting this
+ * value directly.
  *
  * @see {@link layer} for the built-in POSIX `Path` service layer
  *
@@ -57,7 +54,7 @@ import { BadArgument } from "./PlatformError.ts"
 export const TypeId = "~effect/platform/Path"
 
 /**
- * Service interface for platform-specific path manipulation.
+ * Defines the service interface for platform-specific path manipulation.
  *
  * **When to use**
  *
@@ -215,7 +212,7 @@ export declare namespace Path {
 }
 
 /**
- * Context service tag for accessing the current `Path` implementation.
+ * Service tag for accessing the current `Path` implementation.
  *
  * **When to use**
  *

package/src/Pipeable.ts

@@ -611,7 +611,7 @@ export const pipeArguments = <A>(self: A, args: IArguments): unknown => {
  * Use when classes or object prototypes can reuse this value when they need the
  * standard pipe implementation backed by `pipeArguments`.
  *
- * @category models
+ * @category prototypes
  * @since 3.15.0
  */
 export const Prototype: Pipeable = {
@@ -621,7 +621,7 @@ export const Prototype: Pipeable = {
 }
 
 /**
- * Base constructor whose instances implement the standard `Pipeable.pipe`
+ * Provides a base constructor whose instances implement the standard `Pipeable.pipe`
  * method.
  *
  * **When to use**

package/src/PlatformError.ts

@@ -41,7 +41,7 @@ const TypeId = "~effect/platform/PlatformError"
  * **When to use**
  *
  * Use when a platform API rejects caller input before performing the underlying
- * operation and callers need the `BadArgument` reason data directly.
+ * operation and callers need invalid-argument reason data directly.
  *
  * **Details**
  *