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

package/src/HKT.ts

@@ -1,36 +1,52 @@
 /**
- * This module provides utilities for Higher-Kinded Types (HKT) in TypeScript.
+ * Type-level encoding for higher-kinded types in Effect.
  *
- * Higher-Kinded Types are types that take other types as parameters, similar to how
- * functions take values as parameters. They enable generic programming over type
- * constructors, allowing you to write code that works with any container type
- * (like Array, Option, Effect, etc.) in a uniform way.
+ * TypeScript cannot abstract directly over type constructors such as
+ * `Option<_>`, `ReadonlyArray<_>`, or `Effect<_, _, _>`. This module encodes
+ * those constructors with {@link TypeLambda} and applies them with
+ * {@link Kind}, so libraries can define generic APIs that work across many
+ * Effect data types.
  *
- * The HKT system in Effect uses TypeLambdas to encode type-level functions that
- * can represent complex type relationships with multiple type parameters, including
- * contravariant, covariant, and invariant positions.
+ * **Mental model**
  *
- * **Example** (Encoding type lambdas)
+ * - A {@link TypeLambda} is a type-level function with four slots: `In`,
+ *   `Out2`, `Out1`, and `Target`
+ * - A concrete type lambda defines `readonly type` in terms of those slots
+ * - {@link Kind} fills the slots and reads the lambda's resulting concrete type
+ * - {@link TypeClass} lets an interface carry the lambda it implements through
+ *   {@link URI}
+ * - Effect modules expose their own type lambdas when they support generic
+ *   higher-kinded programming
+ *
+ * **Common tasks**
+ *
+ * - Define a type lambda for a data type by extending {@link TypeLambda}
+ * - Apply a lambda to type arguments with {@link Kind}
+ * - Write type class interfaces that are parameterized by a lambda
+ *
+ * **Gotchas**
+ *
+ * - The slot names are positional; check the concrete lambda to see how `In`,
+ *   `Out2`, `Out1`, and `Target` map to that data type's parameters
+ * - Use `never` for slots that a lambda does not read
+ * - HKT values are type-level encodings; they do not create runtime wrappers
+ *
+ * **Example** (Defining a simple type lambda)
  *
  * ```ts
  * import type { HKT } from "effect"
  *
- * // Define a TypeLambda for Array
- * interface ArrayTypeLambda extends HKT.TypeLambda {
- *   readonly type: Array<this["Target"]>
+ * interface ReadonlyArrayTypeLambda extends HKT.TypeLambda {
+ *   readonly type: ReadonlyArray<this["Target"]>
  * }
  *
- * // Use Kind to get the concrete type
- * type MyArray = HKT.Kind<ArrayTypeLambda, never, never, never, string>
- * // MyArray is Array<string>
- *
- * // Define a TypeClass that works with any HKT
- * interface Functor<F extends HKT.TypeLambda> extends HKT.TypeClass<F> {
- *   map<A, B>(
- *     fa: HKT.Kind<F, never, never, never, A>,
- *     f: (a: A) => B
- *   ): HKT.Kind<F, never, never, never, B>
- * }
+ * type StringArray = HKT.Kind<
+ *   ReadonlyArrayTypeLambda,
+ *   never,
+ *   never,
+ *   never,
+ *   string
+ * >
  * ```
  *
  * @since 2.0.0
@@ -38,12 +54,17 @@
 import type * as Types from "./Types.ts"
 
 /**
- * A unique symbol used to associate `TypeClass` implementations with their `TypeLambda`.
+ * Defines the unique symbol used to associate `TypeClass` implementations with their `TypeLambda`.
+ *
+ * **When to use**
+ *
+ * Use when defining a custom type class that needs to expose the `TypeLambda` it
+ * operates on.
  *
  * **Details**
  *
- * This symbol is used internally by the HKT system to link runtime type class
- * instances with their compile-time type information.
+ * This symbol links a type class shape with its compile-time type lambda. It is
+ * intended for type-class definitions and has no runtime behavior.
  *
  * **Example** (Linking a type class to a type lambda)
  *
@@ -77,6 +98,10 @@ export declare const URI: unique symbol
 /**
  * Base interface for type classes that work with Higher-Kinded Types.
  *
+ * **When to use**
+ *
+ * Use to define type class interfaces parameterized by a `TypeLambda`.
+ *
  * **Details**
  *
  * A `TypeClass` defines operations that can be performed on any type constructor
@@ -115,6 +140,10 @@ export interface TypeClass<F extends TypeLambda> {
 /**
  * Base interface for defining Higher-Kinded Type parameters.
  *
+ * **When to use**
+ *
+ * Use to encode a type constructor for higher-kinded generic programming.
+ *
  * **Details**
  *
  * A `TypeLambda` encodes the "shape" of a type constructor, specifying how many
@@ -157,6 +186,10 @@ export interface TypeLambda {
 /**
  * Applies type parameters to a `TypeLambda` to get the concrete type.
  *
+ * **When to use**
+ *
+ * Use to apply a `TypeLambda` to type parameters and obtain its concrete type.
+ *
  * **Details**
  *
  * This type-level function takes a `TypeLambda` and four type parameters, then

package/src/Hash.ts

@@ -1,9 +1,53 @@
 /**
- * This module provides utilities for hashing values in TypeScript.
+ * The `Hash` module computes Effect hash values and defines the interface for
+ * objects that want to provide their own hash implementation. Hashes are small
+ * numeric fingerprints used by Effect data structures to bucket values quickly;
+ * they are not cryptographic digests and they are not proof that two values are
+ * equal.
+ *
+ * **Mental model**
+ *
+ * - {@link hash} dispatches by JavaScript type and handles primitives,
+ *   arrays, typed arrays, maps, sets, plain objects, dates, regular
+ *   expressions, and custom hashable objects
+ * - Objects can implement {@link Hash} by defining a method at {@link symbol}
+ * - Structural object hashes are cached, so repeated hashing of the same object
+ *   is cheap after the first computation
+ * - {@link random} gives reference-stable hash values for values that should
+ *   be hashed by identity
+ * - Lower-level helpers such as {@link combine}, {@link string},
+ *   {@link number}, {@link structure}, {@link structureKeys}, and
+ *   {@link array} are useful when implementing custom hashes
+ *
+ * **Quickstart**
+ *
+ * **Example** (Implementing a custom hash)
  *
- * Hashing is the process of converting data into a fixed-size numeric value,
- * typically used for data structures like hash tables, equality comparisons,
- * and efficient data storage.
+ * ```ts
+ * import { Hash } from "effect"
+ *
+ * class UserKey implements Hash.Hash {
+ *   constructor(
+ *     readonly id: string,
+ *     readonly region: string
+ *   ) {}
+ *
+ *   [Hash.symbol](): number {
+ *     return Hash.combine(Hash.string(this.region))(Hash.string(this.id))
+ *   }
+ * }
+ *
+ * const value = Hash.hash(new UserKey("user-1", "eu"))
+ * ```
+ *
+ * **Gotchas**
+ *
+ * - Hash collisions are possible; hash-based collections also need equality
+ *   semantics to decide whether two values are actually the same
+ * - Do not mutate an object after hashing it structurally, because the cached
+ *   hash can become stale
+ * - Use {@link random} or a custom {@link Hash} implementation for mutable
+ *   objects that should be compared by reference identity
  *
  * @since 2.0.0
  */
