@hpcc-js/dataflow 9.2.0 → 9.2.1

package/src/__tests__/histogram.ts

@@ -0,0 +1,47 @@
+import { expect } from "chai";
+import { histogram } from "../index";
+import { people, Person, population } from "./data";
+
+describe("histogram", () => {
+    it("generator", () => {
+        const h = [...histogram<Person>(row => row.age, { buckets: 10 })(population)];
+        expect(h).to.have.length;
+        expect(h.length).to.equal(10);
+        expect(h[0].from).to.exist;
+        expect(h[0].to).to.exist;
+        expect(h[0].value).to.have.length;
+
+        const h2 = [...histogram<Person>(row => row.age, { min: 15, range: 5 })(population)];
+        expect(h2).to.have.length;
+        expect(h2.length).to.equal(11);
+    });
+
+    it("generator 2", () => {
+        const h = [...histogram<Person>(row => row.age, { buckets: 10 })(people())];
+        expect(h).to.have.length;
+        expect(h.length).to.equal(10);
+        expect(h[0].from).to.exist;
+        expect(h[0].to).to.exist;
+        expect(h[0].value).to.have.length;
+
+        const h2 = [...histogram<Person>(row => row.age, { min: 15, range: 5 })(people())];
+        expect(h2).to.have.length;
+        expect(h2.length).to.equal(11);
+    });
+
+    it("scalarActivity", () => {
+        const h = [...histogram(population, row => row.age, { buckets: 10 })];
+        expect(h).to.have.length;
+        expect(h[0].from).to.exist;
+        expect(h[0].to).to.exist;
+        expect(h[0].value).to.have.length;
+    });
+
+    it("readme", () => {
+        const data = [1, 12, 13, 13, 3, 14, 19, 6];
+        const h = [...histogram(data, n => n, { buckets: 3 })];
+        expect(h).to.have.length;
+        const h2 = [...histogram(data, n => n, { min: 0, range: 5 })];
+        expect(h2).to.have.length;
+    });
+});

package/src/__tests__/index.ts

@@ -0,0 +1,27 @@
+export * from "./chain";
+export * from "./concat";
+export * from "./count";
+export * from "./data";
+export * from "./deviation";
+export * from "./distribution";
+export * from "./each";
+export * from "./entries";
+export * from "./extent";
+export * from "./filter";
+export * from "./first";
+export * from "./generate";
+export * from "./group";
+export * from "./histogram";
+export * from "./join";
+export * from "./map";
+export * from "./max";
+export * from "./mean";
+export * from "./median";
+export * from "./min";
+export * from "./normalize";
+export * from "./quartile";
+export * from "./readme";
+export * from "./reduce";
+export * from "./skip";
+export * from "./sort";
+export * from "./variance";

package/src/__tests__/join.ts

@@ -0,0 +1,20 @@
+import { expect } from "chai";
+import { each, join, map, normalize } from "../index";
+import { Person, population } from "./data";
+
+interface PersonEx extends Person {
+    normalizedAge: number;
+}
+
+describe("join", () => {
+    it("normalize", () => {
+        const extractAge = map<Person, number>(row => row.age);
+        const normalizeFn = normalize();
+        const joinNormalizeAges = join(normalizeFn(extractAge(population)), (row: Person, age: number): PersonEx => ({ ...row, normalizedAge: age }));
+        const doTest = each(row => {
+            expect(row.normalizedAge).to.be.greaterThanOrEqual(0);
+            expect(row.normalizedAge).to.be.lessThanOrEqual(1);
+        });
+        [...doTest(joinNormalizeAges(population))];
+    });
+});

package/src/__tests__/map.ts

@@ -0,0 +1,16 @@
+import { expect } from "chai";
+import { map } from "../index";
+import { population } from "./data";
+
+const testMap = row => ({ ...row.address });
+const expected = population.map(testMap);
+
+describe("map", () => {
+    it("generator", () => {
+        expect([...map(testMap)(population)]).to.deep.equal(expected);
+    });
+
+    it("scalarActivity", () => {
+        expect([...map(population, testMap)]).to.deep.equal(expected);
+    });
+});

package/src/__tests__/max.ts

