effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/BigDecimal.ts

@@ -393,7 +393,8 @@ export const scale: {
  *
  * **When to use**
  *
- * Use to add two `BigDecimal` values.
+ * Use when you need a decimal addition function for piping or higher-order APIs
+ * while preserving decimal precision.
  *
  * **Example** (Adding decimals)
  *
@@ -418,7 +419,8 @@ export const sum: {
    *
    * **When to use**
    *
-   * Use to add two `BigDecimal` values.
+   * Use when you need a decimal addition function for piping or higher-order APIs
+   * while preserving decimal precision.
    *
    * **Example** (Adding decimals)
    *
@@ -443,7 +445,8 @@ export const sum: {
    *
    * **When to use**
    *
-   * Use to add two `BigDecimal` values.
+   * Use when you need a decimal addition function for piping or higher-order APIs
+   * while preserving decimal precision.
    *
    * **Example** (Adding decimals)
    *
@@ -488,7 +491,8 @@ export const sum: {
  *
  * **When to use**
  *
- * Use to sum all `BigDecimal` values in an iterable.
+ * Use when you need to aggregate decimal quantities with decimal precision
+ * instead of converting through JavaScript numbers.
  *
  * **Example** (Adding multiple decimals)
  *
@@ -968,8 +972,8 @@ export const divide: {
  *
  * **When to use**
  *
- * Use when you need the decimal quotient and the divisor is known to be
- * non-zero, so division by zero should be a thrown exception.
+ * Use when you need to divide `BigDecimal` values where the divisor is known
+ * to be non-zero, so division by zero should be a thrown exception.
  *
  * **Details**
  *
@@ -1000,8 +1004,8 @@ export const divideUnsafe: {
    *
    * **When to use**
    *
-   * Use when you need the decimal quotient and the divisor is known to be
-   * non-zero, so division by zero should be a thrown exception.
+   * Use when you need to divide `BigDecimal` values where the divisor is known
+   * to be non-zero, so division by zero should be a thrown exception.
    *
    * **Details**
    *
@@ -1032,8 +1036,8 @@ export const divideUnsafe: {
    *
    * **When to use**
    *
-   * Use when you need the decimal quotient and the divisor is known to be
-   * non-zero, so division by zero should be a thrown exception.
+   * Use when you need to divide `BigDecimal` values where the divisor is known
+   * to be non-zero, so division by zero should be a thrown exception.
    *
    * **Details**
    *
@@ -1080,8 +1084,8 @@ export const divideUnsafe: {
  *
  * **When to use**
  *
- * Use when sorting or comparing decimal values through APIs that accept an
- * ordering instance.
+ * Use when you need to sort or compare decimal values through APIs that accept
+ * an ordering instance.
  *
  * **Example** (Comparing decimals)
  *
@@ -2122,12 +2126,12 @@ export const remainder: {
 
 /**
  * Returns the decimal remainder left over when one operand is divided by a
- * non-zero second operand, throwing for division by zero.
+ * non-zero second operand.
  *
  * **When to use**
  *
- * Use when you need the decimal remainder and the divisor is known to be
- * non-zero, so division by zero should be a thrown exception.
+ * Use when you need to compute a `BigDecimal` remainder with a divisor known to
+ * be non-zero and want a plain `BigDecimal` result instead of an `Option`.
  *
  * **Gotchas**
  *
@@ -2161,12 +2165,12 @@ export const remainder: {
 export const remainderUnsafe: {
   /**
    * Returns the decimal remainder left over when one operand is divided by a
-   * non-zero second operand, throwing for division by zero.
+   * non-zero second operand.
    *
    * **When to use**
    *
-   * Use when you need the decimal remainder and the divisor is known to be
-   * non-zero, so division by zero should be a thrown exception.
+   * Use when you need to compute a `BigDecimal` remainder with a divisor known to
+   * be non-zero and want a plain `BigDecimal` result instead of an `Option`.
    *
    * **Gotchas**
    *
@@ -2200,12 +2204,12 @@ export const remainderUnsafe: {
   (divisor: BigDecimal): (self: BigDecimal) => BigDecimal
   /**
    * Returns the decimal remainder left over when one operand is divided by a
-   * non-zero second operand, throwing for division by zero.
+   * non-zero second operand.
    *
    * **When to use**
    *
-   * Use when you need the decimal remainder and the divisor is known to be
-   * non-zero, so division by zero should be a thrown exception.
+   * Use when you need to compute a `BigDecimal` remainder with a divisor known to
+   * be non-zero and want a plain `BigDecimal` result instead of an `Option`.
    *
    * **Gotchas**
    *
@@ -2389,12 +2393,12 @@ export const equals: {
 export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
 
 /**
- * Creates a `BigDecimal` from a finite `number`, throwing for non-finite input.
+ * Creates a `BigDecimal` from a finite `number`.
  *
  * **When to use**
  *
- * Use when a finite JavaScript number must become a `BigDecimal` and invalid
- * input should throw.
+ * Use when you need to convert a trusted finite JavaScript number to a
+ * `BigDecimal` and want a plain result instead of an `Option`.
  *
  * **Gotchas**
  *
@@ -2556,7 +2560,7 @@ export const fromString = (s: string): Option.Option<BigDecimal> => {
  *
  * **When to use**
  *
- * Use when decimal text is expected to be valid and parse errors should throw.
+ * Use when you expect decimal text to be valid and want parse errors to throw.
  *
  * **Details**
  *
@@ -2688,8 +2692,8 @@ export const toExponential = (n: BigDecimal): string => {
  *
  * **When to use**
  *
- * Use when an interop boundary requires a JavaScript number and can tolerate
- * precision loss.
+ * Use when you need a JavaScript number at an interop boundary where precision
+ * loss is acceptable.
  *
  * **Gotchas**
  *
@@ -2993,7 +2997,8 @@ export const round: {
  *
  * **When to use**
  *
- * Use to remove digits beyond a requested scale by rounding toward zero.
+ * Use when you need to discard fractional digits beyond a scale rather than
+ * round half up, half down, or toward an infinity.
  *
  * **Example** (Truncating decimals)
  *
@@ -3018,7 +3023,8 @@ export const truncate: {
    *
    * **When to use**
    *
-   * Use to remove digits beyond a requested scale by rounding toward zero.
+   * Use when you need to discard fractional digits beyond a scale rather than
+   * round half up, half down, or toward an infinity.
    *
    * **Example** (Truncating decimals)
    *
@@ -3043,7 +3049,8 @@ export const truncate: {
    *
    * **When to use**
    *
-   * Use to remove digits beyond a requested scale by rounding toward zero.
+   * Use when you need to discard fractional digits beyond a scale rather than
+   * round half up, half down, or toward an infinity.
    *
    * **Example** (Truncating decimals)
    *

package/src/BigInt.ts

@@ -141,7 +141,8 @@ export const isBigInt: (u: unknown) => u is bigint = predicate.isBigInt
  *
  * **When to use**
  *
- * Use to add two `bigint` values.
+ * Use when you need a binary addition function for piping or higher-order APIs
+ * instead of the infix addition operator.
  *
  * **Example** (Adding bigints)
  *
@@ -163,7 +164,8 @@ export const sum: {
    *
    * **When to use**
    *
-   * Use to add two `bigint` values.
+   * Use when you need a binary addition function for piping or higher-order APIs
+   * instead of the infix addition operator.
    *
    * **Example** (Adding bigints)
    *
@@ -185,7 +187,8 @@ export const sum: {
    *
    * **When to use**
    *
-   * Use to add two `bigint` values.
+   * Use when you need a binary addition function for piping or higher-order APIs
+   * instead of the infix addition operator.
    *
    * **Example** (Adding bigints)
    *
@@ -434,8 +437,8 @@ export const divide: {
  *
  * **When to use**
  *
- * Use when the divisor is known to be non-zero and division by zero should be a
- * thrown exception.
+ * Use to divide `bigint` values where the divisor is known to be non-zero and
+ * division by zero should be a thrown exception.
  *
  * **Details**
  *
@@ -467,8 +470,8 @@ export const divideUnsafe: {
    *
    * **When to use**
    *
-   * Use when the divisor is known to be non-zero and division by zero should be a
-   * thrown exception.
+   * Use to divide `bigint` values where the divisor is known to be non-zero and
+   * division by zero should be a thrown exception.
    *
    * **Details**
    *
@@ -500,8 +503,8 @@ export const divideUnsafe: {
    *
    * **When to use**
    *
-   * Use when the divisor is known to be non-zero and division by zero should be a
-   * thrown exception.
+   * Use to divide `bigint` values where the divisor is known to be non-zero and
+   * division by zero should be a thrown exception.
    *
    * **Details**
    *
@@ -577,8 +580,8 @@ export const decrement = (n: bigint): bigint => n - bigint1
  *
  * **When to use**
  *
- * Use when sorting or comparing bigint values through APIs that accept an
- * ordering instance.
+ * Use when you need to sort or compare bigint values through APIs that accept
+ * an ordering instance.
  *
  * **Example** (Comparing bigints with Order)
  *
@@ -993,9 +996,9 @@ export const between: {
  *
  * **Details**
  *
- * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
- * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
- * - Otherwise, it returns the original `bigint`.
+ * If the `bigint` is less than the minimum, the function returns the minimum.
+ * If the `bigint` is greater than the maximum, the function returns the
+ * maximum. Otherwise, it returns the original `bigint`.
  *
  * **Example** (Clamping a bigint to bounds)
  *
@@ -1025,9 +1028,9 @@ export const clamp: {
    *
    * **Details**
    *
-   * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
-   * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
-   * - Otherwise, it returns the original `bigint`.
+   * If the `bigint` is less than the minimum, the function returns the minimum.
+   * If the `bigint` is greater than the maximum, the function returns the
+   * maximum. Otherwise, it returns the original `bigint`.
    *
    * **Example** (Clamping a bigint to bounds)
    *
@@ -1062,9 +1065,9 @@ export const clamp: {
    *
    * **Details**
    *
-   * - If the `bigint` is less than the `minimum` value, the function returns the `minimum` value.
-   * - If the `bigint` is greater than the `maximum` value, the function returns the `maximum` value.
-   * - Otherwise, it returns the original `bigint`.
+   * If the `bigint` is less than the minimum, the function returns the minimum.
+   * If the `bigint` is greater than the maximum, the function returns the
+   * maximum. Otherwise, it returns the original `bigint`.
    *
    * **Example** (Clamping a bigint to bounds)
    *
@@ -1435,7 +1438,9 @@ export const lcm: {
  *
  * **When to use**
  *
- * Use when the input is known to be non-negative and invalid input should throw.
+ * Use when you need to compute an integer square root for a `bigint` that has
+ * already been validated as non-negative, and you want negative input to throw
+ * instead of returning `Option.none`.
  *
  * **Details**
  *
@@ -1514,7 +1519,8 @@ export const sqrt = (n: bigint): Option.Option<bigint> =>
  *
  * **When to use**
  *
- * Use to sum all `bigint` values in an iterable.
+ * Use when you want an immediate aggregate from an iterable instead of a
+ * folding reducer owned by another API.
  *
  * **Example** (Summing iterable bigints)
  *
@@ -1691,12 +1697,8 @@ export function fromNumber(n: number): Option.Option<bigint> {
  *
  * **When to use**
  *
- * Use to compute the JavaScript `%` remainder for two `bigint` values.
- *
- * **Details**
- *
- * The result follows JavaScript `%` semantics, including the sign of the
- * dividend.
+ * Use when you want native remainder semantics, including signed remainders and
+ * a thrown division-by-zero error.
  *
  * **Gotchas**
  *
@@ -1723,12 +1725,8 @@ export const remainder: {
    *
    * **When to use**
    *
-   * Use to compute the JavaScript `%` remainder for two `bigint` values.
-   *
-   * **Details**
-   *
-   * The result follows JavaScript `%` semantics, including the sign of the
-   * dividend.
+   * Use when you want native remainder semantics, including signed remainders and
+   * a thrown division-by-zero error.
    *
    * **Gotchas**
    *
@@ -1755,12 +1753,8 @@ export const remainder: {
    *
    * **When to use**
    *
-   * Use to compute the JavaScript `%` remainder for two `bigint` values.
-   *
-   * **Details**
-   *
-   * The result follows JavaScript `%` semantics, including the sign of the
-   * dividend.
+   * Use when you want native remainder semantics, including signed remainders and
+   * a thrown division-by-zero error.
    *
    * **Gotchas**
    *

package/src/Boolean.ts

@@ -218,8 +218,8 @@ export const match: {
  *
  * **When to use**
  *
- * Use when sorting or comparing boolean values through APIs that accept an
- * ordering instance where `false` comes before `true`.
+ * Use when you need to sort or compare boolean values through APIs that accept
+ * an ordering instance where `false` comes before `true`.
  *
  * **Example** (Comparing booleans)
  *
@@ -364,7 +364,7 @@ export const and: {
 } = dual(2, (self: boolean, that: boolean): boolean => self && that)
 
 /**
- * Combines two boolean using NAND: `!(self && that)`.
+ * Combines two booleans using NAND: `!(self && that)`.
  *
  * **When to use**
  *
@@ -387,7 +387,7 @@ export const and: {
  */
 export const nand: {
   /**
-   * Combines two boolean using NAND: `!(self && that)`.
+   * Combines two booleans using NAND: `!(self && that)`.
    *
    * **When to use**
    *
@@ -410,7 +410,7 @@ export const nand: {
    */
   (that: boolean): (self: boolean) => boolean
   /**
-   * Combines two boolean using NAND: `!(self && that)`.
+   * Combines two booleans using NAND: `!(self && that)`.
    *
    * **When to use**
    *
@@ -435,7 +435,7 @@ export const nand: {
 } = dual(2, (self: boolean, that: boolean): boolean => !(self && that))
 
 /**
- * Combines two boolean using OR: `self || that`.
+ * Combines two booleans using OR: `self || that`.
  *
  * **When to use**
  *
@@ -458,7 +458,7 @@ export const nand: {
  */
 export const or: {
   /**
-   * Combines two boolean using OR: `self || that`.
+   * Combines two booleans using OR: `self || that`.
    *
    * **When to use**
    *
@@ -481,7 +481,7 @@ export const or: {
    */
   (that: boolean): (self: boolean) => boolean
   /**
-   * Combines two boolean using OR: `self || that`.
+   * Combines two booleans using OR: `self || that`.
    *
    * **When to use**
    *

package/src/Brand.ts

@@ -55,8 +55,8 @@ import * as Arr from "./Array.ts"
 import * as Option from "./Option.ts"
 import * as Result from "./Result.ts"
 import type * as Schema from "./Schema.ts"
-import * as AST from "./SchemaAST.ts"
-import type * as Issue from "./SchemaIssue.ts"
+import * as SchemaAST from "./SchemaAST.ts"
+import type * as SchemaIssue from "./SchemaIssue.ts"
 import type * as Types from "./Types.ts"
 
 const TypeId = "~effect/Brand"
@@ -128,7 +128,7 @@ export interface Constructor<in out B extends Brand<any>> {
    *
    * @internal
    */
-  checks?: readonly [AST.Check<Brand.Unbranded<B>>, ...Array<AST.Check<Brand.Unbranded<B>>>] | undefined
+  checks?: readonly [SchemaAST.Check<Brand.Unbranded<B>>, ...Array<SchemaAST.Check<Brand.Unbranded<B>>>] | undefined
 }
 
 /**
@@ -148,7 +148,7 @@ export interface Constructor<in out B extends Brand<any>> {
  * @since 4.0.0
  */
 export class BrandError {
-  constructor(issue: Issue.Issue) {
+  constructor(issue: SchemaIssue.Issue) {
     this.issue = issue
   }
   /**
@@ -168,7 +168,7 @@ export class BrandError {
    *
    * @since 4.0.0
    */
-  readonly issue: Issue.Issue
+  readonly issue: SchemaIssue.Issue
   /**
    * Human-readable rendering of the validation issue.
    *
@@ -261,8 +261,10 @@ export type Branded<A, Key extends string> = A & Brand<Key>
  * **When to use**
  *
  * Use to create nominal types that allow distinguishing between two values
- * of the same type but with different meanings. If you also want to perform
- * some validation, see {@link make} or {@link check}.
+ * of the same type but with different meanings.
+ *
+ * @see {@link make} for constructing branded values with validation.
+ * @see {@link check} for constructing branded values from schema checks.
  *
  * @category constructors
  * @since 2.0.0
@@ -281,9 +283,9 @@ export function nominal<A extends Brand<any>>(): Constructor<A> {
  *
  * **When to use**
  *
- * Use when you want validation while constructing the branded type. If you
- * don't want to perform any validation but only distinguish between two values
- * of the same type but with different meanings, see {@link nominal}.
+ * Use when you want validation while constructing the branded type.
+ *
+ * @see {@link nominal} for a brand constructor that performs no validation.
  *
  * @category constructors
  * @since 4.0.0
@@ -291,7 +293,7 @@ export function nominal<A extends Brand<any>>(): Constructor<A> {
 export function make<A extends Brand<any>>(
   filter: (unbranded: Brand.Unbranded<A>) => Schema.FilterOutput
 ): Constructor<A> {
-  return check(AST.makeFilter(filter))
+  return check(SchemaAST.makeFilter(filter))
 }
 
 /**
@@ -315,12 +317,12 @@ export function make<A extends Brand<any>>(
  */
 export function check<A extends Brand<any>>(
   ...checks: readonly [
-    AST.Check<Brand.Unbranded<A>>,
-    ...Array<AST.Check<Brand.Unbranded<A>>>
+    SchemaAST.Check<Brand.Unbranded<A>>,
+    ...Array<SchemaAST.Check<Brand.Unbranded<A>>>
   ]
 ): Constructor<A> {
   const result = (input: Brand.Unbranded<A>): Result.Result<A, BrandError> => {
-    return Result.mapError(AST.runChecks(checks, input), (issue) => new BrandError(issue)) as any
+    return Result.mapError(SchemaAST.runChecks(checks, input), (issue) => new BrandError(issue)) as any
   }
   return Object.assign((input: Brand.Unbranded<A>) => Result.getOrThrow(result(input)), {
     option: (input: Brand.Unbranded<A>) => Option.getSuccess(result(input)),

package/src/Cause.ts

@@ -688,8 +688,7 @@ export const makeInterruptReason: (fiberId?: number | undefined) => Interrupt =
  *
  * **When to use**
  *
- * Use when deciding whether a failure was entirely due to interruption and
- * can be silently discarded.
+ * Use when you need to detect failures caused only by interruption.
  *
  * **Example** (checking interrupt-only causes)
  *
@@ -981,7 +980,8 @@ export const hasFails: <E>(self: Cause<E>) => boolean = effect.hasFails
  *
  * **When to use**
  *
- * Use when you use {@link findError} if you only need the unwrapped error value `E`.
+ * Use when you need the full `Fail` reason from a `Cause`, including
+ * annotations.
  *
  * **Example** (extracting the first Fail reason)
  *
@@ -1010,8 +1010,8 @@ export const findFail: <E>(self: Cause<E>) => Result.Result<Fail<E>, Cause<never
  *
  * **When to use**
  *
- * Use when you use {@link findFail} if you need the full `Fail` reason (including
- * annotations). Use {@link findErrorOption} if you prefer an `Option`.
+ * Use when you need the first typed error value from a `Cause` as a `Result`
+ * that preserves the original cause when no match is found.
  *
  * **Example** (extracting the first error value)
  *
@@ -1038,8 +1038,8 @@ export const findError: <E>(self: Cause<E>) => Result.Result<E, Cause<never>> =
  *
  * **When to use**
  *
- * Use when this is the `Option`-returning variant of {@link findError} for code that
- * does not need the original cause returned in a failed `Result`.
+ * Use when you need the first typed error value from a `Cause` as an `Option`,
+ * discarding the original cause.
  *
  * **Example** (extracting an error as Option)
  *
@@ -1092,7 +1092,8 @@ export const hasDies: <E>(self: Cause<E>) => boolean = effect.hasDies
  *
  * **When to use**
  *
- * Use when you use {@link findDefect} if you only need the unwrapped defect value.
+ * Use when you need the full `Die` reason from a `Cause`, including
+ * annotations.
  *
  * **Example** (extracting the first Die reason)
  *
@@ -1120,8 +1121,8 @@ export const findDie: <E>(self: Cause<E>) => Result.Result<Die, Cause<E>> = effe
  *
  * **When to use**
  *
- * Use when you use {@link findDie} if you need the full `Die` reason (including
- * annotations).
+ * Use when you need the first defect value from a `Cause` as a `Result`,
+ * without the full `Die` reason.
  *
  * **Example** (extracting the first defect)
  *
@@ -1170,8 +1171,8 @@ export const hasInterrupts: <E>(self: Cause<E>) => boolean = effect.hasInterrupt
  *
  * **When to use**
  *
- * Use to extract the first interruption reason when you need its fiber ID and
- * annotations.
+ * Use when you need the first `Interrupt` reason from a `Cause`, including the
+ * fiber ID and annotations.
  *
  * **Example** (extracting the first interrupt)
  *
@@ -1198,9 +1199,8 @@ export const findInterrupt: <E>(self: Cause<E>) => Result.Result<Interrupt, Caus
  *
  * **When to use**
  *
- * Use when this always succeeds. Use {@link filterInterruptors} when you want a
- * `Result` that fails with the original cause if there are no `Interrupt`
- * reasons.
+ * Use when you need interrupting fiber IDs as a set, with absence represented
+ * as an empty set.
  *
  * **Example** (collecting interruptors)
  *
@@ -1229,8 +1229,8 @@ export const interruptors: <E>(self: Cause<E>) => ReadonlySet<number> = effect.c
  *
  * **When to use**
  *
- * Use when you use {@link interruptors} if you always want a `Set` without `Result`
- * wrapping.
+ * Use when you need absence of interrupt reasons to fail with the original
+ * cause.
  *
  * **Gotchas**
  *
@@ -1558,8 +1558,7 @@ export declare namespace Done {
  *
  * **When to use**
  *
- * Use when you need the completion signal value itself. Use {@link done}
- * when you need an `Effect` that fails with the signal.
+ * Use when you need to construct a low-level pull completion signal directly.
  *
  * @see {@link done} — create a failing `Effect` with `Done`
  *
@@ -1574,8 +1573,7 @@ export const Done: <A = void>(value?: A) => Done<A> = core.Done
  *
  * **When to use**
  *
- * Use when you use this in effect workflows that model stream or queue completion through
- * the error channel.
+ * Use when you model stream or queue completion through the error channel.
  *
  * **Example** (failing with Done)
  *
@@ -2186,8 +2184,8 @@ export class StackTrace extends Context.Service<StackTrace, StackFrame>()("effec
  *
  * **When to use**
  *
- * Use when attaching or reading the stack-frame annotation consumed by
- * interrupt-only cause rendering.
+ * Use when you need the stack-frame annotation used by interrupt-only cause
+ * rendering.
  *
  * **Details**
  *