@@ -12,7 +56,16 @@ import { byReferenceInstances, getAllObjectKeys } from "./internal/equal.ts"
 import { hasProperty } from "./Predicate.ts"
 
 /**
- * The unique identifier used to identify objects that implement the Hash interface.
+ * Defines the unique identifier used to identify objects that implement the Hash interface.
+ *
+ * **When to use**
+ *
+ * Use as the computed property key for the method that supplies a custom hash
+ * value on a `Hash` implementor.
+ *
+ * @see {@link Hash} for the interface implemented with this symbol
+ * @see {@link isHash} for checking whether a value implements `Hash`
+ * @see {@link hash} for computing hash values
  *
  * @category symbols
  * @since 2.0.0
@@ -22,6 +75,10 @@ export const symbol = "~effect/interfaces/Hash"
 /**
  * A type that represents an object that can be hashed.
  *
+ * **When to use**
+ *
+ * Use to let a custom type provide its own stable hash value.
+ *
  * **Details**
  *
  * Objects implementing this interface provide a method to compute their hash value,
@@ -54,6 +111,11 @@ export interface Hash {
 /**
  * Computes a hash value for any given value.
  *
+ * **When to use**
+ *
+ * Use to compute an Effect hash for primitives, collections, and hashable
+ * objects.
+ *
  * **Details**
  *
  * This function can hash primitives (numbers, strings, booleans, etc.) as well as
@@ -144,6 +206,10 @@ export const hash: <A>(self: A) => number = <A>(self: A) => {
 /**
  * Generates a random hash value for an object and caches it.
  *
+ * **When to use**
+ *
+ * Use to hash an object by reference identity instead of structural content.
+ *
  * **Details**
  *
  * This function creates a random hash value for objects that don't have their own
@@ -178,11 +244,15 @@ export const random: <A extends object>(self: A) => number = (self) => {
 /**
  * Combines two hash values into a single hash value.
  *
+ * **When to use**
+ *
+ * Use to build a hash for a composite value by folding together hash values for
+ * its parts.
+ *
  * **Details**
  *
- * This function takes two hash values and combines them using a mathematical
- * operation to produce a new hash value. It's useful for creating hash values
- * of composite structures.
+ * Supports both direct and pipeable usage. The implementation combines two
+ * hash values with `(self * 53) ^ b`.
  *
  * **Example** (Combining hash values)
  *
@@ -200,6 +270,9 @@ export const random: <A extends object>(self: A) => number = (self) => {
  * const result = pipe(hash1, Hash.combine(hash2))
  * ```
  *
+ * @see {@link hash} for computing hash values from arbitrary inputs
+ * @see {@link structureKeys} for hashing selected object fields without manual combination
+ *
  * @category hashing
  * @since 2.0.0
  */
