iterflow 0.4.0 → 0.7.0

package/README.md

@@ -221,13 +221,52 @@ const movingAverages = iter(temperatures)
   .toArray();
 ```
 
-<!-- BENCHMARK_SUMMARY_START -->
-<!-- BENCHMARK_SUMMARY_END -->
+## 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.
 
 ## Documentation
 
 - **[FAQ](FAQ.md)** - Frequently asked questions, common patterns, and troubleshooting
 - **[Examples](examples/)** - Real-world usage examples
+- **[Memory Safety Guide](docs/guides/memory-safety.md)** - Avoiding memory leaks and efficient memory usage
+- **[Performance Guide](docs/PERFORMANCE.md)** - Optimization techniques and benchmarking
+- **[Benchmarking Guide](docs/BENCHMARKING.md)** - Running and interpreting benchmarks
 - **[SECURITY.md](SECURITY.md)** - Security best practices and vulnerability reporting
 
 ## Contributing

package/dist/fn/index.cjs

@@ -183,6 +183,13 @@ function transducerToIterator(transducer) {
 
 // src/fn/index.ts
 function sum(iterable) {
+  if (Array.isArray(iterable)) {
+    let total2 = 0;
+    for (let i = 0; i < iterable.length; i++) {
+      total2 += iterable[i];
+    }
+    return total2;
+  }
   let total = 0;
   for (const value of iterable) {
     total += value;
@@ -190,6 +197,14 @@ function sum(iterable) {
   return total;
 }
 function mean(iterable) {
+  if (Array.isArray(iterable)) {
+    if (iterable.length === 0) return void 0;
+    let total2 = 0;
+    for (let i = 0; i < iterable.length; i++) {
+      total2 += iterable[i];
+    }
+    return total2 / iterable.length;
+  }
   let total = 0;
   let count2 = 0;
   for (const value of iterable) {
@@ -199,6 +214,10 @@ function mean(iterable) {
   return count2 === 0 ? void 0 : total / count2;
 }
 function min(iterable) {
+  if (Array.isArray(iterable)) {
+    if (iterable.length === 0) return void 0;
+    return Math.min(...iterable);
+  }
   let minimum = void 0;
   for (const value of iterable) {
     if (minimum === void 0 || value < minimum) {
@@ -208,6 +227,10 @@ function min(iterable) {
   return minimum;
 }
 function max(iterable) {
+  if (Array.isArray(iterable)) {
+    if (iterable.length === 0) return void 0;
+    return Math.max(...iterable);
+  }
   let maximum = void 0;
   for (const value of iterable) {
     if (maximum === void 0 || value > maximum) {
@@ -217,6 +240,9 @@ function max(iterable) {
   return maximum;
 }
 function count(iterable) {
+  if (Array.isArray(iterable)) {
+    return iterable.length;
+  }
   let count2 = 0;
   for (const _ of iterable) {
     count2++;
@@ -224,18 +250,18 @@ function count(iterable) {
   return count2;
 }
 function median(iterable) {
-  const values = Array.from(iterable);
+  const values = Array.isArray(iterable) ? iterable : Array.from(iterable);
   if (values.length === 0) return void 0;
-  values.sort((a, b) => a - b);
-  const mid = Math.floor(values.length / 2);
-  if (values.length % 2 === 0) {
-    return (values[mid - 1] + values[mid]) / 2;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  if (sorted.length % 2 === 0) {
+    return (sorted[mid - 1] + sorted[mid]) / 2;
   } else {
-    return values[mid];
+    return sorted[mid];
   }
 }
 function variance(iterable) {
-  const values = Array.from(iterable);
+  const values = Array.isArray(iterable) ? iterable : Array.from(iterable);
   if (values.length === 0) return void 0;
   const mean2 = values.reduce((sum2, val) => sum2 + val, 0) / values.length;
   let sumSquaredDiffs = 0;
@@ -251,22 +277,22 @@ function stdDev(iterable) {
 }
 function percentile(iterable, p) {
   validateRange(p, 0, 100, "percentile", "percentile");
-  const values = Array.from(iterable);
+  const values = Array.isArray(iterable) ? iterable : Array.from(iterable);
   if (values.length === 0) return void 0;
-  values.sort((a, b) => a - b);
-  if (p === 0) return values[0];
-  if (p === 100) return values[values.length - 1];
-  const index = p / 100 * (values.length - 1);
+  const sorted = values.slice().sort((a, b) => a - b);
+  if (p === 0) return sorted[0];
+  if (p === 100) return sorted[sorted.length - 1];
+  const index = p / 100 * (sorted.length - 1);
   const lower = Math.floor(index);
   const upper = Math.ceil(index);
   if (lower === upper) {
-    return values[lower];
+    return sorted[lower];
   }
   const weight = index - lower;
-  return values[lower] * (1 - weight) + values[upper] * weight;
+  return sorted[lower] * (1 - weight) + sorted[upper] * weight;
 }
 function mode(iterable) {
-  const values = Array.from(iterable);
+  const values = Array.isArray(iterable) ? iterable : Array.from(iterable);
   if (values.length === 0) return void 0;
   const frequency = /* @__PURE__ */ new Map();
   let maxFreq = 0;
@@ -284,20 +310,20 @@ function mode(iterable) {
   return modes.sort((a, b) => a - b);
 }
 function quartiles(iterable) {
-  const values = Array.from(iterable);
+  const values = Array.isArray(iterable) ? iterable : Array.from(iterable);
   if (values.length === 0) return void 0;
-  values.sort((a, b) => a - b);
+  const sorted = values.slice().sort((a, b) => a - b);
   const calculatePercentile = (p) => {
-    if (p === 0) return values[0];
-    if (p === 100) return values[values.length - 1];
-    const index = p / 100 * (values.length - 1);
+    if (p === 0) return sorted[0];
+    if (p === 100) return sorted[sorted.length - 1];
+    const index = p / 100 * (sorted.length - 1);
     const lower = Math.floor(index);
     const upper = Math.ceil(index);
     if (lower === upper) {
-      return values[lower];
+      return sorted[lower];
     }
     const weight = index - lower;
-    return values[lower] * (1 - weight) + values[upper] * weight;
+    return sorted[lower] * (1 - weight) + sorted[upper] * weight;
   };
   return {
     Q1: calculatePercentile(25),