s3db.js 11.0.4 → 11.1.0

package/README.md

@@ -794,7 +794,7 @@ await users.insert({ name: "John", email: "john@example.com" });
 - **📝 [Audit Plugin](./docs/plugins/audit.md)** - Comprehensive audit logging for compliance
 - **📬 [Queue Consumer Plugin](./docs/plugins/queue-consumer.md)** - Message consumption from SQS/RabbitMQ
 - **🔒 [S3Queue Plugin](./docs/plugins/s3-queue.md)** - Distributed queue processing with zero race conditions
-- **📈 [Eventual Consistency Plugin](./docs/plugins/eventual-consistency.md)** - Event sourcing for numeric fields
+- **📈 [Eventual Consistency Plugin](./docs/plugins/eventual-consistency.md)** - Transactional counters with pre-computed analytics (15 functions for time-series data)
 - **📅 [Scheduler Plugin](./docs/plugins/scheduler.md)** - Task scheduling and automation
 - **🔄 [State Machine Plugin](./docs/plugins/state-machine.md)** - State management and transitions
 - **💾 [Backup Plugin](./docs/plugins/backup.md)** - Backup and restore functionality
@@ -1868,6 +1868,12 @@ await users.insert({ name: 'John' });
 
 ## 📖 API Reference
 
+### 📚 Core Classes Documentation
+
+- **[Client Class](./docs/client.md)** - Low-level S3 operations, HTTP client configuration, and advanced object management
+- **[Database Class](./docs/database.md)** - High-level database interface (coming soon)
+- **[Resource Class](./docs/resource.md)** - Resource operations and methods (coming soon)
+
 ### 🔌 Database Operations
 
 | Method | Description | Example |
@@ -1971,4 +1977,55 @@ console.log(`Total users: ${allUsers.length}`);
 | Method | Description | Example |
 |--------|-------------|---------|
 | `readable(options?)` | Create readable stream | `await users.readable()` |
-| `writable(options?)` | Create writable stream | `await users.writable()` |
+| `writable(options?)` | Create writable stream | `await users.writable()` |
+
+---
+
+## 📊 Performance Benchmarks
+
+> **⚠️ Important**: All benchmark results documented below were generated using **Node.js v22.6.0**. Performance results may vary with different Node.js versions.
+
+s3db.js includes comprehensive benchmarks demonstrating real-world performance optimizations. Key areas tested:
+
+### 🎯 Data Encoding & Compression
+
+**[Base62 Encoding](./docs/benchmarks/base62.md)** - Number compression for S3 metadata
+- **40-46% space savings** for large numbers
+- **5x faster encoding** vs Base36
+- **Real-world impact**: More data fits in 2KB S3 metadata limit
+
+**[Advanced Encoding](./docs/benchmarks/advanced-encoding.md)** - Multi-technique compression
+- **67% savings** on ISO timestamps (Unix Base62)
+- **33% savings** on UUIDs (Binary Base64)
+- **95% savings** on common values (Dictionary encoding)
+- **Overall**: 40-50% metadata reduction on typical datasets
+
+**[Smart Encoding](./docs/benchmarks/smart-encoding.md)** - Intelligent encoding selection
+- **Automatic type detection** and optimal encoding selection
+- **2-3x faster** UTF-8 byte calculations with caching
+- **Lazy evaluation** for performance-critical paths
+
+### 🔌 Plugin Performance
+
+**[EventualConsistency Plugin](./docs/benchmarks/eventual-consistency.md)** - Transaction processing & analytics
+- **70-100% faster writes** with async partitions
+- **Parallel analytics updates** for high-throughput scenarios
+- **O(1) partition queries** vs O(n) full scans
+
+### 🗂️ Partitioning Performance
+
+**[Partitions Matrix Benchmark](./docs/benchmarks/partitions.md)** - Performance testing across partition configurations
+- **Test matrix**: 0-10 partitions × 1-10 attributes (110 combinations)
+- **Measurements**: Create, insert, query (partition & full scan)
+- **Insights**: Find optimal partition configuration for your use case
+- Run with: `pnpm run benchmark:partitions`
+
+### 📖 Benchmark Documentation
+
+All benchmarks include:
+- ✅ **TL;DR summary** - Quick results and recommendations
+- ✅ **Code examples** - Runnable benchmark scripts
+- ✅ **Performance metrics** - Real numbers with explanations
+- ✅ **Use cases** - When to apply each optimization
+
+**[📋 Complete Benchmark Index](./docs/benchmarks/README.md)**