docs(readme): enhance documentation with comprehensive formatting and examples

changelog.md

@@ -1,5 +1,21 @@
 # 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
+
+- Replaced the main and typings fields with an exports object that supports both default and web entry points
+- Ensures consistency in module resolution between Node.js and browser environments
+
 ## 2025-06-19 - 3.1.0 - feat(browser)
 Implement fallback SHA256 for non-HTTPS environments and enhance browser tests for consistent hashing
 

package.json

@@ -1,10 +1,12 @@
 {
   "name": "@push.rocks/smarthash",
-  "version": "3.1.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.",
-  "main": "dist_ts/index.js",
+  "exports": {
-  "typings": "dist_ts/index.d.ts",
+    ".": "./dist_ts/index.js",
+    "./web": "./dist_ts_web/index.js"
+  },
   "scripts": {
     "test": "(tstest test/ --web)",
     "build": "(tsbuild tsfolders --allowimplicitany)",

readme.md

@@ -1,119 +1,165 @@
-# @push.rocks/smarthash
+# 🔐 @push.rocks/smarthash
-simplified access to node hash functions
 
-## Install
+> **Cross-environment hashing made simple** 🚀  
-To install `@push.rocks/smarthash`, use the following command with npm:
+> SHA256 and MD5 hash functions that work seamlessly in both Node.js and browsers, with zero configuration.
+
+[![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**: 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
+### 🔤 String Hashing
-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.
 
-### Hashing Strings
-#### SHA-256
 ```typescript
 import { sha256FromString, sha256FromStringSync } from '@push.rocks/smarthash';
 
-// Asynchronously hash a string
+// Async (works everywhere)
-const asyncHash = async () => {
+const hash = await sha256FromString('Hello, world!');
-  const hash = await sha256FromString('Hello, world!');
+console.log(hash); // 📄 64-character hex string
-  console.log(hash); // Output the hashed string
-};
-asyncHash();
 
-// Synchronously hash a string
+// Sync (Node.js only)
-const syncHash = sha256FromStringSync('Hello, world!');
+const hashSync = sha256FromStringSync('Hello, world!');
-console.log(syncHash); // Output the hashed string
+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
+// Legacy MD5 support (use SHA256 for new projects!)
-const md5Hash = async () => {
+const md5Hash = await md5FromString('Hello, world!');
-  const hash = await md5FromString('Hello, world!');
+console.log(md5Hash); // 🔐 32-character MD5 hash
-  console.log(hash); // Output the MD5 hash
-};
-md5Hash();
 ```
 
-### Hashing Files
+## 🌍 Environment Compatibility
-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';
 
-// Asynchronously hash a file
+| Function | Node.js | Browser | Notes |
-const hashFile = async () => {
+|----------|---------|---------|-------|
-  const fileHash = await sha256FromFile('./path/to/your/file.txt');
+| `sha256FromString` | ✅ | ✅ | Universal support |
-  console.log(fileHash); // Output the file's hash
+| `sha256FromStringSync` | ✅ | ❌ | Sync not possible in browsers |
-};
+| `sha256FromBuffer` | ✅ | ✅ | Handles Buffer/Uint8Array |
-hashFile();
+| `sha256FromFile` | ✅ | ❌ | File system access required |
-```
+| `sha256FromStream` | ✅ | ❌ | Node.js streams only |
+| `sha256FromObject` | ✅ | ✅ | Uses JSON serialization |
+| `md5FromString` | ✅ | ❌ | Not supported by Web Crypto API |
 
-### Hashing Streams
+## 🔧 Advanced Usage
-`@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';
 
-// Create a read stream from a file
+### Error Handling
-const readStream = fs.createReadStream('./path/to/your/largeFile.txt');
 
-// 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
+try {
-sha256FromString('test')
+  const hash = await sha256FromString('sensitive data');
-  .then(hash => console.log(hash))
+  console.log(`✅ Hash computed: ${hash}`);
-  .catch(error => console.error(error));
+} catch (error) {
-
+  console.error('❌ Hashing failed:', 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();
 ```
 
-### Best Practices
+### Browser-Specific Features
-- 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.
 
-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
 
@@ -132,4 +178,4 @@ 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.
+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.

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smarthash',
-  version: '3.1.0',
+  version: '3.2.0',
   description: 'Cross-environment hash functions (SHA256 and MD5) for Node.js and browsers, with support for strings, streams, and files.'
 }

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smarthash',
-  version: '3.1.0',
+  version: '3.2.0',
   description: 'Cross-environment hash functions (SHA256 and MD5) for Node.js and browsers, with support for strings, streams, and files.'
 }