iterflow 0.3.2 → 0.5.0

package/README.md

@@ -45,7 +45,7 @@ import { iter } from 'iterflow';
 iter([1, 2, 3, 4, 5])
   .filter(x => x > 2)    // Native iterator method
   .map(x => x * 2)       // Native iterator method
-  .sum();                // iterflow extension - 18
+  .sum();                // iterflow extension - 24
 ```
 
 ### Functional API
@@ -54,7 +54,7 @@ iter([1, 2, 3, 4, 5])
 import { sum, filter, map } from 'iterflow/fn';
 
 const data = [1, 2, 3, 4, 5];
-sum(map(x => x * 2)(filter(x => x > 2)(data))); // 18
+sum(map(x => x * 2)(filter(x => x > 2)(data))); // 24
 ```
 
 ## Operations
@@ -62,13 +62,11 @@ sum(map(x => x * 2)(filter(x => x > 2)(data))); // 18
 ### Statistical
 
 ```typescript
-const numbers = iter([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
-
-numbers.sum();          // 55
-numbers.mean();         // 5.5
-numbers.median();       // 5.5
-numbers.variance();     // 8.25
-numbers.percentile(75); // 7.75
+iter([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]).sum();          // 55
+iter([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]).mean();         // 5.5
+iter([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]).median();       // 5.5
+iter([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]).variance();     // 8.25
+iter([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]).percentile(75); // 7.75
 ```
 
 ### Windowing
@@ -223,9 +221,89 @@ const movingAverages = iter(temperatures)
   .toArray();
 ```
 
+## When to Use iterflow
+
+iterflow balances developer experience with performance. Here's how to decide:
+
+### Use iterflow when:
+
+- **Large datasets** (1000+ items) - lazy evaluation avoids unnecessary work
+- **Early termination** - finding first match, taking limited results (find, some, every, take)
+- **Memory efficiency** - windowing, chunking, or processing huge files
+- **Complex pipelines** - chaining 3+ operations together
+- **Statistical operations** - mean, median, variance, percentile calculations
+- **Code readability** - method chaining feels more natural than manual loops
+
+### Consider alternatives when:
+
+- **Small arrays** (< 100 items) - native Array methods are slightly faster
+- **Single simple operation** - map or filter alone on small data
+- **Performance-critical hot paths** - called millions of times, every microsecond matters
+- **Need multiple iterations** - arrays are easier to loop over multiple times
+
+### The Trade-off
+
+iterflow uses lazy evaluation, which means:
+- **Lower memory usage** - no intermediate arrays created
+- **Slightly slower per operation** - small function call overhead
+- **Better for large datasets** - memory savings far exceed speed cost
+- **Better for partial consumption** - stops early when possible
+
+### Real Performance Impact
+
+For datasets < 100 items, the differences are negligible—use what feels natural.
+
+For datasets > 1000 items:
+- **With early termination** (take 10 from 100K): iterflow can be 20-300x faster
+- **With windowing** (moving average): iterflow can be 35-600x faster due to memory efficiency
+- **Full consumption** (process all items): native arrays are 2-5x faster
+
+See **[docs/BENCHMARKS.md](docs/BENCHMARKS.md)** for detailed performance data and specific operation comparisons.
+
 <!-- BENCHMARK_SUMMARY_START -->
+## Performance
+
+iterflow balances performance with developer experience. Here's how it performs across different operation categories:
+
+| Category | vs Native | vs Lodash | vs Ramda | Operations Tested |
+|----------|-----------|-----------|----------|-------------------|
+| Transformations | 10.8x slower | 6.9x slower | 8.9x slower | 13 |
+| Statistics | N/A | 1.8x slower | 1.4x slower | 14 |
+| Windowing | N/A | 6.1x slower | 8.7x slower | 13 |
+| Terminals | 5.8x slower | 2.6x slower | 5.1x slower | 13 |
+| Lazy Evaluation | 2.8x slower | N/A | 12.9x slower | 3 |
+| Memory Profiling | N/A | N/A | N/A | 0 |
+| Production Profiling | N/A | N/A | N/A | 0 |
+
+**Detailed benchmarks:** See [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for comprehensive performance data.
+
+*Last updated: December 22, 2025 (v0.4.0)*
 <!-- BENCHMARK_SUMMARY_END -->
 
+## Documentation
+
+- **[FAQ](FAQ.md)** - Frequently asked questions, common patterns, and troubleshooting
+- **[Examples](examples/)** - Real-world usage examples
+- **[SECURITY.md](SECURITY.md)** - Security best practices and vulnerability reporting
+
+## Contributing
+
+We welcome contributions! Please see our [PLAYBOOK.md](PLAYBOOK.md) for:
+
+- Development workflow and branching strategy
+- Commit message guidelines
+- Testing requirements
+- Release process
+
+For quick start:
+
+1. Fork the repository
+2. Create a feature branch from `dev`
+3. Make your changes with tests
+4. Submit a PR to `dev`
+
+See [PLAYBOOK.md](PLAYBOOK.md) for complete details.
+
 ## License
 
 The Unlicense - See [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iterflow",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Powerful iterator utilities for ES2022+ with statistical operations, windowing, and lazy evaluation. Forward compatible with ES2025 iterator helpers.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -41,7 +41,21 @@
     "validate-commits": "node scripts/validate-commits.js",
     "prepublishOnly": "npm run build && npm test && npm run test:types",
     "website:dev": "cd website && npm run dev",
-    "website:build": "npm run build && cd website && npm run build && cd .. && npm run docs"
+    "website:build": "npm run build && cd website && npm run build && cd .. && npm run docs",
+    "bench:transformations": "vitest bench --run benchmarks/transformations.bench.ts",
+    "bench:statistics": "vitest bench --run benchmarks/statistics.bench.ts",
+    "bench:windowing": "vitest bench --run benchmarks/windowing.bench.ts",
+    "bench:terminals": "vitest bench --run benchmarks/terminals.bench.ts",
+    "bench:lazy-evaluation": "vitest bench --run benchmarks/lazy-evaluation.bench.ts",
+    "bench:memory-profiling": "vitest bench --run benchmarks/memory-profiling.bench.ts",
+    "bench:production-profiling": "vitest bench --run benchmarks/production-profiling.bench.ts",
+    "bench:quick": "VITEST_BENCH_TIME=1000 node scripts/run-benchmarks.cjs",
+    "bench:all": "node scripts/run-benchmarks.cjs",
+    "bench:report": "node scripts/generate-benchmark-report.cjs",
+    "bench:update-readme": "node scripts/update-readme-benchmarks.cjs",
+    "bench:update-changelog": "node scripts/update-changelog-benchmarks.cjs",
+    "bench:full": "npm run bench:all && npm run bench:report && npm run bench:update-readme",
+    "bench:workflow": "bash scripts/run-benchmarks-full.sh"
   },
   "keywords": [
     "iterator",