# @isdk/hash

> A versatile TypeScript/JavaScript library integrating various hashing algorithms, UUID, and unique ID generation functionalities

Latest version **0.1.1** (published 2025-11-07) · MIT license · 0 weekly downloads

## Install

```sh
npm install @isdk/hash
pnpm add @isdk/hash
yarn add @isdk/hash
bun add @isdk/hash
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2025-11-07 |
| First published | 2025-11-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20.11.1 |
| Dependencies | 6 |
| Unpacked size | 66 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| Author | Riceball LEE |
| Maintainers | isdk |
| Keywords | ai, tool |

## Links

- npm: https://www.npmjs.com/package/@isdk/hash
- Homepage: https://github.com/isdk/hash.js/#readme
- npm.io page: https://npm.io/package/@isdk/hash

## Dependencies (6)

- [uuid](https://npm.io/package/uuid.md) ^11.1.0
- [nanoid](https://npm.io/package/nanoid.md) 5.1.6
- [xxhashjs](https://npm.io/package/xxhashjs.md) ^0.2.2
- [base32768](https://npm.io/package/base32768.md) ^5.0.0
- [hash-wasm](https://npm.io/package/hash-wasm.md) ^4.12.0
- [json-canonicalize](https://npm.io/package/json-canonicalize.md) ^2.0.0

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 0.1.1 (latest) — 2025-11-07

## README

# #️⃣ @isdk/hash

[![NPM version](https://img.shields.io/npm/v/@isdk/hash.svg)](https://www.npmjs.com/package/@isdk/hash)
[![NPM downloads](https://img.shields.io/npm/dm/@isdk/hash.svg)](https://www.npmjs.com/package/@isdk/hash)
[![License](https://img.shields.io/npm/l/@isdk/hash.svg)](https://github.com/isdk/hash.js/blob/main/LICENSE-MIT)

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

```bash
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

```typescript
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.

```typescript
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).

```typescript
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

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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`](https://github.com/wasm3/hash-wasm): WebAssembly powered hashing algorithms.
- [`uuid`](https://github.com/uuidjs/uuid): For robust UUID generation.
- [`nanoid`](https://github.com/ai/nanoid): For small, secure, URL-friendly unique string IDs.
- [`json-canonicalize`](https://github.com/cyberphone/json-canonicalize): For consistent JSON object serialization.
- [`base32768`](https://github.com/isdk/base32768): For compact binary to string encoding.
- [`xxhashjs`](https://github.com/pierrec/js-xxhash): For fast XXHash implementations.

## 📜 License

This project is licensed under the MIT License. See the [LICENSE-MIT](LICENSE-MIT) file for details.

---
_Source: https://npm.io/package/@isdk/hash · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._