feat: create useBetterEffect hook

Author: davidhu2000

.gitignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+coverage

README.md

@@ -0,0 +1,75 @@
+# useBetterEffect
+
+A wrapper around `React.useEffect` but with improved API
+
+## Installation
+
+With Yarn:
+
+```bash
+yarn add use-better-effect
+```
+
+With npm:
+
+```bash
+npm install --save use-better-effect
+```
+
+## Background
+
+`useEffect` is a power tool but the API has some gotchas. See the following examples
+
+```ts
+// not passing dependencies mean someFn runs on ever render
+useEffect(() => someFn());
+
+// passing [] as dependencies mean someFn only run on mount
+useEffect(() => someFn(), []);
+
+// passing [a, b] as dependencies mean someFn rerun when a or b changes
+useEffect(() => someFn(), [a, b]);
+
+// the returned function of the passed in callback function is called on mount.
+useEffect(() => {
+  someFn();
+  return () => anotherFn();
+}, [a, b]);
+```
+
+These implicit behaviors are hard to understand by just looking at the code.
+
+## Improved API
+
+`useBetterEffect` uses typescript function overloading to improve the developer experience when using the effect for different conditions. There are 3 supports run conditions:
+
+- ON_MOUNT
+- EVERY_RENDER
+- DEPENDENCIES_CHANGED
+
+For `ON_MOUNT` and `EVERY_RENDER`, passing in dependencies will result in a type error and `useBetterEffect` auto computes the dependency argument as `[]` and `undefined` respectively.
+
+The cleanup function is passing as an explict optional arugment.
+
+## Examples
+
+```ts
+useBetterEffect({
+  callbackFn: () => console.log("yay better"),
+  cleanupFn: () => console.log("so fresh and so clean"),
+  runCondition: "ON_MOUNT",
+});
+
+useBetterEffect({
+  callbackFn: () => console.log("yay better"),
+  cleanupFn: () => console.log("so fresh and so clean"),
+  runCondition: "EVERY_RENDER",
+});
+
+useBetterEffect({
+  callbackFn: () => console.log("yay better"),
+  cleanupFn: () => console.log("so fresh and so clean"),
+  runCondition: "DEPENDENCIES_CHANGED",
+  dependencies: [count],
+});
+```

jest.config.ts

@@ -0,0 +1,12 @@
+/*
+ * For a detailed explanation regarding each configuration property and type check, visit:
+ * https://jestjs.io/docs/configuration
+ */
+
+export default {
+  preset: "ts-jest",
+  collectCoverage: true,
+  collectCoverageFrom: ["src/**/*.ts"],
+  coverageDirectory: "coverage",
+  testEnvironment: "jsdom",
+};

package.json

@@ -0,0 +1,29 @@
+{
+  "name": "use-better-effect",
+  "version": "0.0.1",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "license": "MIT",
+  "devDependencies": {
+    "@testing-library/react": "^13.4.0",
+    "@types/jest": "^29.2.4",
+    "@types/node": "^18.11.14",
+    "@types/react": "^18.0.26",
+    "@types/react-dom": "^18.0.9",
+    "jest": "^29.3.1",
+    "jest-environment-jsdom": "^29.3.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "ts-jest": "^29.0.3",
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.4"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0"
+  },
+  "scripts": {
+    "test": "jest",
+    "build": "tsc"
+  }
+}

src/index.ts

@@ -0,0 +1 @@
+export { useBetterEffect } from "./use-better-effect";

src/use-better-effect.comp.test.tsx

