fix: Improve when function's type safety for type guard predicates (#325)

* fix: edit when overload return type from Exclude<T,S> to R | Exclude<T,S for when predicate call is true

* test: add tests to prove changed return types

* test: add runtime tests to prove changed codes' correct working

Author: elrion018

src/when.ts

@@ -43,7 +43,7 @@ import isUndefined from "./isUndefined";
 function when<T, S extends T, R>(
   predicate: (input: T) => input is S,
   callback: (input: S) => R,
-): (a: T) => Exclude<T, S>;
+): (a: T) => R | Exclude<T, S>;
 function when<T, R>(
   predicate: (input: T) => boolean,
   callback: (input: T) => R,
@@ -52,7 +52,7 @@ function when<T, S extends T, R>(
   predicate: (input: T) => input is S,
   callback: (input: S) => R,
   a: T,
-): Exclude<T, S>;
+): R | Exclude<T, S>;
 function when<T, R>(
   predicate: (input: T) => boolean,
   callback: (input: T) => R,

test/when.spec.ts

@@ -1,37 +1,80 @@
 import { isString, pipe, when } from "../src";
 
 describe("when", function () {
-  const test = <T>(value: T) =>
-    when(
-      (value) => value === 100,
-      (value) => {
-        expect(value).toBeTruthy();
-      },
-      value,
-    );
-  const withPipe = <T>(value: T) =>
-    pipe(
-      value,
-      test,
-      when(isString, () => "Hello fxts"),
-    );
-
-  it("If the input value is a number, it will be filtered out by the first 'when' function. And throw undefined.", () => {
-    const INPUT_VALUE = 100;
-
-    test(INPUT_VALUE);
-    withPipe(INPUT_VALUE);
-  });
-  it("If the input value is a string, it will be filtered out by the second 'when' function. And return value is 'Hello fxts'", () => {
-    const INPUT_VALUE = "Hello World";
+  describe("with a general predicate", () => {
+    const test = <T>(value: T) =>
+      when(
+        (value) => value === 100,
+        (value) => {
+          expect(value).toBeTruthy();
+          return "value is 100";
+        },
+        value,
+      );
+    const withPipe = <T>(value: T) =>
+      pipe(
+        value,
+        test,
+        when(isString, () => "Hello fxts"),
+      );
+
+    it("If the input value is a number 100, the callback is executed and returns its result.", () => {
+      const INPUT_VALUE = 100;
+      expect(test(INPUT_VALUE)).toBe("value is 100");
+    });
+
+    it("If the input value does not match predicate, it returns the original value.", () => {
+      const INPUT_VALUE = "Hello World";
+      expect(test(INPUT_VALUE)).toBe("Hello World");
+    });
 
-    expect(test(INPUT_VALUE)).toBe("Hello World");
-    expect(withPipe(INPUT_VALUE)).toBe("Hello fxts");
+    it("If nothing matches, all 'when' functions will be passed.", () => {
+      const INPUT_VALUE = [1, 2, 3, 4];
+      expect(test(INPUT_VALUE)).toEqual(INPUT_VALUE);
+      expect(withPipe(INPUT_VALUE)).toEqual(INPUT_VALUE);
+    });
   });
-  it("If nothing matches, all 'when' functions will be passed.", () => {
-    const INPUT_VALUE = [1, 2, 3, 4];
 
-    expect(test(INPUT_VALUE)).toEqual(INPUT_VALUE);
-    expect(withPipe(INPUT_VALUE)).toEqual(INPUT_VALUE);
+  describe("with a type guard predicate", () => {
+    type Shape =
+      | { type: "circle"; radius: number }
+      | { type: "square"; side: number };
+
+    const isCircle = (
+      shape: Shape,
+    ): shape is { type: "circle"; radius: number } => shape.type === "circle";
+
+    it("should return the result of the callback when the type guard is true", () => {
+      const myShape: Shape = { type: "circle", radius: 10 };
+      const result = when(
+        isCircle,
+        (circle) => `A circle with radius ${circle.radius}`,
+        myShape,
+      );
+      expect(result).toBe("A circle with radius 10");
+    });
+
+    it("should return the original value when the type guard is false", () => {
+      const anotherShape: Shape = { type: "square", side: 5 };
+      const result = when(
+        isCircle,
+        (circle) => `A circle with radius ${circle.radius}`,
+        anotherShape,
+      );
+      expect(result).toEqual(anotherShape);
+    });
+
+    it("should work correctly with pipe", () => {
+      const myShape: Shape = { type: "circle", radius: 10 };
+      const anotherShape: Shape = { type: "square", side: 5 };
+
+      const shapeHandler = when(
+        isCircle,
+        (circle) => `A circle with radius ${circle.radius}`,
+      );
+
+      expect(pipe(myShape, shapeHandler)).toBe("A circle with radius 10");
+      expect(pipe(anotherShape, shapeHandler)).toEqual(anotherShape);
+    });
   });
 });

type-check/when.test.ts

@@ -19,10 +19,48 @@ const check4 = when(
   VALUE_2,
 );
 
+// New test cases for R | Exclude<T, S>
+type Shape =
+  | { type: "circle"; radius: number }
+  | { type: "square"; side: number };
+const myShape: Shape = { type: "circle", radius: 10 };
+const anotherShape: Shape = { type: "square", side: 5 };
+
+const isCircle = (
+  shape: Shape,
+): shape is { type: "circle"; radius: number } => {
+  return shape.type === "circle";
+};
+
+// When predicate is a type guard and is true at runtime
+const check5 = when(
+  isCircle,
+  (circle) => `A circle with radius ${circle.radius}`, // R = string
+  myShape,
+);
+
+// When predicate is a type guard and is false at runtime
+const check6 = when(
+  isCircle,
+  (circle) => `A circle with radius ${circle.radius}`, // R = string
+  anotherShape,
+);
+
+// Curried version
+const curriedWhen = when(
+  isCircle,
+  (circle) => `A circle with radius ${circle.radius}`,
+);
+const check7 = curriedWhen(myShape);
+
 checks([
   check<typeof VALUE_1, 100, Test.Pass>(),
   check<typeof check1, string, Test.Pass>(),
-  check<typeof check2, number, Test.Pass>(),
+  check<typeof check2, string | number, Test.Pass>(),
   check<typeof check3, typeof VALUE_2 | string, Test.Pass>(),
   check<typeof check4, typeof VALUE_2 | string, Test.Pass>(),
+  // --- Added Tests ---
+  check<typeof check5, string, Test.Pass>(),
+  check<typeof check6, string | { type: "square"; side: number }, Test.Pass>(),
+  check<typeof check7, string | { type: "square"; side: number }, Test.Pass>(),
 ]);