@@ -0,0 +1,42 @@
+import { expect } from "chai";
+import { pipe, filter, max, scalar, sensor } from "../index";
+import { population } from "./data";
+
+describe("max", () => {
+    it("NumberArray", () => {
+        const s1 = max();
+        const s2 = max();
+        const p1 = pipe(
+            sensor(s1),
+            filter(r => r < 3),
+            sensor(s2),
+        );
+        const data = [...p1([1, 2, 3, 4, 5, 0])];
+        expect(data.length).to.equal(3);
+        expect(s1.peek()).to.equal(5);
+        expect(s2.peek()).to.equal(2);
+    });
+
+    it("Population", () => {
+        const s1 = max(r => r.age);
+        const s2 = max(r => r.age);
+        const p1 = pipe(
+            sensor(s1),
+            filter(r => r.age < 30),
+            sensor(s2),
+        );
+        const data = [...p1(population)];
+        expect(data.length).to.equal(286);
+        expect(s1.peek()).to.equal(66);
+        expect(s2.peek()).to.equal(29);
+    });
+
+    it("scalarActivity", () => {
+        const s1 = scalar(max());
+        expect(s1([1, 2, 3, 4, 5, 0])).to.equal(5);
+
+        const s2 = scalar(max(r => r.age));
+        expect(s2(population)).to.equal(66);
+    });
+});
+

package/src/__tests__/mean.ts

@@ -0,0 +1,11 @@
+import { expect } from "chai";
+import { mean, scalar } from "../index";
+
+describe("mean", () => {
+    it("scalarActivity", () => {
+        const a1 = scalar(mean());
+        expect(a1([5, -6, 1, 2, -2])).to.equal(0);
+        expect(a1([9])).to.deep.equal(9);
+    });
+});
+

package/src/__tests__/median.ts

@@ -0,0 +1,14 @@
+import { expect } from "chai";
+import { median, scalar } from "../index";
+
+describe("median", () => {
+
+    it("scalarActivity", () => {
+        const calcMedian = scalar(median());
+        expect(calcMedian([-6, -2, 1, 2, 5])).to.equal(1);
+        expect(calcMedian([5, -6, 1, 2, -2])).to.equal(1);
+        expect(calcMedian([-6, -2, 1, 2, 5, 6])).to.equal(1.5);
+        expect(calcMedian([5, -6, 1, 2, -2, 6])).to.equal(1.5);
+        expect(calcMedian([9])).to.deep.equal(9);
+    });
+});

package/src/__tests__/min.ts

@@ -0,0 +1,42 @@
+import { expect } from "chai";
+import { pipe, filter, min, scalar, sensor } from "../index";
+import { population } from "./data";
+
+describe("min", () => {
+    it("NumberArray", () => {
+        const s1 = min();
+        const s2 = min();
+        const p1 = pipe(
+            sensor(s1),
+            filter(r => r > 3),
+            sensor(s2),
+        );
+        const data = [...p1([1, 2, 3, 4, 5, 0])];
+        expect(data.length).to.equal(2);
+        expect(s1.peek()).to.equal(0);
+        expect(s2.peek()).to.equal(4);
+    });
+
+    it("Population", () => {
+        const s1 = min(r => r.age);
+        const s2 = min(r => r.age);
+        const p1 = pipe(
+            sensor(s1),
+            filter(r => r.age > 30),
+            sensor(s2),
+        );
+        const data = [...p1(population)];
+        expect(data.length).to.equal(699);
+        expect(s1.peek()).to.equal(16);
+        expect(s2.peek()).to.equal(31);
+    });
+
+    it("scalarActivity", () => {
+        const a1 = scalar(min());
+        expect(a1([1, 2, 3, 4, 5, 0])).to.equal(0);
+
+        const a2 = scalar(min(r => r.age));
+        expect(a2(population)).to.equal(16);
+    });
+});
+

package/src/__tests__/normalize.ts

@@ -0,0 +1,14 @@
+import { expect } from "chai";
+import { normalize } from "../index";
+
+describe("normalize", () => {
+
+    it("numberArray", () => {
+        const normFunc = normalize();
+        expect([...normFunc([0, 5, 10])]).to.deep.equal([0, .5, 1]);
+        expect([...normFunc([0, 10, 20])]).to.deep.equal([0, .5, 1]);
+        expect([...normFunc([0, 1, 2, 3, 4])]).to.deep.equal([0, .25, .5, .75, 1]);
+        expect([...normFunc([0, 10, 20, 30, 40])]).to.deep.equal([0, .25, .5, .75, 1]);
+    });
+});
+

package/src/__tests__/quartile.ts

