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.

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

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

• hash for the general-purpose hash dispatcher

declare const 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) // => 6151
Hash.array(arr2) // => 6151
Hash.array(arr3) // => 6151
Hash.array(arr1) === Hash.array(arr2) // => true
Hash.array(arr1) === Hash.array(arr3) // => true

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

• 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

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.

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

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.

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

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.

declare function optimize(n: number): number

import { Hash } from "effect"

Hash.optimize(1234567890) // => 160826066

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.

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"

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.

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

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.

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) // => -590673747
Hash.structure(obj2) // => -590160631
Hash.structure(obj3) // => -590673747
Hash.structure(obj1) === Hash.structure(obj3) // => true

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.

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 // => -590673747
hash2 // => 284850673

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

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.

interface Hash {
  "~effect/interfaces/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

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

• 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/interfaces/Hash"