@quicore/hash 1.0.0 → 1.1.0

package/README.md

@@ -1,2 +1,111 @@
-# hash
-A lightweight utility for fast access to the most commonly used hashing algorithms including SHA, Blake2, and PBKDF2
+# @quicore/hash
+
+> A lightweight utility for fast access to the most commonly used hashing algorithms including SHA, Blake2, and PBKDF2.
+
+@quicore/hash provides a simple and unified interface to widely-used cryptographic hashing functions. It wraps Node.js' native crypto module to offer convenient helpers for generating SHA, BLAKE2, SHA3, PBKDF2, and other hashes, as well as Base62-encoded compact IDs.
+
+---
+
+## ✨ Features
+
+* 🔒 Fast, secure hash generation (SHA-256, SHA-512, SHA3, BLAKE2, PBKDF2)
+* 🧠 Compact Base62-encoded hashes for short unique identifiers
+* 💡 Unified interface for all supported algorithms
+* ⚠️ Legacy algorithm support (MD5, SHA-1, RIPEMD160) with deprecation warnings
+* 🔋 Zero dependencies, fully built on Node.js native crypto
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @quicore/hash
+```
+
+---
+
+## 🚀 Usage
+
+```ts
+import { GenerateHash } from '@quicore/hash';
+
+// SHA-256
+const sha = GenerateHash.SHA256('hello');
+
+// Compact ID (Base62 encoded Blake2b hash)
+const id = GenerateHash.compactHash('user@example.com');
+
+// PBKDF2
+const derivedKey = GenerateHash.PBKDF2('password123', 'random-salt');
+
+// SHA3-256
+const sha3 = GenerateHash.SHA3_256('some input');
+```
+
+---
+
+## 🔐 API Reference
+
+### Hash Functions
+
+| Method                 | Description                                      |
+| ---------------------- | ------------------------------------------------ |
+| SHA256(input)          | Generates a SHA-256 hex hash                     |
+| SHA512(input)          | Generates a SHA-512 hex hash                     |
+| SHA1(input)            | ⚠️ Deprecated. SHA-1 hash                        |
+| MD5(input)             | ⚠️ Deprecated. MD5 hash                          |
+| SHA3\_256(input)       | SHA3-256 hex hash                                |
+| SHA3\_512(input)       | SHA3-512 hex hash                                |
+| RIPEMD160(input)       | RIPEMD160 hex hash                               |
+| BLAKE2s256(input)      | BLAKE2s-256 hex hash                             |
+| blake2b(input, size)   | Returns a Buffer from BLAKE2b hash               |
+| PBKDF2(password, salt) | PBKDF2 w/ SHA-512 (100,000 iterations, 64 bytes) |
+
+### Utility
+
+| Method                  | Description                                     |
+| ----------------------- | ----------------------------------------------- |
+| compactHash(input, len) | Returns Base62-encoded BLAKE2b digest           |
+| toBase62(buffer, len)   | Encodes Buffer to Base62 string of given length |
+
+---
+
+## 📏 Defaults
+
+* Base62 alphabet: 0-9, a-z, A-Z
+* Default Base62 ID length: 22 characters
+* Minimum Base62 ID length: 10 characters
+* BLAKE2b default digest size: 20 bytes
+* PBKDF2: 100,000 iterations, SHA-512, 64-byte output
+
+---
+
+## 🛑 Deprecated Algorithms
+
+* MD5
+* SHA-1
+
+These are retained for non-security use cases (e.g., checksum comparisons) but are not recommended for cryptographic use.
+
+---
+
+## 📚 Use Cases
+
+* ID and slug generation for URLs, database keys
+* Password hashing with PBKDF2
+* Content fingerprinting or data integrity checks
+* Simple cryptographic utilities for CLI or server-side apps
+
+---
+
+## 🧪 Example: Mongo-Friendly ID
+
+```ts
+const id = GenerateHash.compactHash('file_upload_123');
+// e.g., "03xr9SDcKVUuAkcBfYzLpT"
+```
+
+---
+
+## 📜 License
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quicore/hash",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A lightweight utility for fast access to the most commonly used hashing algorithms including SHA, Blake2, and PBKDF2",
   "main": "dist/index.js",
   "scripts": {
@@ -29,4 +29,4 @@
   "engines": {
     "node": ">=18.0.0"
   }
-}
+}