@@ -0,0 +1,14 @@
+import { expect } from "chai";
+import { quartile, scalar } from "../index";
+
+describe("quartile", () => {
+
+    it("scalarActivity", () => {
+        const calcQuartile = scalar(quartile());
+        expect(calcQuartile([6, 7, 15, 36, 39, 40, 41, 42, 43, 47, 49])).to.deep.equal([6, 15, 40, 43, 49]);
+        expect(calcQuartile([7, 15, 36, 39, 40, 41])).to.deep.equal([7, 15, 37.5, 40, 41]);
+        expect(calcQuartile([1, 22, 133])).to.deep.equal([1, 1, 22, 133, 133]);
+        expect(calcQuartile([2, 144, 33])).to.deep.equal([2, 2, 33, 144, 144]);
+    });
+});
+

package/src/__tests__/readme.ts

@@ -0,0 +1,113 @@
+import { expect } from "chai";
+
+import { count, filter, first, generate, map, max, pipe, sensor } from "../index";
+
+describe("readme", () => {
+
+    it("quick example", () => {
+
+        const c1 = count();
+        const c2 = count();
+        const c3 = count();
+        const m1 = max(row => row.value);
+
+        const p1 = pipe(
+            sensor(c1),                         //  Keep running count of input
+            filter(n => n <= 0.5),              //  Filter out numbers > 0.5  
+            sensor(c2),                         //  Keep running count of filtered rows
+            map((n, idx) =>                     //  Convert to JSON Object 
+                ({ index: idx, value: n })),
+            filter(row => row.index % 2 === 0), //  Filter even row indecies 
+            sensor(c3),                         //  Keep running count of final rows
+            sensor(m1),                         //  Track largest value
+            first(3)                            //  Take first 3 rows
+        );
+
+        console.info(`Counts: ${c1.peek()}, ${c2.peek()}, ${c3.peek()}`);
+        // [1] => Counts: undefined, undefined, undefined
+        const outIterable = p1(generate(Math.random, 1000));
+        console.info(`Counts: ${c1.peek()}, ${c2.peek()}, ${c3.peek()}`);
+        // [2] => Counts: undefined, undefined, undefined
+        console.info(JSON.stringify([...outIterable]));
+        // [3] => [{"index":0,"value":0.19075931906641008},{"index":2,"value":0.4873469062925415},{"index":4,"value":0.4412516774100035}]
+        console.info(`Counts: ${c1.peek()}, ${c2.peek()}, ${c3.peek()}, ${m1.peek()}`);
+        // [4] => Counts: 6, 5, 3, 0.4873469062925415
+
+        const outArray = [...p1([0.7, 0.5, 0.4, 0.8, 0.3, 1])];
+        console.info(JSON.stringify(outArray));
+        // [5] => [{"index":0,"value":0.5},{"index":2,"value":0.3}]
+        console.info(`Counts: ${c1.peek()}, ${c2.peek()}, ${c3.peek()}, ${m1.peek()}`);
+        // [6] => Counts:  6, 3, 2, 0.5
+
+        expect(outArray.length).to.equal(2);
+
+        for (const row of p1(generate(Math.random, 1000000))) {
+            console.info(`${row.index}: ${c1.peek()}, ${c2.peek()}, ${c3.peek()}, ${m1.peek()}`);
+        }
+    });
+
+    it("interesting example", () => {
+        const c1 = count();
+        const c2 = count();
+        const c3 = count();
+        const m1 = max(row => row.value);
+
+        const p1 = pipe(
+            sensor(c1),                         //  Keep running count of input
+            filter(n => n <= 0.5),              //  Filter out numbers > 0.5  
+            sensor(c2),                         //  Keep running count of filtered rows
+            map((n, idx) =>                     //  Convert to JSON Object 
+                ({ index: idx, value: n })),
+            filter(row => row.index % 2 === 0), //  Filter even row indecies 
+            sensor(c3),                         //  Keep running count of final rows
+            sensor(m1),                         //  Track largest value
+        );
+
+        for (const row of p1(generate(Math.random, 1000000))) {
+            if (row.index % 100000 === 0) {
+                console.info(`${row.index}: ${c1.peek()}, ${c2.peek()}, ${c3.peek()}, ${m1.peek()}`);
+            }
+        }
+    });
+});
+
+/*
+const process3 = pipe(
+    filter(n => n <= 0.5),
+    map((n, idx) => ({ index: idx, value: n })),
+    filter(row => row.index % 2 === 0),
+    sort((l, r) => l.value - r.value),
+    first(3)
+);
+console.log(...process3([]));
+
+// Iterable output
+pipe([0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    filter(n => n <= 5),
+    map((n, idx) => ({ index: idx, value: n })),
+    filter(row => row.index % 2 === 0),
+    sort((l, r) => l.value - r.value),
+    first(3)
+);  // => { index: 0, value: 0 }, { index: 2, value: 2 }, { index: 4, value: 4 }
+
+const process = pipe(
+    filter(n => n <= 5),
+    map((n, idx) => ({ index: idx, value: n })),
+    filter(row => row.index % 2 === 0),
+    sort((l, r) => l.value - r.value),
+    first(3)
+);
+console.log([...process([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])]); // => { index: 0, value: 0 }, { index: 2, value: 2 }, { index: 4, value: 4 }
+
+// Scalar output
+pipe([0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    process,
+    scalar(max(row => row.value))
+);  // => 4
+
+const process_2 = pipe(
+    process,
+    scalar(min(row => row.value))
+);
+console.log(process_2([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]));  // => 0
+*/

