From 651e281df6ca7f713e78d17c656bb59bea52f877 Mon Sep 17 00:00:00 2001
From: Karsten Schmidt <k@postspectacular.com>
Date: Fri, 22 Nov 2019 03:14:28 +0000
Subject: [PATCH] fix(transducers): add type hints

---
 packages/transducers/src/iter/choices.ts      |  2 +-
 packages/transducers/src/iter/concat.ts       |  5 ++-
 packages/transducers/src/iter/cycle.ts        |  2 +-
 packages/transducers/src/iter/extend-sides.ts |  2 +-
 packages/transducers/src/iter/iterate.ts      |  5 ++-
 packages/transducers/src/iter/norm-range.ts   |  5 ++-
 packages/transducers/src/iter/pad-sides.ts    |  2 +-
 packages/transducers/src/iter/repeat.ts       |  2 +-
 packages/transducers/src/iter/repeatedly.ts   |  2 +-
 packages/transducers/src/iter/symmetric.ts    |  2 +-
 packages/transducers/src/iter/wrap-sides.ts   |  2 +-
 packages/transducers/src/iter/zip.ts          | 41 +++++++++++--------
 packages/transducers/src/xform/cat.ts         |  3 +-
 13 files changed, 45 insertions(+), 30 deletions(-)

diff --git a/packages/transducers/src/iter/choices.ts b/packages/transducers/src/iter/choices.ts
index 24d8d8eea8..9d56718639 100644
--- a/packages/transducers/src/iter/choices.ts
+++ b/packages/transducers/src/iter/choices.ts
@@ -21,7 +21,7 @@ export const choices = <T>(
     choices: ArrayLike<T> & Iterable<T>,
     weights?: ArrayLike<number>,
     rnd: IRandom = SYSTEM
-) =>
+): IterableIterator<T> =>
     repeatedly(
         weights
             ? weightedRandom(ensureArray(choices), weights, rnd)
diff --git a/packages/transducers/src/iter/concat.ts b/packages/transducers/src/iter/concat.ts
index a4f89396aa..c0f721fa29 100644
--- a/packages/transducers/src/iter/concat.ts
+++ b/packages/transducers/src/iter/concat.ts
@@ -1,3 +1,4 @@
+import { Nullable } from "@thi.ng/api";
 import { ensureIterable } from "@thi.ng/arrays";
 
 /**
@@ -15,7 +16,9 @@ import { ensureIterable } from "@thi.ng/arrays";
  *
  * @param xs
  */
-export function* concat<T>(...xs: Iterable<T>[]): IterableIterator<T> {
+export function* concat<T>(
+    ...xs: Nullable<Iterable<T>>[]
+): IterableIterator<T> {
     for (let x of xs) {
         x != null && (yield* ensureIterable(x));
     }
diff --git a/packages/transducers/src/iter/cycle.ts b/packages/transducers/src/iter/cycle.ts
index 1aaa85eb2b..991712fe95 100644
--- a/packages/transducers/src/iter/cycle.ts
+++ b/packages/transducers/src/iter/cycle.ts
@@ -1,4 +1,4 @@
-export function* cycle<T>(input: Iterable<T>) {
+export function* cycle<T>(input: Iterable<T>): IterableIterator<T> {
     let cache: T[] = [];
     for (let i of input) {
         cache.push(i);
diff --git a/packages/transducers/src/iter/extend-sides.ts b/packages/transducers/src/iter/extend-sides.ts
index 54c61dda44..3fed9c46a1 100644
--- a/packages/transducers/src/iter/extend-sides.ts
+++ b/packages/transducers/src/iter/extend-sides.ts
@@ -29,7 +29,7 @@ export function* extendSides<T>(
     src: Iterable<T>,
     numLeft = 1,
     numRight = numLeft
-) {
+): IterableIterator<T> {
     let prev: T | typeof SEMAPHORE = SEMAPHORE;
     for (let x of src) {
         if (numLeft > 0 && prev === SEMAPHORE) {
diff --git a/packages/transducers/src/iter/iterate.ts b/packages/transducers/src/iter/iterate.ts
index 00cecd3796..6f7a88d7d1 100644
--- a/packages/transducers/src/iter/iterate.ts
+++ b/packages/transducers/src/iter/iterate.ts
@@ -20,7 +20,10 @@ import { Fn2 } from "@thi.ng/api";
  * @param fn
  * @param seed
  */
-export function* iterate<T>(fn: Fn2<T, number, T>, seed: T) {
+export function* iterate<T>(
+    fn: Fn2<T, number, T>,
+    seed: T
+): IterableIterator<T> {
     let i = 0;
     while (true) {
         yield seed;
diff --git a/packages/transducers/src/iter/norm-range.ts b/packages/transducers/src/iter/norm-range.ts
index 70360be26e..3e163f50d1 100644
--- a/packages/transducers/src/iter/norm-range.ts
+++ b/packages/transducers/src/iter/norm-range.ts
@@ -10,7 +10,10 @@
  * @param n number of steps
  * @param inclLast include last value (i.e. `1.0`)
  */
-export function* normRange(n: number, inclLast = true) {
+export function* normRange(
+    n: number,
+    inclLast = true
+): IterableIterator<number> {
     if (n > 0) {
         for (let i = 0, m = inclLast ? n + 1 : n; i < m; i++) {
             yield i / n;
diff --git a/packages/transducers/src/iter/pad-sides.ts b/packages/transducers/src/iter/pad-sides.ts
index 100dbcf31d..fcc17b3ad0 100644
--- a/packages/transducers/src/iter/pad-sides.ts
+++ b/packages/transducers/src/iter/pad-sides.ts
@@ -33,7 +33,7 @@ export const padSides = <T>(
     x: T,
     numLeft = 1,
     numRight = numLeft
-) =>
+): IterableIterator<T> =>
     numLeft > 0
         ? numRight > 0
             ? concat(repeat(x, numLeft), src, repeat(x, numRight))
diff --git a/packages/transducers/src/iter/repeat.ts b/packages/transducers/src/iter/repeat.ts
index 6afeb86f58..d5b0ad5a2c 100644
--- a/packages/transducers/src/iter/repeat.ts
+++ b/packages/transducers/src/iter/repeat.ts
@@ -1,4 +1,4 @@
-export function* repeat<T>(x: T, n = Infinity) {
+export function* repeat<T>(x: T, n = Infinity): IterableIterator<T> {
     while (n-- > 0) {
         yield x;
     }
diff --git a/packages/transducers/src/iter/repeatedly.ts b/packages/transducers/src/iter/repeatedly.ts
index 8a043affd3..ed520423b9 100644
--- a/packages/transducers/src/iter/repeatedly.ts
+++ b/packages/transducers/src/iter/repeatedly.ts
@@ -1,6 +1,6 @@
 import { Fn0 } from "@thi.ng/api";
 
-export function* repeatedly<T>(fn: Fn0<T>, n = Infinity) {
+export function* repeatedly<T>(fn: Fn0<T>, n = Infinity): IterableIterator<T> {
     while (n-- > 0) {
         yield fn();
     }
diff --git a/packages/transducers/src/iter/symmetric.ts b/packages/transducers/src/iter/symmetric.ts
index 95e8d29b1d..2e66ab6618 100644
--- a/packages/transducers/src/iter/symmetric.ts
+++ b/packages/transducers/src/iter/symmetric.ts
@@ -15,7 +15,7 @@ interface Cell<T> {
  *
  * @param src
  */
-export function* symmetric<T>(src: Iterable<T>) {
+export function* symmetric<T>(src: Iterable<T>): IterableIterator<T> {
     let head: Cell<T> | undefined = undefined;
     for (let x of src) {
         head = { x, n: head };
diff --git a/packages/transducers/src/iter/wrap-sides.ts b/packages/transducers/src/iter/wrap-sides.ts
index 108df6011d..2ca38a783a 100644
--- a/packages/transducers/src/iter/wrap-sides.ts
+++ b/packages/transducers/src/iter/wrap-sides.ts
@@ -20,7 +20,7 @@ export function* wrapSides<T>(
     src: Iterable<T>,
     numLeft = 1,
     numRight = numLeft
-) {
+): IterableIterator<T> {
     const _src: T[] = ensureArray(src);
     !(inRange(numLeft, 0, _src.length) && inRange(numRight, 0, _src.length)) &&
         illegalArgs(`allowed wrap range: [0..${_src.length}]`);
diff --git a/packages/transducers/src/iter/zip.ts b/packages/transducers/src/iter/zip.ts
index c09a2dbe82..723f303705 100644
--- a/packages/transducers/src/iter/zip.ts
+++ b/packages/transducers/src/iter/zip.ts
@@ -1,3 +1,26 @@
+/**
+ * Accepts a number of iterables and combines them into an iterable of
+ * tuples of successively consumed input values.
+ *
+ * @remarks
+ * Tuples are formed by merging each value of each input iterable, such
+ * that the first yielded tuple contains the first elements of the given
+ * inputs, the second tuple contains the second elements of the inputs,
+ * etc.
+ *
+ * The number of resulting tuples will be the same as the length of the
+ * shortest input iterable. Given only a single argument, `zip` yields a
+ * sequence of 1-tuples.
+ *
+ * @example
+ * ```ts
+ * zip([1, 2, 3], [3, 4, 5, 0, 9])
+ * // [ 1, 3 ] [ 2, 4 ] [ 3, 5 ]
+ *
+ * zip([1, 2, 3])
+ * // [ 1 ] [ 2 ] [ 3 ]
+ * ```
+ */
 export function zip<A>(a: Iterable<A>): IterableIterator<[A]>;
 export function zip<A, B>(
     a: Iterable<A>,
@@ -62,21 +85,3 @@ export function* zip(...src: Iterable<any>[]): IterableIterator<any[]> {
         yield tuple;
     }
 }
-
-/**
- * Zip function accepts a list of iterables, and combines them by merging each value of each iterable,
- * Such as the first yield element contains the first elements of the given iterables, the second of which contains the second elements of the given iterables, and so on.
- * 
- * The returned iterable is truncated in length to the length of the shortest argument sequence. With a single sequence argument, it yields a list of 1-tuples.
- * 
- * ```
- * tx.zip([1, 2, 3], [3, 4, 5, 0, 9])
- * // [ 1, 3 ] [ 2, 4 ] [ 3, 5 ]
- * 
- * tx.zip([1, 2, 3])
- * // [ 1 ] [ 2 ] [ 3 ]
- * ```
- *
- * @deprecated renamed to `zip`
- */
-export const tuples = zip;
diff --git a/packages/transducers/src/xform/cat.ts b/packages/transducers/src/xform/cat.ts
index a5bf704d0b..87ab761399 100644
--- a/packages/transducers/src/xform/cat.ts
+++ b/packages/transducers/src/xform/cat.ts
@@ -1,3 +1,4 @@
+import { Nullable } from "@thi.ng/api";
 import { Reducer, Transducer } from "../api";
 import { compR } from "../func/compr";
 import { ensureReduced, isReduced, unreduced } from "../reduced";
@@ -32,7 +33,7 @@ import { ensureReduced, isReduced, unreduced } from "../reduced";
  * @see thi.ng/transducers/iter/concat
  * @see thi.ng/transducers/xform/mapcat
  */
-export const cat = <T>(): Transducer<Iterable<T> | null | undefined, T> => (
+export const cat = <T>(): Transducer<Nullable<Iterable<T>>, T> => (
     rfn: Reducer<any, T>
 ) => {
     const r = rfn[2];