3.2.4

changelog.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2025-09-12 - 3.2.4 - fix(deps)
+Bump devDependencies, update smartjson and add workspace/CI settings
+
+- Bump @git.zone/tsbuild from ^2.1.70 to ^2.6.8
+- Bump @git.zone/tstest from ^2.3.2 to ^2.3.8
+- Bump @push.rocks/smartjson from ^5.0.10 to ^5.2.0
+- Add pnpm-workspace.yaml with onlyBuiltDependencies: esbuild, mongodb-memory-server, puppeteer
+- Add .claude/settings.local.json to allow WebFetch access to www.npmjs.com
+
+## 2025-08-03 - 3.2.3 - fix(dependencies/config)
+Update dependency versions and add local settings for web fetch configuration
+
+- Bump @git.zone/tstest from ^1.0.81 to ^2.3.2
+- Bump @push.rocks/smartenv from ^5.0.5 to ^5.0.13
+- Add .claude/settings.local.json to allow WebFetch permissions for www.npmjs.com
+
+## 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
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/smarthash",
-  "version": "3.2.0",
+  "version": "3.2.4",
   "private": false,
   "description": "Cross-environment hash functions (SHA256 and MD5) for Node.js and browsers, with support for strings, streams, and files.",
   "exports": {
@@ -32,14 +32,14 @@
   "author": "Lossless GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.70",
+    "@git.zone/tsbuild": "^2.6.8",
     "@git.zone/tsrun": "^1.2.46",
-    "@git.zone/tstest": "^1.0.81",
+    "@git.zone/tstest": "^2.3.8",
     "@types/node": "^20.6.3"
   },
   "dependencies": {
-    "@push.rocks/smartenv": "^5.0.5",
-    "@push.rocks/smartjson": "^5.0.10",
+    "@push.rocks/smartenv": "^5.0.13",
+    "@push.rocks/smartjson": "^5.2.0",
     "@push.rocks/smartpromise": "^4.0.3",
     "@types/through2": "^2.0.39",
     "through2": "^4.0.2"

pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+onlyBuiltDependencies:
+  - esbuild
+  - mongodb-memory-server
+  - puppeteer

readme.md

@@ -1,119 +1,161 @@
-# @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.
+
+[![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
-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
 
 ## License and Legal Information
 
@@ -132,4 +174,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.2.0',
+  version: '3.2.4',
   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.2.0',
+  version: '3.2.4',
   description: 'Cross-environment hash functions (SHA256 and MD5) for Node.js and browsers, with support for strings, streams, and files.'
 }