pure-md5 🎯

A lightweight, zero-dependency JavaScript library for MD5 hashing with streaming support for large files.

🚀 Quick Start

Install

npm install pure-md5
# or
yarn add pure-md5
# or
pnpm add pure-md5

Basic Usage

import { md5 } from 'pure-md5/md5';

const hash = md5('hello');
console.log(hash); // "5d41402abc4b2a76b9719d911017c592"

Streaming (Large Files)

import { createMD5Stream } from 'pure-md5';
import fs from 'fs';

const stream = createMD5Stream();
stream.on('md5', result => console.log('MD5:', result.digest));

fs.createReadStream('large-file.bin').pipe(stream);

✨ Features

• ⚡ Zero Dependencies - No external dependencies, ever
• 📦 Tiny Bundle - ~1.4KB gzipped for md5() only (with tree-shaking), ~6KB for full bundle
• 🎯 Multiple APIs - Simple, streaming, and promise-based
• 🦺 TypeScript Ready - Full type definitions included
• 🔌 Adapter System - Automatic detection (WebCrypto, Node.js, Pure JS)
• 📄 File Hashing - Stream large files with progress tracking
• 🌐 Universal - Works in Node.js and browsers

📚 Documentation

• API Reference
• Streaming API
• Streaming Examples
• Migration Guide
• Troubleshooting
• Benchmarks
• Contributing

🛠️ API Reference

Basic MD5

md5(message[, encoding])

Compute MD5 hash of a string or buffer.

import { md5 } from 'pure-md5/md5'; // Tree-shakeable, ~1.4KB

const hash = md5('hello');
console.log(hash); // "5d41402abc4b2a76b9719d911017c592"

Streaming API

createMD5Stream()

Create a new MD5Stream instance.

import { createMD5Stream } from 'pure-md5';

const stream = createMD5Stream();
stream.on('md5', result => {
  console.log('MD5:', result.digest);      // "5d41402abc4b2a76b9719d911017c592"
  console.log('Bytes:', result.bytesProcessed); // 5
});

pipeThroughMD5(source)

Pipe a stream through MD5 hashing and get a promise.

import { pipeThroughMD5, fromReadable } from 'pure-md5';

const source = fromReadable(['hello', ' ', 'world']);
const result = await pipeThroughMD5(source);
console.log('MD5:', result.digest);

fromStream(stream)

Convenience method to create a stream and get result.

import { fromStream } from 'pure-md5';
import fs from 'fs';

const { stream, result } = fromStream(fs.createReadStream('file.txt'));
result.then(r => console.log('MD5:', r.digest));

File System Utilities

hashFile(filePath, options?)

Hash a file asynchronously.

import { hashFile } from 'pure-md5';

const result = await hashFile('path/to/file.txt');
console.log('MD5:', result.digest);
console.log('Bytes:', result.bytesProcessed);

// With progress tracking
const progress = createProgressTracker(result.bytesProcessed, percent => {
  console.log(`Progress: ${percent.toFixed(1)}%`);
});

const result = await hashFile('large-file.bin', { onProgress: progress });

hashFileDigest(filePath)

Hash a file and return only the digest.

import { hashFileDigest } from 'pure-md5';

const digest = await hashFileDigest('path/to/file.txt');
console.log('MD5:', digest);

hashFileSync(filePath)

Hash a file synchronously (for small files).

import { hashFileSync } from 'pure-md5';

const digest = hashFileSync('small-file.txt');
console.log('MD5:', digest);

verifyFile(filePath, expectedDigest)

Verify file integrity using MD5.

import { verifyFile } from 'pure-md5';

const isVerified = await verifyFile('path/to/file.txt', '5d41402abc4b2a76b9719d911017c592');
console.log('Verified:', isVerified); // true or false

CDN Usage

<script src="https://unpkg.com/pure-md5@latest/dist/index.js"></script>
<script>
  console.log(md5('hello')); // "5d41402abc4b2a76b9719d911017c592"
</script>

📊 Comparison with Alternatives

| Feature | pure-md5 | pvorb/node-md5 | crypto-js | js-md4 | Node.js crypto | |---------|----------|----------------|-----------|--------|----------------| | Bundle Size (md5 only) | ~1.4KB¹ | ~3KB | ~4KB | ~2KB | N/A | | Bundle Size (full) | ~6KB¹ | ~3KB | ~4KB | ~2KB | N/A | | Dependencies | 0 | 0 | 0 | 0 | 0 | | Streaming | ✅ | ❌ | ❌ | ❌ | ✅ | | Browser Support | ✅ | ❌ | ✅ | ✅ | ❌ | | TypeScript | ✅ | ❌ | ❌ | ⚠️ | ❌ | | Zero Config | ✅ | ❌² | ✅ | ❌ | ✅ | | Tree-shaking | ✅ | ❌ | ❌ | ❌ | N/A | | Pure JS (no Node) | ✅ | ❌ | ✅ | ✅ | ❌ |

¹ With tree-shaking: Only import what you use!
² Requires Node.js environment - not browser-compatible

Why choose pure-md5 over pvorb/node-md5?

1. Browser Support: pvorb/node-md5 only works in Node.js, while pure-md5 works everywhere
2. Tree-shaking: pure-md5 supports modern tree-shaking for smaller bundles
3. Streaming: built-in streaming API for large files in pure-md5
4. TypeScript: first-class TypeScript support with full type definitions
5. Zero dependencies: truly zero-dependency implementation
6. Modern API: cleaner, more intuitive interface with promise-based options

pvorb/node-md5 is still a good choice if you only need Node.js and prefer its API style.

🔧 Configuration

Node.js

// Node.js adapter is auto-detected
import { md5 } from 'pure-md5';

Browser

// WebCrypto adapter is auto-detected
import { md5 } from 'pure-md5';

Manual Adapter Selection

Use adapter backends directly when you need explicit control:

import { NodeCryptoBackend, WebCryptoBackend, PureJSBackend } from 'pure-md5';

// Create backend instances
const nodeBackend = new NodeCryptoBackend();
const hash = await nodeBackend.hash('hello');
console.log(hash);

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

Setup

git clone https://github.com/eustatos/pure-md5.git
cd pure-md5
npm install
npm test

Running Tests

npm test                  # Run all tests
npm run coverage          # Generate coverage report
npm run build:watch       # Build in watch mode

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.

💙 Support This Project

If you find this project helpful, please consider supporting it:

• ⭐ Star this repository
• 🐦 Tweet about it
• 💬 Share with your community
• 🍺 Buy me a coffee (coming soon)

📚 Related Resources

• MD5 on Wikipedia
• RFC 1321 - The MD5 Message-Digest Algorithm
• Node.js crypto documentation