runframe 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runframe",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "High-performance, security-hardened JavaScript sandbox for executing untrusted code with worker pooling, script caching, and resource limits",
   "type": "module",
   "main": "dist/sandbox.js",

package/README.md

@@ -1,351 +0,0 @@
-# 📚 Complete Documentation Index
-
-## 🚀 Start Here
-
-If you're new, read in this order:
-
-1. **[QUICK_START.md](QUICK_START.md)** ← **START HERE** (10 min read)
-   - 3-step setup
-   - Copy-paste examples
-   - Configuration recipes
-   - Quick troubleshooting
-
-2. **[OPTIMIZATION_SUMMARY.md](OPTIMIZATION_SUMMARY.md)** (5 min read)
-   - What was optimized
-   - Benchmark results
-   - 4 major improvements
-   - Getting started checklist
-
-3. **[FEATURE_MATRIX.md](FEATURE_MATRIX.md)** (10 min read)
-   - Architecture layers
-   - Feature comparison
-   - Security matrix
-   - Performance metrics
-
-4. **[OPTIMIZATION.md](OPTIMIZATION.md)** (20 min read)
-   - Deep technical dive
-   - How each optimization works
-   - When to use what
-   - Pro tips
-
-5. **[FILE_STRUCTURE.md](FILE_STRUCTURE.md)** (15 min read)
-   - What each file does
-   - ~2,000 lines of code explained
-   - Migration guide
-   - Usage flowchart
-
----
-
-## 🎯 By Use Case
-
-### "I just want to use it"
-→ Read [QUICK_START.md](QUICK_START.md) then copy an example
-
-### "I want to understand the optimizations"
-→ Read [OPTIMIZATION.md](OPTIMIZATION.md)
-
-### "I need to monitor/debug"
-→ Go to [FEATURE_MATRIX.md](FEATURE_MATRIX.md) section on monitoring
-
-### "I'm migrating from old sandbox"
-→ Check [FILE_STRUCTURE.md](FILE_STRUCTURE.md) migration guide
-
-### "I need specific performance numbers"
-→ Check [OPTIMIZATION_SUMMARY.md](OPTIMIZATION_SUMMARY.md) benchmarks
-
-### "I want to understand architecture"
-→ Read [FEATURE_MATRIX.md](FEATURE_MATRIX.md) architecture section
-
----
-
-## 📁 File Descriptions
-
-### Documentation Files (Read These)
-
-| File | Purpose | Read Time | Depth |
-|------|---------|-----------|-------|
-| [QUICK_START.md](QUICK_START.md) | Get started fast | 10 min | Shallow |
-| [OPTIMIZATION_SUMMARY.md](OPTIMIZATION_SUMMARY.md) | Overview & results | 5 min | Shallow |
-| [FEATURE_MATRIX.md](FEATURE_MATRIX.md) | Complete feature list | 10 min | Medium |
-| [OPTIMIZATION.md](OPTIMIZATION.md) | Technical deep dive | 20 min | Deep |
-| [FILE_STRUCTURE.md](FILE_STRUCTURE.md) | Code organization | 15 min | Medium |
-| **This file** | Documentation index | 5 min | - |
-
-### Source Code Files (Use These)
-
-#### Core (Original)
-| File | Lines | Purpose | Importance |
-|------|-------|---------|------------|
-| [src/sandbox.ts](src/sandbox.ts) | 126 | Original basic API | 🟡 Backup |
-| [src/worker.ts](src/worker.ts) | 44 | Worker entry point | 🔴 Internal |
-| [src/vm-runtime.ts](src/vm-runtime.ts) | 224 | VM setup + hardening | 🟢 Core |
-
-#### Features (Original)
-| File | Lines | Purpose | Importance |
-|------|-------|---------|------------|
-| [src/capabilities.ts](src/capabilities.ts) | 115 | Access control | 🟡 Feature |
-| [src/deterministic.ts](src/deterministic.ts) | 115 | Safe APIs | 🟡 Feature |
-| [src/stats.ts](src/stats.ts) | 71 | Metrics | 🟡 Feature |
-| [src/async.ts](src/async.ts) | 91 | Promise tracking | 🟡 Feature |
-| [src/test-corpus.ts](src/test-corpus.ts) | 196 | Security tests | 🟡 Testing |
-| [src/limits.ts](src/limits.ts) | 62 | Resource presets | 🟡 Config |
-
-#### Optimizations (NEW)
-| File | Lines | Purpose | Use This |
-|------|-------|---------|----------|
-| [src/optimized-sandbox.ts](src/optimized-sandbox.ts) | 168 | 🚀 Main optimized API | **✅ YES** |
-| [src/worker-pool.ts](src/worker-pool.ts) | 174 | Worker reuse | ✅ Included |
-| [src/script-cache.ts](src/script-cache.ts) | 86 | Script caching | ✅ Included |
-| [src/memory-optimization.ts](src/memory-optimization.ts) | 148 | Memory utils | ✅ Included |
-
-#### Examples & Tests
-| File | Lines | Purpose | Run With |
-|------|-------|---------|----------|
-| [src/optimization-examples.ts](src/optimization-examples.ts) | 364 | 6 examples | `npx tsx src/optimization-examples.ts` |
-| [src/benchmark.ts](src/benchmark.ts) | 340 | Performance tests | `npx tsx src/benchmark.ts` |
-
----
-
-## 🎯 Decision Tree
-
-```
-START
-  ↓
-"Which API should I use?"
-  ├─ Learning/Development? → createSandbox (original)
-  └─ Production? → createOptimizedSandbox ✅
-       ↓
-     "Do I have high traffic?"
-       ├─ NO (<10 req/s)? → DEFAULT_POOL_CONFIG
-       └─ YES (>50 req/s)? → HIGH_CONCURRENCY_CONFIG
-            ↓
-          "Is code repeated?"
-            ├─ NO (all unique)? → cacheScripts: false
-            └─ YES (templates/rules)? → cacheScripts: true ✅
-                 ↓
-               "Many operations?"
-                 ├─ Sequential? → Use .run()
-                 └─ Batch? → Use .batch() ✅
-```
-
----
-
-## 📖 Code Examples by Topic
-
-### Setup & Configuration
-→ [QUICK_START.md](QUICK_START.md#5-minute-setup)
-
-### Batch Processing
-→ [QUICK_START.md](QUICK_START.md#example-3-batch-processing)
-
-### Discord Bot
-→ [QUICK_START.md](QUICK_START.md#example-1-discord-bot-high-throughput)
-
-### Express API
-→ [QUICK_START.md](QUICK_START.md#example-2-express-api)
-
-### Monitoring
-→ [QUICK_START.md](QUICK_START.md#monitoring)
-
-### Performance Tuning
-→ [OPTIMIZATION.md](OPTIMIZATION.md#-pro-tips)
-
-### Running Benchmarks
-→ [src/benchmark.ts](src/benchmark.ts) (run it!)
-
-### 6 Working Examples
-→ [src/optimization-examples.ts](src/optimization-examples.ts)
-
----
-
-## 🚀 Quick Commands
-
-```bash
-# Build the project
-npm run build
-
-# Run performance benchmarks
-npx tsx src/benchmark.ts
-
-# Run 6 optimization examples
-npx tsx src/optimization-examples.ts
-
-# Run TypeScript
-npm run dev
-
-# Watch for changes
-npm run dev
-```
-
----
-
-## 📊 Performance Quick Reference
-
-### Old vs New
-```
-Metric              Before      After       Improvement
-────────────────────────────────────────────────────────
-100 concurrent      11.5s       0.8s        14.4x faster ⚡
-Same formula ×50    250ms       50ms        5x faster
-Memory (100 exec)   45MB        20MB        55% saved
-Workers needed      100         4           96% fewer
-p99 latency         500ms       50ms        10x better
-```
-
-### Configuration Recommendations
-```
-Traffic Level    Min Workers    Max Workers    Cache Scripts
-─────────────────────────────────────────────────────────────
-Hobby            1              2              Yes
-Light (<5/s)     2              4              Yes
-Medium (5-50/s)  4              16             Yes
-High (>50/s)     8              32             Yes
-Batch/ETL        2              16             No
-Memory const.    1              2              No
-```
-
----
-
-## ✅ Setup Checklist
-
-- [ ] Read [QUICK_START.md](QUICK_START.md)
-- [ ] Run `npm run build`
-- [ ] Run `npx tsx src/benchmark.ts` to see improvements
-- [ ] Choose API: `createOptimizedSandbox` (recommended)
-- [ ] Configure pool size for your traffic
-- [ ] Enable/disable script caching (yes for templates)
-- [ ] Set up monitoring with `.stats()`
-- [ ] Test with your real code
-- [ ] Monitor in production
-- [ ] Adjust config based on metrics
-
----
-
-## 🔍 Troubleshooting
-
-**"Where do I start?"**
-→ [QUICK_START.md](QUICK_START.md)
-
-**"Why is it slow?"**
-→ [OPTIMIZATION.md](OPTIMIZATION.md#quick-troubleshooting-guide)
-
-**"How do I monitor?"**
-→ [QUICK_START.md](QUICK_START.md#monitoring)
-
-**"What config should I use?"**
-→ [QUICK_START.md](QUICK_START.md#configuration-recipes)
-
-**"Is it secure?"**
-→ [FEATURE_MATRIX.md](FEATURE_MATRIX.md#-security-features-matrix)
-
-**"How much faster?"**
-→ [OPTIMIZATION_SUMMARY.md](OPTIMIZATION_SUMMARY.md#-benchmark-results)
-
-**"Will it break my code?"**
-→ [FILE_STRUCTURE.md](FILE_STRUCTURE.md#-migration-guide)
-
----
-
-## 📈 Learning Path
-
-### Beginner (30 min)
-1. Read [QUICK_START.md](QUICK_START.md) (10 min)
-2. Run `npm run build && npx tsx src/benchmark.ts` (5 min)
-3. Copy an example and modify it (15 min)
-
-### Intermediate (90 min)
-1. Read [OPTIMIZATION.md](OPTIMIZATION.md) (20 min)
-2. Read [FEATURE_MATRIX.md](FEATURE_MATRIX.md) (10 min)
-3. Run [optimization-examples.ts](src/optimization-examples.ts) (10 min)
-4. Tune config for your hardware (50 min)
-
-### Advanced (3 hours)
-1. Read [FILE_STRUCTURE.md](FILE_STRUCTURE.md) (15 min)
-2. Study [worker-pool.ts](src/worker-pool.ts) (30 min)
-3. Study [script-cache.ts](src/script-cache.ts) (20 min)
-4. Study [memory-optimization.ts](src/memory-optimization.ts) (20 min)
-5. Implement custom pooling strategy (90 min)
-
----
-
-## 🎓 Key Concepts
-
-### Worker Pooling
-- Reuse threads instead of spawning new ones
-- Keep minimum workers warm
-- Kill idle workers after timeout
-- Prevent resource explosion
-
-[Learn more →](OPTIMIZATION.md#1-worker-pool-50-70-faster)
-
-### Script Caching
-- Compile code once, run many times
-- Hash-based lookup
-- LRU eviction when full
-- Especially good for templates
-
-[Learn more →](OPTIMIZATION.md#2-script-caching-30-80-faster)
-
-### Batch Execution
-- Execute many operations in parallel
-- Controlled concurrency
-- Single pool overhead
-- Per-operation stats
-
-[Learn more →](OPTIMIZATION.md#3-batch-execution-40-60-overhead-reduction)
-
-### Memory Optimization
-- Lazy proxies only for denied capabilities
-- Compressed stats storage
-- GC hints when needed
-- Bounded queues prevent explosion
-
-[Learn more →](OPTIMIZATION.md#4-memory-optimization-30-50-less-memory)
-
----
-
-## 🏆 What You Get
-
-✅ **10-100x faster** execution
-✅ **50-75% less memory** usage
-✅ **Production ready** code
-✅ **Zero breaking changes** to original API
-✅ **6 working examples**
-✅ **Performance benchmarks**
-✅ **Complete documentation**
-✅ **Security hardened** sandbox
-✅ **Monitoring** built-in
-✅ **Easy to tune** for your hardware
-
----
-
-## 🚀 Next Steps
-
-1. **Right now:** Read [QUICK_START.md](QUICK_START.md)
-2. **Today:** Run benchmarks, copy an example
-3. **This week:** Deploy optimized version
-4. **Ongoing:** Monitor and tune
-
----
-
-## 📞 Questions?
-
-- **Setup?** → [QUICK_START.md](QUICK_START.md)
-- **Performance?** → [OPTIMIZATION.md](OPTIMIZATION.md)
-- **Architecture?** → [FEATURE_MATRIX.md](FEATURE_MATRIX.md)
-- **Files?** → [FILE_STRUCTURE.md](FILE_STRUCTURE.md)
-- **Results?** → [OPTIMIZATION_SUMMARY.md](OPTIMIZATION_SUMMARY.md)
-
----
-
-## 🎉 You're Ready!
-
-Everything is documented, tested, and ready for production.
-
-**Pick your configuration, deploy, and enjoy 10-100x faster execution!** 🚀
-
----
-
-**Last updated:** December 27, 2025
-**Version:** 1.0.0 Optimized
-**Status:** ✅ Production Ready