Hash
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. The module also includes helpers for primitive, structure, array, and reference-based hashes, plus functions for combining and optimizing numeric hash values.
Guards
Hashing
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
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.
See
hashfor the general-purpose hash dispatcher
Signature
declare const array: <A>(arr: Iterable<A>) => number;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
Supports both direct and pipeable usage. The implementation combines two hash values with (self * 53) ^ b.
See
hashfor computing hash values from arbitrary inputsstructureKeysfor hashing selected object fields without manual combination
Signature
declare const combine: {
(b: number): (self: number) => number;
(self: number, b: number): number;
};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 objects, arrays, and other complex data structures. It automatically handles different types and provides a consistent hash value for equivalent inputs.
Gotchas
Objects being hashed must be treated as immutable after their first hash computation. Hash results are cached, so mutating an object after hashing will lead to stale cached values and broken hash-based operations. For mutable objects, implement a custom Hash interface that hashes the object reference rather than its content.
Signature
declare const hash: <A>(self: A) => number;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 like NaN, Infinity, and -Infinity with distinct hash values. It uses bitwise operations to ensure good distribution of hash values across different numeric inputs.
Signature
declare function number(n: number): number;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
This function takes a hash value and applies bitwise operations to improve the distribution of hash values, reducing the likelihood of collisions.
Signature
declare function optimize(n: number): number;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 hash implementation. The hash value is cached using a WeakMap, so the same object will always return the same hash value during its lifetime.
Signature
declare const random: <A extends object>(self: A) => number;Computes a hash value for a string using the djb2 algorithm.
When to use
Use when you need a string field to contribute to a custom structural hash implementation.
Details
This function implements a variation of the djb2 hash algorithm, which is known for its good distribution properties and speed. It processes each character of the string to produce a consistent hash value.
Signature
declare function string(str: string): number;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 symbol keys and relevant prototype keys for non-plain objects.
Signature
declare function structure<A extends object>(o: A): number;structureKeys
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, which is useful when you want to create a hash based on a subset of an object's properties.
Signature
declare function structureKeys(o: object, keys: Iterable<PropertyKey>): number;Models
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, which is used for efficient comparison and storage operations.
Signature
interface Hash {
"~effect/interfaces/Hash"(): number;
}Symbols
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
Signature
declare const symbol: "~effect/interfaces/Hash";
Checks whether a value implements the Hash interface.
When to use
Use to detect whether an unknown value provides a custom hash implementation.
Details
This function determines whether a given value has the Hash symbol property, indicating that it can provide its own hash value implementation.