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

package/src/Boolean.ts

@@ -1,6 +1,57 @@
 /**
- * This module provides utility functions and type class instances for working with the `boolean` type in TypeScript.
- * It includes functions for basic boolean operations.
+ * Operations for working with TypeScript `boolean` values in expression-oriented
+ * code. Use this module to narrow unknown input, branch without inline
+ * conditionals, combine boolean flags with named logical operators, and reduce
+ * boolean collections.
+ *
+ * **Mental model**
+ *
+ * Boolean values are plain JavaScript booleans. The module adds a small
+ * vocabulary around them: {@link match} for choosing between two lazy branches,
+ * logical combinators such as {@link and}, {@link or}, {@link xor}, and
+ * {@link implies}, and collection helpers such as {@link every} and
+ * {@link some}. The exported {@link Order} sorts `false` before `true`, and
+ * {@link Equivalence} compares booleans with strict equality.
+ *
+ * **Common tasks**
+ *
+ * - Coerce or narrow input: {@link Boolean}, {@link isBoolean}
+ * - Branch on a boolean: {@link match}
+ * - Invert and combine flags: {@link not}, {@link and}, {@link or},
+ *   {@link nand}, {@link nor}, {@link xor}, {@link eqv}, {@link implies}
+ * - Check boolean collections: {@link every}, {@link some}
+ * - Pass boolean instances to generic APIs: {@link Order}, {@link Equivalence},
+ *   {@link ReducerAnd}, {@link ReducerOr}
+ *
+ * **Gotchas**
+ *
+ * - {@link Boolean} is the native JavaScript constructor. It follows truthiness
+ *   rules, so values such as `"false"` and `[]` coerce to `true`.
+ * - {@link every} returns `true` for an empty iterable, matching logical AND.
+ *   {@link some} returns `false` for an empty iterable, matching logical OR.
+ * - {@link ReducerAnd} and {@link ReducerOr} are for APIs that consume a
+ *   `Reducer`; use {@link every} or {@link some} when you want direct iterable
+ *   checks.
+ *
+ * **Quickstart**
+ *
+ * **Example** (Combining validation flags)
+ *
+ * ```ts
+ * import { Boolean } from "effect"
+ *
+ * const hasName = true
+ * const hasEmail = false
+ *
+ * const isComplete = Boolean.and(hasName, hasEmail)
+ * console.log(isComplete) // false
+ *
+ * const message = Boolean.match(isComplete, {
+ *   onFalse: () => "missing fields",
+ *   onTrue: () => "ready"
+ * })
+ * console.log(message) // "missing fields"
+ * ```
  *
  * @since 2.0.0
  */
