fix(transducers): fix matchLast(), fix & update return match*() types

- use iterator() instead of iterator1() for matchLast()
- fix return type decls for both matchFirst() / matchLast()
- update doc strings

packages/transducers/src/xform/match-first.ts

@@ -14,12 +14,28 @@ import { take } from "./take";
  * ```
  *
  * Yields none or only the first value which passed the predicate check
- * and then causes early termination.
+ * and then causes early termination. If `src` input is given, returns
+ * first match found (or `undefined`). Also see `matchLast()`.
+ *
+ * ```
+ * matchFirst((x) => x >= 5, [3, 1, 4, 2, 6, 5])
+ * // 6
+ *
+ * transduce(
+ *   comp(
+ *     matchFirst((x) => x >= 5),
+ *     map((x) => x * 10)
+ *   ),
+ *   last(),
+ *   [3, 1, 4, 2, 6, 5]
+ * )
+ * // 60
+ * ```
  *
  * @param pred predicate function
  */
 export function matchFirst<T>(pred: Predicate<T>): Transducer<T, T>;
-export function matchFirst<T>(pred: Predicate<T>, src: Iterable<T>): IterableIterator<T>;
+export function matchFirst<T>(pred: Predicate<T>, src: Iterable<T>): T | undefined;
 export function matchFirst<T>(pred: Predicate<T>, src?: Iterable<T>): any {
     return src ?
         [...iterator1(matchFirst(pred), src)][0] :

packages/transducers/src/xform/match-last.ts

@@ -2,7 +2,7 @@ import { Predicate } from "@thi.ng/api";
 
 import { Transducer } from "../api";
 import { comp } from "../func/comp";
-import { iterator1 } from "../iterator";
+import { iterator } from "../iterator";
 import { filter } from "./filter";
 import { takeLast } from "./take-last";
 
@@ -14,14 +14,30 @@ import { takeLast } from "./take-last";
  * ```
  *
  * Yields none or only the last value which passed the predicate check.
+ * If `src` input is given, returns last match found (or `undefined`).
+ *
+ * ```
+ * matchLast((x) => x >= 5, [3, 1, 6, 5, 4, 2])
+ * // 5
+ *
+ * transduce(
+ *   comp(
+ *     matchLast((x) => x >= 5),
+ *     map((x) => x * 10)
+ *   ),
+ *   last(),
+ *   [3, 1, 4, 2, 6, 5]
+ * )
+ * // 50
+ * ```
  *
  * @param pred predicate function
  * @param src
  */
 export function matchLast<T>(pred: Predicate<T>): Transducer<T, T>;
-export function matchLast<T>(pred: Predicate<T>, src: Iterable<T>): IterableIterator<T>;
+export function matchLast<T>(pred: Predicate<T>, src: Iterable<T>): T | undefined;
 export function matchLast<T>(pred: Predicate<T>, src?: Iterable<T>): any {
     return src ?
-        iterator1(matchLast(pred), src) :
+        [...iterator(matchLast(pred), src)][0] :
         comp(filter(pred), takeLast(1));
 }