cmpstr/dist/types/utils/HashTable.d.ts

CmpStr is a lightweight, fast and well performing package for calculating string similarity

/**
 * Hash Table Utility
 * src/utils/HashTable.ts
 *
 * @see https://en.wikipedia.org/wiki/Fowler–Noll–Vo_hash_function
 * @see https://en.wikipedia.org/wiki/MurmurHash
 * @see https://en.wikipedia.org/wiki/Hash_table
 *
 * This module implements an instantiable hash table/cache using a modified FNV-1a hash
 * algorithm, optimized for speed and low collision rates.
 *
 * It allows for multiple independent caches (e.g. for metrics, normalization, etc.) with
 * type safety and high performance.
 *
 * The key() method supports any number of string arguments, enabling flexible cache keys
 * for different use cases (e.g. normalization, metrics, etc.).
 *
 * @module Utils
 * @name HashTable
 * @author Paul Köhler (komed3)
 * @license MIT
 */
/**
 * Hasher Utility
 * Static class for modified FNV-1a hash algorithm implementation.
 */
export declare class Hasher {
    /** Constants for the hash algorithm */
    private static readonly FNV_PRIME;
    private static readonly HASH_OFFSET;
    /**
     * Computes a hash value for a given string using the FNV-1a algorithm.
     *
     * Modifications:
     * - Processes 4 characters at a time (chunks)
     * - Using MurmurHash3 finalizer
     *
     * @param {string} str - The string to hash
     * @return {number} - The computed hash value as an unsigned 32-bit integer
     */
    static fastFNV1a(str: string): number;
}
/**
 * HashTable class implements an instantiable hash table/cache.
 * Allows for multiple independent caches with type safety and high performance.
 *
 * @template K - The type of the label for the key (e.g. string, MetricName, …)
 * @template T - The type of value to be stored in the hash table (e.g. MetricCompute, string, …)
 */
export declare class HashTable<K extends string, T> {
    private readonly LRU;
    /** The max. length of a string to hash, which is set to 2048 characters */
    private static readonly MAX_LEN;
    /** The max. size of the hash table, which is set to 10,000 */
    private static readonly TABLE_SIZE;
    /**
     * The internal map to store entries.
     * The key is a string generated from the label and any number of hashed strings.
     * The value is of type T.
     */
    private table;
    /**
     * Creates an instance of HashTable.
     *
     * @param {boolean} [LRU=true] - Whether to use Least Recently Used (LRU) eviction policy
     */
    constructor(LRU?: boolean);
    /**
     * Generates a unique hash key for any number of string arguments.
     * Return false if any string exceeds the maximum length.
     * The key is in the format "label-H1-H2-H3-..."
     *
     * @param {K} label - Label for this key (e.g. metric name, normalization flags, …)
     * @param {string[]} strs - Array of strings to hash (e.g. input, params, …)
     * @param {boolean} [sorted=false] - Whether to sort the hashes before creating the key
     * @returns {string | false} - A unique hash key or false if any string is too long
     */
    key(label: K, strs: string[], sorted?: boolean): string | false;
    /**
     * Checks if a key exists in the hash table.
     *
     * @param {string} key - The key to check
     * @returns {boolean} - True if the key exists, false otherwise
     */
    has: (key: string) => boolean;
    /**
     * Retrieves the entry from the hash table by its key.
     *
     * @param {string} key - The key to look up
     * @returns {T | undefined} - The entry if found, undefined otherwise
     */
    get: (key: string) => T | undefined;
    /**
     * Adds an entry to the hash table.
     * If the table is full, it evicts the least recently used entry (if LRU is enabled).
     *
     * @param {string} key - The hashed key for the entry
     * @param {T} entry - The entry itself to add
     * @param {boolean} [update=true] - Whether to update the entry if it already exists
     * @returns {boolean} - True if added successfully, false if the table is full
     */
    set(key: string, entry: T, update?: boolean): boolean;
    /**
     * Deletes an entry from the hash table by its key.
     *
     * @param {string} key - The key of the entry to delete
     * @returns {boolean} - True if the entry was deleted, false if the key was not found
     */
    delete: (key: string) => boolean;
    /**
     * Clears the hash table.
     * This method removes all entries from the hash table.
     */
    clear: () => void;
    /**
     * Returns the current size of the hash table.
     *
     * @returns {number} - The number of entries in the hash table
     */
    size: () => number;
}