CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-parcel--hash

High-performance hashing utility providing xxHash-based functions for strings and buffers

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

@parcel/hash

@parcel/hash is a high-performance hashing utility designed for the Parcel bundler ecosystem. It provides xxHash (XXH3) implementations through dual execution environments: a JavaScript version using xxhash-wasm for browser compatibility and a native Rust implementation using xxhash-rust with napi-rs bindings for Node.js environments.

Package Information

  • Package Name: @parcel/hash
  • Package Type: npm
  • Language: JavaScript with Rust native bindings
  • Installation: npm install @parcel/hash

Core Imports

const { hashString, hashBuffer, Hash, init } = require('@parcel/hash');

For ES modules:

import { hashString, hashBuffer, Hash, init } from '@parcel/hash';

Basic Usage

Node.js Environment (Native Rust)

const { hashString, hashBuffer, Hash } = require('@parcel/hash');

// Hash a string
const stringHash = hashString('hello world');
console.log(stringHash); // '0123456789abcdef' (16-char hex)

// Hash a buffer
const buffer = Buffer.from('hello world', 'utf8');
const bufferHash = hashBuffer(buffer);
console.log(bufferHash); // '0123456789abcdef' (16-char hex)

// Incremental hashing
const hash = new Hash();
hash.writeString('hello ');
hash.writeString('world');
const result = hash.finish();
console.log(result); // '0123456789abcdef' (16-char hex)

Browser Environment (WebAssembly)

import { hashString, hashBuffer, Hash, init } from '@parcel/hash';

// Initialize the WASM module first
await init;

// Hash a string
const stringHash = hashString('hello world');
console.log(stringHash); // '0123456789abcdef' (16-char hex)

// Hash a Uint8Array
const buffer = new TextEncoder().encode('hello world');
const bufferHash = hashBuffer(buffer);
console.log(bufferHash); // '0123456789abcdef' (16-char hex)

// Incremental hashing
const hash = new Hash();
hash.writeString('hello ');
hash.writeString('world');
const result = hash.finish();
console.log(result); // '0123456789abcdef' (16-char hex)

Architecture

@parcel/hash implements a dual-target strategy:

  • Node.js: Native Rust implementation via napi-rs bindings for maximum performance
  • Browser: JavaScript implementation using xxhash-wasm for cross-platform compatibility
  • Algorithm: xxHash3 (XXH3_64) for consistent, high-performance hashing
  • Output Format: 64-bit hash values formatted as 16-character hexadecimal strings

Capabilities

String Hashing

Hash string inputs using the xxHash3 algorithm.

/**
 * Hash a string using xxHash3 algorithm
 * @param s - The input string to hash
 * @returns 16-character hexadecimal hash string
 */
function hashString(s: string): string;

Buffer Hashing

Hash binary data using the xxHash3 algorithm.

/**
 * Hash a buffer using xxHash3 algorithm
 * @param b - The input buffer to hash (Buffer in Node.js, Uint8Array in browser)
 * @returns 16-character hexadecimal hash string
 */
function hashBuffer(b: Buffer | Uint8Array): string;

Incremental Hashing

Build hashes incrementally from multiple inputs using the Hash class.

/**
 * Hash class for incremental hashing operations
 */
class Hash {
  /**
   * Create a new Hash instance
   */
  constructor();

  /**
   * Add a string to the incremental hash
   * @param s - String to add to the hash
   */
  writeString(s: string): void;

  /**
   * Add a buffer to the incremental hash
   * @param b - Buffer to add to the hash (Buffer in Node.js, Uint8Array in browser)
   */
  writeBuffer(b: Buffer | Uint8Array): void;

  /**
   * Finalize the incremental hash and return the result
   * @returns 16-character hexadecimal hash string
   */
  finish(): string;
}

Initialization (Browser Only)

WebAssembly module initialization for browser environments.

/**
 * Promise that resolves when the WASM module is initialized (browser only)
 * Must be awaited before using other functions in browser environment
 */
const init: Promise<void>;

Usage Examples

Single-Shot Hashing

const { hashString, hashBuffer } = require('@parcel/hash');

// Hash strings
const hash1 = hashString('user123');
const hash2 = hashString('file-content-data');

// Hash buffers
const jsonData = Buffer.from(JSON.stringify({id: 123, name: 'test'}));
const jsonHash = hashBuffer(jsonData);

const binaryData = new Uint8Array([0xFF, 0x00, 0xAB, 0xCD]);
const binaryHash = hashBuffer(binaryData);

Incremental Hashing for Complex Data

const { Hash } = require('@parcel/hash');

// Build hash from multiple components
const hash = new Hash();
hash.writeString('module:');
hash.writeString(moduleName);
hash.writeString(':version:');
hash.writeString(moduleVersion);
hash.writeBuffer(moduleContent);

const finalHash = hash.finish();

Browser with Async Initialization

import { init, hashString, Hash } from '@parcel/hash';

async function computeHashes() {
  // Wait for WASM initialization
  await init;
  
  // Now safe to use hashing functions
  const quickHash = hashString('fast-computation');
  
  const incrementalHash = new Hash();
  incrementalHash.writeString('browser-');
  incrementalHash.writeString('compatible');
  const result = incrementalHash.finish();
  
  return { quickHash, result };
}

Performance Characteristics

  • Deterministic: Same input always produces the same hash
  • Fast: xxHash3 algorithm optimized for speed
  • Consistent: Identical output across Node.js and browser environments
  • 64-bit: Full 64-bit hash space with minimal collision probability
  • Cross-platform: Works identically in Node.js (native) and browsers (WASM)

Error Handling

Browser Environment

In browser environments, ensure the WASM module initializes successfully:

import { init, hashString } from '@parcel/hash';

try {
  await init;
  const hash = hashString('data');
} catch (error) {
  console.error('Failed to initialize WASM module:', error);
  // Fallback to alternative hashing if needed
}

Node.js Environment

Native bindings should load automatically. If native bindings fail to load, the package will fall back to the browser implementation:

const { hashString } = require('@parcel/hash');

try {
  const hash = hashString('data');
} catch (error) {
  console.error('Hashing failed:', error);
}

Common Use Cases

  • File Content Hashing: Generate consistent hashes for file contents in build processes
  • Cache Keys: Create reliable cache keys for bundling and asset management
  • Data Integrity: Verify data consistency across transformations
  • Incremental Builds: Hash multiple inputs to determine when rebuilds are needed
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@parcel/hash@2.9.x
Publish Source
CLI
Badge
tessl/npm-parcel--hash badge