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';

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 - < 1KB gzipped
• 🎯 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';

// String input
md5('hello'); // "5d41402abc4b2a76b9719d911017c592"

// Buffer input
md5(Buffer.from('hello')); // "5d41402abc4b2a76b9719d911017c592"

// Custom encoding
md5('hello', 'hex'); // "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 | crypto-js | js-md4 | Node.js crypto | |---------|----------|-----------|--------|----------------| | Bundle Size | <1KB | ~4KB | ~2KB | N/A | | Dependencies | 0 | 0 | 0 | 0 | | Streaming | ✅ | ❌ | ❌ | ✅ | | Browser Support | ✅ | ✅ | ✅ | ❌ | | TypeScript | ✅ | ❌ | ⚠️ | ❌ | | Zero Config | ✅ | ✅ | ❌ | ✅ |

🔧 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

import { md5 } from 'pure-md5/adapters/node';
// or
import { md5 } from 'pure-md5/adapters/webcrypto';
// or
import { md5 } from 'pure-md5/adapters/pure-js';

🤝 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

*Made with ❤️ by Aleksandr Astashkin