Hash

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.

declare function isHash(u: unknown): u is Hash

import { Hash } from "effect"

class MyHashable implements Hash.Hash {
  [Hash.symbol]() {
    return 42
  }
}

Hash.isHash(new MyHashable()) // => true
Hash.isHash({}) // => false
Hash.isHash("string") // => false

When to use

Use to hash the values yielded by an iterable with Effect hash semantics.

Details

Folds element hashes with combine, so order and length affect the result.

Gotchas

A hash is not an equality proof. Distinct inputs can still share a hash.

See

• hash for the general-purpose hash dispatcher

declare function array<A>(arr: Iterable<A>): number

import { Hash } from "effect"

const arr1 = [1, 2, 3]
const arr2 = [1, 2, 3]
const arr3 = [3, 2, 1]

Hash.array(arr1) === Hash.array(arr2) // => true
Hash.array(arr1) === Hash.array(arr3) // => false

When to use

Use to build a hash for a composite value by folding together hash values for its parts.

Details

Supports direct and pipeable usage. Argument order affects the result.

See

• hash for computing hash values from arbitrary inputs
• structureKeys for hashing selected object fields without manual combination

declare const combine: {
  (b: number): (self: number) => number;
  (self: number, b: number): number;
}

import { Hash, pipe } from "effect"

const hash1 = Hash.hash("hello")
const hash2 = Hash.hash("world")

const combined = Hash.combine(hash2)(hash1)
combined === pipe(hash1, Hash.combine(hash2)) // => true

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.

declare const hash: <A>(self: A) => number

import { Hash } from "effect"

Hash.hash(42) === Hash.hash(42) // => true
Hash.hash("hello") === Hash.hash("hello") // => true
Hash.hash([1, 2, 3]) === Hash.hash([1, 2, 3]) // => true

When to use

Use to hash a JavaScript number with Effect's numeric hash semantics.

Details

Int32 values hash to themselves. Other numbers hash from their IEEE-754 bits, with a canonical representation for NaN.

declare function number(n: number): number

import { Hash } from "effect"

Number.isInteger(Hash.number(42)) // => true
Number.isInteger(Hash.number(3.14)) // => true
Hash.number(NaN) === Hash.number(NaN) // => true
Hash.number(Infinity) === Hash.number(Infinity) // => true
Hash.number(100) === Hash.number(100) // => true

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.

declare function optimize(n: number): number

import { Hash } from "effect"

Hash.optimize(1234567890) // => 160826066

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.

declare const random: <A extends object>(self: A) => number

import { Hash } from "effect"

const obj1 = { a: 1 }
const obj2 = { a: 1 }

Hash.random(obj1) === Hash.random(obj1) // => true

typeof Hash.random(obj2) // => "number"

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.

declare function string(str: string): number

import { Hash } from "effect"

Hash.string("hello") // => 181380007
Hash.string("world") // => 164394279
Hash.string("") // => 5381
Hash.string("test") === Hash.string("test") // => true

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.

declare function structure<A extends object>(o: A): number

import { Hash } from "effect"

const obj1 = { name: "John", age: 30 }
const obj2 = { name: "Jane", age: 25 }
const obj3 = { name: "John", age: 30 }

Hash.structure(obj1) // => -731887653
Hash.structure(obj2) // => -222100417
Hash.structure(obj3) // => -731887653
Hash.structure(obj1) === Hash.structure(obj3) // => true

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.

declare function structureKeys(o: object, keys: Iterable<PropertyKey>): number

import { Hash } from "effect"

const person = { name: "John", age: 30, city: "New York" }

const hash1 = Hash.structureKeys(person, ["name", "age"])
const hash2 = Hash.structureKeys(person, ["name", "city"])

hash1 // => -731887653
hash2 // => 148523102

const person2 = { name: "John", age: 30, city: "Boston" }
const hash3 = Hash.structureKeys(person2, ["name", "age"])
hash1 === hash3 // => true

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.

interface Hash {
  "~effect/Hash"(): number;
}

import { Hash } from "effect"

class MyClass implements Hash.Hash {
  constructor(private value: number) {}

  [Hash.symbol](): number {
    return Hash.hash(this.value)
  }
}

new MyClass(42)[Hash.symbol]() // => 42

When to use

Use as the computed property key for the method that supplies a custom hash value on a Hash implementor.

See

• Hash for the interface implemented with this symbol
• isHash for checking whether a value implements Hash
• hash for computing hash values

declare const symbol: "~effect/Hash"