docs(readme): enhance documentation with comprehensive formatting and examples
This commit is contained in:
10
changelog.md
10
changelog.md
@@ -1,5 +1,15 @@
|
||||
# Changelog
|
||||
|
||||
## 2025-08-03 - 3.2.1 - docs(readme)
|
||||
Enhance readme with comprehensive documentation and modern formatting
|
||||
|
||||
- Updated readme.md with enhanced formatting, emojis, and badges
|
||||
- Added comprehensive API reference with clear examples for all functions
|
||||
- Included environment compatibility table showing Node.js vs Browser support
|
||||
- Added advanced usage examples including error handling and import strategies
|
||||
- Improved documentation structure with better visual organization
|
||||
- Fixed typo in sha265FromObject examples to sha256FromObject
|
||||
|
||||
## 2025-06-19 - 3.2.0 - feat(package)
|
||||
Update package.json to use exports field for dual entry points
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@push.rocks/smarthash",
|
||||
"version": "3.2.0",
|
||||
"version": "3.2.1",
|
||||
"private": false,
|
||||
"description": "Cross-environment hash functions (SHA256 and MD5) for Node.js and browsers, with support for strings, streams, and files.",
|
||||
"exports": {
|
||||
|
||||
222
readme.md
222
readme.md
@@ -1,119 +1,165 @@
|
||||
# @push.rocks/smarthash
|
||||
simplified access to node hash functions
|
||||
# 🔐 @push.rocks/smarthash
|
||||
|
||||
## Install
|
||||
To install `@push.rocks/smarthash`, use the following command with npm:
|
||||
> **Cross-environment hashing made simple** 🚀
|
||||
> SHA256 and MD5 hash functions that work seamlessly in both Node.js and browsers, with zero configuration.
|
||||
|
||||
[](https://www.npmjs.com/package/@push.rocks/smarthash)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](#)
|
||||
|
||||
## ✨ Why SmartHash?
|
||||
|
||||
- 🌐 **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
|
||||
|
||||
```bash
|
||||
npm install @push.rocks/smarthash --save
|
||||
pnpm install @push.rocks/smarthash
|
||||
```
|
||||
|
||||
This will add `@push.rocks/smarthash` to your project's dependencies.
|
||||
## 📖 API Reference
|
||||
|
||||
## Usage
|
||||
The `@push.rocks/smarthash` library provides a simplified interface to Node.js hash functions, including utilities for hashing strings, files, and streams with popular algorithms like SHA-256 and MD5. Below are detailed examples to demonstrate the capabilities and usage of this library using ESM syntax and TypeScript.
|
||||
### 🔤 String Hashing
|
||||
|
||||
### Hashing Strings
|
||||
#### SHA-256
|
||||
```typescript
|
||||
import { sha256FromString, sha256FromStringSync } from '@push.rocks/smarthash';
|
||||
|
||||
// Asynchronously hash a string
|
||||
const asyncHash = async () => {
|
||||
const hash = await sha256FromString('Hello, world!');
|
||||
console.log(hash); // Output the hashed string
|
||||
};
|
||||
asyncHash();
|
||||
// Async (works everywhere)
|
||||
const hash = await sha256FromString('Hello, world!');
|
||||
console.log(hash); // 📄 64-character hex string
|
||||
|
||||
// Synchronously hash a string
|
||||
const syncHash = sha256FromStringSync('Hello, world!');
|
||||
console.log(syncHash); // Output the hashed string
|
||||
// Sync (Node.js only)
|
||||
const hashSync = sha256FromStringSync('Hello, world!');
|
||||
console.log(hashSync); // ⚡ Instant result
|
||||
```
|
||||
|
||||
#### MD5
|
||||
### 🗂️ File & Stream Hashing (Node.js Only)
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 🧱 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
|
||||
```
|
||||
|
||||
### 🎯 Object Hashing
|
||||
|
||||
```typescript
|
||||
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)
|
||||
|
||||
```typescript
|
||||
import { md5FromString } from '@push.rocks/smarthash';
|
||||
|
||||
// Asynchronously hash a string with MD5
|
||||
const md5Hash = async () => {
|
||||
const hash = await md5FromString('Hello, world!');
|
||||
console.log(hash); // Output the MD5 hash
|
||||
};
|
||||
md5Hash();
|
||||
// Legacy MD5 support (use SHA256 for new projects!)
|
||||
const md5Hash = await md5FromString('Hello, world!');
|
||||
console.log(md5Hash); // 🔐 32-character MD5 hash
|
||||
```
|
||||
|
||||
### Hashing Files
|
||||
To hash a file, you can use the `sha256FromFile` function. It reads the file specified by the path and calculates the SHA-256 hash.
|
||||
```typescript
|
||||
import { sha256FromFile } from '@push.rocks/smarthash';
|
||||
## 🌍 Environment Compatibility
|
||||
|
||||
// Asynchronously hash a file
|
||||
const hashFile = async () => {
|
||||
const fileHash = await sha256FromFile('./path/to/your/file.txt');
|
||||
console.log(fileHash); // Output the file's hash
|
||||
};
|
||||
hashFile();
|
||||
```
|
||||
| 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 |
|
||||
|
||||
### Hashing Streams
|
||||
`@push.rocks/smarthash` also allows for hashing of streams, which is particularly useful for large files or data streams.
|
||||
```typescript
|
||||
import { sha256FromStream } from '@push.rocks/smarthash';
|
||||
import fs from 'fs';
|
||||
## 🔧 Advanced Usage
|
||||
|
||||
// Create a read stream from a file
|
||||
const readStream = fs.createReadStream('./path/to/your/largeFile.txt');
|
||||
### Error Handling
|
||||
|
||||
// Asynchronously hash the stream
|
||||
const hashStream = async () => {
|
||||
const streamHash = await sha256FromStream(readStream);
|
||||
console.log(streamHash); // Output the hash of the stream's content
|
||||
};
|
||||
hashStream();
|
||||
```
|
||||
|
||||
### Advanced Usage
|
||||
#### Hashing Objects
|
||||
For hashing JavaScript objects, you can serialize them and hash the resulting string. This is useful for creating hashes from complex data structures.
|
||||
```typescript
|
||||
import { sha265FromObject } from '@push.rocks/smarthash';
|
||||
|
||||
// Hash a JavaScript object
|
||||
const hashObject = async () => {
|
||||
const object = { hello: 'world', number: 42 };
|
||||
const objectHash = await sha265FromObject(object);
|
||||
console.log(objectHash); // Output the hash of the object
|
||||
};
|
||||
hashObject();
|
||||
```
|
||||
|
||||
#### Error Handling
|
||||
All asynchronous functions return promises, so you can use `.catch()` for error handling or try-catch blocks within async functions.
|
||||
```typescript
|
||||
import { sha256FromString } from '@push.rocks/smarthash';
|
||||
|
||||
// Using .catch() for promises
|
||||
sha256FromString('test')
|
||||
.then(hash => console.log(hash))
|
||||
.catch(error => console.error(error));
|
||||
|
||||
// Using try-catch with async functions
|
||||
const getHash = async () => {
|
||||
try {
|
||||
const hash = await sha256FromString('test');
|
||||
console.log(hash);
|
||||
} catch (error) {
|
||||
console.error(error);
|
||||
}
|
||||
};
|
||||
getHash();
|
||||
try {
|
||||
const hash = await sha256FromString('sensitive data');
|
||||
console.log(`✅ Hash computed: ${hash}`);
|
||||
} catch (error) {
|
||||
console.error('❌ Hashing failed:', error);
|
||||
}
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
- Utilize asynchronous functions for hashing large files or streams to avoid blocking the main thread.
|
||||
- For hashing sensitive information, ensure to follow security best practices, including using up-to-date algorithms and managing secrets properly.
|
||||
### Browser-Specific Features
|
||||
|
||||
By leveraging `@push.rocks/smarthash`, developers can easily integrate hashing functionalities into their Node.js applications, benefiting from its simplified API and TypeScript support for better development experience.
|
||||
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
|
||||
|
||||
```typescript
|
||||
// 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
We welcome contributions! This project follows modern TypeScript practices and includes comprehensive tests for both environments.
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
|
||||
Reference in New Issue
Block a user