s3db.js 11.0.5 → 11.2.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)**

package/SECURITY.md

@@ -0,0 +1,76 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 11.x.x  | :white_check_mark: |
+| < 11.0  | :x:                |
+
+## Known Security Advisories
+
+### Development Dependencies
+
+The following vulnerabilities exist in **development-only** dependencies and **do not affect** the published npm package or runtime security:
+
+#### pkg (GHSA-22r3-9w55-cj54) - MODERATE
+- **Status**: Acknowledged, monitored
+- **Impact**: Local privilege escalation
+- **Scope**: Only affects developers running `pnpm run build:binaries`
+- **Mitigation**: pkg is deprecated and archived. No patched version available (`<0.0.0`).
+- **Risk Assessment**: LOW - Only used for creating standalone binaries during release process
+- **Future Plans**: Migrate to Node.js Single Executable Applications (SEA) when stable
+
+#### tar-fs - HIGH
+- **Status**: RESOLVED in v11.1.1+
+- **Fix**: Updated to patched version 2.1.4+
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in the **runtime code** (not dev dependencies), please report it by:
+
+1. **DO NOT** open a public issue
+2. Email: [security contact - update this]
+3. Include:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+### Response Timeline
+
+- **Initial Response**: Within 48 hours
+- **Status Update**: Within 7 days
+- **Fix Timeline**: Depends on severity
+  - Critical: 7 days
+  - High: 14 days
+  - Medium: 30 days
+  - Low: 60 days
+
+## Security Best Practices
+
+### For Users
+
+1. **Always encrypt sensitive data**: Use `secret` field type for passwords, tokens, etc.
+2. **Validate credentials**: Never commit AWS credentials to version control
+3. **Use IAM policies**: Implement least-privilege access for S3 buckets
+4. **Enable paranoid mode**: For production, use `paranoid: true` for soft deletes
+5. **Audit hooks**: Review serialized functions before deploying to production
+
+### For Contributors
+
+1. **No secrets in tests**: Use environment variables or LocalStack
+2. **Validate input**: All user input should be validated before S3 operations
+3. **Handle errors safely**: Never expose AWS error details to end users
+4. **Review dependencies**: Run `pnpm audit` before submitting PRs
+5. **Test encryption**: Verify `secret` fields are actually encrypted in S3
+
+## Audit Configuration
+
+This project uses `audit-level=high` in `.npmrc` to focus on critical vulnerabilities affecting production. Moderate/low severity issues in dev-only dependencies are monitored but may not block releases if:
+
+- They only affect development tools
+- No patch is available
+- The risk is assessed as acceptable
+
+Current audit threshold: **HIGH** (ignores moderate/low in dev dependencies)