DOCSEARCHbyAlgolia
Submit Docs

fnv1a

repository·main·Indexed 42 days ago

https://github.com/sindresorhus/fnv1a

A high-performance, non-cryptographic FNV-1a hash function implementation for strings and Uint8Array buffers. Version 3.1.0 supports hash sizes of 32, 64, 128, 256, 512, and 1024 bits, returning results as a positive BigInt. It includes a utf8Buffer option to optimize performance by reusing buffers during UTF-8 encoding.

Tokens
1.2K
Snippets
7
Records
7
Agent score
5%

What's inside fnv1a

  2. Optimize string hashing with utf8Buffer

    main

    When hashing strings, fnv1a normally creates a new Uint8Array via TextEncoder.encode(). To avoid this allocation and improve performance (especially in tight loops), you can provide a utf8Buffer via the options object. The function will use TextEncoder.encodeInto() to write the string bytes directly into your provided buffer.

    Note: The utf8Buffer must have a length greater than zero. If it is provided but has a length of 0, the function will throw an error.

    const buffer = new Uint8Array(1024);
const hash = fnv1a('my string', { utf8Buffer: buffer });

  3. Use fnv1a for hashing strings and bytes

    main

    You can hash strings or Uint8Array buffers using fnv1a. The function returns the hash as a positive BigInt. If you require a standard JavaScript number, use a bit size of 32 and wrap the result in Number().

    import fnv1a from '@sindresorhus/fnv1a';

// Hashing a string with 32-bit size
fnv1a('🦄🌈', {size: 32});
//=> 2868248295n

// Converting a 32-bit hash to a Number
Number(fnv1a('🦄🌈', {size: 32}));
//=> 2868248295

// Hashing a Uint8Array
const bytes = new Uint8Array([240, 159, 166, 132, 240, 159, 140, 136]);
fnv1a(bytes, {size: 32});
//=> 2868248295n

  5. Configure fnv1a options

    main

    The options object allows you to control the hash bit size and optimize performance for string encoding.

    size

    Type: number | Default: 32
    Specifies the bit size of the hash. Supported values: 32 | 64 | 128 | 256 | 512 | 1024.

    utf8Buffer

    Type: Uint8Array
    Used when value is a string. Providing a pre-allocated Uint8Array allows the function to reuse the buffer for UTF-8 encoding, avoiding new allocations and improving performance. The buffer does not need to be large enough to hold the entire string, but performance is better if it is.

    import fnv1a from '@sindresorhus/fnv1a';

// Performance optimization using a reusable utf8Buffer
const utf8Buffer = new Uint8Array(100);
fnv1a('🦄🌈', {size: 32, utf8Buffer});
//=> 2868248295n

  6. Use the fnv1a function to generate a non-cryptographic hash

    main

    The fnv1a function generates a non-cryptographic FNV-1a hash as a BigInt. It supports multiple hash sizes and can be optimized for strings using a provided utf8Buffer to avoid unnecessary memory allocations.

    Parameters

    • value: The value to hash. Can be a string or a Uint8Array.
    • options (optional):
      • size: The bit size of the hash. Must be one of 32, 64, 128, 256, 512, or 1024. Defaults to 32.
      • utf8Buffer: A Uint8Array used to encode strings into UTF-8 bytes. Providing this is highly recommended when hashing strings to improve performance by reusing the buffer.

    Returns

    • A BigInt representing the calculated hash.
    import fnv1a from 'fnv1a';

// Basic usage with a string (defaults to 32-bit)
const hash = fnv1a('hello');

// Usage with a specific size
const hash64 = fnv1a('hello', { size: 64 });

// Optimized usage for strings using a reusable buffer
const buffer = new Uint8Array(1024);
const hashOptimized = fnv1a('hello', { size: 64, utf8Buffer: buffer });

// Usage with a Uint8Array
const bytes = new Uint8Array([1, 2, 3]);
const hashBytes = fnv1a(bytes);

  7. Configure the hash size for fnv1a

    main

    The size option determines the bit length of the resulting hash. The function only supports specific bit sizes. If an unsupported size is provided, the function will throw an error.

    Supported sizes:

    • 32
    • 64
    • 128
    • 256
    • 512
    • 1024
    fnv1a(value, { size: 64 });