@esfx/equatable Package

Provides a low level API for defining equality.

Installation

npm i @esfx/equatable

Usage

TypeScript
JavaScript (CommonJS)

import { Equatable, Equaler, Comparable, Comparer } from "@esfx/equatable";

class Person {
    firstName: string;
    lastName: string;
    constructor(firstName: string, lastName: string) {
        this.firstName = firstName;
        this.lastName = lastName;
    }

    toString() {
        return `${this.firstName} ${this.lastName}`;
    }

    [Equatable.equals](other: unknown) {
        return other instanceof Person
            && this.lastName === other.lastName
            && this.firstName === other.firstName;
    }

    [Equatable.hash]() {
        return Equaler.defaultEqualer.hash(this.lastName)
            ^ Equaler.defaultEqualer.hash(this.firstName);
    }

    [Comparable.compareTo](other: unknown) {
        if (!(other instanceof Person)) throw new TypeError();
        return Comparer.defaultComparer.compare(this.lastName, other.lastName)
            || Comparer.defaultComparer.compare(this.firstName, other.firstName);
    }
}

const people = [
    new Person("Alice", "Johnson"),
    new Person("Bob", "Clark")
];
people.sort(Comparer.defaultComparer.compare);
console.log(people); // Bob Clark,Alice Johnson

const obj1 = new Person("Bob", "Clark");
const obj2 = new Person("Bob", "Clark");
obj1 === obj2; // false
Equaler.defaultEqualer.equals(obj1, obj2); // true

const { Equatable, Equaler, Comparable, Comparer } = require("@esfx/equatable");

class Person {
    constructor(firstName, lastName) {
        this.firstName = firstName;
        this.lastName = lastName;
    }

    toString() {
        return `${this.firstName} ${this.lastName}`;
    }

    [Equatable.equals](other) {
        return other instanceof Person
            && this.lastName === other.lastName
            && this.firstName === other.firstName;
    }

    [Equatable.hash]() {
        return Equaler.defaultEqualer.hash(this.lastName)
            ^ Equaler.defaultEqualer.hash(this.firstName);
    }

    [Comparable.compareTo](other) {
        if (!(other instanceof Person)) throw new TypeError();
        return Comparer.defaultComparer.compare(this.lastName, other.lastName)
            || Comparer.defaultComparer.compare(this.firstName, other.firstName);
    }
}

const people = [
    new Person("Alice", "Johnson"),
    new Person("Bob", "Clark")
];
people.sort(Comparer.defaultComparer.compare);
console.log(people); // Bob Clark,Alice Johnson

const obj1 = new Person("Bob", "Clark");
const obj2 = new Person("Bob", "Clark");
obj1 === obj2; // false
Equaler.defaultEqualer.equals(obj1, obj2); // true

Interfaces

Comparable

Represents a value that can compare itself relationally with another value.

Comparer<T>

Represents an object that can be used to perform a relational comparison between two values.

Equaler<T>

Represents an object that can be used to compare the equality of two values.

Equatable

Represents a value that can compare its equality with another value.

StructuralComparable

Represents a value that can compare its structure relationally with another value.

StructuralEquatable

Represents a value that can compare its structural equality with another value.

Functions

combineHashes(x, y, rotate)

Combines two hash codes.

Declaration

function combineHashes(x: number, y: number, rotate?: number): number;

Parameters

x: number

The first hash code.

y: number

The second hash code.

rotate: number

The number of bits (between 0 and 31) to left-rotate the first hash code before XOR'ing it with the second (default 7).

Returns

number

rawHash(value)

Gets the raw hashcode for a value. This bypasses any [Equatable.hash] properties on an object.

Declaration

export declare function rawHash(value: unknown): number;

Parameters

value: unknown

Any value.

Returns

number

The hashcode for the value.

Variables

defaultComparer

The default Comparer.

Declaration

defaultComparer: Comparer<unknown>

defaultEqualer

Gets the default Equaler.

Declaration

defaultEqualer: Equaler<unknown>

structuralComparer

A default Comparer that supports StructuralComparable values.

Declaration

structuralComparer: Comparer<unknown>

structuralEqualer

Gets a default Equaler that supports StructuralEquatable values.

Declaration

structuralEqualer: Equaler<unknown>

tupleComparer

A default Comparer that compares array values rather than the arrays themselves.

Declaration

tupleComparer: Comparer<readonly unknown[]>

tupleEqualer

An Equaler that compares array values rather than the arrays themselves.

Declaration

tupleEqualer: Equaler<readonly unknown[]>

tupleStructuralComparer

A default Comparer that compares array values that may be StructuralComparable rather than the arrays themselves.

Declaration

tupleStructuralComparer: Comparer<readonly unknown[]>

Type Aliases

Comparison

Describes a function that can be used to compare the relational equality of two values, returning a value indicating one of the following conditions:

A negative value indicates x is lesser than y.
A positive value indicates x is greater than y.
A zero value indicates x and y are equivalent.

Declaration

export declare type Comparison<T> = (x: T, y: T) => number;

Type Parameters

T

The type of value that can be compared.

EqualityComparison

Describes a function that can be used to compare the equality of two values.

Declaration

export declare type EqualityComparison<T> = (x: T, y: T) => boolean;

Type Parameters

T

The type of value that can be compared.

HashGenerator

Describes a function that can be used to compute a hash code for a value.

Declaration

export declare type HashGenerator<T> = (x: T) => number;

Type Parameters

T

The type of value that can be hashed.

Namespaces

Comparable

Utility functions and well-known symbols used to define a Comparable.

Comparer

Provides various implementations of Comparer.

Equaler

Provides various implementations of Equaler.

Equatable

Utility functions and well-known symbols used to define an Equatable.

StructuralComparable

Utility functions and well-known symbols used to define a StructuralComparable.

StructuralEquatable

Utility functions and well-known symbols used to define a StructuralEquatable.