@@ -12,7 +63,18 @@ import * as predicate from "./Predicate.ts"
 import * as Reducer from "./Reducer.ts"
 
 /**
- * Reference to the global Boolean constructor.
+ * Reference to the global `Boolean` constructor for JavaScript truthiness
+ * coercion.
+ *
+ * **When to use**
+ *
+ * Use when you want native `Boolean` constructor coercion from the Effect module
+ * namespace.
+ *
+ * **Gotchas**
+ *
+ * This follows native truthiness rules. For example, non-empty strings such as
+ * `"false"` coerce to `true`.
  *
  * **Example** (Coercing values to booleans)
  *
@@ -37,6 +99,10 @@ export const Boolean = globalThis.Boolean
 /**
  * Tests if a value is a `boolean`.
  *
+ * **When to use**
+ *
+ * Use to validate unknown input and narrow it to `boolean`.
+ *
  * **Example** (Checking for booleans)
  *
  * ```ts
@@ -56,6 +122,10 @@ export const isBoolean: (input: unknown) => input is boolean = predicate.isBoole
  * This function returns the result of either of the given functions depending on the value of the boolean parameter.
  * It is useful when you have to run one of two functions depending on the boolean value.
  *
+ * **When to use**
+ *
+ * Use to choose between two lazy branches based on a boolean value.
+ *
  * **Example** (Pattern matching on booleans)
  *
  * ```ts
@@ -79,6 +149,10 @@ export const match: {
    * This function returns the result of either of the given functions depending on the value of the boolean parameter.
    * It is useful when you have to run one of two functions depending on the boolean value.
    *
+   * **When to use**
+   *
+   * Use to choose between two lazy branches based on a boolean value.
+   *
    * **Example** (Pattern matching on booleans)
    *
    * ```ts
@@ -107,6 +181,10 @@ export const match: {
    * This function returns the result of either of the given functions depending on the value of the boolean parameter.
    * It is useful when you have to run one of two functions depending on the boolean value.
    *
+   * **When to use**
+   *
+   * Use to choose between two lazy branches based on a boolean value.
+   *
    * **Example** (Pattern matching on booleans)
    *
    * ```ts
@@ -141,6 +219,11 @@ export const match: {
  * Provides an `Order` instance for `boolean` that allows comparing and sorting boolean values.
  * In this ordering, `false` is considered less than `true`.
  *
+ * **When to use**
+ *
+ * Use when an API needs an `Order` instance for booleans with `false` before
+ * `true`.
+ *
  * **Example** (Comparing booleans)
  *
  * ```ts
@@ -159,6 +242,10 @@ export const Order: order.Order<boolean> = order.Boolean
 /**
  * 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 for equivalence)
  *
  * ```ts
@@ -176,6 +263,10 @@ export const Equivalence: Equ.Equivalence<boolean> = Equ.Boolean
 /**
  * Negates the given boolean: `!self`
  *
+ * **When to use**
+ *
+ * Use to invert a boolean value.
+ *
  * **Example** (Negating booleans)
  *
  * ```ts
@@ -192,7 +283,15 @@ export const Equivalence: Equ.Equivalence<boolean> = Equ.Boolean
 export const not = (self: boolean): boolean => !self
 
 /**
- * Combines two boolean using AND: `self && that`.
+ * Combines two booleans using logical AND: `self && that`.
+ *
+ * **When to use**
+ *
+ * Use to require both boolean operands to be `true`.
+ *
+ * **Details**
+ *
+ * Supports both data-first and data-last forms.
  *
  * **Example** (Combining booleans with AND)
  *
@@ -211,7 +310,15 @@ export const not = (self: boolean): boolean => !self
  */
 export const and: {
   /**
-   * Combines two boolean using AND: `self && that`.
+   * Combines two booleans using logical AND: `self && that`.
+   *
+   * **When to use**
+   *
+   * Use to require both boolean operands to be `true`.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms.
    *
    * **Example** (Combining booleans with AND)
    *
@@ -230,7 +337,15 @@ export const and: {
    */
   (that: boolean): (self: boolean) => boolean
   /**
-   * Combines two boolean using AND: `self && that`.
+   * Combines two booleans using logical AND: `self && that`.
+   *
+   * **When to use**
+   *
+   * Use to require both boolean operands to be `true`.
+   *
+   * **Details**
+   *
+   * Supports both data-first and data-last forms.
    *
    * **Example** (Combining booleans with AND)
    *
@@ -253,6 +368,10 @@ export const and: {
 /**
  * Combines two boolean using NAND: `!(self && that)`.
  *
+ * **When to use**
+ *
+ * Use to negate a logical AND result.
+ *
  * **Example** (Combining booleans with NAND)
  *
  * ```ts
@@ -272,6 +391,10 @@ export const nand: {
   /**
    * Combines two boolean using NAND: `!(self && that)`.
    *
+   * **When to use**
+   *
+   * Use to negate a logical AND result.
+   *
    * **Example** (Combining booleans with NAND)
    *
    * ```ts
@@ -291,6 +414,10 @@ export const nand: {
   /**
    * Combines two boolean using NAND: `!(self && that)`.
    *
+   * **When to use**
+   *
+   * Use to negate a logical AND result.
+   *
    * **Example** (Combining booleans with NAND)
    *
    * ```ts
@@ -312,6 +439,10 @@ export const nand: {
 /**
  * Combines two boolean using OR: `self || that`.
  *
+ * **When to use**
+ *
+ * Use to accept when either boolean operand is `true`.
+ *
  * **Example** (Combining booleans with OR)
  *
  * ```ts
@@ -331,6 +462,10 @@ export const or: {
   /**
    * Combines two boolean using OR: `self || that`.
    *
+   * **When to use**
+   *
+   * Use to accept when either boolean operand is `true`.
+   *
    * **Example** (Combining booleans with OR)
    *
    * ```ts
@@ -350,6 +485,10 @@ export const or: {
   /**
    * Combines two boolean using OR: `self || that`.
    *
+   * **When to use**
+   *
+   * Use to accept when either boolean operand is `true`.
+   *
    * **Example** (Combining booleans with OR)
    *
    * ```ts
@@ -371,6 +510,10 @@ export const or: {
 /**
  * Combines two booleans using NOR: `!(self || that)`.
  *
+ * **When to use**
+ *
+ * Use to accept only when both boolean operands are `false`.
+ *
  * **Example** (Combining booleans with NOR)
  *
  * ```ts
@@ -390,6 +533,10 @@ export const nor: {
   /**
    * Combines two booleans using NOR: `!(self || that)`.
    *
+   * **When to use**
+   *
+   * Use to accept only when both boolean operands are `false`.
+   *
    * **Example** (Combining booleans with NOR)
    *
    * ```ts
@@ -409,6 +556,10 @@ export const nor: {
   /**
    * Combines two booleans using NOR: `!(self || that)`.
    *
+   * **When to use**
+   *
+   * Use to accept only when both boolean operands are `false`.
+   *
    * **Example** (Combining booleans with NOR)
    *
    * ```ts
@@ -430,6 +581,10 @@ export const nor: {
 /**
  * Combines two booleans using XOR: `(!self && that) || (self && !that)`.
  *
+ * **When to use**
+ *
+ * Use to accept when exactly one boolean operand is `true`.
+ *
  * **Example** (Combining booleans with XOR)
  *
  * ```ts
@@ -449,6 +604,10 @@ export const xor: {
   /**
    * Combines two booleans using XOR: `(!self && that) || (self && !that)`.
    *
+   * **When to use**
+   *
+   * Use to accept when exactly one boolean operand is `true`.
+   *
    * **Example** (Combining booleans with XOR)
    *
    * ```ts
@@ -468,6 +627,10 @@ export const xor: {
   /**
    * Combines two booleans using XOR: `(!self && that) || (self && !that)`.
    *
+   * **When to use**
+   *
+   * Use to accept when exactly one boolean operand is `true`.
+   *
    * **Example** (Combining booleans with XOR)
    *
    * ```ts
@@ -489,6 +652,10 @@ export const xor: {
 /**
  * Combines two booleans using EQV (aka XNOR): `!xor(self, that)`.
  *
+ * **When to use**
+ *
+ * Use to accept when both boolean operands have the same truth value.
+ *
  * **Example** (Checking boolean equivalence)
  *
  * ```ts
@@ -508,6 +675,10 @@ export const eqv: {
   /**
    * Combines two booleans using EQV (aka XNOR): `!xor(self, that)`.
    *
+   * **When to use**
+   *
+   * Use to accept when both boolean operands have the same truth value.
+   *
    * **Example** (Checking boolean equivalence)
    *
    * ```ts
@@ -527,6 +698,10 @@ export const eqv: {
   /**
    * Combines two booleans using EQV (aka XNOR): `!xor(self, that)`.
    *
+   * **When to use**
+   *
+   * Use to accept when both boolean operands have the same truth value.
+   *
    * **Example** (Checking boolean equivalence)
    *
    * ```ts
@@ -548,6 +723,10 @@ export const eqv: {
 /**
  * Combines two booleans using an implication: `(!self || that)`.
  *
+ * **When to use**
+ *
+ * Use to model logical implication between a condition and a consequence.
+ *
  * **Example** (Checking boolean implication)
  *
  * ```ts
@@ -567,6 +746,10 @@ export const implies: {
   /**
    * Combines two booleans using an implication: `(!self || that)`.
    *
+   * **When to use**
+   *
+   * Use to model logical implication between a condition and a consequence.
+   *
    * **Example** (Checking boolean implication)
    *
    * ```ts
@@ -586,6 +769,10 @@ export const implies: {
   /**
    * Combines two booleans using an implication: `(!self || that)`.
    *
+   * **When to use**
+   *
+   * Use to model logical implication between a condition and a consequence.
+   *
    * **Example** (Checking boolean implication)
    *
    * ```ts
@@ -607,6 +794,10 @@ export const implies: {
 /**
  * This utility function is used to check if all the elements in a collection of boolean values are `true`.
  *
+ * **When to use**
+ *
+ * Use to check that every boolean in an iterable is `true`.
+ *
  * **Example** (Checking every boolean)
  *
  * ```ts
@@ -617,6 +808,9 @@ export const implies: {
  * assert.deepStrictEqual(Boolean.every([true, false, true]), false)
  * ```
  *
+ * @see {@link some} for checking whether at least one value is `true`
+ * @see {@link ReducerAnd} for reducing booleans with AND through a `Reducer`
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -632,6 +826,10 @@ export const every = (collection: Iterable<boolean>): boolean => {
 /**
  * This utility function is used to check if at least one of the elements in a collection of boolean values is `true`.
  *
+ * **When to use**
+ *
+ * Use to check that at least one boolean in an iterable is `true`.
+ *
  * **Example** (Checking some booleans)
  *
  * ```ts
@@ -642,6 +840,9 @@ export const every = (collection: Iterable<boolean>): boolean => {
  * assert.deepStrictEqual(Boolean.some([false, false, false]), false)
  * ```
  *
+ * @see {@link every} for checking whether all values are `true`
+ * @see {@link ReducerOr} for reducing booleans with OR through a `Reducer`
+ *
  * @category utils
  * @since 2.0.0
  */
@@ -657,9 +858,22 @@ export const some = (collection: Iterable<boolean>): boolean => {
 /**
  * A `Reducer` for combining `boolean`s using AND.
  *
+ * **When to use**
+ *
+ * Use to require every accumulated boolean to be `true` through APIs that
+ * consume a `Reducer`.
+ *
  * **Details**
  *
- * The `initialValue` is `true`.
+ * The `initialValue` is `true`, so `combineAll([])` returns `true`.
+ *
+ * **Gotchas**
+ *
+ * `combineAll` uses the default left-to-right `Reducer.make` fold and does not
+ * short-circuit on `false`.
+ *
+ * @see {@link ReducerOr} for reducing with OR semantics
+ * @see {@link every} for checking an iterable directly
  *
  * @category math
  * @since 4.0.0
@@ -669,10 +883,18 @@ export const ReducerAnd: Reducer.Reducer<boolean> = Reducer.make((a, b) => a &&
 /**
  * A `Reducer` for combining `boolean`s using OR.
  *
+ * **When to use**
+ *
+ * Use to reduce boolean values where the result should be `true` if any
+ * combined value is `true`.
+ *
  * **Details**
  *
  * The `initialValue` is `false`.
  *
+ * @see {@link ReducerAnd} for reducing with AND semantics
+ * @see {@link some} for checking an iterable directly
+ *
  * @category math
  * @since 4.0.0
  */

package/src/Brand.ts

@@ -1,7 +1,53 @@
 /**
- * This module provides types and utility functions to create and work with
- * branded types, which are TypeScript types with an added type tag to prevent
- * accidental usage of a value in the wrong context.
+ * The `Brand` module adds compile-time names to ordinary TypeScript values so
+ * structurally identical values cannot be mixed accidentally. A branded value
+ * has the same runtime representation as its unbranded value; the extra
+ * information lives in the type system unless you choose a validating
+ * constructor.
+ *
+ * **Mental model**
+ *
+ * - {@link Branded} is an existing value type plus a phantom {@link Brand}
+ *   marker
+ * - {@link nominal} creates constructors for purely nominal brands and
+ *   performs no runtime validation
+ * - {@link make} and {@link check} create constructors that validate input
+ *   before returning the branded value
+ * - A {@link Constructor} can throw, return `Option`, return `Result`, or act
+ *   as a type guard through its `is` method
+ * - {@link all} combines multiple brand constructors with the same base type so
+ *   a value can carry several brands
+ *
+ * **Common tasks**
+ *
+ * - Distinguish identifiers with the same primitive representation, such as
+ *   `UserId` and `OrderId`
+ * - Constrain primitive values after validation, such as positive numbers,
+ *   non-empty strings, or normalized tokens
+ * - Keep public APIs precise without wrapping values in runtime classes
+ *
+ * **Quickstart**
+ *
+ * **Example** (Validated identifier)
+ *
+ * ```ts
+ * import { Brand } from "effect"
+ *
+ * type UserId = Brand.Branded<number, "UserId">
+ *
+ * const UserId = Brand.make<UserId>(
+ *   (n) => Number.isInteger(n) && n > 0 || "Expected a positive integer"
+ * )
+ *
+ * const id = UserId(1)
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - Brands do not change the runtime value; `id` above is still a number at
+ *   runtime
+ * - {@link nominal} accepts every value of the base type, so use
+ *   {@link make} or {@link check} at trust boundaries that need validation
  *
  * @since 2.0.0
  */
@@ -18,6 +64,15 @@ const TypeId = "~effect/Brand"
 /**
  * A generic interface that defines a branded type.
  *
+ * **When to use**
+ *
+ * Use to define a branded type such as `number & Brand<"Positive">` when
+ * TypeScript should keep structurally identical values separate without
+ * changing their runtime value.
+ *
+ * @see {@link Branded} for applying a brand key to a base type
+ * @see {@link Constructor} for validating or constructing branded values
+ *
  * @category models
  * @since 2.0.0
  */
@@ -31,6 +86,17 @@ export interface Brand<in out Keys extends string> {
  * A constructor for a branded type that provides validation and safe
  * construction methods.
  *
+ * **When to use**
+ *
+ * Use as the shared callable interface for branded values when an API accepts
+ * or returns a brand constructor and callers need throwing, `Option`, `Result`,
+ * or type-guard validation forms.
+ *
+ * @see {@link nominal} for a constructor without runtime validation
+ * @see {@link make} for creating a constructor from a validation predicate
+ * @see {@link check} for creating a constructor from schema checks
+ * @see {@link all} for combining brand constructors
+ *
  * @category models
  * @since 2.0.0
  */
@@ -69,6 +135,16 @@ export interface Constructor<in out B extends Brand<any>> {
  * A `BrandError` is returned when a branded type is constructed from an invalid
  * value.
  *
+ * **Details**
+ *
+ * The error wraps a `SchemaIssue.Issue`, exposes `message` through
+ * `issue.toString()`, and formats as `BrandError(<message>)`.
+ *
+ * **Gotchas**
+ *
+ * `BrandError` is an error-like model with `_tag`, `name`, `message`, and
+ * `toString`; it does not extend JavaScript `Error`.
+ *
  * @category models
  * @since 4.0.0
  */
@@ -185,7 +261,7 @@ export type Branded<A, Key extends string> = A & Brand<Key>
  *
  * **When to use**
  *
- * Use this to create nominal types that allow distinguishing between two values
+ * 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}.
  *
@@ -206,7 +282,7 @@ export function nominal<A extends Brand<any>>(): Constructor<A> {
  *
  * **When to use**
  *
- * Use this when you want validation while constructing the branded type. If you
+ * 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}.
  *
@@ -222,12 +298,19 @@ export function make<A extends Brand<any>>(
 /**
  * Creates a branded type `Constructor` from one or more schema checks.
  *
+ * **When to use**
+ *
+ * Use when you need a branded type constructor that performs runtime validation
+ * via schema checks.
+ *
  * **Details**
  *
  * Calling the returned constructor validates the unbranded value and throws on
  * failure. Use the returned `option`, `result`, or `is` methods for
  * non-throwing validation.
  *
+ * @see {@link nominal} for a brand constructor without runtime validation
+ * @see {@link all} for combining multiple brand constructors
  * @category constructors
  * @since 4.0.0
  */
@@ -249,9 +332,18 @@ export function check<A extends Brand<any>>(
 }
 
 /**
- * Combines two or more brands together to form a single branded type. This API
- * is useful when you want to validate that the input data passes multiple brand
- * validators.
+ * Combines one or more brand constructors to form a single branded type.
+ *
+ * **When to use**
+ *
+ * Use to require an input to satisfy every runtime check collected by the
+ * provided brand constructors.
+ *
+ * **Details**
+ *
+ * If the provided constructors contain runtime checks, the combined
+ * constructor succeeds only when all checks pass. If no runtime checks are
+ * present, it behaves as a nominal constructor.
  *
  * @category combining
  * @since 2.0.0