feat(callIfExists): improved type safety

Author: João Dias

cypress/test/functions/utlities/call-if-exists.cy.ts

@@ -3,18 +3,102 @@
  *
  * (c) 2024 Feedzai
  */
-import { callIfExists } from "src/functions";
+import { callIfExists } from "src/functions/utilities/call-if-exists";
 
-describe("callIfExist", () => {
+describe("callIfExists", () => {
   it("should not throw an exception when no callback is passed", () => {
     expect(callIfExists.bind(this, undefined)).not.throw();
   });
 
+  it("should not throw an exception when null callback is passed", () => {
+    expect(callIfExists.bind(this, null)).not.throw();
+  });
+
+  it("should not throw an exception when non-function is passed", () => {
+    // @ts-expect-error - Testing invalid input
+    expect(callIfExists.bind(this, "not a function")).not.throw();
+    // @ts-expect-error - Testing invalid input
+    expect(callIfExists.bind(this, 42)).not.throw();
+    // @ts-expect-error - Testing invalid input
+    expect(callIfExists.bind(this, {})).not.throw();
+  });
+
   it("should call the function passed", () => {
     const func = cy.stub();
-
     callIfExists(func);
-
     expect(func).to.have.been.called;
   });
+
+  it("should pass arguments to the callback function", () => {
+    const func = cy.stub();
+    callIfExists(func, "arg1", 42, { key: "value" });
+    expect(func).to.have.been.calledWith("arg1", 42, { key: "value" });
+  });
+
+  it("should return the result of the callback function", () => {
+    const result = callIfExists(() => "test");
+    expect(result).to.equal("test");
+  });
+
+  it("should return undefined when callback is not a function", () => {
+    expect(callIfExists(undefined)).to.be.undefined;
+    expect(callIfExists(null)).to.be.undefined;
+    // @ts-expect-error - Testing invalid input
+    expect(callIfExists("not a function")).to.be.undefined;
+    // @ts-expect-error - Testing invalid input
+    expect(callIfExists(42)).to.be.undefined;
+    // @ts-expect-error - Testing invalid input
+    expect(callIfExists({})).to.be.undefined;
+  });
+
+  it("should handle functions with different return types", () => {
+    expect(callIfExists(() => 42)).to.equal(42);
+    expect(callIfExists(() => "string")).to.equal("string");
+    expect(callIfExists(() => true)).to.be.true;
+    expect(callIfExists(() => ({ key: "value" }))).to.deep.equal({ key: "value" });
+    expect(callIfExists(() => [1, 2, 3])).to.deep.equal([1, 2, 3]);
+  });
+
+  it("should handle functions with different parameter types", () => {
+    const stringFunc = (str: string) => str.toUpperCase();
+    const numberFunc = (num: number) => num * 2;
+    const objectFunc = (obj: { key: string }) => obj.key;
+    const arrayFunc = (arr: number[]) => arr.reduce((a, b) => a + b, 0);
+
+    // @ts-expect-error - Testing type compatibility
+    expect(callIfExists(stringFunc, "test")).to.equal("TEST");
+    // @ts-expect-error - Testing type compatibility
+    expect(callIfExists(numberFunc, 21)).to.equal(42);
+    // @ts-expect-error - Testing type compatibility
+    expect(callIfExists(objectFunc, { key: "value" })).to.equal("value");
+    // @ts-expect-error - Testing type compatibility
+    expect(callIfExists(arrayFunc, [1, 2, 3])).to.equal(6);
+  });
+
+  it("should handle async functions", async () => {
+    const asyncFunc = async () => "async result";
+    const result = await callIfExists(asyncFunc);
+    expect(result).to.equal("async result");
+  });
+
+  it("should handle functions that throw errors", () => {
+    const errorFunc = () => {
+      throw new Error("test error");
+    };
+    expect(() => callIfExists(errorFunc)).to.throw("test error");
+  });
+
+  it("should handle functions with rest parameters", () => {
+    const sum = (...numbers: number[]) => numbers.reduce((a, b) => a + b, 0);
+    // @ts-expect-error - Testing type compatibility
+    expect(callIfExists(sum, 1, 2, 3, 4)).to.equal(10);
+  });
+
+  it("should handle functions with optional parameters", () => {
+    const greet = (name: string, greeting = "Hello") => `${greeting}, ${name}!`;
+    // @ts-expect-error - Testing type compatibility
+    expect(callIfExists(greet, "John")).to.equal("Hello, John!");
+    // @ts-expect-error - Testing type compatibility
+    expect(callIfExists(greet, "John", "Hi")).to.equal("Hi, John!");
+  });
 });

docs/docs/functions/utils/call-if-exists.mdx

@@ -6,7 +6,10 @@ Executes the given callback function, if present.
 ## API
 
 ```typescript
-function callIfExists<GenericFunctionType>(callback: GenericFunctionType, ...args: any[]): void;
+function callIfExists<T extends (...args: unknown[]) => ReturnType<T>>(
+  callback: T | undefined | null,
+  ...args: Parameters<T>
+): ReturnType<T> | undefined
 ```
 
 ### Usage

src/functions/utilities/call-if-exists.ts

@@ -4,30 +4,34 @@
  * (c) 2024 Feedzai
  */
 
+import { isFunction } from "../typed";
+
 /**
- * Executes the given callback function, if it exists.
+ * Safely executes a callback function if it exists.
+ *
+ * @template T - The type of the callback function
  *
  * @param callback - The function to be executed if it exists
  * @param args - Arguments to be passed to the callback
  *
+ * @returns The result of the callback function, or undefined if callback is not a function
+ *
  * @example
- * // Calling a function with several arguments
+ * // Basic usage
  * callIfExists((a: number, b: string) => console.log(a, b), 1, "test");
  *
- * // Calling a function without any argument
+ * // No arguments
  * callIfExists(() => console.log("Hello"));
  *
- * // Nothing happens if the callback is not a function
- * callIfExists(undefined);
- * callIfExists(null);
- * callIfExists("not a function");
+ * // Non-function callback
+ * callIfExists(undefined); // => undefined
+ * callIfExists(null); // => undefined
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function callIfExists<T extends (...args: any[]) => any>(
+export function callIfExists<T extends (...args: unknown[]) => ReturnType<T>>(
   callback: T | undefined | null,
   ...args: Parameters<T>
-): void {
-  if (typeof callback === "function") {
-    callback(...args);
+): ReturnType<T> | undefined {
+  if (isFunction(callback)) {
+    return callback(...args);
   }
 }