or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-farmhash

Node.js implementation of FarmHash, Google's family of very fast hash functions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/farmhash@4.0.x

To install, run

npx @tessl/cli install tessl/npm-farmhash@4.0.0

index.mddocs/

FarmHash

FarmHash is a Node.js implementation of Google's FarmHash family of very fast, non-cryptographic hash functions. It provides both platform-independent fingerprint methods and platform-dependent hash methods with optimizations for different CPU architectures including SSE4.2 and AVX intrinsics.

Package Information

  • Package Name: farmhash
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install farmhash

Core Imports

const farmhash = require('farmhash');

For ES modules:

import * as farmhash from 'farmhash';

Basic Usage

const farmhash = require('farmhash');

// Platform-independent fingerprinting
const fingerprint = farmhash.fingerprint32('hello world');
console.log(fingerprint); // number

const fp64 = farmhash.fingerprint64('hello world');
console.log(fp64); // bigint

// Platform-dependent hashing (optimized for current CPU)
const hash = farmhash.hash32('hello world');
console.log(hash); // number

const hashWithSeed = farmhash.hash32WithSeed('hello world', 42);
console.log(hashWithSeed); // number

Architecture

FarmHash provides two distinct API categories optimized for different use cases:

  • Fingerprint Methods: Platform-independent functions that produce consistent results across different architectures and CPU types. Ideal for distributed systems, checksums, and data integrity verification.
  • Hash Methods: Platform-dependent functions optimized for specific CPU features (SSE4.2, AVX) that may produce different results on different machines but offer maximum performance. Best for local hashing, hash tables, and performance-critical applications.

Both categories support multiple input types (String and Buffer) and provide both 32-bit and 64-bit output options.

Capabilities

Fingerprint Methods (Platform Independent)

Platform-independent fingerprint functions that produce consistent results across different architectures. These are ideal for distributed systems where hash consistency is required.

/**
 * Generate 32-bit unsigned integer fingerprint value
 * @param input - String or Buffer to fingerprint  
 * @returns 32-bit unsigned integer fingerprint
 * @throws Error if input is not String or Buffer
 */
function fingerprint32(input: string | Buffer): number;

/**
 * Generate 64-bit unsigned integer fingerprint value
 * @param input - String or Buffer to fingerprint
 * @returns 64-bit unsigned integer fingerprint as BigInt
 * @throws Error if input is not String or Buffer  
 */
function fingerprint64(input: string | Buffer): bigint;

/**
 * Generate 64-bit signed integer fingerprint value
 * Compatible with Google BigQuery's FARM_FINGERPRINT function
 * @param input - String or Buffer to fingerprint
 * @returns 64-bit signed integer fingerprint as BigInt
 * @throws Error if input is not String or Buffer
 */
function fingerprint64signed(input: string | Buffer): bigint;

Usage Examples:

const farmhash = require('farmhash');

// Consistent fingerprints across platforms
const data = 'The quick brown fox';
const fp32 = farmhash.fingerprint32(data);
const fp64 = farmhash.fingerprint64(data);
const fp64signed = farmhash.fingerprint64signed(data);

// Works with Buffers too
const buffer = Buffer.from('binary data', 'utf8');
const bufferFingerprint = farmhash.fingerprint32(buffer);

// BigQuery compatibility
const bqCompatible = farmhash.fingerprint64signed('test data');
console.log(bqCompatible.toString()); // Matches BigQuery FARM_FINGERPRINT

Hash Methods (Platform Dependent)

Platform-dependent hash functions optimized for the current CPU architecture. These may produce different results on different machines but offer maximum performance.

/**
 * Generate 32-bit unsigned integer hash value
 * @param input - String or Buffer to hash
 * @returns 32-bit unsigned integer hash
 * @throws Error if input is not String or Buffer
 */
function hash32(input: string | Buffer): number;

/**
 * Generate 32-bit unsigned integer hash value with seed
 * @param input - String or Buffer to hash
 * @param seed - Integer seed value
 * @returns 32-bit unsigned integer hash
 * @throws Error if input is not String or Buffer, or seed is not integer
 */
function hash32WithSeed(input: string | Buffer, seed: number): number;

/**
 * Generate 64-bit unsigned integer hash value
 * @param input - String or Buffer to hash
 * @returns 64-bit unsigned integer hash as BigInt
 * @throws Error if input is not String or Buffer
 */
function hash64(input: string | Buffer): bigint;

/**
 * Generate 64-bit unsigned integer hash value with seed
 * @param input - String or Buffer to hash
 * @param seed - Integer seed value
 * @returns 64-bit unsigned integer hash as BigInt
 * @throws Error if input is not String or Buffer, or seed is not integer
 */
function hash64WithSeed(input: string | Buffer, seed: number): bigint;

/**
 * Generate 64-bit unsigned integer hash value with two seeds
 * @param input - String or Buffer to hash
 * @param seed1 - First integer seed value
 * @param seed2 - Second integer seed value
 * @returns 64-bit unsigned integer hash as BigInt
 * @throws Error if input is not String or Buffer, or seeds are not integers
 */
function hash64WithSeeds(input: string | Buffer, seed1: number, seed2: number): bigint;

Usage Examples:

const farmhash = require('farmhash');

// Basic hashing
const data = 'performance critical data';
const hash32 = farmhash.hash32(data);
const hash64 = farmhash.hash64(data);

// Seeded hashing for hash tables
const seed = 12345;
const seededHash = farmhash.hash32WithSeed(data, seed);

// Double-seeded hashing for advanced use cases
const hash2seeds = farmhash.hash64WithSeeds(data, 111, 222);

// Buffer hashing for binary data
const binaryData = Buffer.from([0x01, 0x02, 0x03, 0x04]);
const binaryHash = farmhash.hash64(binaryData);

Error Handling

All functions validate their inputs and throw descriptive errors:

  • Invalid input type: Throws Error('Expected a String or Buffer for input') if input is not String or Buffer
  • Invalid seed type: Throws Error('Expected an integer for seed') if seed parameter is not an integer
const farmhash = require('farmhash');

try {
  // This will throw - invalid input type
  farmhash.hash32(123);
} catch (error) {
  console.log(error.message); // "Expected a String or Buffer for input"
}

try {
  // This will throw - invalid seed type  
  farmhash.hash32WithSeed('data', 'not a number');
} catch (error) {
  console.log(error.message); // "Expected an integer for seed"
}

Performance Notes

  • Pre-compiled binaries are available for Intel CPUs with SSE4.2 intrinsics and ARM64 CPUs
  • Build from source using npm install --build-from-source to enable additional CPU-specific optimizations (AVX intrinsics)
  • Platform-dependent methods (hash*) are optimized for the target CPU architecture
  • Platform-independent methods (fingerprint*) prioritize consistency over maximum performance
  • BigInt return values for 64-bit functions ensure full precision in JavaScript environments

Requirements

  • Node.js: >= 16
  • Native Dependencies: Uses N-API v8 for optimal compatibility across Node.js versions