@push.rocks/smarthash

Provides simplified access to Node.js hash functions, including SHA256 and MD5, with support for strings, streams, and files.

readme.md for @push.rocks/smarthash

🔐 @push.rocks/smarthash

Cross-environment hashing made simple 🚀
SHA256 and MD5 hash functions that work seamlessly in both Node.js and browsers, with zero configuration.

npm version TypeScript Cross Platform

✨ Why SmartHash?

🚀 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:

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

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.

Company Information

Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

changelog.md for @push.rocks/smarthash

2025-09-12 - 3.2.6 - fix(ci)

Add .claude local settings to permit web fetch to www.npmjs.com

2025-09-12 - 3.2.5 - fix(ts_web)

Ensure sha256FromBuffer uses correct ArrayBuffer slice for Uint8Array inputs and add local project config files

2025-09-12 - 3.2.4 - fix(deps)

Bump devDependencies, update smartjson and add workspace/CI settings

2025-08-03 - 3.2.3 - fix(dependencies/config)

Update dependency versions and add local settings for web fetch configuration

2025-08-03 - 3.2.1 - docs(readme)

Enhance readme with comprehensive documentation and modern formatting

2025-06-19 - 3.2.0 - feat(package)

Update package.json to use exports field for dual entry points

2025-06-19 - 3.1.0 - feat(browser)

Implement fallback SHA256 for non-HTTPS environments and enhance browser tests for consistent hashing

2025-06-19 - 3.0.4 - feat

Merge isohash functionality into smarthash to enable cross‐environment hash support. This release introduces browser‐compatible SHA256 functions via the Web Crypto API and plugins for environment detection and JSON handling.

Note: Several non–breaking maintenance updates (e.g. description, tsconfig, and npmextra.json adjustments) were applied between 2024 and 2023 alongside version marker commits.

2023-09-22 to 2022-06-26 - 3.0.0 - Maintenance

Between versions 3.0.3 and 3.0.0, a series of core fixes and organizational improvements were rolled out.

2022-06-26 - 2.1.10 - BREAKING CHANGE

A major change was introduced by switching the module system.

2021-03-01 to 2019-11-21 - 2.1.0 - Maintenance

Across versions 2.1.9 down to 2.1.0, the project received multiple fixes and CI updates.

2019-11-21 - 2.0.6 - feat

New functionality was added to expand the available hashing algorithms.

2019-07-04 to 2018-09-07 - 2.0.0 - Maintenance

This range of releases was dedicated to refining core functionality and enhancing security.

2018-09-07 - 1.0.4 - BREAKING CHANGE

A breaking change was introduced by renaming the package scope.

2016-08-16 to 2016-05-23 - 1.0.0 - Initial Setup

During the early days of the project, core implementation and structure were established.