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

package/src/MutableRef.ts

@@ -109,7 +109,7 @@ const MutableRefProto: Omit<MutableRef<unknown>, "current"> = {
  *
  * **When to use**
  *
- * Use to create a synchronous mutable reference initialized with a value.
+ * Use to create a synchronous `MutableRef` initialized with a value.
  *
  * **Example** (Creating mutable refs)
  *
@@ -146,8 +146,8 @@ export const make = <T>(value: T): MutableRef<T> => {
  *
  * **When to use**
  *
- * Use to replace a value only when the current value still matches an expected
- * value.
+ * Use to replace a `MutableRef` value only when the current value still matches
+ * an expected value.
  *
  * **Example** (Comparing and setting values)
  *
@@ -189,8 +189,8 @@ export const compareAndSet: {
    *
    * **When to use**
    *
-   * Use to replace a value only when the current value still matches an expected
-   * value.
+   * Use to replace a `MutableRef` value only when the current value still matches
+   * an expected value.
    *
    * **Example** (Comparing and setting values)
    *
@@ -232,8 +232,8 @@ export const compareAndSet: {
    *
    * **When to use**
    *
-   * Use to replace a value only when the current value still matches an expected
-   * value.
+   * Use to replace a `MutableRef` value only when the current value still matches
+   * an expected value.
    *
    * **Example** (Comparing and setting values)
    *
@@ -284,8 +284,8 @@ export const compareAndSet: {
  *
  * **When to use**
  *
- * Use to decrement a numeric reference in place when you want the same
- * reference back.
+ * Use when you need an in-place `MutableRef` decrement that returns the same
+ * `MutableRef`.
  *
  * **Example** (Decrementing numeric refs)
  *
@@ -321,7 +321,8 @@ export const decrement = (self: MutableRef<number>): MutableRef<number> => updat
  *
  * **When to use**
  *
- * Use to decrement a numeric reference and immediately read the updated value.
+ * Use to decrement a numeric `MutableRef` and immediately read the updated
+ * value.
  *
  * **Example** (Decrementing and reading refs)
  *
@@ -357,7 +358,7 @@ export const decrementAndGet = (self: MutableRef<number>): number => updateAndGe
  *
  * **When to use**
  *
- * Use to read the current value without mutating the reference.
+ * Use to read the current `MutableRef` value without mutating it.
  *
  * **Example** (Reading current values)
  *
@@ -391,7 +392,7 @@ export const get = <T>(self: MutableRef<T>): T => self.current
  *
  * **When to use**
  *
- * Use to read the current numeric value before decrementing it.
+ * Use to read the current numeric `MutableRef` value before decrementing it.
  *
  * **Example** (Reading before decrementing)
  *
@@ -428,7 +429,7 @@ export const getAndDecrement = (self: MutableRef<number>): number => getAndUpdat
  *
  * **When to use**
  *
- * Use to read the current numeric value before incrementing it.
+ * Use to read the current numeric `MutableRef` value before incrementing it.
  *
  * **Example** (Reading before incrementing)
  *
@@ -473,7 +474,8 @@ export const getAndIncrement = (self: MutableRef<number>): number => getAndUpdat
  *
  * **When to use**
  *
- * Use to replace the current value while keeping the previous value.
+ * Use to replace the current `MutableRef` value while keeping the previous
+ * value.
  *
  * **Example** (Reading before setting)
  *
@@ -513,7 +515,8 @@ export const getAndSet: {
    *
    * **When to use**
    *
-   * Use to replace the current value while keeping the previous value.
+   * Use to replace the current `MutableRef` value while keeping the previous
+   * value.
    *
    * **Example** (Reading before setting)
    *
@@ -553,7 +556,8 @@ export const getAndSet: {
    *
    * **When to use**
    *
-   * Use to replace the current value while keeping the previous value.
+   * Use to replace the current `MutableRef` value while keeping the previous
+   * value.
    *
    * **Example** (Reading before setting)
    *
@@ -603,7 +607,8 @@ export const getAndSet: {
  *
  * **When to use**
  *
- * Use to transform the current value while keeping the previous value.
+ * Use to transform the current `MutableRef` value while keeping the previous
+ * value.
  *
  * **Example** (Reading before updating)
  *
@@ -650,7 +655,8 @@ export const getAndUpdate: {
    *
    * **When to use**
    *
-   * Use to transform the current value while keeping the previous value.
+   * Use to transform the current `MutableRef` value while keeping the previous
+   * value.
    *
    * **Example** (Reading before updating)
    *
@@ -697,7 +703,8 @@ export const getAndUpdate: {
    *
    * **When to use**
    *
-   * Use to transform the current value while keeping the previous value.
+   * Use to transform the current `MutableRef` value while keeping the previous
+   * value.
    *
    * **Example** (Reading before updating)
    *
@@ -748,8 +755,8 @@ export const getAndUpdate: {
  *
  * **When to use**
  *
- * Use to increment a numeric reference in place when you want the same
- * reference back.
+ * Use when you need an in-place `MutableRef` increment that returns the same
+ * `MutableRef`.
  *
  * **Example** (Incrementing numeric refs)
  *
@@ -788,7 +795,8 @@ export const increment = (self: MutableRef<number>): MutableRef<number> => updat
  *
  * **When to use**
  *
- * Use to increment a numeric reference and immediately read the updated value.
+ * Use to increment a numeric `MutableRef` and immediately read the updated
+ * value.
  *
  * **Example** (Incrementing and reading refs)
  *
@@ -828,8 +836,8 @@ export const incrementAndGet = (self: MutableRef<number>): number => updateAndGe
  *
  * **When to use**
  *
- * Use to replace the current value in place when you want the same reference
- * back.
+ * Use when you need an in-place `MutableRef` replacement that returns the same
+ * `MutableRef`.
  *
  * **Example** (Setting values)
  *
@@ -873,8 +881,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the current value in place when you want the same reference
-   * back.
+   * Use when you need an in-place `MutableRef` replacement that returns the same
+   * `MutableRef`.
    *
    * **Example** (Setting values)
    *
@@ -918,8 +926,8 @@ export const set: {
    *
    * **When to use**
    *
-   * Use to replace the current value in place when you want the same reference
-   * back.
+   * Use when you need an in-place `MutableRef` replacement that returns the same
+   * `MutableRef`.
    *
    * **Example** (Setting values)
    *
@@ -971,7 +979,8 @@ export const set: {
  *
  * **When to use**
  *
- * Use to replace the current value and immediately read the replacement.
+ * Use to replace the current `MutableRef` value and immediately read the
+ * replacement.
  *
  * **Example** (Setting and reading values)
  *
@@ -1011,7 +1020,8 @@ export const setAndGet: {
    *
    * **When to use**
    *
-   * Use to replace the current value and immediately read the replacement.
+   * Use to replace the current `MutableRef` value and immediately read the
+   * replacement.
    *
    * **Example** (Setting and reading values)
    *
@@ -1051,7 +1061,8 @@ export const setAndGet: {
    *
    * **When to use**
    *
-   * Use to replace the current value and immediately read the replacement.
+   * Use to replace the current `MutableRef` value and immediately read the
+   * replacement.
    *
    * **Example** (Setting and reading values)
    *
@@ -1100,8 +1111,8 @@ export const setAndGet: {
  *
  * **When to use**
  *
- * Use to transform the current value in place when you want the same reference
- * back.
+ * Use when you need an in-place `MutableRef` value transformation that returns
+ * the same `MutableRef`.
  *
  * **Example** (Updating values)
  *
@@ -1150,8 +1161,8 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to transform the current value in place when you want the same reference
-   * back.
+   * Use when you need an in-place `MutableRef` value transformation that returns
+   * the same `MutableRef`.
    *
    * **Example** (Updating values)
    *
@@ -1200,8 +1211,8 @@ export const update: {
    *
    * **When to use**
    *
-   * Use to transform the current value in place when you want the same reference
-   * back.
+   * Use when you need an in-place `MutableRef` value transformation that returns
+   * the same `MutableRef`.
    *
    * **Example** (Updating values)
    *
@@ -1255,7 +1266,8 @@ export const update: {
  *
  * **When to use**
  *
- * Use to transform the current value and immediately read the updated value.
+ * Use to transform the current `MutableRef` value and immediately read the
+ * updated value.
  *
  * **Example** (Updating and reading values)
  *
@@ -1306,7 +1318,8 @@ export const updateAndGet: {
    *
    * **When to use**
    *
-   * Use to transform the current value and immediately read the updated value.
+   * Use to transform the current `MutableRef` value and immediately read the
+   * updated value.
    *
    * **Example** (Updating and reading values)
    *
@@ -1357,7 +1370,8 @@ export const updateAndGet: {
    *
    * **When to use**
    *
-   * Use to transform the current value and immediately read the updated value.
+   * Use to transform the current `MutableRef` value and immediately read the
+   * updated value.
    *
    * **Example** (Updating and reading values)
    *
@@ -1413,8 +1427,8 @@ export const updateAndGet: {
  *
  * **When to use**
  *
- * Use to flip a boolean reference in place when you want the same reference
- * back.
+ * Use when you need an in-place boolean `MutableRef` toggle that returns the
+ * same `MutableRef`.
  *
  * **Example** (Toggling boolean refs)
  *

package/src/Newtype.ts

@@ -169,8 +169,8 @@ export declare namespace Newtype {
  *
  * **When to use**
  *
- * Use when you only need to read the inner value and do not need to wrap
- * new values. For both wrapping and unwrapping, prefer {@link makeIso}.
+ * Use when you need the carrier value from an existing newtype without
+ * constructing a new newtype value at the same call site.
  *
  * **Details**
  *
@@ -237,7 +237,8 @@ export function makeIso<N extends Newtype.Any>(): Optic.Iso<N, Newtype.Carrier<N
  *
  * **When to use**
  *
- * Use when you need to compare two newtype values for equality.
+ * Use when you need equality for newtype-wrapped values to behave like
+ * equality for the wrapped carrier value, without manually unwrapping.
  *
  * **Details**
  *
@@ -272,7 +273,8 @@ export const makeEquivalence: <N extends Newtype.Any>(
  *
  * **When to use**
  *
- * Use when you need to sort or compare newtype values.
+ * Use when you need to sort newtype-wrapped values according to the ordering
+ * of the wrapped carrier value, without manually unwrapping.
  *
  * **Details**
  *
@@ -303,7 +305,8 @@ export const makeOrder: <N extends Newtype.Any>(order: Order.Order<Newtype.Carri
  *
  * **When to use**
  *
- * Use when you need to combine newtype values.
+ * Use when you need to combine newtype-wrapped values with the carrier's
+ * combining logic, without manually unwrapping.
  *
  * **Details**
  *
@@ -338,8 +341,8 @@ export const makeCombiner: <N extends Newtype.Any>(
  *
  * **When to use**
  *
- * Use when you need to fold or reduce over a collection of newtype
- * values.
+ * Use when you need to reduce a collection of newtype-wrapped values with the
+ * carrier's reducer, without manually unwrapping.
  *
  * **Details**
  *

package/src/Number.ts

@@ -393,12 +393,16 @@ export const divide: {
 )
 
 /**
- * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
+ * Divides two `number` values without returning an `Option`.
  *
  * **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 `number` values where the divisor is known to be non-zero and
+ * a plain `number` result is preferred over handling `Option.none`.
+ *
+ * **Gotchas**
+ *
+ * Throws a `RangeError` if the divisor is `0`.
  *
  * **Example** (Dividing numbers unsafely)
  *
@@ -417,12 +421,16 @@ export const divide: {
  */
 export const divideUnsafe: {
   /**
-   * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
+   * Divides two `number` values without returning an `Option`.
    *
    * **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 `number` values where the divisor is known to be non-zero and
+   * a plain `number` result is preferred over handling `Option.none`.
+   *
+   * **Gotchas**
+   *
+   * Throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Dividing numbers unsafely)
    *
@@ -441,12 +449,16 @@ export const divideUnsafe: {
    */
   (that: number): (self: number) => number
   /**
-   * Provides an unsafe division operation on `number`s that throws a `RangeError` if the divisor is `0`.
+   * Divides two `number` values without returning an `Option`.
    *
    * **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 `number` values where the divisor is known to be non-zero and
+   * a plain `number` result is preferred over handling `Option.none`.
+   *
+   * **Gotchas**
+   *
+   * Throws a `RangeError` if the divisor is `0`.
    *
    * **Example** (Dividing numbers unsafely)
    *
@@ -517,8 +529,8 @@ export const decrement = (n: number): number => n - 1
  *
  * **When to use**
  *
- * Use when sorting or comparing numbers through APIs that accept an ordering
- * instance.
+ * Use when you need to sort or compare numbers through APIs that accept an
+ * ordering instance.
  *
  * **Example** (Comparing numbers)
  *

package/src/Optic.ts

@@ -100,8 +100,8 @@ import * as Option from "./Option.ts"
 import * as Predicate from "./Predicate.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 * as Struct from "./Struct.ts"
 import type { IsUnion } from "./Types.ts"
 
@@ -152,12 +152,12 @@ export interface Iso<in out S, in out A> extends Lens<S, A>, Prism<S, A> {}
  *
  * **When to use**
  *
- * Use when you have two pure functions that form a lossless round-trip between `S`
- *   and `A`.
+ * Use when you have two pure conversion functions that preserve all information
+ * between `S` and `A`.
  *
  * **Details**
  *
- * - The returned optic can be composed with any other optic.
+ * The returned optic can be composed with any other optic.
  *
  * **Example** (wrapping/unwrapping a branded type)
  *
@@ -192,9 +192,8 @@ export function makeIso<S, A>(get: (s: S) => A, set: (a: A) => S): Iso<S, A> {
  *
  * **When to use**
  *
- * 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}).
+ * Use when you always have a value to read and need the original `S` to produce
+ * the updated whole, unlike `Iso`.
  *
  * **Details**
  *
@@ -396,7 +395,7 @@ export function makePrism<S, A>(getResult: (s: S) => Result.Result<A, string>, s
  * @category constructors
  * @since 4.0.0
  */
-export function fromChecks<T>(...checks: readonly [AST.Check<T>, ...Array<AST.Check<T>>]): Prism<T, T> {
+export function fromChecks<T>(...checks: readonly [SchemaAST.Check<T>, ...Array<SchemaAST.Check<T>>]): Prism<T, T> {
   return make(new CheckNode(checks))
 }
 
@@ -480,9 +479,9 @@ class PathNode {
 
 class CheckNode<T> {
   readonly _tag = "CheckNode"
-  readonly checks: readonly [AST.Check<T>, ...Array<AST.Check<T>>]
+  readonly checks: readonly [SchemaAST.Check<T>, ...Array<SchemaAST.Check<T>>]
 
-  constructor(checks: readonly [AST.Check<T>, ...Array<AST.Check<T>>]) {
+  constructor(checks: readonly [SchemaAST.Check<T>, ...Array<SchemaAST.Check<T>>]) {
     this.checks = checks
   }
 }
@@ -733,8 +732,11 @@ export interface Optional<in out S, in out A> {
    *
    * @see {@link fromChecks} — standalone prism from checks
    */
-  check<S, A>(this: Prism<S, A>, ...checks: readonly [AST.Check<A>, ...Array<AST.Check<A>>]): Prism<S, A>
-  check<S, A>(this: Optional<S, A>, ...checks: readonly [AST.Check<A>, ...Array<AST.Check<A>>]): Optional<S, A>
+  check<S, A>(this: Prism<S, A>, ...checks: readonly [SchemaAST.Check<A>, ...Array<SchemaAST.Check<A>>]): Prism<S, A>
+  check<S, A>(
+    this: Optional<S, A>,
+    ...checks: readonly [SchemaAST.Check<A>, ...Array<SchemaAST.Check<A>>]
+  ): Optional<S, A>
 
   /**
    * Narrows the focus to a subtype `B` using a type guard.
@@ -805,11 +807,11 @@ export interface Optional<in out S, in out A> {
    *
    * @see `.refine()` — for arbitrary type guards
    */
-  tag<S, A extends { readonly _tag: AST.LiteralValue }, Tag extends A["_tag"]>(
+  tag<S, A extends { readonly _tag: SchemaAST.LiteralValue }, Tag extends A["_tag"]>(
     this: Prism<S, A>,
     tag: Tag
   ): Prism<S, Extract<A, { readonly _tag: Tag }>>
-  tag<S, A extends { readonly _tag: AST.LiteralValue }, Tag extends A["_tag"]>(
+  tag<S, A extends { readonly _tag: SchemaAST.LiteralValue }, Tag extends A["_tag"]>(
     this: Optional<S, A>,
     tag: Tag
   ): Optional<S, Extract<A, { readonly _tag: Tag }>>
@@ -1026,7 +1028,8 @@ export interface Optional<in out S, in out A> {
  *
  * **When to use**
  *
- * Use when both reading and writing can fail.
+ * Use when you need an optic for a focus that may be missing on read and may
+ * reject updates on write.
  *
  * **Details**
  *
@@ -1159,11 +1162,11 @@ class OptionalImpl<S, A> implements Optional<S, A> {
       )
     )
   }
-  check(...checks: readonly [AST.Check<any>, ...Array<AST.Check<any>>]): any {
+  check(...checks: readonly [SchemaAST.Check<any>, ...Array<SchemaAST.Check<any>>]): any {
     return make(compose(this.node, new CheckNode(checks)))
   }
   refine<B extends A>(refinement: (a: A) => a is B, annotations?: Schema.Annotations.Filter): any {
-    return make(compose(this.node, new CheckNode([AST.makeFilterByGuard(refinement, annotations)])))
+    return make(compose(this.node, new CheckNode([SchemaAST.makeFilterByGuard(refinement, annotations)])))
   }
   tag(tag: string): any {
     return make(
@@ -1376,7 +1379,7 @@ const recur = memoize((node: Node): Op => {
     case "CheckNode":
       return {
         _tag: "PrismNode",
-        get: (s: any) => Result.mapError(AST.runChecks(node.checks, s), String),
+        get: (s: any) => Result.mapError(SchemaAST.runChecks(node.checks, s), String),
         set: identity
       }
     case "CompositionNode": {
@@ -1520,7 +1523,7 @@ const identityIso = make(identityNode)
  *
  * **When to use**
  *
- * Use when starting an optic chain with a focus on the whole value.
+ * Use when you need to start an optic chain with a focus on the whole value.
  *
  * **Details**
  *
@@ -1775,6 +1778,6 @@ export function failure<A, E>(): Prism<Result.Result<A, E>, E> {
 function runRefinement<T extends E, E>(
   refinement: (e: E) => e is T,
   annotations?: Schema.Annotations.Filter
-): (e: E) => Result.Result<T, Issue.Issue> {
-  return (e) => AST.runChecks([AST.makeFilterByGuard(refinement, annotations)], e) as any
+): (e: E) => Result.Result<T, SchemaIssue.Issue> {
+  return (e) => SchemaAST.runChecks([SchemaAST.makeFilterByGuard(refinement, annotations)], e) as any
 }