@@ -207,11 +280,15 @@ export const combine: {
   /**
    * Combines two hash values into a single hash value.
    *
+   * **When to use**
+   *
+   * Use to build a hash for a composite value by folding together hash values for
+   * its parts.
+   *
    * **Details**
    *
-   * This function takes two hash values and combines them using a mathematical
-   * operation to produce a new hash value. It's useful for creating hash values
-   * of composite structures.
+   * Supports both direct and pipeable usage. The implementation combines two
+   * hash values with `(self * 53) ^ b`.
    *
    * **Example** (Combining hash values)
    *
@@ -229,6 +306,9 @@ export const combine: {
    * const result = pipe(hash1, Hash.combine(hash2))
    * ```
    *
+   * @see {@link hash} for computing hash values from arbitrary inputs
+   * @see {@link structureKeys} for hashing selected object fields without manual combination
+   *
    * @category hashing
    * @since 2.0.0
    */
@@ -236,11 +316,15 @@ export const combine: {
   /**
    * Combines two hash values into a single hash value.
    *
+   * **When to use**
+   *
+   * Use to build a hash for a composite value by folding together hash values for
+   * its parts.
+   *
    * **Details**
    *
-   * This function takes two hash values and combines them using a mathematical
-   * operation to produce a new hash value. It's useful for creating hash values
-   * of composite structures.
+   * Supports both direct and pipeable usage. The implementation combines two
+   * hash values with `(self * 53) ^ b`.
    *
    * **Example** (Combining hash values)
    *
@@ -258,6 +342,9 @@ export const combine: {
    * const result = pipe(hash1, Hash.combine(hash2))
    * ```
    *
+   * @see {@link hash} for computing hash values from arbitrary inputs
+   * @see {@link structureKeys} for hashing selected object fields without manual combination
+   *
    * @category hashing
    * @since 2.0.0
    */
@@ -265,7 +352,11 @@ export const combine: {
 } = dual(2, (self: number, b: number): number => (self * 53) ^ b)
 
 /**
- * Optimizes a hash value by applying bit manipulation techniques.
+ * Applies bit manipulation techniques to optimize a hash value.
+ *
+ * **When to use**
+ *
+ * Use to improve the bit distribution of a raw numeric hash value.
  *
  * **Details**
  *
@@ -291,7 +382,11 @@ export const combine: {
 export const optimize = (n: number): number => (n & 0xbfffffff) | ((n >>> 1) & 0x40000000)
 
 /**
- * Checks if a value implements the Hash interface.
+ * Checks whether a value implements the Hash interface.
+ *
+ * **When to use**
+ *
+ * Use to detect whether an unknown value provides a custom hash implementation.
  *
  * **Details**
  *
@@ -323,6 +418,10 @@ export const isHash = (u: unknown): u is Hash => hasProperty(u, symbol)
 /**
  * Computes a hash value for a number.
  *
+ * **When to use**
+ *
+ * Use to hash a JavaScript number with Effect's numeric hash semantics.
+ *
  * **Details**
  *
  * This function creates a hash value for numeric inputs, handling special cases
@@ -369,6 +468,10 @@ export const number = (n: number) => {
 /**
  * Computes a hash value for a string using the djb2 algorithm.
  *
+ * **When to use**
+ *
+ * Use to hash a string directly.
+ *
  * **Details**
  *
  * This function implements a variation of the djb2 hash algorithm, which is
@@ -402,6 +505,10 @@ export const string = (str: string) => {
 /**
  * Computes a hash value for an object using only the specified keys.
  *
+ * **When to use**
+ *
+ * Use to hash an object by a selected set of property keys.
+ *
  * **Details**
  *
  * This function allows you to hash an object by considering only specific keys,
@@ -442,6 +549,10 @@ export const structureKeys = (o: object, keys: Iterable<PropertyKey>) => {
 /**
  * Computes a structural hash for an object using Effect's object key collection.
  *
+ * **When to use**
+ *
+ * Use to hash an object from all structural keys collected by Effect.
+ *
  * **Details**
  *
  * The hash is based on the object's structural keys and their values, including
@@ -478,13 +589,21 @@ const iterableWith = (seed: number, f: (el: any) => number) => (iter: Iterable<a
 }
 
 /**
- * Computes a hash value for an array by hashing all of its elements.
+ * Computes a hash value for an iterable by hashing all of its elements.
+ *
+ * **When to use**
+ *
+ * Use to hash the values yielded by an iterable with Effect hash semantics.
  *
  * **Details**
  *
- * This function creates a hash value based on all elements in the array.
- * The order of elements matters, so arrays with the same elements in different
- * orders will produce different hash values.
+ * The implementation folds element hashes from the seed `6151` with XOR and
+ * then optimizes the final hash.
+ *
+ * **Gotchas**
+ *
+ * A hash is not an equality proof. Because this implementation uses XOR,
+ * reordered inputs can produce the same hash.
  *
  * **Example** (Hashing arrays)
  *
@@ -497,13 +616,14 @@ const iterableWith = (seed: number, f: (el: any) => number) => (iter: Iterable<a
  *
  * console.log(Hash.array(arr1)) // hash of [1, 2, 3]
  * console.log(Hash.array(arr2)) // same hash as arr1
- * console.log(Hash.array(arr3)) // different hash (different order)
+ * console.log(Hash.array(arr3)) // may match reordered inputs
  *
- * // Arrays with same elements in same order produce same hash
  * console.log(Hash.array(arr1) === Hash.array(arr2)) // true
- * console.log(Hash.array(arr1) === Hash.array(arr3)) // false
+ * console.log(Hash.array(arr1) === Hash.array(arr3)) // true
  * ```
  *
+ * @see {@link hash} for the general-purpose hash dispatcher
+ *
  * @category hashing
  * @since 2.0.0
  */