🌐 Universal: Works in Node.js AND browsers without polyfills
⚡ Smart Fallbacks: Automatically handles Web Crypto API limitations (like non-HTTPS environments)
🔧 TypeScript First: Full type safety and IntelliSense support
📦 Dual Entry Points: Optimized builds for both environments
🎯 Simple API: Consistent interface across all platforms

🚀 Quick Start

pnpm install @push.rocks/smarthash

📖 API Reference

🔤 String Hashing

import { sha256FromString, sha256FromStringSync } from '@push.rocks/smarthash';

// Async (works everywhere)
const hash = await sha256FromString('Hello, world!');
console.log(hash); // 📄 64-character hex string

// Sync (Node.js only)
const hashSync = sha256FromStringSync('Hello, world!');
console.log(hashSync); // ⚡ Instant result

🗂️ File & Stream Hashing (Node.js Only)

import { sha256FromFile, sha256FromStream } from '@push.rocks/smarthash';
import fs from 'fs';

// Hash files directly
const fileHash = await sha256FromFile('./myfile.txt');
console.log(fileHash); // 📁 File's SHA256 hash

// Hash streams (perfect for large files)
const stream = fs.createReadStream('./largefile.zip');
const streamHash = await sha256FromStream(stream);
console.log(streamHash); // 🌊 Stream's SHA256 hash

🧱 Buffer Hashing

import { sha256FromBuffer } from '@push.rocks/smarthash';

// Works with both Buffer (Node.js) and Uint8Array (Browser)
const encoder = new TextEncoder();
const buffer = encoder.encode('Hello, world!');
const bufferHash = await sha256FromBuffer(buffer);
console.log(bufferHash); // 🔢 Buffer's SHA256 hash

🎯 Object Hashing

import { sha256FromObject } from '@push.rocks/smarthash';

// Consistent hashing for JavaScript objects
const myObject = { 
  userId: 12345, 
  role: 'admin',
  timestamp: Date.now()
};

const objectHash = await sha256FromObject(myObject);
console.log(objectHash); // 🎯 Deterministic object hash

🔥 Pro Tip: Object property order doesn't matter! {a: 1, b: 2} and {b: 2, a: 1} produce the same hash.

🛡️ MD5 Hashing (Node.js Only)

import { md5FromString } from '@push.rocks/smarthash';

// Legacy MD5 support (use SHA256 for new projects!)
const md5Hash = await md5FromString('Hello, world!');
console.log(md5Hash); // 🔐 32-character MD5 hash

🌍 Environment Compatibility

Function	Node.js	Browser	Notes
`sha256FromString`	✅	✅	Universal support
`sha256FromStringSync`	✅	❌	Sync not possible in browsers
`sha256FromBuffer`	✅	✅	Handles Buffer/Uint8Array
`sha256FromFile`	✅	❌	File system access required
`sha256FromStream`	✅	❌	Node.js streams only
`sha256FromObject`	✅	✅	Uses JSON serialization
`md5FromString`	✅	❌	Not supported by Web Crypto API

🔧 Advanced Usage

Error Handling

import { sha256FromString } from '@push.rocks/smarthash';

try {
  const hash = await sha256FromString('sensitive data');
  console.log(`✅ Hash computed: ${hash}`);
} catch (error) {
  console.error('❌ Hashing failed:', error);
}

Browser-Specific Features

In browsers, SmartHash automatically:

🔒 Uses Web Crypto API when available (HTTPS contexts)
🔄 Falls back to pure JavaScript implementation in non-HTTPS environments
⚠️ Warns when trying to use Node.js-only functions

Import Strategies

// Main entry point (Node.js optimized)
import { sha256FromString } from '@push.rocks/smarthash';

// Browser-specific entry point (smaller bundle)
import { sha256FromString } from '@push.rocks/smarthash/web';

🛠️ Development

# Run tests (both Node.js and browser)
pnpm test

# Build the project
pnpm build

# Generate documentation
pnpm buildDocs

🔐 Security Notes

✅ SHA256: Cryptographically secure, recommended for all use cases
⚠️ MD5: Legacy support only, not recommended for security-critical applications
🌍 Cross-Environment: Produces identical hashes across Node.js and browsers
🔒 Web Crypto: Uses native browser APIs when available for maximum performance

License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the license file within this repository.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

readme.md

🔐 @push.rocks/smarthash

✨ Why SmartHash?