@mathscapes/iterflow 1.0.0-rc1

package/dist/index.d.cts

@@ -0,0 +1,129 @@
+/**
+ * Base error class for all iterflow errors.
+ */
+declare class IterflowError extends Error {
+    constructor(msg: string);
+}
+/**
+ * Thrown by statistical methods when called on empty sequences.
+ */
+declare class EmptySequenceError extends IterflowError {
+    readonly op: string;
+    constructor(op: string);
+}
+type Predicate<T> = (v: T, i: number) => boolean;
+type Mapper<T, U> = (v: T, i: number) => U;
+type Reducer<T, U> = (acc: U, v: T, i: number) => U;
+type FlatMapper<T, U> = (v: T, i: number) => Iterable<U>;
+/**
+ * Type guard to check if a value is iterable.
+ */
+declare const isIterable: (v: unknown) => v is Iterable<unknown>;
+
+/**
+ * Calculate the sum of all numbers.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const sum: (src: Iterable<number>) => number;
+/**
+ * Calculate the arithmetic mean.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const mean: (src: Iterable<number>) => number;
+/**
+ * Calculate the median (50th percentile) using Quickselect algorithm.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const median: (src: Iterable<number>) => number;
+/**
+ * Find the minimum value.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const min: (src: Iterable<number>) => number;
+/**
+ * Find the maximum value.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const max: (src: Iterable<number>) => number;
+/**
+ * Calculate the population variance using Welford's online algorithm.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const variance: (src: Iterable<number>) => number;
+
+/**
+ * iterflow - Lazy iterators with statistics and windowing
+ * @packageDocumentation
+ */
+
+declare class Iterflow<T> implements Iterable<T> {
+    private readonly src;
+    constructor(src: Iterable<T>);
+    [Symbol.iterator](): Iterator<T>;
+    map<U>(fn: Mapper<T, U>): Iterflow<U>;
+    filter(fn: Predicate<T>): Iterflow<T>;
+    flatMap<U>(fn: FlatMapper<T, U>): Iterflow<U>;
+    take(n: number): Iterflow<T>;
+    drop(n: number): Iterflow<T>;
+    takeWhile(fn: Predicate<T>): Iterflow<T>;
+    dropWhile(fn: Predicate<T>): Iterflow<T>;
+    distinct(): Iterflow<T>;
+    /**
+     * Yield [index, value] pairs.
+     */
+    enumerate(): Iterflow<[number, T]>;
+    /**
+     * Append additional iterables to the sequence.
+     */
+    concat<U>(...others: Iterable<U>[]): Iterflow<T | U>;
+    /**
+     * Create sliding windows of the specified size.
+     */
+    window(size: number): Iterflow<T[]>;
+    /**
+     * Split the sequence into fixed-size chunks.
+     */
+    chunk(size: number): Iterflow<T[]>;
+    toArray(): T[];
+    reduce<U>(fn: Reducer<T, U>, init: U): U;
+    find(fn: Predicate<T>): T | undefined;
+    forEach(fn: (v: T, i: number) => void): void;
+    first(): T | undefined;
+    last(): T | undefined;
+    count(): number;
+    some(fn: Predicate<T>): boolean;
+    every(fn: Predicate<T>): boolean;
+    /**
+     * Calculate the sum of all numbers.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    sum(this: Iterflow<number>): number;
+    /**
+     * Calculate the arithmetic mean.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    mean(this: Iterflow<number>): number;
+    /**
+     * Calculate the median (50th percentile).
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    median(this: Iterflow<number>): number;
+    /**
+     * Find the minimum value.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    min(this: Iterflow<number>): number;
+    /**
+     * Find the maximum value.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    max(this: Iterflow<number>): number;
+    /**
+     * Calculate the population variance.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    variance(this: Iterflow<number>): number;
+}
+declare function iter<T>(src: Iterable<T>): Iterflow<T>;
+
+export { EmptySequenceError, type FlatMapper, Iterflow, IterflowError, type Mapper, type Predicate, type Reducer, isIterable, iter, max, mean, median, min, sum, variance };

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Base error class for all iterflow errors.
+ */
+declare class IterflowError extends Error {
+    constructor(msg: string);
+}
+/**
+ * Thrown by statistical methods when called on empty sequences.
+ */
+declare class EmptySequenceError extends IterflowError {
+    readonly op: string;
+    constructor(op: string);
+}
+type Predicate<T> = (v: T, i: number) => boolean;
+type Mapper<T, U> = (v: T, i: number) => U;
+type Reducer<T, U> = (acc: U, v: T, i: number) => U;
+type FlatMapper<T, U> = (v: T, i: number) => Iterable<U>;
+/**
+ * Type guard to check if a value is iterable.
+ */
+declare const isIterable: (v: unknown) => v is Iterable<unknown>;
+
+/**
+ * Calculate the sum of all numbers.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const sum: (src: Iterable<number>) => number;
+/**
+ * Calculate the arithmetic mean.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const mean: (src: Iterable<number>) => number;
+/**
+ * Calculate the median (50th percentile) using Quickselect algorithm.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const median: (src: Iterable<number>) => number;
+/**
+ * Find the minimum value.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const min: (src: Iterable<number>) => number;
+/**
+ * Find the maximum value.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const max: (src: Iterable<number>) => number;
+/**
+ * Calculate the population variance using Welford's online algorithm.
+ * @throws {EmptySequenceError} If the sequence is empty.
+ */
+declare const variance: (src: Iterable<number>) => number;
+
+/**
+ * iterflow - Lazy iterators with statistics and windowing
+ * @packageDocumentation
+ */
+
+declare class Iterflow<T> implements Iterable<T> {
+    private readonly src;
+    constructor(src: Iterable<T>);
+    [Symbol.iterator](): Iterator<T>;
+    map<U>(fn: Mapper<T, U>): Iterflow<U>;
+    filter(fn: Predicate<T>): Iterflow<T>;
+    flatMap<U>(fn: FlatMapper<T, U>): Iterflow<U>;
+    take(n: number): Iterflow<T>;
+    drop(n: number): Iterflow<T>;
+    takeWhile(fn: Predicate<T>): Iterflow<T>;
+    dropWhile(fn: Predicate<T>): Iterflow<T>;
+    distinct(): Iterflow<T>;
+    /**
+     * Yield [index, value] pairs.
+     */
+    enumerate(): Iterflow<[number, T]>;
+    /**
+     * Append additional iterables to the sequence.
+     */
+    concat<U>(...others: Iterable<U>[]): Iterflow<T | U>;
+    /**
+     * Create sliding windows of the specified size.
+     */
+    window(size: number): Iterflow<T[]>;
+    /**
+     * Split the sequence into fixed-size chunks.
+     */
+    chunk(size: number): Iterflow<T[]>;
+    toArray(): T[];
+    reduce<U>(fn: Reducer<T, U>, init: U): U;
+    find(fn: Predicate<T>): T | undefined;
+    forEach(fn: (v: T, i: number) => void): void;
+    first(): T | undefined;
+    last(): T | undefined;
+    count(): number;
+    some(fn: Predicate<T>): boolean;
+    every(fn: Predicate<T>): boolean;
+    /**
+     * Calculate the sum of all numbers.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    sum(this: Iterflow<number>): number;
+    /**
+     * Calculate the arithmetic mean.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    mean(this: Iterflow<number>): number;
+    /**
+     * Calculate the median (50th percentile).
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    median(this: Iterflow<number>): number;
+    /**
+     * Find the minimum value.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    min(this: Iterflow<number>): number;
+    /**
+     * Find the maximum value.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    max(this: Iterflow<number>): number;
+    /**
+     * Calculate the population variance.
+     * @throws {EmptySequenceError} If the sequence is empty.
+     */
+    variance(this: Iterflow<number>): number;
+}
+declare function iter<T>(src: Iterable<T>): Iterflow<T>;
+
+export { EmptySequenceError, type FlatMapper, Iterflow, IterflowError, type Mapper, type Predicate, type Reducer, isIterable, iter, max, mean, median, min, sum, variance };

package/dist/index.js

@@ -0,0 +1,441 @@
+// src/core.ts
+var IterflowError = class extends Error {
+  constructor(msg) {
+    super(msg);
+    this.name = "IterflowError";
+  }
+};
+var EmptySequenceError = class extends IterflowError {
+  constructor(op) {
+    super(`Cannot compute ${op} of empty sequence`);
+    this.op = op;
+    this.name = "EmptySequenceError";
+  }
+};
+var isIterable = (v) => v != null && typeof v === "object" && Symbol.iterator in v;
+
+// src/internal.ts
+function makeTransform(src, generator) {
+  return {
+    *[Symbol.iterator]() {
+      yield* generator(src);
+    }
+  };
+}
+function assertNonEmpty(count2, op) {
+  if (count2 === 0) {
+    throw new EmptySequenceError(op);
+  }
+}
+function assertHasValue(has, op) {
+  if (!has) {
+    throw new EmptySequenceError(op);
+  }
+}
+function validateInteger(n, param) {
+  if (!Number.isFinite(n)) {
+    throw new RangeError(`${param} must be finite`);
+  }
+  if (!Number.isInteger(n)) {
+    throw new TypeError(`${param} must be an integer`);
+  }
+}
+function validateNonNegative(n, param) {
+  validateInteger(n, param);
+  if (n < 0) {
+    throw new RangeError(`${param} must be non-negative`);
+  }
+}
+function validatePositive(n, param) {
+  validateInteger(n, param);
+  if (n <= 0) {
+    throw new RangeError(`${param} must be positive`);
+  }
+}
+
+// src/transforms.ts
+function map(src, fn) {
+  return makeTransform(src, function* (s) {
+    let i = 0;
+    for (const v of s) yield fn(v, i++);
+  });
+}
+function flatMap(src, fn) {
+  return makeTransform(src, function* (s) {
+    let i = 0;
+    for (const v of s) yield* fn(v, i++);
+  });
+}
+function enumerate(src) {
+  return makeTransform(src, function* (s) {
+    let i = 0;
+    for (const v of s) yield [i++, v];
+  });
+}
+function filter(src, fn) {
+  return makeTransform(src, function* (s) {
+    let i = 0;
+    for (const v of s) if (fn(v, i++)) yield v;
+  });
+}
+function take(src, n) {
+  validateNonNegative(n, "Count");
+  return makeTransform(src, function* (s) {
+    let remaining = n;
+    for (const v of s) {
+      if (remaining-- <= 0) break;
+      yield v;
+    }
+  });
+}
+function drop(src, n) {
+  validateNonNegative(n, "Count");
+  return makeTransform(src, function* (s) {
+    let i = 0;
+    for (const v of s) if (i++ >= n) yield v;
+  });
+}
+function takeWhile(src, fn) {
+  return makeTransform(src, function* (s) {
+    let i = 0;
+    for (const v of s) {
+      if (!fn(v, i++)) break;
+      yield v;
+    }
+  });
+}
+function dropWhile(src, fn) {
+  return makeTransform(src, function* (s) {
+    let i = 0, dropping = true;
+    for (const v of s) {
+      if (dropping && !fn(v, i)) dropping = false;
+      if (!dropping) yield v;
+      i++;
+    }
+  });
+}
+function distinct(src) {
+  return makeTransform(src, function* (s) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const v of s) {
+      if (!seen.has(v)) {
+        seen.add(v);
+        yield v;
+      }
+    }
+  });
+}
+function window(src, size) {
+  validatePositive(size, "Window size");
+  return makeTransform(src, function* (s) {
+    const buf = [];
+    for (const v of s) {
+      buf.push(v);
+      if (buf.length === size) {
+        yield buf.slice();
+        buf.shift();
+      }
+    }
+  });
+}
+function chunk(src, size) {
+  validatePositive(size, "Chunk size");
+  return makeTransform(src, function* (s) {
+    let batch = [];
+    for (const v of s) {
+      batch.push(v);
+      if (batch.length === size) {
+        yield batch;
+        batch = [];
+      }
+    }
+    if (batch.length) yield batch;
+  });
+}
+function concat(src, ...others) {
+  return makeTransform(src, function* (s) {
+    yield* s;
+    for (const o of others) yield* o;
+  });
+}
+
+// src/terminals.ts
+function toArray(src) {
+  return Array.from(src);
+}
+function reduce(src, fn, init) {
+  let acc = init, i = 0;
+  for (const v of src) acc = fn(acc, v, i++);
+  return acc;
+}
+function find(src, fn) {
+  let i = 0;
+  for (const v of src) if (fn(v, i++)) return v;
+  return void 0;
+}
+function forEach(src, fn) {
+  let i = 0;
+  for (const v of src) fn(v, i++);
+}
+function first(src) {
+  for (const v of src) return v;
+  return void 0;
+}
+function last(src) {
+  if (Array.isArray(src)) return src[src.length - 1];
+  let last2;
+  for (const v of src) last2 = v;
+  return last2;
+}
+function count(src) {
+  if (Array.isArray(src)) return src.length;
+  let n = 0;
+  for (const _ of src) n++;
+  return n;
+}
+function some(src, fn) {
+  let i = 0;
+  for (const v of src) if (fn(v, i++)) return true;
+  return false;
+}
+function every(src, fn) {
+  let i = 0;
+  for (const v of src) if (!fn(v, i++)) return false;
+  return true;
+}
+var sum = (src) => {
+  let total = 0, count2 = 0;
+  for (const v of src) {
+    total += v;
+    count2++;
+  }
+  assertNonEmpty(count2, "sum");
+  return total;
+};
+var mean = (src) => {
+  let total = 0, count2 = 0;
+  for (const v of src) {
+    total += v;
+    count2++;
+  }
+  assertNonEmpty(count2, "mean");
+  return total / count2;
+};
+function partition(arr, left, right) {
+  const pivot = arr[right];
+  let i = left;
+  for (let j = left; j < right; j++) {
+    if (arr[j] < pivot) {
+      [arr[i], arr[j]] = [arr[j], arr[i]];
+      i++;
+    }
+  }
+  [arr[i], arr[right]] = [arr[right], arr[i]];
+  return i;
+}
+function quickselect(arr, k) {
+  let left = 0;
+  let right = arr.length - 1;
+  while (left < right) {
+    const pivotIndex = partition(arr, left, right);
+    if (pivotIndex === k) {
+      return arr[k];
+    } else if (pivotIndex > k) {
+      right = pivotIndex - 1;
+    } else {
+      left = pivotIndex + 1;
+    }
+  }
+  return arr[left];
+}
+var median = (src) => {
+  const arr = Array.from(src);
+  assertNonEmpty(arr.length, "median");
+  const mid = arr.length >> 1;
+  if (arr.length % 2) {
+    return quickselect(arr, mid);
+  } else {
+    const upper = quickselect(arr, mid);
+    const lower = quickselect(arr, mid - 1);
+    return (lower + upper) / 2;
+  }
+};
+var min = (src) => {
+  let result = Infinity, has = false;
+  for (const v of src) {
+    if (v < result) result = v;
+    has = true;
+  }
+  assertHasValue(has, "min");
+  return result;
+};
+var max = (src) => {
+  let result = -Infinity, has = false;
+  for (const v of src) {
+    if (v > result) result = v;
+    has = true;
+  }
+  assertHasValue(has, "max");
+  return result;
+};
+var variance = (src) => {
+  let count2 = 0;
+  let mean2 = 0;
+  let M2 = 0;
+  for (const x of src) {
+    count2++;
+    const delta = x - mean2;
+    mean2 += delta / count2;
+    const delta2 = x - mean2;
+    M2 += delta * delta2;
+  }
+  assertNonEmpty(count2, "variance");
+  return M2 / count2;
+};
+
+// src/index.ts
+var Iterflow = class _Iterflow {
+  constructor(src) {
+    this.src = src;
+  }
+  [Symbol.iterator]() {
+    return this.src[Symbol.iterator]();
+  }
+  // Transforms
+  map(fn) {
+    return new _Iterflow(map(this.src, fn));
+  }
+  filter(fn) {
+    return new _Iterflow(filter(this.src, fn));
+  }
+  flatMap(fn) {
+    return new _Iterflow(flatMap(this.src, fn));
+  }
+  take(n) {
+    return new _Iterflow(take(this.src, n));
+  }
+  drop(n) {
+    return new _Iterflow(drop(this.src, n));
+  }
+  takeWhile(fn) {
+    return new _Iterflow(takeWhile(this.src, fn));
+  }
+  dropWhile(fn) {
+    return new _Iterflow(dropWhile(this.src, fn));
+  }
+  distinct() {
+    return new _Iterflow(distinct(this.src));
+  }
+  /**
+   * Yield [index, value] pairs.
+   */
+  enumerate() {
+    return new _Iterflow(enumerate(this.src));
+  }
+  /**
+   * Append additional iterables to the sequence.
+   */
+  concat(...others) {
+    return new _Iterflow(concat(this.src, ...others));
+  }
+  /**
+   * Create sliding windows of the specified size.
+   */
+  window(size) {
+    return new _Iterflow(window(this.src, size));
+  }
+  /**
+   * Split the sequence into fixed-size chunks.
+   */
+  chunk(size) {
+    return new _Iterflow(chunk(this.src, size));
+  }
+  // Terminals
+  toArray() {
+    return toArray(this.src);
+  }
+  reduce(fn, init) {
+    return reduce(this.src, fn, init);
+  }
+  find(fn) {
+    return find(this.src, fn);
+  }
+  forEach(fn) {
+    forEach(this.src, fn);
+  }
+  first() {
+    return first(this.src);
+  }
+  last() {
+    return last(this.src);
+  }
+  count() {
+    return count(this.src);
+  }
+  some(fn) {
+    return some(this.src, fn);
+  }
+  every(fn) {
+    return every(this.src, fn);
+  }
+  // Stats (numbers only)
+  /**
+   * Calculate the sum of all numbers.
+   * @throws {EmptySequenceError} If the sequence is empty.
+   */
+  sum() {
+    return sum(this.src);
+  }
+  /**
+   * Calculate the arithmetic mean.
+   * @throws {EmptySequenceError} If the sequence is empty.
+   */
+  mean() {
+    return mean(this.src);
+  }
+  /**
+   * Calculate the median (50th percentile).
+   * @throws {EmptySequenceError} If the sequence is empty.
+   */
+  median() {
+    return median(this.src);
+  }
+  /**
+   * Find the minimum value.
+   * @throws {EmptySequenceError} If the sequence is empty.
+   */
+  min() {
+    return min(this.src);
+  }
+  /**
+   * Find the maximum value.
+   * @throws {EmptySequenceError} If the sequence is empty.
+   */
+  max() {
+    return max(this.src);
+  }
+  /**
+   * Calculate the population variance.
+   * @throws {EmptySequenceError} If the sequence is empty.
+   */
+  variance() {
+    return variance(this.src);
+  }
+};
+function iter(src) {
+  return new Iterflow(src);
+}
+export {
+  EmptySequenceError,
+  Iterflow,
+  IterflowError,
+  isIterable,
+  iter,
+  max,
+  mean,
+  median,
+  min,
+  sum,
+  variance
+};
+//# sourceMappingURL=index.js.map