v1.3.0

- Add configurable options to hook
- Add `cleanUpOnCall` option
- Add `cleanUpOnDepsChange` option
- Add `cleanUpOnUnmount` option

Author: Shrugsy

README.md

@@ -120,6 +120,16 @@ const result = greetAndAlert("world");
 // `result` is returned here, *and* we still get to use the cleanup!
 ```
 
+## Options
+`useCleanupCallback` takes an optional object as a third argument to pass additional options to in order to customize the behaviour of the hook.
+
+| Name                | Type    | Default | Description                                                                      |
+|---------------------|---------|---------|----------------------------------------------------------------------------------|
+| cleanUpOnCall       | boolean | true    | Whether to call the last cleanup when the output callback of the hook is called. |
+| cleanUpOnDepsChange | boolean | false   | Whether to call the last cleanup when dependencies change.                       |
+| cleanUpOnUnmount    | boolean | true    | Whether to call the last cleanup when the hook unmounts.                         |
+
+
 ## Limitations
 
 - Similarly to `useEffect`, the `callback` and returned `cleanup callback` must be synchronous (i.e. an `async` function callback will not work). You can alleviate this the same way you would with `useEffect` by defining the asynchronous function within the callback, and calling it immediately.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-cleanup-callback",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "React hook that is a hybrid of useCallback and the cleanup from useEffect",
   "main": "dist/index.js",
   "source": "src/index.ts",
@@ -11,8 +11,11 @@
   "scripts": {
     "build": "rimraf dist/* && microbundle && rimraf dist/*mjs* dist/*umd* dist/*test*",
     "dev": "microbundle watch",
+    "lint": "eslint ./src/**",
     "test": "jest",
-    "test-watch": "jest --watch"
+    "test-types": "tsc --noEmit",
+    "test-watch": "jest --watch",
+    "checks": "eslint ./src/** && jest && tsc --noEmit"
   },
   "keywords": [
     "react",

src/index.ts

@@ -1,22 +1,55 @@
 import { useCallback, useEffect, DependencyList, useRef } from 'react';
 
+/**
+ * A standard cleanup
+ */
 export type Cleanup = void | (() => void | undefined);
 
+/**
+ * An object notation cleanup used when a return value is required from the callback returned
+ * by `useCleanupCallback`
+ */
 export type ReturnObject<V> = {
   value: V;
   cleanup: Cleanup;
 };
 
+/**
+ * An input/output callback that returns a standard cleanup
+ */
 export type CleanupCallback<T extends unknown[]> = (...args: T) => Cleanup;
-export type CleanupCallbackWithReturn<T extends unknown[], V> = (
-  ...args: T
-) => ReturnObject<V>;
-export type ReturnedCleanupCallbackWithReturn<T extends unknown[], V> = (
-  ...args: T
-) => V;
-
-function executeIfFunction(arg: unknown) {
-  if (typeof arg === 'function') arg();
+
+/**
+ * An input callback that returns an object notation cleanup
+ */
+export type CleanupCallbackWithReturn<T extends unknown[], V> = (...args: T) => ReturnObject<V>;
+
+/**
+ * Additional `useCleanupCallback` options
+ */
+export type Options = {
+  cleanUpOnCall?: boolean;
+  cleanUpOnDepsChange?: boolean;
+  cleanUpOnUnmount?: boolean;
+};
+
+/**
+ * The output callback returned from `useCleanupCallback` when an object notation cleanup is used.
+ * Provides a callback that itself returns the desired value.
+ */
+export type ReturnedCleanupCallbackWithReturn<T extends unknown[], V> = (...args: T) => V;
+
+/**
+ * Handles calling a cleanup if it hasn't been called, and is a function
+ */
+function handleCleanupObj(cleanupObj: { cleanup: unknown; isCalled: boolean }): void {
+  const { cleanup, isCalled } = cleanupObj;
+  if (!isCalled && typeof cleanup === 'function') {
+    // mark it as called
+    cleanupObj.isCalled = true;
+    // call the cleanup function
+    cleanup();
+  }
 }
 
 /**
@@ -26,43 +59,108 @@ function executeIfFunction(arg: unknown) {
  * @param callback - Callback to be memoized. Supports returning a 'cleanup' callback.
  * @param deps - Dependency array for the associated callback.
  */
+
+/* overload 1 - no cleanup, or standard cleanup
+  e.g.
+  useCleanupCallback(() => {
+    // some code
+    return;
+  }, []);
+
+  e.g.
+  useCleanupCallback(() => {
+    // some code
+    return () => {
+      // do cleanup
+    };
+  }, []);
+*/
 function useCleanupCallback<T extends unknown[]>(
   callback: CleanupCallback<T>,
-  deps: DependencyList
+  deps: DependencyList,
+  options?: Options
 ): CleanupCallback<T>;
+
+/* overload 2 - object return notation (return value & cleanup)
+  e.g.
+  useCleanupCallback(() => {
+    // some code
+    return {
+      value: 'foo',
+      cleanup: () =>{ 
+        // do cleanup
+      }
+    }
+  }, [])
+*/
 function useCleanupCallback<T extends unknown[], V>(
   callback: CleanupCallbackWithReturn<T, V>,
-  deps: DependencyList
+  deps: DependencyList,
+  options?: Options
 ): ReturnedCleanupCallbackWithReturn<T, V>;
+
+/* overload 3 - Union of overloads 1 & 2 */
 function useCleanupCallback<T extends unknown[], V>(
   callback: CleanupCallback<T> | CleanupCallbackWithReturn<T, V>,
-  deps: DependencyList
+  deps: DependencyList,
+  options?: Options
 ): CleanupCallback<T> | ReturnedCleanupCallbackWithReturn<T, V>;
+
+/* implementation signature */
 function useCleanupCallback<T extends unknown[], V>(
   callback: CleanupCallback<T> | CleanupCallbackWithReturn<T, V>,
-  deps: DependencyList
+  deps: DependencyList,
+  { cleanUpOnCall = true, cleanUpOnDepsChange = false, cleanUpOnUnmount = true }: Options = {}
 ) {
-  const cleanupRef = useRef<Cleanup | null>(null);
+  const cleanupRef = useRef<{ cleanup: Cleanup | null; isCalled: boolean }>({
+    cleanup: null,
+    isCalled: false,
+  });
+
+  // re-construct options & keep stored in a ref to cheat through useEffect deps
+  const options = { cleanUpOnCall, cleanUpOnDepsChange, cleanUpOnUnmount };
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    optionsRef.current = options;
+  });
 
   useEffect(() => {
     return () => {
-      // clean up last call if applicable
-      executeIfFunction(cleanupRef.current);
+      if (optionsRef.current.cleanUpOnDepsChange) {
+        handleCleanupObj(cleanupRef.current);
+      }
+    };
+  }, [deps]);
+
+  useEffect(() => {
+    return () => {
+      if (optionsRef.current.cleanUpOnUnmount) {
+        // clean up last call if applicable
+        handleCleanupObj(cleanupRef.current);
+      }
     };
   }, []);
 
   const outputCallback = useCallback((...args: T) => {
     // clean up previous call if applicable
-    executeIfFunction(cleanupRef.current);
+    if (optionsRef.current.cleanUpOnCall) {
+      handleCleanupObj(cleanupRef.current);
+    }
 
     const returnValue = callback(...args);
 
     if (typeof returnValue === 'object') {
       const { value, cleanup } = returnValue;
-      cleanupRef.current = cleanup;
+      cleanupRef.current = {
+        cleanup,
+        isCalled: false,
+      };
       return value;
     } else if (typeof returnValue === 'function') {
-      cleanupRef.current = returnValue;
+      cleanupRef.current = {
+        cleanup: returnValue,
+        isCalled: false,
+      };
     }
 
     return returnValue;