@isdk/hash

@isdk/hash

The @isdk/hash library is a versatile TypeScript/JavaScript library integrating various hashing algorithms, UUID, and unique ID generation functionalities. It leverages modern, efficient modules like hash-wasm, uuid, and nanoid to provide a wide range of functionalities suitable for both browser and Node.js environments.

Features

• Multiple Hash Algorithms: Supports MD5, SHA-1, SHA-256/224/384/512, RIPEMD-160, and non-cryptographic XXHash32/64/128.
• Stream Hashing: Efficiently hash large files or data streams without loading everything into memory.
• Canonical Object Hashing: Generate consistent hashes for JavaScript objects by canonicalizing them first.
• Versatile UUID Generation: Create v1, v4, v5, v6, and v7 UUIDs.
• Secure Unique ID Generation: Generate secure, URL-friendly unique IDs with nanoid.
• Compact Encoding: encode to produce shorter, URL-safe strings from hashes and UUIDs.
• High Performance: Built on hash-wasm for WebAssembly-powered speed.
• Type-Safe: Fully written in TypeScript with exported types.

Installation

npm install @isdk/hash

Usage

Hashing

The library provides a flexible hash function that can handle various data types, algorithms, and output formats.

Hashing a String

import { hash, HashAlgorithm } from '@isdk/hash';

// Using the default algorithm (xxhash64) and output (encoded string)
const h1 = await hash('hello world');
console.log(h1);

// Using SHA-256 with hex output
const h2 = await hash('hello world', {
  hashAlgo: HashAlgorithm.sha256,
  outputType: 'hex',
});
console.log(h2); // 'b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9'

Hashing a JavaScript Object

The hashObject function ensures that the hash is consistent regardless of key order.

import { hashObject } from '@isdk/hash';

const obj1 = { a: 1, b: 2 };
const obj2 = { b: 2, a: 1 };

const h1 = await hashObject(obj1);
const h2 = await hashObject(obj2);

console.log(h1 === h2); // true

Hashing a Stream

Efficiently hash a ReadableStream (e.g., from a file).

import { hashStream } from '@isdk/hash';
import { createReadStream } from 'fs';

// This example is for Node.js
// In browsers, you can use `response.body` from a fetch request.
const stream = createReadStream('path/to/your/file');
const fileHash = await hashStream(stream);

console.log(fileHash);

UUID Generation

Generate standard or encoded UUIDs with the uuid function.

Standard UUIDs

import { uuid } from '@isdk/hash';

// Generate a v1 UUID (default)
const u1 = uuid();
console.log(u1);

// Generate a v4 UUID
const u4 = uuid(4);
console.log(u4);

// Generate a v7 UUID
const u7 = uuid(7);
console.log(u7);

Encoded UUIDs

Generate compact, encoded UUIDs. This is useful for creating shorter, URL-friendly identifiers.

import { uuid } from '@isdk/hash';

// Generate an encoded v1 UUID
const encodedUuid1 = uuid(true); // or uuid(1, true)
console.log(encodedUuid1);

// Generate an encoded v4 UUID
const encodedUuid4 = uuid(4, true);
console.log(encodedUuid4);

Nano ID Generation

Generate secure and URL-friendly unique identifiers.

import { nanoid } from '@isdk/hash';

const id = nanoid();
console.log(id); // e.g., 'V1StGXR8_Z5jdHi6B-myT'

// Generate a custom-sized ID
const shortId = nanoid(10);
console.log(shortId); // e.g., 'Uakgb_J5m9'

XXHash (String-optimized)

For quick, non-cryptographic hashing of strings and objects, you can use the dedicated xxhash functions.

import { xxhash32, xxhash64 } from '@isdk/hash';

// Get a 32-bit hash as a hex string
const h32 = xxhash32('hello world');
console.log(h32);

// Get a 64-bit hash from an object as a hex string
const h64 = xxhash64({ a: 1, b: 2 });
console.log(h64);

API Reference

Hashing Functions

• hash(value: IDataType, options?: HashAlgoParams): Promise<string | Uint8Array>: Hashes a value (string, Buffer, ArrayBuffer).
• hashStream(stream: ReadableStream, options?: HashAlgoParams): Promise<string | Uint8Array>: Hashes a readable stream.
• hashObject(value: any, options?: HashAlgoParams): Promise<string | Uint8Array>: Hashes a JavaScript object by canonicalizing it.
• HashAlgoParams: { hashAlgo?: HashAlgorithm, seed?: number, outputType?: 'hex' | 'binary' | 'string' }

ID Generation Functions

• uuid(encode?: boolean): string: Generates a v1 UUID. If encode is true, returns an encoded string.
• uuid(ver?: UUIDVersions | boolean, encode?: boolean): string: Generates a UUID of version ver (1, 4, 5, 6, 7).
• nanoid(size?: number): string: Generates a secure, URL-friendly unique ID.

XXHash Functions

• xxhash32(value: string | object, radix?: number): string: Computes a 32-bit xxhash.
• xxhash64(value: string | object, radix?: number): string: Computes a 64-bit xxhash.

Credit

This library integrates and leverages the following excellent third-party libraries:

• hash-wasm: WebAssembly powered hashing algorithms.
• uuid: For robust UUID generation.
• nanoid: For small, secure, URL-friendly unique string IDs.
• json-canonicalize: For consistent JSON object serialization.
• base32768: For compact binary to string encoding.
• xxhashjs: For fast XXHash implementations.

License

This project is licensed under the MIT License. See the LICENSE-MIT file for details.