package/src/__tests__/reduce.ts

@@ -0,0 +1,17 @@
+import { expect } from "chai";
+import { reduce, scalar } from "../index";
+
+const data = [1, 2, 3, 4, 5];
+const reduceFunc = (prev, row) => prev + row;
+const expectedA = data.reduce(reduceFunc);
+const expectedB = data.reduce(reduceFunc, 10);
+
+describe("reduce", () => {
+
+    it("scalarActivity", () => {
+        const calcReduce = scalar(reduce(reduceFunc));
+        const calcReduce2 = scalar(reduce(reduceFunc, 10));
+        expect(calcReduce(data)).to.equal(expectedA);
+        expect(calcReduce2(data)).to.equal(expectedB);
+    });
+});

package/src/__tests__/skip.ts

@@ -0,0 +1,15 @@
+import { expect } from "chai";
+import { skip } from "../index";
+
+describe("skip", () => {
+    it("generator", () => {
+        expect([...skip(2)([])]).to.deep.equal([]);
+        expect([...skip(2)(["a", "b", "c"])]).to.deep.equal(["c"]);
+    });
+
+    it("scalarActivity", () => {
+        expect([...skip([], 22)]).to.deep.equal([]);
+        expect([...skip(["a", "b", "c"], 2)]).to.deep.equal(["c"]);
+        expect([...skip(["a", "b", "c"], 22)]).to.deep.equal([]);
+    });
+});

package/src/__tests__/sort.ts

@@ -0,0 +1,21 @@
+import { expect } from "chai";
+import { sort } from "../index";
+import { Person, population } from "./data";
+
+function sortFunc(l: Person, r: Person): number {
+    const retVal = l.lname.localeCompare(r.lname);
+    if (retVal === 0) return l.fname.localeCompare(r.fname);
+    return retVal;
+}
+
+const expected = [...population].sort(sortFunc);
+
+describe("sort", () => {
+    it("generator", () => {
+        expect([...sort(sortFunc)(population)]).to.deep.equal(expected);
+    });
+
+    it("scalarActivity", () => {
+        expect([...sort(population, sortFunc)]).to.deep.equal(expected);
+    });
+});

package/src/__tests__/variance.ts

@@ -0,0 +1,14 @@
+import { expect } from "chai";
+import { variance, scalar } from "../index";
+
+describe("variance", () => {
+    it("scalarActivity", () => {
+        const calcVariance = scalar(variance());
+        expect(calcVariance([5, 1, 2, 3, 4])).to.equal(2.5);
+    });
+
+    it("empty array", () => {
+        const varianceActivity = scalar(variance());
+        expect(varianceActivity([])).to.be.undefined;
+    });
+});

package/src/activities/activity.ts

@@ -1,8 +1,8 @@
-export type Source<T> = IterableIterator<T> | T[];
-export type IterableActivity<T, U = T> = (source: Source<T>) => IterableIterator<U>;
-export type ScalarActivity<T, U = T> = (source: Source<T>) => U;
-export type Activity<T, U = T> = IterableActivity<T, U> | ScalarActivity<T, U>;
-
-export function isSource<T>(source: Source<T> | any): source is Source<T> {
-    return source && (typeof source[Symbol.iterator] === "function" || Array.isArray(source));
-}
+export type Source<T> = IterableIterator<T> | T[];
+export type IterableActivity<T, U = T> = (source: Source<T>) => IterableIterator<U>;
+export type ScalarActivity<T, U = T> = (source: Source<T>) => U;
+export type Activity<T, U = T> = IterableActivity<T, U> | ScalarActivity<T, U>;
+
+export function isSource<T>(source: Source<T> | any): source is Source<T> {
+    return source && (typeof source[Symbol.iterator] === "function" || Array.isArray(source));
+}

