effect 4.0.0-beta.70 → 4.0.0-beta.72

package/src/Effectable.ts

@@ -43,11 +43,19 @@ 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.
  *
- * @category Prototypes
+ * @see {@link Class} for a class-based approach to defining custom Effect values
+ *
+ * @category prototypes
  * @since 4.0.0
  */
 export const Prototype = <A extends Effect.Effect<any, any, any>>(options: {
@@ -74,8 +82,14 @@ const Base: new<A, E, R>() => Effect.Effect<A, E, R> = (() => {
 })()
 
 /**
- * An abstract class that can be extended to create an `Effect`.
+ * Provides 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,7 +60,14 @@ import * as Result from "./Result.ts"
  * Type identifier stored on `EncodingError` values and used by
  * `isEncodingError`.
  *
- * @category symbols
+ * **Details**
+ *
+ * This marker is part of the runtime representation of `EncodingError`. Prefer
+ * `isEncodingError` when narrowing unknown values.
+ *
+ * @see {@link isEncodingError} for the public guard that checks this marker
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export const EncodingErrorTypeId = "~effect/encoding/EncodingError" as const
@@ -23,7 +75,11 @@ export const EncodingErrorTypeId = "~effect/encoding/EncodingError" as const
 /**
  * Literal type of the `EncodingErrorTypeId` marker.
  *
- * @category symbols
+ * **When to use**
+ *
+ * Use to type the marker carried by `EncodingError` values.
+ *
+ * @category type IDs
  * @since 4.0.0
  */
 export type EncodingErrorTypeId = typeof EncodingErrorTypeId
@@ -32,12 +88,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 +112,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 +124,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 +149,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 +173,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
  */
@@ -95,7 +184,12 @@ export const encodeBase64: (input: Uint8Array | string) => string = (input) =>
   typeof input === "string" ? base64EncodeUint8Array(encoder.encode(input)) : base64EncodeUint8Array(input)
 
 /**
- * Decodes a base64 (RFC4648) string into bytes.
+ * Decodes a base64 (RFC4648) string into bytes safely.
+ *
+ * **When to use**
+ *
+ * Use to decode a standard padded Base64 string into bytes without throwing on
+ * invalid input.
  *
  * **Details**
  *
@@ -170,7 +264,12 @@ export const decodeBase64 = (str: string): Result.Result<Uint8Array, EncodingErr
 }
 
 /**
- * Decodes a base64 (RFC4648) string into a UTF-8 string.
+ * Decodes a base64 (RFC4648) string into a UTF-8 string safely.
+ *
+ * **When to use**
+ *
+ * Use to decode a standard padded Base64 string into UTF-8 text without
+ * throwing on invalid input.
  *
  * **Details**
  *
@@ -200,6 +299,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 +322,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
  */
@@ -219,7 +333,12 @@ export const encodeBase64Url: (input: Uint8Array | string) => string = (input) =
   typeof input === "string" ? base64UrlEncodeUint8Array(encoder.encode(input)) : base64UrlEncodeUint8Array(input)
 
 /**
- * Decodes a URL-safe base64 string into bytes.
+ * Decodes a URL-safe base64 string into bytes safely.
+ *
+ * **When to use**
+ *
+ * Use to decode padded or unpadded Base64Url text into bytes without throwing
+ * on invalid input.
  *
  * **Details**
  *
@@ -275,7 +394,12 @@ export const decodeBase64Url = (str: string): Result.Result<Uint8Array, Encoding
 }
 
 /**
- * Decodes a URL-safe base64 string into a UTF-8 string.
+ * Decodes a URL-safe base64 string into a UTF-8 string safely.
+ *
+ * **When to use**
+ *
+ * Use to decode padded or unpadded Base64Url text into UTF-8 text without
+ * throwing on invalid input.
  *
  * **Details**
  *
@@ -306,6 +430,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
@@ -326,7 +454,11 @@ export const encodeHex: (input: Uint8Array | string) => string = (input) =>
   typeof input === "string" ? hexEncodeUint8Array(encoder.encode(input)) : hexEncodeUint8Array(input)
 
 /**
- * Decodes a hexadecimal string into bytes.
+ * Decodes a hexadecimal string into bytes safely.
+ *
+ * **When to use**
+ *
+ * Use to decode hexadecimal text into bytes without throwing on invalid input.
  *
  * **Details**
  *
@@ -384,7 +516,12 @@ export const decodeHex = (str: string): Result.Result<Uint8Array, EncodingError>
 }
 
 /**
- * Decodes a hexadecimal string into a UTF-8 string.
+ * Decodes a hexadecimal string into a UTF-8 string safely.
+ *
+ * **When to use**
+ *
+ * Use to decode hexadecimal text into UTF-8 text without throwing on invalid
+ * input.
  *
  * **Details**
  *

package/src/Equal.ts

@@ -75,11 +75,11 @@ import { byReferenceInstances, getAllObjectKeys } from "./internal/equal.ts"
 import { hasProperty } from "./Predicate.ts"
 
 /**
- * The unique string identifier for the {@link Equal} interface.
+ * Defines the unique string identifier for the `Equal` interface.
  *
  * **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
@@ -170,11 +170,11 @@ export interface Equal extends Hash.Hash {
 }
 
 /**
- * Compares two values for deep structural equality.
+ * Checks whether two values are deeply structurally equal.
  *
  * **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.
@@ -576,12 +576,11 @@ export const asEquivalence: <A>() => Equivalence<A> = () => equals
 export const byReference = <T extends object>(obj: T): T => byReferenceUnsafe(new Proxy(obj, {}))
 
 /**
- * Permanently marks an object to use reference equality, without creating a
- * proxy.
+ * Marks an object permanently to use reference equality, without creating a proxy.
  *
  * **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).
  *