feat: type predicate overloads

fp_test.ts

@@ -1,4 +1,10 @@
-import { assertArrayIncludes, assertEquals } from "./test_deps.ts";
+import {
+  assertArrayIncludes,
+  assertEquals,
+  assertType,
+  type IsExact,
+} from "./test_deps.ts";
+
 import { c, p } from "https://deno.land/x/[email protected]/mod.ts";
 import * as mod from "./mod.ts";
 import * as fp from "./fp.ts";
@@ -7,6 +13,14 @@ Deno.test("All functions are available in functional programming version", () =>
   assertArrayIncludes(["curried", ...Object.keys(fp)], Object.keys(mod));
 });
 
+Deno.test("Curried functions with type predicates type checks", () => {
+  const xs = [1, "a", 2, "b"];
+  const result = fp.find((x): x is number => typeof x === "number")(xs);
+
+  assertType<IsExact<typeof result, number | undefined>>(true);
+  assertEquals(result, 1);
+});
+
 Deno.test("With copb", () => {
   const pipeline = c(
     p(fp.map<number>((x) => x * 100)) // Only needed type annotation, the rest is inferred.

lib/reducers.ts

@@ -1,5 +1,8 @@
 import { kComb } from "./internal/util.ts";
-import { IterablePredicateCallback } from "./types.ts";
+import {
+  IterablePredicateCallback,
+  IterableTypePredicateCallback,
+} from "./types.ts";
 import { map } from "./transformers.ts";
 
 /**
@@ -160,6 +163,15 @@ export function some<T>(
  * // const allPositive = iter.every(naturals, (n) => n > 0);
  * ```
  */
+
+export function every<T>(
+  it: Iterable<T>,
+  predicate: IterablePredicateCallback<T>,
+): boolean;
+export function every<T, S extends T>(
+  it: Iterable<T>,
+  predicate: IterableTypePredicateCallback<T, S>,
+): it is Iterable<S>;
 export function every<T>(
   it: Iterable<T>,
   predicate: IterablePredicateCallback<T>,
@@ -227,6 +239,14 @@ export function includes<T>(it: Iterable<T>, value: T): boolean {
  * // Find a solution to n³ = 3n, n ∈ ℕ
  * // const solution2 = iter.find(naturals, (n) => n ** 3 === 3 * n);
  */
+export function find<T>(
+  it: Iterable<T>,
+  predicate: IterablePredicateCallback<T>,
+): T | undefined;
+export function find<T, S extends T>(
+  it: Iterable<T>,
+  predicate: IterableTypePredicateCallback<T, S>,
+): S | undefined;
 export function find<T>(
   it: Iterable<T>,
   predicate: IterablePredicateCallback<T>,

lib/transformers.ts

@@ -2,6 +2,7 @@ import { isIterable } from "./internal/util.ts";
 import {
   IterableCircular,
   IterablePredicateCallback,
+  IterableTypePredicateCallback,
   Peekable,
 } from "./types.ts";
 
@@ -318,6 +319,14 @@ export function dropUntil<T>(
  * // -> 5
  * ```
  */
+export function takeWhile<T>(
+  it: Iterable<T>,
+  f: IterablePredicateCallback<T>,
+): IterableCircular<T>;
+export function takeWhile<T, S extends T>(
+  it: Iterable<T>,
+  f: IterableTypePredicateCallback<T, S>,
+): IterableCircular<S>;
 export function takeWhile<T>(
   it: Iterable<T>,
   f: IterablePredicateCallback<T>,
@@ -354,6 +363,14 @@ export function takeWhile<T>(
  * // -> 10
  * ```
  */
+export function dropWhile<T>(
+  it: Iterable<T>,
+  f: IterablePredicateCallback<T>,
+): IterableCircular<T>;
+export function dropWhile<T, S extends T>(
+  it: Iterable<T>,
+  f: IterableTypePredicateCallback<T, S>,
+): IterableCircular<T>;
 export function dropWhile<T>(
   it: Iterable<T>,
   f: IterablePredicateCallback<T>,
@@ -386,6 +403,14 @@ export function dropWhile<T>(
  * console.log(iterator.next().value); // -> 11
  * ```
  */
+export function filter<T>(
+  it: Iterable<T>,
+  predicate: IterablePredicateCallback<T>,
+): IterableCircular<T>;
+export function filter<T, S extends T>(
+  it: Iterable<T>,
+  predicate: IterableTypePredicateCallback<T, S>,
+): IterableCircular<S>;
 export function filter<T>(
   it: Iterable<T>,
   predicate: IterablePredicateCallback<T>,

lib/types.ts

@@ -28,6 +28,23 @@ export interface IterablePredicateCallback<T> {
   (value: T, index: number, it: Iterable<T>): boolean;
 }
 
+/**
+ * Iterable type predicate callback.
+ * @typeParam T - Type of value to be predicated.
+ * @typeParam S - Type of value to be narrowed to.
+ */
+export interface IterableTypePredicateCallback<T, S extends T> {
+  /**
+   * Iterable type predicate callback.
+   * @callback IterableTypePredicateCallback
+   * @param value - The value of the item being predicated.
+   * @param index - The index of the item being predicated.
+   * @param it - The iterable.
+   * @returns The narrowed predicate result.
+   */
+  (value: T, index: number, it: Iterable<T>): value is S;
+}
+
 /**
  * The same as the `Iterable` type, but the iterator implementation is iterable.
  * @typeParam T - Type of items in the iterable.

test_deps.ts

@@ -2,3 +2,7 @@ export { assert } from "https://deno.land/[email protected]/assert/assert.ts";
 export { assertThrows } from "https://deno.land/[email protected]/assert/assert_throws.ts";
 export { assertEquals } from "https://deno.land/[email protected]/assert/assert_equals.ts";
 export { assertArrayIncludes } from "https://deno.land/[email protected]/assert/assert_array_includes.ts";
+export {
+  assertType,
+  type IsExact,
+} from "https://deno.land/[email protected]/testing/types.ts";