@@ -0,0 +1,113 @@
+import { useState } from "react";
+import { act, render } from "@testing-library/react";
+import { useBetterEffect } from "./use-better-effect";
+
+describe("useBetterEffect", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe("runCondition: ON_MOUNT", () => {
+    const TestComponent = () => {
+      const [count, setCount] = useState(0);
+      useBetterEffect({
+        callbackFn: () => {
+          setCount(count + 1);
+        },
+        runCondition: "ON_MOUNT",
+      });
+      return <div>{count}</div>;
+    };
+
+    it("should update count to 1 on mount", () => {
+      const wrapper = render(<TestComponent />);
+      expect(wrapper.queryByText("1")).toBeTruthy();
+    });
+
+    it("should not update count on rerender", () => {
+      const wrapper = render(<TestComponent />);
+      expect(wrapper.queryByText("1")).toBeTruthy();
+      wrapper.rerender(<TestComponent />);
+      expect(wrapper.queryByText("1")).toBeTruthy();
+      wrapper.rerender(<TestComponent />);
+      expect(wrapper.queryByText("1")).toBeTruthy();
+    });
+  });
+
+  describe("runCondition: EVERY_RENDER", () => {
+    const someFn = jest.fn();
+    const TestComponent = () => {
+      useBetterEffect({
+        callbackFn: () => {
+          someFn();
+        },
+        runCondition: "EVERY_RENDER",
+      });
+      return <div>EVERY_RENDER</div>;
+    };
+
+    it("should call someFn on mount", () => {
+      render(<TestComponent />);
+      expect(someFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should call someFn on rerender", () => {
+      const wrapper = render(<TestComponent />);
+      expect(someFn).toHaveBeenCalledTimes(1);
+      wrapper.rerender(<TestComponent />);
+      expect(someFn).toHaveBeenCalledTimes(2);
+      wrapper.rerender(<TestComponent />);
+      expect(someFn).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("runCondition: DEPENDENCIES_CHANGED", () => {
+    const someFn = jest.fn();
+    const TestComponent = () => {
+      const [count, setCount] = useState(0);
+      useBetterEffect({
+        callbackFn: someFn,
+        runCondition: "DEPENDENCIES_CHANGED",
+        dependencies: [count],
+      });
+
+      return (
+        <div>
+          <div>{count}</div>
+          <button onClick={() => setCount(count + 1)}>click</button>
+        </div>
+      );
+    };
+
+    it("should call someFn and render initial count on mount", () => {
+      const wrapper = render(<TestComponent />);
+      expect(wrapper.queryByText("0")).toBeTruthy();
+      expect(someFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should call someFn when count changes", async () => {
+      const wrapper = render(<TestComponent />);
+      expect(wrapper.queryByText("0")).toBeTruthy();
+      expect(someFn).toHaveBeenCalledTimes(1);
+      act(() => {
+        wrapper.getByText("click").click();
+      });
+      expect(wrapper.queryByText("1")).toBeTruthy();
+      expect(someFn).toHaveBeenCalledTimes(2);
+      act(() => {
+        wrapper.getByText("click").click();
+      });
+      expect(wrapper.queryByText("2")).toBeTruthy();
+      expect(someFn).toHaveBeenCalledTimes(3);
+    });
+
+    it("should not call someFn when component rerenders by deps did not change", () => {
+      const wrapper = render(<TestComponent />);
+      expect(wrapper.queryByText("0")).toBeTruthy();
+      expect(someFn).toHaveBeenCalledTimes(1);
+      wrapper.rerender(<TestComponent />);
+      expect(wrapper.queryByText("0")).toBeTruthy();
+      expect(someFn).toHaveBeenCalledTimes(1);
+    });
+  });
+});

src/use-better-effect.hook.test.ts

@@ -0,0 +1,136 @@
+import { renderHook } from "@testing-library/react";
+import { useEffect } from "react";
+
+import { useBetterEffect } from "./use-better-effect";
+
+describe("useBetterEffect", () => {
+  describe('runCondition: "ON_MOUNT"', () => {
+    it("should run callbackFn on mount", () => {
+      const callbackFn = jest.fn();
+      renderHook(() =>
+        useBetterEffect({ callbackFn, runCondition: "ON_MOUNT" })
+      );
+      expect(callbackFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should not run callbackFn on rerenders", () => {
+      const callbackFn = jest.fn();
+      const { rerender } = renderHook(() => {
+        useBetterEffect({
+          callbackFn,
+          runCondition: "ON_MOUNT",
+        });
+      });
+      expect(callbackFn).toHaveBeenCalledTimes(1);
+      rerender();
+      expect(callbackFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should run cleanupFn on unmount", () => {
+      const cleanupFn = jest.fn();
+      const { unmount } = renderHook(() =>
+        useBetterEffect({
+          callbackFn: () => {},
+          cleanupFn,
+          runCondition: "ON_MOUNT",
+        })
+      );
+      expect(cleanupFn).toHaveBeenCalledTimes(0);
+      unmount();
+      expect(cleanupFn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('runCondition: "EVERY_RENDER"', () => {
+    it("should run callbackFn on mount", () => {
+      const callbackFn = jest.fn();
+      renderHook(() =>
+        useBetterEffect({ callbackFn, runCondition: "EVERY_RENDER" })
+      );
+      expect(callbackFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should run callbackFn on every render", () => {
+      const callbackFn = jest.fn();
+      const { rerender } = renderHook(() =>
+        useBetterEffect({ callbackFn, runCondition: "EVERY_RENDER" })
+      );
+      expect(callbackFn).toHaveBeenCalledTimes(1);
+      rerender();
+      expect(callbackFn).toHaveBeenCalledTimes(2);
+      rerender();
+      expect(callbackFn).toHaveBeenCalledTimes(3);
+    });
+
+    it("should run cleanupFn on unmount", () => {
+      const cleanupFn = jest.fn();
+      const { unmount } = renderHook(() =>
+        useBetterEffect({
+          callbackFn: () => {},
+          cleanupFn,
+          runCondition: "EVERY_RENDER",
+        })
+      );
+      expect(cleanupFn).toHaveBeenCalledTimes(0);
+      unmount();
+      expect(cleanupFn).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('runCondition: "DEPENDENCIES_CHANGED"', () => {
+    it("should run callbackFn on mount", () => {
+      const callbackFn = jest.fn();
+      renderHook(() =>
+        useBetterEffect({
+          callbackFn,
+          runCondition: "DEPENDENCIES_CHANGED",
+          dependencies: [1, 2, 3],
+        })
+      );
+      expect(callbackFn).toHaveBeenCalledTimes(1);
+    });
+
+    it.only("should run callbackFn on dependencies changed", () => {
+      const callbackFn = jest.fn();
+      const { rerender } = renderHook(
+        ({ dependencies }) => useEffect(callbackFn, dependencies),
+        { initialProps: { dependencies: [1, 2, 3] } }
+      );
+      expect(callbackFn).toHaveBeenCalledTimes(1);
+      rerender({ dependencies: [1, 2, 3, 4] });
+      expect(callbackFn).toHaveBeenCalledTimes(2);
+    });
+
+    it("should not run cleanupFn on dependencies changed", () => {
+      const cleanupFn = jest.fn();
+      const { rerender } = renderHook(
+        ({ dependencies }) =>
+          useBetterEffect({
+            callbackFn: () => {},
+            cleanupFn,
+            runCondition: "DEPENDENCIES_CHANGED",
+            dependencies,
+          }),
+        { initialProps: { dependencies: [1, 2, 3] } }
+      );
+      expect(cleanupFn).toHaveBeenCalledTimes(0);
+      rerender({ dependencies: [1, 2, 3, 4] });
+      expect(cleanupFn).toHaveBeenCalledTimes(0);
+    });
+
+    it("should run cleanupFn on unmount", () => {
+      const cleanupFn = jest.fn();
+      const { unmount } = renderHook(() =>
+        useBetterEffect({
+          callbackFn: () => {},
+          cleanupFn,
+          runCondition: "DEPENDENCIES_CHANGED",
+          dependencies: [1, 2, 3],
+        })
+      );
+      expect(cleanupFn).toHaveBeenCalledTimes(0);
+      unmount();
+      expect(cleanupFn).toHaveBeenCalledTimes(1);
+    });
+  });
+});