Browser / Nodejs Compatible Object Hashing
WebCrypto API for both environmentsparse and stringify with custom functionsnpm install hashery
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Hash an object (defaults to SHA-256)
const hash = await hashery.toHash({ name: 'John', age: 30 });
console.log(hash); // SHA-256 hash string
// Hash a string
const stringHash = await hashery.toHash('hello world');
// Hash any value (numbers, arrays, etc.)
const numberHash = await hashery.toHash(42);
const arrayHash = await hashery.toHash([1, 2, 3, 4, 5]);
For performance-critical applications or when you need to avoid async/await, use the synchronous hashing methods. These work with non-cryptographic hash algorithms (djb2, fnv1, murmer, crc32) and are significantly faster than WebCrypto methods.
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Synchronous hash (defaults to djb2)
const hash = hashery.toHashSync({ name: 'John', age: 30 });
console.log(hash); // djb2 hash string (8 hex characters)
// Sync with specific algorithm
const fnv1Hash = hashery.toHashSync({ data: 'example' }, { algorithm: 'fnv1' });
const murmerHash = hashery.toHashSync({ data: 'example' }, { algorithm: 'murmer' });
const crcHash = hashery.toHashSync({ data: 'example' }, { algorithm: 'crc32' });
// Note: WebCrypto algorithms (SHA-256, SHA-384, SHA-512) are NOT supported in sync mode
// This will throw an error:
// hashery.toHashSync({ data: 'example' }, { algorithm: 'SHA-256' }); // ❌ Error!
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Use SHA-384
const hash384 = await hashery.toHash({ data: 'example' }, { algorithm: 'SHA-384' });
// Use SHA-512
const hash512 = await hashery.toHash({ data: 'example' }, { algorithm: 'SHA-512' });
// Use non-crypto hash algorithms
const fastHash = await hashery.toHash({ data: 'example' }, { algorithm: 'djb2' });
You can set a default algorithm for all hash operations via constructor or property:
import { Hashery } from 'hashery';
// Set default algorithm via constructor
const hashery = new Hashery({ defaultAlgorithm: 'SHA-512' });
// Now all hashes use SHA-512 by default
const hash1 = await hashery.toHash({ data: 'example' }); // Uses SHA-512
console.log(hash1.length); // 128 (SHA-512 produces 128 hex characters)
// You can still override it per call
const hash2 = await hashery.toHash({ data: 'example' }, { algorithm: 'SHA-256' });
console.log(hash2.length); // 64 (SHA-256 produces 64 hex characters)
// Change default algorithm at runtime
hashery.defaultAlgorithm = 'djb2';
const hash3 = await hashery.toHash({ data: 'example' }); // Uses djb2
You can limit the length of the hash output using the maxLength option:
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Get a shorter hash (16 characters instead of 64)
const shortHash = await hashery.toHash(
{ data: 'example' },
{ algorithm: 'SHA-256', maxLength: 16 }
);
console.log(shortHash); // "3f79bb7b435b0518" (16 chars)
// Full hash for comparison
const fullHash = await hashery.toHash({ data: 'example' });
console.log(fullHash); // "3f79bb7b435b05181e4ccf0d4e8..." (64 chars)
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Convert hash to a number within a range
const slot = await hashery.toNumber({ userId: 123 }, { min: 0, max: 100 });
console.log(slot); // Deterministic number between 0-100
// Use for consistent slot assignment
const userSlot = await hashery.toNumber({ userId: 'user@example.com' }, { min: 0, max: 9 });
// Same user will always get the same slot number
Generate deterministic numbers synchronously for high-performance scenarios. Perfect for A/B testing, sharding, and load balancing without async overhead.
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Synchronous number generation (defaults to djb2)
const slot = hashery.toNumberSync({ userId: 123 }, { min: 0, max: 100 });
console.log(slot); // Deterministic number between 0-100
// A/B testing without async/await
const variant = hashery.toNumberSync({ userId: 'user123' }, { min: 0, max: 1 });
console.log(variant === 0 ? 'Group A' : 'Group B');
// Load balancing across servers
const serverIndex = hashery.toNumberSync(
{ requestId: 'req_abc123' },
{ min: 0, max: 9, algorithm: 'fnv1' } // 10 servers
);
// Sharding assignment
const shardId = hashery.toNumberSync(
{ customerId: 'cust_xyz' },
{ min: 0, max: 15, algorithm: 'murmer' } // 16 shards
);
// Set default sync algorithm for all sync operations
const hashery2 = new Hashery({ defaultAlgorithmSync: 'fnv1' });
const num = hashery2.toNumberSync({ data: 'test' }); // Uses fnv1 by default
Hashery works seamlessly in the browser using the Web Crypto API. You can include it via CDN or bundle it with your application.
<!DOCTYPE html>
<html>
<head>
<title>Hashery Browser Example</title>
</head>
<body>
<script type="module">
import { Hashery } from 'https://cdn.jsdelivr.net/npm/hashery@latest/dist/browser/index.js';
const hashery = new Hashery();
// Hash data in the browser
const hash = await hashery.toHash({ page: 'home', userId: 123 });
console.log('Hash:', hash);
// Generate slot numbers for A/B testing
const variant = await hashery.toNumber({ userId: 'user123' }, { min: 0, max: 1 });
console.log('A/B Test Variant:', variant === 0 ? 'A' : 'B');
</script>
</body>
</html>
Hashery extends Hookified to provide event-based functionality through hooks. Hooks allow you to intercept and modify behavior during the hashing process.
before:toHashFired before hashing occurs. This hook receives a context object containing:
data - The data to be hashed (can be modified)algorithm - The hash algorithm to use (can be modified)maxLength - Optional maximum length for the hash outputafter:toHashFired after hashing completes. This hook receives a result object containing:
hash - The generated hash (can be modified)data - The data that was hashedalgorithm - The algorithm that was usedbefore:toHashSyncFired before synchronous hashing occurs. This hook receives a context object containing:
data - The data to be hashed (can be modified)algorithm - The hash algorithm to use (can be modified)maxLength - Optional maximum length for the hash outputNote: This hook fires asynchronously (non-blocking) to maintain the synchronous nature of toHashSync(). Hook execution happens in the background and won't delay the method's return.
after:toHashSyncFired after synchronous hashing completes. This hook receives a result object containing:
hash - The generated hash (can be modified)data - The data that was hashedalgorithm - The algorithm that was usedNote: This hook fires asynchronously (non-blocking) to maintain the synchronous nature of toHashSync(). Hook execution happens in the background.
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Listen to before:toHash hook
hashery.onHook('before:toHash', async (context) => {
console.log('About to hash:', context.data);
console.log('Using algorithm:', context.algorithm);
});
// Listen to after:toHash hook
hashery.onHook('after:toHash', async (result) => {
console.log('Hash generated:', result.hash);
console.log('Original data:', result.data);
});
await hashery.toHash({ name: 'John', age: 30 });
You can modify the data before it's hashed:
const hashery = new Hashery();
// Add a timestamp to all hashed data
hashery.onHook('before:toHash', async (context) => {
context.data = {
original: context.data,
timestamp: new Date().toISOString()
};
});
const hash = await hashery.toHash({ userId: 123 });
// Data will be hashed with timestamp included
You can force a specific algorithm regardless of what's requested:
const hashery = new Hashery();
// Force all hashes to use SHA-512
hashery.onHook('before:toHash', async (context) => {
context.algorithm = 'SHA-512';
});
// Even though we request SHA-256, it will use SHA-512
const hash = await hashery.toHash({ data: 'example' }, { algorithm: 'SHA-256' });
console.log(hash.length); // 128 (SHA-512 hash length)
You can transform the hash after it's generated:
const hashery = new Hashery();
// Convert all hashes to uppercase
hashery.onHook('after:toHash', async (result) => {
result.hash = result.hash.toUpperCase();
});
const hash = await hashery.toHash({ data: 'example' });
console.log(hash); // Hash will be in uppercase
Use hooks to implement a caching layer:
const hashery = new Hashery();
const cache = new Map<string, string>();
// Store hashes in cache after generation
hashery.onHook('after:toHash', async (result) => {
const cacheKey = `${result.algorithm}:${JSON.stringify(result.data)}`;
cache.set(cacheKey, result.hash);
});
// Later you can check the cache before hashing
// (Note: You would need to implement cache lookup logic in your application)
Hooks are perfect for logging and debugging:
const hashery = new Hashery();
hashery.onHook('before:toHash', async (context) => {
console.log(`[DEBUG] Hashing data with ${context.algorithm}:`, context.data);
});
hashery.onHook('after:toHash', async (result) => {
console.log(`[DEBUG] Hash generated: ${result.hash.substring(0, 8)}...`);
});
await hashery.toHash({ userId: 'user123' });
You can register multiple hooks, and they will execute in the order they were registered:
const hashery = new Hashery();
hashery.onHook('before:toHash', async (context) => {
console.log('First hook');
context.data = { step: 1, original: context.data };
});
hashery.onHook('before:toHash', async (context) => {
console.log('Second hook');
context.data = { step: 2, previous: context.data };
});
await hashery.toHash({ name: 'test' });
// Output: "First hook" then "Second hook"
// Data will be wrapped twice
Synchronous methods (toHashSync, toNumberSync) support hooks, but they fire asynchronously in the background to maintain the synchronous nature of the methods.
const hashery = new Hashery();
// Listen to synchronous hash hooks
hashery.onHook('before:toHashSync', async (context) => {
console.log('About to hash synchronously:', context.data);
console.log('Using algorithm:', context.algorithm);
});
hashery.onHook('after:toHashSync', async (result) => {
console.log('Sync hash generated:', result.hash);
});
// Call synchronous method - hooks fire in background
const hash = hashery.toHashSync({ name: 'John', age: 30 });
console.log('Method returned:', hash);
// Method returns immediately, hooks execute asynchronously
Important Notes:
toHash, toNumber)Synchronous methods are designed for maximum performance. Making hooks blocking would defeat this purpose. The async hook execution allows:
If you need hooks that modify data or behavior, use the async methods (toHash, toNumber).
When an invalid or unknown hash algorithm is provided to toHash() or toHashSync(), Hashery emits a 'warn' event and automatically falls back to the default algorithm instead of throwing an error. This ensures your application continues to work even when invalid algorithms are specified.
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Listen for warning events
hashery.on('warn', (message: string) => {
console.log('Warning:', message);
});
// Using an invalid algorithm will trigger the warning
const hash = await hashery.toHash({ data: 'test' }, { algorithm: 'invalid-algo' });
// Warning: Invalid algorithm 'invalid-algo' not found. Falling back to default algorithm 'SHA-256'.
// Hash is still generated using SHA-256 (the default)
console.log(hash); // Valid SHA-256 hash
For async methods (toHash, toNumber):
defaultAlgorithm (SHA-256 by default)For sync methods (toHashSync, toNumberSync):
defaultAlgorithmSync (djb2 by default)The warning message includes both the invalid algorithm name and the fallback algorithm being used:
Invalid algorithm '<requested-algorithm>' not found. Falling back to default algorithm '<default-algorithm>'.
Development/Debugging:
const hashery = new Hashery();
hashery.on('warn', (message) => {
console.error('[Hashery Warning]', message);
// Log to monitoring service, etc.
});
Production Monitoring:
const hashery = new Hashery();
hashery.on('warn', (message) => {
// Send to error tracking service
errorTracker.captureMessage(message, 'warning');
});
Graceful Degradation:
const hashery = new Hashery();
let hasWarnings = false;
hashery.on('warn', () => {
hasWarnings = true;
});
const hash = await hashery.toHash(userData, { algorithm: userPreferredAlgo });
if (hasWarnings) {
// Notify user that their preferred algorithm is not available
console.log('Using default algorithm instead of your preference');
}
You can remove hooks when they're no longer needed:
const hashery = new Hashery();
const myHook = async (context: any) => {
console.log('Hook called');
};
// Add the hook
hashery.onHook('before:toHash', myHook);
// Remove the hook
hashery.offHook('before:toHash', myHook);
// Same works for sync hooks
hashery.onHook('before:toHashSync', myHook);
hashery.offHook('before:toHashSync', myHook);
Control how errors in hooks are handled using the throwOnEmitError option:
// Throw errors that occur in hooks
const hashery1 = new Hashery({ throwOnEmitError: true });
hashery1.onHook('before:toHash', async (context) => {
throw new Error('Hook error');
});
// This will throw the error
await hashery1.toHash({ data: 'example' }); // Throws Error: Hook error
// Silently handle errors in hooks
const hashery2 = new Hashery({ throwOnEmitError: false });
hashery2.onHook('before:toHash', async (context) => {
throw new Error('Hook error');
});
// This will not throw, hashing continues
const hash = await hashery2.toHash({ data: 'example' }); // Returns hash successfully
Hashery includes a built-in FIFO (First In, First Out) cache that stores computed hash values. When the same data is hashed with the same algorithm, the cached result is returned instead of recomputing.
maxSize is reached (default: 4000)import { Hashery } from 'hashery';
// Default: cache enabled with maxSize of 4000
const hashery = new Hashery();
// Custom configuration
const hashery2 = new Hashery({
cache: {
enabled: true, // default: true
maxSize: 10000 // default: 4000
}
});
// Disable cache
const hashery3 = new Hashery({ cache: { enabled: false } });
// Toggle at runtime
hashery.cache.enabled = false;
hashery.cache.enabled = true;
const hashery = new Hashery();
hashery.cache.enabled; // boolean - is caching enabled
hashery.cache.maxSize; // number - maximum entries (default: 4000)
hashery.cache.size; // number - current cached entries
hashery.cache.store; // Map<string, string> - underlying store
hashery.cache.clear(); // Clear all cached entries
The default maxSize of 4000 provides a good balance (~1-2 MB memory). JavaScript Maps can hold up to 2^24 (~16.7 million) entries, but practical limits depend on available memory. For most use cases, 4000-10000 entries is sufficient.
Hashery is built on top of the Web Crypto API, which provides cryptographic operations in both browser and Node.js environments. This ensures consistent, secure hashing across all platforms.
The Web Crypto API is supported in all modern browsers:
Web Crypto API was introduced in Node.js 15.0.0. Hashery is tested against Node.js LTS 20+ and automatically detects and uses the appropriate crypto implementation for your environment via the crypto.webcrypto global.
These algorithms use the Web Crypto API and are only available asynchronously:
These are cryptographically secure and suitable for security-sensitive applications.
These algorithms support both synchronous and asynchronous operation:
Async methods (toHash, toNumber):
SHA-256Sync methods (toHashSync, toNumberSync):
djb2import { Hashery } from 'hashery';
const hashery = new Hashery();
// Web Crypto algorithms
const sha256 = await hashery.toHash({ data: 'example' }); // Default SHA-256
const sha384 = await hashery.toHash({ data: 'example' }, { algorithm: 'SHA-384' });
const sha512 = await hashery.toHash({ data: 'example' }, { algorithm: 'SHA-512' });
// Non-crypto algorithms (faster, but not cryptographically secure)
const djb2Hash = await hashery.toHash({ data: 'example' }, { algorithm: 'djb2' });
const fnv1Hash = await hashery.toHash({ data: 'example' }, { algorithm: 'fnv1' });
DJB2 is a non-cryptographic hash function created by Daniel J. Bernstein. It's known for its simplicity and speed, making it ideal for hash tables, checksums, and other non-security applications.
Good for:
Not suitable for:
| Feature | DJB2 | SHA-256 |
|---|---|---|
| Speed | Very Fast | Slower |
| Security | Not Secure | Cryptographically Secure |
| Hash Length | 32-bit | 256-bit |
| Collision Resistance | Good | Excellent |
| Use Case | General Purpose | Security |
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Hash with DJB2 (fast, non-cryptographic)
const djb2Hash = await hashery.toHash({ userId: 123, action: 'login' }, { algorithm: 'djb2' });
// Use for cache keys
const cacheKey = await hashery.toHash({
endpoint: '/api/users',
params: { page: 1, limit: 10 }
}, { algorithm: 'djb2' });
// Generate slot numbers with DJB2
const slot = await hashery.toNumber({ userId: 'user123' }, { min: 0, max: 99, algorithm: 'djb2' });
DJB2 uses a simple formula:
hash = 5381
for each character c:
hash = ((hash << 5) + hash) + c
This translates to: hash * 33 + c, where 5381 is the magic initial value chosen by Daniel J. Bernstein for its distribution properties.
FNV1 (Fowler-Noll-Vo) is a non-cryptographic hash function designed for fast hash table and checksum use. Created by Glenn Fowler, Landon Curt Noll, and Kiem-Phong Vo, it's known for its excellent distribution properties and simplicity.
Good for:
Not suitable for:
| Feature | FNV1 | DJB2 | SHA-256 |
|---|---|---|---|
| Speed | Very Fast | Very Fast | Slower |
| Distribution | Excellent | Good | Excellent |
| Security | Not Secure | Not Secure | Cryptographically Secure |
| Collision Resistance | Good | Good | Excellent |
| Use Case | Hash Tables | General Purpose | Security |
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Hash with FNV1 (fast, excellent distribution)
const fnv1Hash = await hashery.toHash({ productId: 'ABC123', variant: 'red' }, { algorithm: 'fnv1' });
// Use for hash table keys
const tableKey = await hashery.toHash({
userId: 'user@example.com',
resource: 'profile'
}, { algorithm: 'fnv1' });
// Generate distributed slot numbers with FNV1
const slot = await hashery.toNumber({ sessionId: 'sess_xyz789' }, { min: 0, max: 999, algorithm: 'fnv1' });
// Use for data deduplication
const fingerprint = await hashery.toHash({
content: 'document content here',
metadata: { author: 'John', date: '2024-01-01' }
}, { algorithm: 'fnv1' });
FNV1 uses the following formula:
hash = FNV_offset_basis
for each byte b:
hash = hash * FNV_prime
hash = hash XOR b
Where:
The algorithm multiplies by a prime and XORs with each input byte, creating excellent avalanche properties where small input changes result in very different hash values.
CRC (Cyclic Redundancy Check) is a non-cryptographic hash function designed primarily for detecting accidental changes to data. CRC32 is a 32-bit variant widely used in network protocols, file formats, and data integrity verification.
Good for:
Not suitable for:
| Feature | CRC32 | DJB2 | FNV1 | SHA-256 |
|---|---|---|---|---|
| Primary Use | Error Detection | Hash Tables | Hash Tables | Security |
| Speed | Very Fast | Very Fast | Very Fast | Slower |
| Security | Not Secure | Not Secure | Not Secure | Cryptographically Secure |
| Hash Length | 32-bit | 32-bit | 32-bit/64-bit | 256-bit |
| Error Detection | Excellent | Poor | Poor | Excellent |
| Use Case | Data Integrity | General Purpose | Hash Tables | Security |
import { Hashery } from 'hashery';
const hashery = new Hashery();
// Hash with CRC32 for data integrity
const crcHash = await hashery.toHash({ fileData: 'content here' }, { algorithm: 'crc32' });
// Verify file integrity
const fileChecksum = await hashery.toHash({
filename: 'document.pdf',
size: 1024000,
modified: '2024-01-01'
}, { algorithm: 'crc32' });
// Network packet validation
const packetChecksum = await hashery.toHash({
header: { type: 'data', seq: 123 },
payload: 'packet payload data'
}, { algorithm: 'crc32' });
// Quick data validation
const dataIntegrity = await hashery.toHash({
recordId: 'rec_123',
data: { field1: 'value1', field2: 'value2' }
}, { algorithm: 'crc32' });
CRC32 uses polynomial division in a finite field (GF(2)):
CRC32 polynomial: 0x04C11DB7 (IEEE 802.3 standard)
for each byte b:
crc = (crc >> 8) XOR table[(crc XOR b) & 0xFF]
Key characteristics:
⚠️ Security Warning: CRC is NOT cryptographically secure. It's designed to detect accidental errors, not intentional tampering. For security applications, use SHA-256 or other cryptographic hash functions.
✅ Best Practice: Use CRC32 for checksums and error detection in non-adversarial environments. Use cryptographic hashes (SHA-256, SHA-512) when security matters.
parseGets or sets the parse function used to deserialize stored values.
Type: ParseFn
Default: JSON.parse
const hashery = new Hashery();
hashery.parse = customParseFunction;
stringifyGets or sets the stringify function used to serialize values for storage.
Type: StringifyFn
Default: JSON.stringify
const hashery = new Hashery();
hashery.stringify = customStringifyFunction;
providersGets or sets the HashProviders instance used to manage hash providers.
Type: HashProviders
const hashery = new Hashery();
console.log(hashery.providers);
namesGets the names of all registered hash algorithm providers.
Type: Array<string>
Returns: An array of provider names (e.g., ['SHA-256', 'SHA-384', 'SHA-512', 'djb2', 'fnv1', 'murmer', 'crc32'])
const hashery = new Hashery();
console.log(hashery.names); // ['SHA-256', 'SHA-384', 'SHA-512', 'djb2', 'fnv1', 'murmer', 'crc32']
defaultAlgorithmGets or sets the default hash algorithm to use when none is specified for async methods.
Type: string
Default: 'SHA-256'
const hashery = new Hashery();
// Get default algorithm
console.log(hashery.defaultAlgorithm); // 'SHA-256'
// Set default algorithm
hashery.defaultAlgorithm = 'SHA-512';
// Now all async hashes use SHA-512 by default
const hash = await hashery.toHash({ data: 'example' });
console.log(hash.length); // 128 (SHA-512 produces 128 hex characters)
defaultAlgorithmSyncGets or sets the default hash algorithm to use when none is specified for synchronous methods.
Type: string
Default: 'djb2'
const hashery = new Hashery();
// Get default sync algorithm
console.log(hashery.defaultAlgorithmSync); // 'djb2'
// Set default sync algorithm
hashery.defaultAlgorithmSync = 'fnv1';
// Now all sync hashes use fnv1 by default
const hash = hashery.toHashSync({ data: 'example' });
// You can also set it in the constructor
const hashery2 = new Hashery({ defaultAlgorithmSync: 'murmer' });
const hash2 = hashery2.toHashSync({ data: 'test' }); // Uses murmer
toHash(data, options?)Generates a cryptographic hash of the provided data using the specified algorithm (async). The data is first stringified using the configured stringify function, then hashed.
Parameters:
data (unknown) - The data to hash (will be stringified before hashing)options (object, optional) - Configuration options
algorithm (string, optional) - The hash algorithm to use (defaults to 'SHA-256')maxLength (number, optional) - Maximum length for the hash output (truncates from the start)Returns: Promise<string> - A Promise that resolves to the hexadecimal string representation of the hash
Example:
const hashery = new Hashery();
// Using default SHA-256
const hash = await hashery.toHash({ name: 'John', age: 30 });
// Using a different algorithm
const hash512 = await hashery.toHash({ name: 'John' }, { algorithm: 'SHA-512' });
const fastHash = await hashery.toHash({ name: 'John' }, { algorithm: 'djb2' });
// Truncating hash output
const shortHash = await hashery.toHash(
{ name: 'John' },
{ algorithm: 'SHA-256', maxLength: 16 }
);
toHashSync(data, options?)Generates a hash of the provided data synchronously using a non-cryptographic hash algorithm. The data is first stringified using the configured stringify function, then hashed.
Important: This method only works with synchronous hash providers (djb2, fnv1, murmer, crc32). WebCrypto algorithms (SHA-256, SHA-384, SHA-512) are not supported and will throw an error.
Parameters:
data (unknown) - The data to hash (will be stringified before hashing)options (object, optional) - Configuration options
algorithm (string, optional) - The hash algorithm to use (defaults to 'djb2')maxLength (number, optional) - Maximum length for the hash output (truncates from the start)Returns: string - The hexadecimal string representation of the hash
Throws: Error if the specified algorithm does not support synchronous hashing
Example:
const hashery = new Hashery();
// Using default djb2
const hash = hashery.toHashSync({ name: 'John', age: 30 });
// Using a different algorithm
const hashFnv1 = hashery.toHashSync({ name: 'John' }, { algorithm: 'fnv1' });
const hashMurmer = hashery.toHashSync({ name: 'John' }, { algorithm: 'murmer' });
const hashCrc = hashery.toHashSync({ name: 'John' }, { algorithm: 'crc32' });
// Truncating hash output
const shortHash = hashery.toHashSync(
{ name: 'John' },
{ algorithm: 'djb2', maxLength: 4 }
);
// This will throw an error (WebCrypto not supported in sync mode)
// const invalid = hashery.toHashSync({ name: 'John' }, { algorithm: 'SHA-256' }); // ❌
toNumber(data, options?)Generates a deterministic number within a specified range based on the hash of the provided data (async). This method uses the toHash function to create a consistent hash, then maps it to a number between min and max (inclusive).
Parameters:
data (unknown) - The data to hash (will be stringified before hashing)options (object, optional) - Configuration options
min (number, optional) - The minimum value of the range (inclusive, defaults to 0)max (number, optional) - The maximum value of the range (inclusive, defaults to 100)algorithm (string, optional) - The hash algorithm to use (defaults to 'SHA-256')hashLength (number, optional) - Number of characters from hash to use for conversion (defaults to 16)Returns: Promise<number> - A Promise that resolves to a number between min and max (inclusive)
Throws: Error if min is greater than max
Example:
const hashery = new Hashery();
// Generate a number between 0 and 100 (default range)
const num = await hashery.toNumber({ user: 'john' });
// Generate a number with custom range
const num2 = await hashery.toNumber({ user: 'john' }, { min: 0, max: 100 });
// Using a different algorithm
const num512 = await hashery.toNumber({ user: 'john' }, { min: 0, max: 255, algorithm: 'SHA-512' });
toNumberSync(data, options?)Generates a deterministic number within a specified range based on the hash of the provided data synchronously. This method uses the toHashSync function to create a consistent hash, then maps it to a number between min and max (inclusive).
Important: This method only works with synchronous hash providers (djb2, fnv1, murmer, crc32).
Parameters:
data (unknown) - The data to hash (will be stringified before hashing)options (object, optional) - Configuration options
min (number, optional) - The minimum value of the range (inclusive, defaults to 0)max (number, optional) - The maximum value of the range (inclusive, defaults to 100)algorithm (string, optional) - The hash algorithm to use (defaults to 'djb2')hashLength (number, optional) - Number of characters from hash to use for conversion (defaults to 16)Returns: number - A number between min and max (inclusive)
Throws:
Example:
const hashery = new Hashery();
// Generate a number between 0 and 100 (default range)
const num = hashery.toNumberSync({ user: 'john' });
// Generate a number with custom range
const slot = hashery.toNumberSync({ user: 'john' }, { min: 0, max: 9 });
// Using a different algorithm
const numFnv1 = hashery.toNumberSync({ user: 'john' }, { min: 0, max: 255, algorithm: 'fnv1' });
// A/B testing
const variant = hashery.toNumberSync({ userId: 'user123' }, { min: 0, max: 1 });
console.log(variant === 0 ? 'Group A' : 'Group B');
// Load balancing
const serverId = hashery.toNumberSync(
{ requestId: 'req_abc' },
{ min: 0, max: 9, algorithm: 'murmer' } // 10 servers
);
// This will throw an error (WebCrypto not supported in sync mode)
// const invalid = hashery.toNumberSync({ user: 'john' }, { algorithm: 'SHA-256' }); // ❌
loadProviders(providers?, options?)Loads hash providers into the Hashery instance. This allows you to add custom hash providers or replace the default ones.
Parameters:
providers (Array, optional) - Array of hash providers to addoptions (HasheryLoadProviderOptions, optional) - Options object
includeBase (boolean) - Whether to include base providers (default: true)Returns: void
Example:
const hashery = new Hashery();
// Add a custom provider
const customProvider = {
name: 'custom',
toHash: async (data: BufferSource) => 'custom-hash'
};
hashery.loadProviders([customProvider]);
// Load without base providers
hashery.loadProviders([customProvider], { includeBase: false });
Overall view of the current algorithm's and their performance using simple hashing with random data. Sync is when we use toHashSync and Async is the toHash function which requires await.
NOTE: Many of these are not secure and should be used only for object hashing. Read about each one in the documentation and pick what works best for your use case.
| name | summary | ops/sec | time/op | margin | samples |
|---|---|---|---|---|---|
| MURMER Sync | 🥇 | 726K | 1µs | ±0.02% | 707K |
| CRC32 Sync | -1.9% | 713K | 1µs | ±0.02% | 672K |
| DJB2 Sync | -2.7% | 707K | 1µs | ±0.03% | 672K |
| FNV1 Sync | -2.9% | 705K | 1µs | ±0.03% | 670K |
| CRC32 Async | -8.8% | 663K | 2µs | ±0.02% | 647K |
| MURMER Async | -11% | 649K | 2µs | ±0.03% | 620K |
| SHA-512 Async | -11% | 647K | 2µs | ±0.03% | 596K |
| SHA-384 Async | -11% | 645K | 2µs | ±0.03% | 589K |
| SHA-256 Async | -12% | 642K | 2µs | ±0.03% | 583K |
| FNV1 Async | -12% | 641K | 2µs | ±0.03% | 615K |
| DJB2 Async | -12% | 639K | 2µs | ±0.03% | 613K |
| name | summary | ops/sec | time/op | margin | samples |
|---|---|---|---|---|---|
| DJB2 Sync | 🥇 | 507K | 2µs | ±0.04% | 475K |
| MURMER Sync | -0.6% | 504K | 2µs | ±0.04% | 476K |
| DJB2 Async | -3.6% | 489K | 2µs | ±0.04% | 463K |
| MURMER Async | -4.4% | 484K | 2µs | ±0.04% | 457K |
| FNV1 Sync | -6.6% | 474K | 2µs | ±0.04% | 447K |
| FNV1 Async | -14% | 436K | 2µs | ±0.04% | 412K |
| CRC32 Sync | -31% | 349K | 3µs | ±0.04% | 334K |
| CRC32 Async | -31% | 347K | 3µs | ±0.04% | 336K |
| SHA-256 Async | -86% | 69K | 15µs | ±0.11% | 66K |
| SHA-384 Async | -87% | 64K | 17µs | ±0.14% | 60K |
| SHA-512 Async | -88% | 61K | 17µs | ±0.12% | 58K |
Caching is enabled by default and is a simple FIFO with default max keys at 4000. The performance gain is greater than 20%+ on average. Some of the biggest gains are on SHA hashing which 10x when caching is enabled.
| name | summary | ops/sec | time/op | margin | samples |
|---|---|---|---|---|---|
| Hashery SHA-384 (Cache) | 🥇 | 646K | 2µs | ±0.03% | 596K |
| Hashery SHA-256 (Cache) | -0.42% | 643K | 2µs | ±0.03% | 594K |
| Hashery SHA-512 (Cache) | -0.71% | 641K | 2µs | ±0.03% | 589K |
| node:crypto SHA-256 | -1.2% | 638K | 2µs | ±0.02% | 588K |
| node:crypto SHA-384 | -6.9% | 602K | 2µs | ±0.03% | 507K |
| node:crypto SHA-512 | -7.3% | 599K | 2µs | ±0.03% | 525K |
| Hashery SHA-256 | -89% | 69K | 15µs | ±0.10% | 66K |
| Hashery SHA-384 | -90% | 65K | 16µs | ±0.11% | 62K |
| Hashery SHA-512 | -91% | 61K | 17µs | ±0.11% | 59K |
In this benchmark it shows the performance gap that happens between web crypto and the standard node:crypto. By default node:crypto has significant performance natively and doesnt use async/await to perform its hash. With caching enabled we start to see the performance become more similar.
Please use our Code of Conduct and Contributing guidelines for development and testing. We appreciate your contributions!
MIT & © Jared Wray
FAQs
Browser Compatible Object Hashing
The npm package hashery receives a total of 0 weekly downloads. As such, hashery popularity was classified as not popular.
We found that hashery demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.
Research
/Security News
The compromise affects MemTensor's MemOS, an open source memory framework for large language models (LLMs) and AI agents. Both npm package @memtensor/memos-cloud-openclaw-plugin and the PyPI package MemoryOS are compromised. They drop cross-platform Go binaries that exfiltrate developer secrets.
Security News
Lovable’s OJ rewrites Vite’s dev server in Rust, reducing memory use and preview times as AI lowers the cost of open source reimplementation.