package/src/activities/concat.ts

@@ -1,14 +1,14 @@
-import { Source, IterableActivity } from "./activity.ts";
-
-function concatGen<T = any>(concatSource: Source<T>): IterableActivity<T> {
-    return function* (source: Source<T>) {
-        yield* source;
-        yield* concatSource;
-    };
-}
-
-export function concat<T = any>(concatSource: Source<T>): IterableActivity<T, T>;
-export function concat<T>(source: Source<T>, concatSource: Source<T>): IterableIterator<T>;
-export function concat<T = any>(s_or_n: Source<T>, concatSource?: Source<T>): IterableActivity<T, T> | IterableIterator<T> {
-    return concatSource !== undefined ? concatGen<T>(concatSource!)(s_or_n) : concatGen<T>(s_or_n);
-}
+import { Source, IterableActivity } from "./activity";
+
+function concatGen<T = any>(concatSource: Source<T>): IterableActivity<T> {
+    return function* (source: Source<T>) {
+        yield* source;
+        yield* concatSource;
+    };
+}
+
+export function concat<T = any>(concatSource: Source<T>): IterableActivity<T, T>;
+export function concat<T>(source: Source<T>, concatSource: Source<T>): IterableIterator<T>;
+export function concat<T = any>(s_or_n: Source<T>, concatSource?: Source<T>): IterableActivity<T, T> | IterableIterator<T> {
+    return concatSource !== undefined ? concatGen<T>(concatSource!)(s_or_n) : concatGen<T>(s_or_n);
+}

package/src/activities/each.ts

@@ -1,19 +1,19 @@
-import { IterableActivity, Source, isSource } from "./activity.ts";
-
-export type EachCallback<T> = (value: T, index: number) => void;
-
-function eachGen<T = any>(callbackFn: EachCallback<T>): IterableActivity<T> {
-    return function* (source: Source<T>) {
-        let i = -1;
-        for (const item of source) {
-            callbackFn(item, ++i);
-            yield item;
-        }
-    };
-}
-
-export function each<T = any>(callbackFn: EachCallback<T>): IterableActivity<T>;
-export function each<T>(source: Source<T>, callbackFn: EachCallback<T>): IterableIterator<T>;
-export function each<T>(s_or_cb: Source<T> | EachCallback<T>, callbackFn?: EachCallback<T>): IterableActivity<T> | IterableIterator<T> {
-    return isSource(s_or_cb) ? eachGen(callbackFn!)(s_or_cb) : eachGen(s_or_cb);
-}
+import { IterableActivity, Source, isSource } from "./activity";
+
+export type EachCallback<T> = (value: T, index: number) => void;
+
+function eachGen<T = any>(callbackFn: EachCallback<T>): IterableActivity<T> {
+    return function* (source: Source<T>) {
+        let i = -1;
+        for (const item of source) {
+            callbackFn(item, ++i);
+            yield item;
+        }
+    };
+}
+
+export function each<T = any>(callbackFn: EachCallback<T>): IterableActivity<T>;
+export function each<T>(source: Source<T>, callbackFn: EachCallback<T>): IterableIterator<T>;
+export function each<T>(s_or_cb: Source<T> | EachCallback<T>, callbackFn?: EachCallback<T>): IterableActivity<T> | IterableIterator<T> {
+    return isSource(s_or_cb) ? eachGen(callbackFn!)(s_or_cb) : eachGen(s_or_cb);
+}

package/src/activities/entries.ts

