effect 4.0.0-beta.70 → 4.0.0-beta.71

package/src/Effectable.ts

@@ -43,10 +43,18 @@ import { evaluate, makePrimitiveProto } from "./internal/core.ts"
 /**
  * Create a low-level `Effect` prototype.
  *
+ * **When to use**
+ *
+ * Use when you need to create a custom Effect-like value without extending a
+ * class, by providing a label and an evaluate function that receives the
+ * current fiber.
+ *
  * **Details**
  *
  * When the effect is evaluated, it calls `evaluate` with the current fiber.
  *
+ * @see {@link Class} for a class-based approach to defining custom Effect values
+ *
  * @category Prototypes
  * @since 4.0.0
  */
@@ -76,6 +84,12 @@ const Base: new<A, E, R>() => Effect.Effect<A, E, R> = (() => {
 /**
  * An abstract class that can be extended to create an `Effect`.
  *
+ * **When to use**
+ *
+ * Use as an abstract base class to define custom classes whose instances behave
+ * as `Effect` values.
+ *
+ * @see {@link Prototype} for a lower-level primitive approach to creating custom Effect-like values without a class
  * @category constructors
  * @since 2.0.0
  */

package/src/Encoding.ts

@@ -1,5 +1,50 @@
 /**
- * Encoding & decoding for Base64 (RFC4648), Base64Url, and Hex.
+ * Encode and decode text and bytes as Base64, Base64Url, and hexadecimal.
+ *
+ * This module covers small, synchronous format conversions where invalid input
+ * should be reported as data instead of thrown exceptions. Encode functions
+ * return strings directly; decode functions return `Result.Result` so callers
+ * can branch on success or inspect an {@link EncodingError}.
+ *
+ * **Mental model**
+ *
+ * String inputs are first converted to UTF-8 bytes with `TextEncoder`.
+ * `Uint8Array` inputs are encoded directly. Byte decoders return raw
+ * `Uint8Array` values, while `*String` decoders decode the resulting bytes as
+ * UTF-8 text with `TextDecoder`.
+ *
+ * **Common tasks**
+ *
+ * - Use {@link encodeBase64} and {@link decodeBase64} for standard padded RFC
+ *   4648 Base64
+ * - Use {@link encodeBase64Url} and {@link decodeBase64Url} for unpadded
+ *   URL-safe Base64
+ * - Use {@link encodeHex} and {@link decodeHex} for lowercase hexadecimal
+ * - Use the `*String` decoders when the encoded data represents UTF-8 text
+ * - Use {@link isEncodingError} to recognize failures returned by decode
+ *   operations
+ *
+ * **Gotchas**
+ *
+ * - Decode functions do not throw for malformed input; they return
+ *   `Result.fail` with an `EncodingError`.
+ * - Base64 decoders ignore carriage returns and line feeds before validation.
+ * - {@link decodeBase64Url} accepts padded and unpadded URL-safe input, but
+ *   {@link encodeBase64Url} emits unpadded output.
+ * - Hex encoding emits lowercase letters, and hex decoding requires an even
+ *   number of hexadecimal characters.
+ *
+ * **Example** (Decode Base64 without throwing)
+ *
+ * ```ts
+ * import { Encoding, Result } from "effect"
+ *
+ * const decoded = Encoding.decodeBase64String("aGVsbG8=")
+ *
+ * if (Result.isSuccess(decoded)) {
+ *   console.log(decoded.success)
+ * }
+ * ```
  *
  * @since 4.0.0
  */
@@ -15,6 +60,10 @@ import * as Result from "./Result.ts"
  * Type identifier stored on `EncodingError` values and used by
  * `isEncodingError`.
  *
+ * **When to use**
+ *
+ * Use to identify `EncodingError` values at runtime.
+ *
  * @category symbols
  * @since 4.0.0
  */
@@ -23,6 +72,10 @@ export const EncodingErrorTypeId = "~effect/encoding/EncodingError" as const
 /**
  * Literal type of the `EncodingErrorTypeId` marker.
  *
+ * **When to use**
+ *
+ * Use to type the marker carried by `EncodingError` values.
+ *
  * @category symbols
  * @since 4.0.0
  */
@@ -32,12 +85,18 @@ export type EncodingErrorTypeId = typeof EncodingErrorTypeId
  * Error returned when an encoding or decoding operation cannot process its
  * input.
  *
+ * **When to use**
+ *
+ * Use when you need to handle or inspect failures from encoding or decoding
+ * operations.
+ *
  * **Details**
  *
  * The error records whether the failure happened during encoding or decoding,
  * which encoding module reported it, the original input, and a human-readable
  * message.
  *
+ * @see {@link isEncodingError} for checking whether a value is an EncodingError
  * @category constructors
  * @since 4.0.0
  */
@@ -50,6 +109,10 @@ export class EncodingError extends Data.TaggedError("EncodingError")<{
   /**
    * Marks this value as an encoding or decoding error for runtime guards.
    *
+   * **When to use**
+   *
+   * Use to identify `EncodingError` instances through `isEncodingError`.
+   *
    * @since 4.0.0
    */
   readonly [EncodingErrorTypeId]: EncodingErrorTypeId = EncodingErrorTypeId
@@ -58,11 +121,19 @@ export class EncodingError extends Data.TaggedError("EncodingError")<{
 /**
  * Checks whether a value is an `EncodingError`.
  *
+ * **When to use**
+ *
+ * Use to narrow an unknown value before handling it as an `EncodingError` from
+ * encoding or decoding code.
+ *
  * **Details**
  *
  * Returns `true` when the value carries the `EncodingErrorTypeId` marker and
  * narrows the value to `EncodingError`.
  *
+ * @see {@link EncodingError} for the structured error produced by failed
+ * encoding and decoding operations
+ *
  * @category guards
  * @since 4.0.0
  */
@@ -75,6 +146,17 @@ export const isEncodingError = (u: unknown): u is EncodingError => hasProperty(u
 /**
  * Encodes the given value into a base64 (RFC4648) `string`.
  *
+ * **When to use**
+ *
+ * Use to encode text or bytes as a standard padded Base64 string for storage or
+ * transport.
+ *
+ * **Details**
+ *
+ * String inputs are encoded as UTF-8 bytes before Base64 encoding.
+ * `Uint8Array` inputs are encoded directly. The output uses the standard
+ * RFC4648 alphabet with `=` padding.
+ *
  * **Example** (Encoding Base64 strings and bytes)
  *
  * ```ts
@@ -88,6 +170,10 @@ export const isEncodingError = (u: unknown): u is EncodingError => hasProperty(u
  * console.log(Encoding.encodeBase64(bytes)) // "SGVsbG8="
  * ```
  *
+ * @see {@link decodeBase64} for decoding standard Base64 to bytes
+ * @see {@link decodeBase64String} for decoding standard Base64 to UTF-8 text
+ * @see {@link encodeBase64Url} for URL-safe unpadded Base64 output
+ *
  * @category encoding
  * @since 2.0.0
  */
@@ -97,6 +183,11 @@ export const encodeBase64: (input: Uint8Array | string) => string = (input) =>
 /**
  * Decodes a base64 (RFC4648) string into bytes.
  *
+ * **When to use**
+ *
+ * Use to decode a standard padded Base64 string into bytes without throwing on
+ * invalid input.
+ *
  * **Details**
  *
  * Returns `Result.succeed` with a `Uint8Array` when decoding succeeds, or
@@ -172,6 +263,11 @@ export const decodeBase64 = (str: string): Result.Result<Uint8Array, EncodingErr
 /**
  * Decodes a base64 (RFC4648) string into a UTF-8 string.
  *
+ * **When to use**
+ *
+ * Use to decode a standard padded Base64 string into UTF-8 text without
+ * throwing on invalid input.
+ *
  * **Details**
  *
  * Returns `Result.succeed` with the decoded text when decoding succeeds, or
@@ -200,6 +296,17 @@ export const decodeBase64String = (str: string) => Result.map(decodeBase64(str),
 /**
  * Encodes the given value into a base64 (URL) `string`.
  *
+ * **When to use**
+ *
+ * Use to encode text or bytes as an unpadded Base64Url string for contexts that
+ * require the URL-safe alphabet.
+ *
+ * **Details**
+ *
+ * String inputs are encoded as UTF-8 bytes before Base64Url encoding.
+ * `Uint8Array` inputs are encoded directly. The output removes `=` padding and
+ * replaces `+` with `-` and `/` with `_`.
+ *
  * **Example** (Encoding URL-safe Base64)
  *
  * ```ts
@@ -212,6 +319,10 @@ export const decodeBase64String = (str: string) => Result.map(decodeBase64(str),
  * console.log(Encoding.encodeBase64Url(bytes)) // "SGVsbG8_"
  * ```
  *
+ * @see {@link decodeBase64Url} for decoding URL-safe Base64 to bytes
+ * @see {@link decodeBase64UrlString} for decoding URL-safe Base64 to UTF-8 text
+ * @see {@link encodeBase64} for standard padded Base64 output
+ *
  * @category encoding
  * @since 2.0.0
  */
@@ -221,6 +332,11 @@ export const encodeBase64Url: (input: Uint8Array | string) => string = (input) =
 /**
  * Decodes a URL-safe base64 string into bytes.
  *
+ * **When to use**
+ *
+ * Use to decode padded or unpadded Base64Url text into bytes without throwing
+ * on invalid input.
+ *
  * **Details**
  *
  * Returns `Result.succeed` with a `Uint8Array` when decoding succeeds, or
@@ -277,6 +393,11 @@ export const decodeBase64Url = (str: string): Result.Result<Uint8Array, Encoding
 /**
  * Decodes a URL-safe base64 string into a UTF-8 string.
  *
+ * **When to use**
+ *
+ * Use to decode padded or unpadded Base64Url text into UTF-8 text without
+ * throwing on invalid input.
+ *
  * **Details**
  *
  * Returns `Result.succeed` with the decoded text when decoding succeeds, or
@@ -306,6 +427,10 @@ export const decodeBase64UrlString = (str: string) => Result.map(decodeBase64Url
 /**
  * Encodes the given value into a hex `string`.
  *
+ * **When to use**
+ *
+ * Use to encode text or bytes as lowercase hexadecimal text.
+ *
  * **Example** (Encoding hex strings and bytes)
  *
  * ```ts
@@ -328,6 +453,10 @@ export const encodeHex: (input: Uint8Array | string) => string = (input) =>
 /**
  * Decodes a hexadecimal string into bytes.
  *
+ * **When to use**
+ *
+ * Use to decode hexadecimal text into bytes without throwing on invalid input.
+ *
  * **Details**
  *
  * Returns `Result.succeed` with a `Uint8Array` when decoding succeeds, or
@@ -386,6 +515,11 @@ export const decodeHex = (str: string): Result.Result<Uint8Array, EncodingError>
 /**
  * Decodes a hexadecimal string into a UTF-8 string.
  *
+ * **When to use**
+ *
+ * Use to decode hexadecimal text into UTF-8 text without throwing on invalid
+ * input.
+ *
  * **Details**
  *
  * Returns `Result.succeed` with the decoded text when decoding succeeds, or

package/src/Equal.ts

@@ -79,7 +79,7 @@ import { hasProperty } from "./Predicate.ts"
  *
  * **When to use**
  *
- * - Use it as the computed property key when implementing custom equality on a
+ * Use when you use it as the computed property key when implementing custom equality on a
  *   class or object literal.
  * - Use it to check manually whether an object carries an equality method (prefer
  *   {@link isEqual} instead).
@@ -118,7 +118,7 @@ export const symbol = "~effect/interfaces/Equal"
  *
  * **When to use**
  *
- * - When you need value-based equality for a class (e.g. domain IDs,
+ * Use when when you need value-based equality for a class (e.g. domain IDs,
  *   coordinates, money values).
  * - When your type will be stored in `HashMap` or `HashSet`.
  * - When the default structural comparison is too broad or too narrow for
@@ -174,7 +174,7 @@ export interface Equal extends Hash.Hash {
  *
  * **When to use**
  *
- * - As the default equality check throughout Effect code.
+ * Use when as the default equality check throughout Effect code.
  * - In data-level assertions or conditional logic where structural comparison
  *   is needed.
  * - In its curried (single-argument) form to build reusable predicates.
@@ -462,7 +462,7 @@ const compareSets = makeCompareSet(compareBoth)
  *
  * **When to use**
  *
- * - To branch on whether a value supports custom equality before calling
+ * Use when to branch on whether a value supports custom equality before calling
  *   its `[Equal.symbol]` method directly.
  * - In generic utility code that needs to distinguish `Equal` implementors
  *   from plain values.
@@ -506,7 +506,7 @@ export const isEqual = (u: unknown): u is Equal => hasProperty(u, symbol)
  *
  * **When to use**
  *
- * - When an API (e.g. `Array.dedupeWith`, `Equivalence.mapInput`) requires an
+ * Use when when an API (e.g. `Array.dedupeWith`, `Equivalence.mapInput`) requires an
  *   `Equivalence` and you want to reuse `Equal.equals`.
  *
  * **Details**
@@ -536,7 +536,7 @@ export const asEquivalence: <A>() => Equivalence<A> = () => equals
  *
  * **When to use**
  *
- * - When you have a plain object or array that should be compared by identity
+ * Use when when you have a plain object or array that should be compared by identity
  *   (reference), not by contents.
  * - When you want to preserve the original object unchanged and get a new
  *   reference-equal handle.
@@ -581,7 +581,7 @@ export const byReference = <T extends object>(obj: T): T => byReferenceUnsafe(ne
  *
  * **When to use**
  *
- * - When you want reference equality semantics and can accept that the
+ * Use when when you want reference equality semantics and can accept that the
  *   original object is **permanently** modified.
  * - When proxy overhead is unacceptable (hot paths, large collections).
  *

package/src/Equivalence.ts

@@ -45,9 +45,9 @@
  *
  * ## See also
  *
- * - {@link Equal} - For structural equality (can convert to Equivalence)
- * - {@link Array_.dedupeWith} - Remove duplicates using an equivalence
- * - {@link Chunk} - Collections that use equivalences for operations
+ * - `Equal` - For structural equality (can convert to Equivalence)
+ * - `Array.dedupeWith` - Remove duplicates using an equivalence
+ * - `Chunk` - Collections that use equivalences for operations
  *
  * @since 2.0.0
  */
@@ -60,7 +60,7 @@ import * as Reducer from "./Reducer.ts"
  *
  * **When to use**
  *
- * - Use as a type annotation for equivalence functions
+ * Use as a type annotation for equivalence functions
  * - Use when implementing custom equivalence logic
  * - Use when working with collection operations that require equivalence relations
  *
@@ -109,7 +109,7 @@ export type Equivalence<in A> = (self: A, that: A) => boolean
  *
  * **When to use**
  *
- * - Rarely needed in application code
+ * Use when rarely needed in application code
  * - Use primarily for internal type system operations and HKT (Higher-Kinded Types) abstractions
  * - Use when working with generic type constructors that require type lambdas
  *
@@ -148,7 +148,7 @@ export interface EquivalenceTypeLambda extends TypeLambda {
  *
  * **When to use**
  *
- * - Use when you need a custom equivalence that is not just strict equality
+ * Use when you need a custom equivalence that is not just strict equality
  * - Use when creating equivalences for complex types with custom comparison logic
  * - Use when you want the performance benefit of reference equality optimization
  *
@@ -202,7 +202,7 @@ const isStrictEquivalent = (x: unknown, y: unknown) => x === y
  *
  * **When to use**
  *
- * - Use for primitive types where `===` is appropriate
+ * Use when you need primitive types where `===` is appropriate
  * - Use when you need reference equality for objects
  * - Use as a building block for more complex equivalences via {@link mapInput} or {@link combine}
  * - Use when performance is critical and you do not need structural equality
@@ -243,7 +243,7 @@ const isStrictEquivalent = (x: unknown, y: unknown) => x === y
  * ```
  *
  * @see {@link make}
- * @see {@link Equal} for structural equality
+ * @see `Equal` for structural equality
  * @category constructors
  * @since 4.0.0
  */
@@ -252,6 +252,10 @@ export const strictEqual: <A>() => Equivalence<A> = () => isStrictEquivalent
 /**
  * An `Equivalence` instance for strings using strict equality (`===`).
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for string equality.
+ *
  * **Example** (Comparing strings)
  *
  * ```ts
@@ -269,6 +273,11 @@ export const String: Equivalence<string> = isStrictEquivalent
 /**
  * An `Equivalence` instance for numbers.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for numeric equality where
+ * `NaN` equals `NaN`.
+ *
  * **Details**
  *
  * `NaN` is considered equal to `NaN`.
@@ -293,6 +302,10 @@ export const Number: Equivalence<number> = make((self, that) =>
 /**
  * An `Equivalence` instance for booleans using strict equality (`===`).
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for boolean equality.
+ *
  * **Example** (Comparing booleans)
  *
  * ```ts
@@ -310,6 +323,10 @@ export const Boolean: Equivalence<boolean> = isStrictEquivalent
 /**
  * An `Equivalence` instance for bigints using strict equality (`===`).
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Equivalence` instance for `bigint` equality.
+ *
  * **Example** (Comparing bigints)
  *
  * ```ts
@@ -329,7 +346,7 @@ export const BigInt: Equivalence<bigint> = isStrictEquivalent
  *
  * **When to use**
  *
- * - Use when you need to combine exactly two equivalences
+ * Use when you need to combine exactly two equivalences
  * - Use when building complex equivalences from simpler ones
  * - Use when you want both conditions to be satisfied
  *
@@ -381,7 +398,7 @@ export const combine: {
    *
    * **When to use**
    *
-   * - Use when you need to combine exactly two equivalences
+   * Use when you need to combine exactly two equivalences
    * - Use when building complex equivalences from simpler ones
    * - Use when you want both conditions to be satisfied
    *
@@ -433,7 +450,7 @@ export const combine: {
    *
    * **When to use**
    *
-   * - Use when you need to combine exactly two equivalences
+   * Use when you need to combine exactly two equivalences
    * - Use when building complex equivalences from simpler ones
    * - Use when you want both conditions to be satisfied
    *
@@ -487,7 +504,7 @@ export const combine: {
  *
  * **When to use**
  *
- * - Use when you need to combine three or more equivalences
+ * Use when you need to combine three or more equivalences
  * - Use when you have a dynamic collection of equivalences to combine
  * - Use when building equivalences from arrays or iterables
  * - Prefer this over multiple `combine` calls when you have many equivalences
@@ -564,7 +581,7 @@ export const combineAll = <A>(collection: Iterable<Equivalence<A>>): Equivalence
  *
  * **When to use**
  *
- * - Use when you need an equivalence for a complex type based on a single property
+ * Use when you need an equivalence for a complex type based on a single property
  * - Use when you want to normalize values before comparison, such as case-insensitive strings
  * - Use when creating equivalences that focus on specific fields of objects
  * - Use as a building block for creating equivalences via {@link combine} or {@link combineAll}
@@ -627,7 +644,7 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * - Use when you need an equivalence for a complex type based on a single property
+   * Use when you need an equivalence for a complex type based on a single property
    * - Use when you want to normalize values before comparison, such as case-insensitive strings
    * - Use when creating equivalences that focus on specific fields of objects
    * - Use as a building block for creating equivalences via {@link combine} or {@link combineAll}
@@ -690,7 +707,7 @@ export const mapInput: {
    *
    * **When to use**
    *
-   * - Use when you need an equivalence for a complex type based on a single property
+   * Use when you need an equivalence for a complex type based on a single property
    * - Use when you want to normalize values before comparison, such as case-insensitive strings
    * - Use when creating equivalences that focus on specific fields of objects
    * - Use as a building block for creating equivalences via {@link combine} or {@link combineAll}
@@ -758,7 +775,7 @@ export const mapInput: {
  *
  * **When to use**
  *
- * - Use when comparing tuples with different types at each position
+ * Use when comparing tuples with different types at each position
  * - Use when you need different equivalence logic for each tuple element
  * - Use when working with fixed-length tuples instead of arrays
  * - Prefer this over `Array` when you have a known tuple structure with different types
@@ -811,8 +828,6 @@ export const mapInput: {
  * ) // true
  * ```
  *
- * @see {@link Array_}
- * @see {@link Struct}
  * @category combinators
  * @since 4.0.0
  */
@@ -852,7 +867,7 @@ export {
    *
    * **When to use**
    *
-   * - Use when comparing arrays with homogeneous element types
+   * Use when comparing arrays with homogeneous element types
    * - Use when all elements should use the same equivalence logic
    * - Use when working with variable-length arrays instead of fixed tuples
    * - Prefer this over `Tuple` when you have arrays of the same type
@@ -907,7 +922,7 @@ export {
  *
  * **When to use**
  *
- * - Use when comparing objects with known, fixed property names
+ * Use when comparing objects with known, fixed property names
  * - Use when you need different equivalence logic for different properties
  * - Use when working with struct or interface types with specific fields
  * - Prefer this over `Record` when you have a fixed set of known properties
@@ -990,7 +1005,7 @@ export function Struct<R extends Record<string, Equivalence<any>>>(
  *
  * **When to use**
  *
- * - Use when comparing objects with dynamic or unknown property names
+ * Use when comparing objects with dynamic or unknown property names
  * - Use when all property values should use the same equivalence logic
  * - Use when working with record or dictionary types
  * - Prefer this over `Struct` when you have variable properties or need to compare all properties uniformly
@@ -1037,8 +1052,6 @@ export function Struct<R extends Record<string, Equivalence<any>>>(
  * console.log(numberRecordEq(scores1, scores3)) // false
  * ```
  *
- * @see {@link Struct}
- * @see {@link Array_}
  * @category combinators
  * @since 4.0.0
  */
@@ -1064,7 +1077,7 @@ export function Record<A>(value: Equivalence<A>): Equivalence<Record<PropertyKey
  *
  * **When to use**
  *
- * - Use when you need to combine multiple equivalences from a collection using reducer patterns
+ * Use when you need to combine multiple equivalences from a collection using reducer patterns
  * - Use when implementing fold operations over collections of equivalences
  * - Use when working with reducers that operate on equivalences
  *
@@ -1109,6 +1122,10 @@ export function makeReducer<A>() {
 /**
  * An `Equivalence` instance for `Date` objects that compares their `getTime()` values using `Equivalence.Number`.
  *
+ * **When to use**
+ *
+ * Use when comparing `Date` values by their millisecond timestamp.
+ *
  * **Details**
  *
  * Different `Date` instances that represent the same millisecond timestamp are equivalent. Because `Equivalence.Number`
@@ -1143,9 +1160,9 @@ export function makeReducer<A>() {
  * console.log(Equivalence.Date(d1, d2)) // true (same time value)
  * ```
  *
- * @see {@link Number}
- * @see {@link mapInput}
- * @see {@link strictEqual}
+ * @see {@link Number} for the numeric equivalence applied to each `Date#getTime()` result
+ * @see {@link mapInput} for deriving an equivalence by mapping inputs before comparison
+ * @see {@link strictEqual} for reference equality when two values must be the same object
  * @category instances
  * @since 2.0.0
  */