# @push.rocks/smarthash

> Cross-environment hash functions (SHA256 and MD5) for Node.js and browsers, with support for strings, streams, and files.

Latest version **3.3.0** (published 2026-07-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install @push.rocks/smarthash
pnpm add @push.rocks/smarthash
yarn add @push.rocks/smarthash
bun add @push.rocks/smarthash
```

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 3.3.0 |
| Published | 2026-07-31 |
| First published | 2023-07-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 2 |
| Unpacked size | 78.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Task Venture Capital GmbH |
| Maintainers | lossless |
| Keywords | crypto, hashing, SHA256, MD5, security, node.js, browser, cross-environment, web crypto, stream hashing, file hashing, synchronous hashing, asynchronous hashing, data integrity, typescript |

## Links

- npm: https://www.npmjs.com/package/@push.rocks/smarthash
- Repository: https://code.foss.global/push.rocks/smarthash
- Issues: https://code.foss.global/push.rocks/smarthash/issues
- npm.io page: https://npm.io/package/@push.rocks/smarthash

## Dependencies (2)

- [@push.rocks/smartenv](https://npm.io/package/@push.rocks/smartenv.md) ^6.0.0
- [@push.rocks/smartjson](https://npm.io/package/@push.rocks/smartjson.md) ^6.0.1

## Alternatives

- [replicas-cli](https://npm.io/package/replicas-cli.md) — 3.0K weekly downloads
- [env-contract](https://npm.io/package/env-contract.md) — 133 weekly downloads
- [@openveo/api](https://npm.io/package/@openveo/api.md) — 61 weekly downloads
- [@ryniaubenpm2/cumque-error-reiciendis](https://npm.io/package/@ryniaubenpm2/cumque-error-reiciendis.md) — 54 weekly downloads
- [ts-global-type-extra](https://npm.io/package/ts-global-type-extra.md) — 11 weekly downloads

## Recent versions

- 3.3.0 (latest) — 2026-07-31
- 3.2.7 — 2026-04-30
- 3.2.6 — 2025-09-12
- 3.2.5 — 2025-09-12
- 3.2.3 — 2025-08-03
- 3.2.2 — 2025-08-03
- 3.2.1 — 2025-08-03
- 3.2.0 — 2025-06-19
- 3.1.0 — 2025-06-19
- 3.0.4 — 2023-09-22
- 3.0.2 — 2023-07-12

## README

# 🔐 @push.rocks/smarthash

> **Cross-environment hashing made simple** 🚀  
> SHA-256 hashing for Node.js and browsers, with Node-only file and legacy MD5 helpers.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

[![npm version](https://img.shields.io/npm/v/@push.rocks/smarthash.svg)](https://www.npmjs.com/package/@push.rocks/smarthash)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Cross Platform](https://img.shields.io/badge/Platform-Node.js%20%7C%20Browser-brightgreen.svg)](#)

## ✨ Why SmartHash?

- 🌐 **Universal SHA-256**: Works in Node.js and browsers without polyfills
- ⚡ **Smart Fallbacks**: Uses the local implementation when Web Crypto is unavailable
- 🔧 **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

```bash
pnpm install @push.rocks/smarthash
```

## 📖 API Reference

### 🔤 String Hashing

```typescript
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 and browsers)
const hashSync = sha256FromStringSync('Hello, world!');
console.log(hashSync); // ⚡ Instant result
```

Browser code imports the same functions from `@push.rocks/smarthash/web`.

### 🗂️ File & Stream Hashing

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

`sha256FromFile()` is Node-only. `sha256FromStream()` accepts Node readable
streams in the main entrypoint and WHATWG `ReadableStream<Uint8Array>` objects
in both entrypoints.

### 🧱 Buffer Hashing

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

### Incremental Hashing

`createSha256Hasher()` is available from both entrypoints and accepts
incremental updates without buffering the complete payload.

```typescript
import { createSha256Hasher } from '@push.rocks/smarthash';

const hasher = createSha256Hasher();
hasher.update(new Uint8Array([0xca, 0xfe]));
hasher.update(new Uint8Array([0xba, 0xbe]));
const digest = hasher.digest();
```

`update()` accepts `ArrayBuffer` and `Uint8Array` values and returns the hasher
for chaining. `digest()` returns lowercase hexadecimal and finalizes the
instance. Further `update()` or `digest()` calls throw.

Browser byte streams can be hashed directly:

```typescript
import { sha256FromStream } from '@push.rocks/smarthash/web';

const response = await fetch('/artifact');
const digest = await sha256FromStream(response.body!);
```

### 🎯 Object Hashing

```typescript
import { sha265FromObject } from '@push.rocks/smarthash';

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

const objectHash = await sha265FromObject(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)

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

The Browser column refers to the `@push.rocks/smarthash/web` entrypoint.

| Function | Node.js | Browser | Notes |
|----------|---------|---------|-------|
| `sha256FromString` | ✅ | ✅ | Universal support |
| `sha256FromStringSync` | ✅ | ✅ | Local incremental implementation in browsers |
| `sha256FromBuffer` | ✅ | ✅ | Handles Buffer/Uint8Array |
| `sha256FromFile` | ✅ | ❌ | File system access required |
| `sha256FromStream` | ✅ | ✅ | Node streams and WHATWG byte streams |
| `createSha256Hasher` | ✅ | ✅ | Incremental, bounded-memory SHA-256 |
| `sha265FromObject` | ✅ | ✅ | Existing typo-preserving API; uses JSON serialization |
| `md5FromString` | ✅ | ❌ | Not supported by Web Crypto API |

## 🔧 Advanced Usage

### Error Handling

```typescript
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 `crypto.subtle` is available
- 🔄 Falls back to the local implementation when `crypto.subtle` is unavailable
- 🌊 Hashes WHATWG byte streams incrementally

### Import Strategies

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

// Browser-compatible entry point
import { sha256FromString } from '@push.rocks/smarthash/web';
```

## 🛠️ Development

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

# Build the project
pnpm build

# Generate documentation
pnpm buildDocs
```

## 🔐 Security Notes

- ✅ **SHA256**: Suitable for cryptographic digests and data-integrity checks
- ⚠️ **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

## 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](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

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

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.

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