@@ -1,17 +1,17 @@
-import { IterableActivity, Source } from "./activity.ts";
-
-//  Array.entries
-function entriesGen<T = any>(): IterableActivity<T, [number, T]> {
-    return function* (source: Source<T>) {
-        let i = -1;
-        for (const item of source) {
-            yield [++i, item];
-        }
-    };
-}
-
-export function entries<T = any>(): IterableActivity<T, [number, T]>;
-export function entries<T>(source: Source<T>): IterableIterator<[number, T]>;
-export function entries<T>(source?: Source<T>): IterableActivity<T, [number, T]> | IterableIterator<[number, T]> {
-    return source ? entriesGen<T>()(source) : entriesGen<T>();
-}
+import { IterableActivity, Source } from "./activity";
+
+//  Array.entries
+function entriesGen<T = any>(): IterableActivity<T, [number, T]> {
+    return function* (source: Source<T>) {
+        let i = -1;
+        for (const item of source) {
+            yield [++i, item];
+        }
+    };
+}
+
+export function entries<T = any>(): IterableActivity<T, [number, T]>;
+export function entries<T>(source: Source<T>): IterableIterator<[number, T]>;
+export function entries<T>(source?: Source<T>): IterableActivity<T, [number, T]> | IterableIterator<[number, T]> {
+    return source ? entriesGen<T>()(source) : entriesGen<T>();
+}

package/src/activities/filter.ts

@@ -1,20 +1,20 @@
-import { IterableActivity, Source, isSource } from "./activity.ts";
-
-export type FilterCallback<T> = (value: T, index: number) => boolean;
-
-function filterGen<T = any>(callbackFn: FilterCallback<T>): IterableActivity<T> {
-    return function* (source: Source<T>) {
-        let i = -1;
-        for (const item of source) {
-            if (callbackFn(item, ++i)) {
-                yield item;
-            }
-        }
-    };
-}
-
-export function filter<T = any>(callbackFn: FilterCallback<T>): IterableActivity<T>;
-export function filter<T>(source: Source<T>, callbackFn: FilterCallback<T>): IterableIterator<T>;
-export function filter<T>(s_or_cb: Source<T> | FilterCallback<T>, callbackFn?: FilterCallback<T>): IterableActivity<T> | IterableIterator<T> {
-    return isSource(s_or_cb) ? filterGen(callbackFn!)(s_or_cb) : filterGen(s_or_cb);
-}
+import { IterableActivity, Source, isSource } from "./activity";
+
+export type FilterCallback<T> = (value: T, index: number) => boolean;
+
+function filterGen<T = any>(callbackFn: FilterCallback<T>): IterableActivity<T> {
+    return function* (source: Source<T>) {
+        let i = -1;
+        for (const item of source) {
+            if (callbackFn(item, ++i)) {
+                yield item;
+            }
+        }
+    };
+}
+
+export function filter<T = any>(callbackFn: FilterCallback<T>): IterableActivity<T>;
+export function filter<T>(source: Source<T>, callbackFn: FilterCallback<T>): IterableIterator<T>;
+export function filter<T>(s_or_cb: Source<T> | FilterCallback<T>, callbackFn?: FilterCallback<T>): IterableActivity<T> | IterableIterator<T> {
+    return isSource(s_or_cb) ? filterGen(callbackFn!)(s_or_cb) : filterGen(s_or_cb);
+}

package/src/activities/first.ts

@@ -1,20 +1,20 @@
-import { IterableActivity, isSource, Source } from "./activity.ts";
-
-function firstGen<T = any>(n: number): IterableActivity<T, T> {
-    return function* (source: Source<T>) {
-        let i = 0;
-        for (const item of source) {
-            yield item;
-            if (++i >= n) {
-                break;
-            }
-        }
-    };
-}
-
-export function first<T = any>(n: number): IterableActivity<T, T>;
-export function first<T>(source: Source<T>, n: number): IterableIterator<T>;
-export function first<T = any>(s_or_n: Source<T> | number, n?: number): IterableActivity<T, T> | IterableIterator<T> {
-    if (!isSource(s_or_n)) return firstGen<T>(s_or_n);
-    return firstGen<T>(n!)(s_or_n);
-}
+import { IterableActivity, isSource, Source } from "./activity";
+
+function firstGen<T = any>(n: number): IterableActivity<T, T> {
+    return function* (source: Source<T>) {
+        let i = 0;
+        for (const item of source) {
+            yield item;
+            if (++i >= n) {
+                break;
+            }
+        }
+    };
+}
+
+export function first<T = any>(n: number): IterableActivity<T, T>;
+export function first<T>(source: Source<T>, n: number): IterableIterator<T>;
+export function first<T = any>(s_or_n: Source<T> | number, n?: number): IterableActivity<T, T> | IterableIterator<T> {
+    if (!isSource(s_or_n)) return firstGen<T>(s_or_n);
+    return firstGen<T>(n!)(s_or_n);
+}