@conorroberts/utils 0.0.85 → 0.0.86

package/dist/react.d.mts

@@ -61,6 +61,22 @@ declare const useLocalOnce: (condition: unknown, callback: () => void) => void;
  * ```
  */
 declare const useOnMount: (callback: React.EffectCallback) => void;
+/**
+ * Calls the given async callback when the component mounts.
+ * Uses useStableCallback internally to ensure the latest version is called.
+ * Unlike useOnMount, this does not support cleanup functions.
+ *
+ * @param callback - The async function to run when the component mounts.
+ *
+ * @example
+ * ```tsx
+ * useAsyncOnMount(async () => {
+ *   const data = await fetchData();
+ *   console.log("Data loaded:", data);
+ * });
+ * ```
+ */
+declare const useAsyncOnMount: (callback: () => Promise<void>) => void;
 //#endregion
 //#region src/react/useOnUnmount.d.ts
 /**
@@ -69,5 +85,5 @@ declare const useOnMount: (callback: React.EffectCallback) => void;
  */
 declare const useOnUnmount: (callback: () => void) => void;
 //#endregion
-export { useLocalOnce, useOnMount, useOnUnmount, useOnce, useStableCallback };
+export { useAsyncOnMount, useLocalOnce, useOnMount, useOnUnmount, useOnce, useStableCallback };
 //# sourceMappingURL=react.d.mts.map

package/dist/react.mjs

@@ -96,6 +96,31 @@ const useOnMount = (callback) => {
 		}
 	}, [stableCallback]);
 };
+/**
+* Calls the given async callback when the component mounts.
+* Uses useStableCallback internally to ensure the latest version is called.
+* Unlike useOnMount, this does not support cleanup functions.
+*
+* @param callback - The async function to run when the component mounts.
+*
+* @example
+* ```tsx
+* useAsyncOnMount(async () => {
+*   const data = await fetchData();
+*   console.log("Data loaded:", data);
+* });
+* ```
+*/
+const useAsyncOnMount = (callback) => {
+	const stableCallback = useStableCallback(callback);
+	const isRun = useRef(false);
+	useEffect(() => {
+		if (!isRun.current) {
+			isRun.current = true;
+			stableCallback();
+		}
+	}, [stableCallback]);
+};
 
 //#endregion
 //#region src/react/useOnUnmount.ts
@@ -113,5 +138,5 @@ const useOnUnmount = (callback) => {
 };
 
 //#endregion
-export { useLocalOnce, useOnMount, useOnUnmount, useOnce, useStableCallback };
+export { useAsyncOnMount, useLocalOnce, useOnMount, useOnUnmount, useOnce, useStableCallback };
 //# sourceMappingURL=react.mjs.map

package/dist/react.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"react.mjs","names":[],"sources":["../src/react/useStableCallback.ts","../src/react/useOnce.ts","../src/react/useLocalOnce.ts","../src/react/useOnMount.ts","../src/react/useOnUnmount.ts"],"sourcesContent":["// oxlint-disable no-explicit-any\r\n\r\nimport { useCallback, useRef } from \"react\";\r\n\r\ntype AnyFunction = (...args: any[]) => any;\r\ntype AnyArgs = any[];\r\n\r\n/**\r\n * Creates a stable callback that always calls the latest version of the function.\r\n * Useful for callbacks that need to be used in dependency arrays but should always\r\n * execute the most recent version of the callback.\r\n */\r\nexport const useStableCallback = <T extends AnyFunction>(callback: T): T => {\r\n  const callbackRef = useRef(callback);\r\n\r\n  // Update the ref on every render\r\n  callbackRef.current = callback;\r\n\r\n  return useCallback((...args: AnyArgs) => {\r\n    return callbackRef.current(...args);\r\n  }, []) as T;\r\n};\r\n","import { useEffect, useRef } from \"react\";\r\nimport { useStableCallback } from \"./useStableCallback\";\r\n\r\n/**\r\n * Runs a callback only once when a condition becomes truthy.\r\n * The callback is stabilized internally to always reference the latest version.\r\n *\r\n * @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).\r\n * @param callback - The function to run once when the condition is met.\r\n *\r\n * @example\r\n * ```tsx\r\n * const isReady = true;\r\n * useOnce(isReady, () => {\r\n *   console.log(\"Ready!\");\r\n * });\r\n * ```\r\n */\r\nexport const useOnce = (condition: unknown, callback: () => void): void => {\r\n  const hasRunRef = useRef(false);\r\n  const stableCallback = useStableCallback(callback);\r\n\r\n  useEffect(() => {\r\n    if (Boolean(condition) && !hasRunRef.current) {\r\n      hasRunRef.current = true;\r\n      stableCallback();\r\n    }\r\n  }, [condition, stableCallback]);\r\n};\r\n","import { useRef } from \"react\";\r\nimport { useStableCallback } from \"./useStableCallback\";\r\n\r\n/**\r\n * Runs a callback only once when a condition becomes truthy, executing synchronously\r\n * during render. The callback is stabilized internally to always reference the latest version.\r\n *\r\n * Unlike `useOnce`, this runs at the top level of the hook (not in useEffect),\r\n * making it suitable for state updates that need to happen synchronously during render.\r\n *\r\n * @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).\r\n * @param callback - The function to run once when the condition is met.\r\n *\r\n * @example\r\n * ```tsx\r\n * const user: User | null = getUser();\r\n * useLocalOnce(user, () => {\r\n *   setState(user.name);\r\n * });\r\n * ```\r\n */\r\nexport const useLocalOnce = (condition: unknown, callback: () => void): void => {\r\n  const hasRunRef = useRef(false);\r\n  const stableCallback = useStableCallback(callback);\r\n\r\n  if (Boolean(condition) && !hasRunRef.current) {\r\n    hasRunRef.current = true;\r\n    stableCallback();\r\n  }\r\n};\r\n","import { useEffect, useRef } from \"react\";\nimport { useStableCallback } from \"./useStableCallback\";\n\n/**\n * Calls the given callback when the component mounts.\n * Uses useStableCallback internally to ensure the latest version is called.\n *\n * @param callback - The function to run when the component mounts.\n *\n * @example\n * ```tsx\n * useOnMount(() => {\n *   console.log(\"Component mounted!\");\n * });\n * ```\n */\nexport const useOnMount = (callback: React.EffectCallback): void => {\n  const stableCallback = useStableCallback(callback);\n  const isRun = useRef(false);\n\n  useEffect(() => {\n    if (!isRun.current) {\n      isRun.current = true;\n      return stableCallback();\n    }\n  }, [stableCallback]);\n};\n","import { useEffect } from \"react\";\r\nimport { useStableCallback } from \"./useStableCallback\";\r\n\r\n/**\r\n * Calls the given callback when the component unmounts.\r\n * Uses useStableCallback internally to ensure the latest version is called.\r\n */\r\nexport const useOnUnmount = (callback: () => void): void => {\r\n  const stableCallback = useStableCallback(callback);\r\n\r\n  useEffect(() => {\r\n    return () => {\r\n      stableCallback();\r\n    };\r\n  }, [stableCallback]);\r\n};\r\n"],"mappings":";;;;;;;;AAYA,MAAa,qBAA4C,aAAmB;CAC1E,MAAM,cAAc,OAAO,SAAS;AAGpC,aAAY,UAAU;AAEtB,QAAO,aAAa,GAAG,SAAkB;AACvC,SAAO,YAAY,QAAQ,GAAG,KAAK;IAClC,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;ACFR,MAAa,WAAW,WAAoB,aAA+B;CACzE,MAAM,YAAY,OAAO,MAAM;CAC/B,MAAM,iBAAiB,kBAAkB,SAAS;AAElD,iBAAgB;AACd,MAAI,QAAQ,UAAU,IAAI,CAAC,UAAU,SAAS;AAC5C,aAAU,UAAU;AACpB,mBAAgB;;IAEjB,CAAC,WAAW,eAAe,CAAC;;;;;;;;;;;;;;;;;;;;;;;ACNjC,MAAa,gBAAgB,WAAoB,aAA+B;CAC9E,MAAM,YAAY,OAAO,MAAM;CAC/B,MAAM,iBAAiB,kBAAkB,SAAS;AAElD,KAAI,QAAQ,UAAU,IAAI,CAAC,UAAU,SAAS;AAC5C,YAAU,UAAU;AACpB,kBAAgB;;;;;;;;;;;;;;;;;;;ACXpB,MAAa,cAAc,aAAyC;CAClE,MAAM,iBAAiB,kBAAkB,SAAS;CAClD,MAAM,QAAQ,OAAO,MAAM;AAE3B,iBAAgB;AACd,MAAI,CAAC,MAAM,SAAS;AAClB,SAAM,UAAU;AAChB,UAAO,gBAAgB;;IAExB,CAAC,eAAe,CAAC;;;;;;;;;AClBtB,MAAa,gBAAgB,aAA+B;CAC1D,MAAM,iBAAiB,kBAAkB,SAAS;AAElD,iBAAgB;AACd,eAAa;AACX,mBAAgB;;IAEjB,CAAC,eAAe,CAAC"}
+{"version":3,"file":"react.mjs","names":[],"sources":["../src/react/useStableCallback.ts","../src/react/useOnce.ts","../src/react/useLocalOnce.ts","../src/react/useOnMount.ts","../src/react/useOnUnmount.ts"],"sourcesContent":["// oxlint-disable no-explicit-any\r\n\r\nimport { useCallback, useRef } from \"react\";\r\n\r\ntype AnyFunction = (...args: any[]) => any;\r\ntype AnyArgs = any[];\r\n\r\n/**\r\n * Creates a stable callback that always calls the latest version of the function.\r\n * Useful for callbacks that need to be used in dependency arrays but should always\r\n * execute the most recent version of the callback.\r\n */\r\nexport const useStableCallback = <T extends AnyFunction>(callback: T): T => {\r\n  const callbackRef = useRef(callback);\r\n\r\n  // Update the ref on every render\r\n  callbackRef.current = callback;\r\n\r\n  return useCallback((...args: AnyArgs) => {\r\n    return callbackRef.current(...args);\r\n  }, []) as T;\r\n};\r\n","import { useEffect, useRef } from \"react\";\r\nimport { useStableCallback } from \"./useStableCallback\";\r\n\r\n/**\r\n * Runs a callback only once when a condition becomes truthy.\r\n * The callback is stabilized internally to always reference the latest version.\r\n *\r\n * @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).\r\n * @param callback - The function to run once when the condition is met.\r\n *\r\n * @example\r\n * ```tsx\r\n * const isReady = true;\r\n * useOnce(isReady, () => {\r\n *   console.log(\"Ready!\");\r\n * });\r\n * ```\r\n */\r\nexport const useOnce = (condition: unknown, callback: () => void): void => {\r\n  const hasRunRef = useRef(false);\r\n  const stableCallback = useStableCallback(callback);\r\n\r\n  useEffect(() => {\r\n    if (Boolean(condition) && !hasRunRef.current) {\r\n      hasRunRef.current = true;\r\n      stableCallback();\r\n    }\r\n  }, [condition, stableCallback]);\r\n};\r\n","import { useRef } from \"react\";\r\nimport { useStableCallback } from \"./useStableCallback\";\r\n\r\n/**\r\n * Runs a callback only once when a condition becomes truthy, executing synchronously\r\n * during render. The callback is stabilized internally to always reference the latest version.\r\n *\r\n * Unlike `useOnce`, this runs at the top level of the hook (not in useEffect),\r\n * making it suitable for state updates that need to happen synchronously during render.\r\n *\r\n * @param condition - When truthy (evaluated via Boolean()), the callback will be executed (only once).\r\n * @param callback - The function to run once when the condition is met.\r\n *\r\n * @example\r\n * ```tsx\r\n * const user: User | null = getUser();\r\n * useLocalOnce(user, () => {\r\n *   setState(user.name);\r\n * });\r\n * ```\r\n */\r\nexport const useLocalOnce = (condition: unknown, callback: () => void): void => {\r\n  const hasRunRef = useRef(false);\r\n  const stableCallback = useStableCallback(callback);\r\n\r\n  if (Boolean(condition) && !hasRunRef.current) {\r\n    hasRunRef.current = true;\r\n    stableCallback();\r\n  }\r\n};\r\n","import { useEffect, useRef } from \"react\";\nimport { useStableCallback } from \"./useStableCallback\";\n\n/**\n * Calls the given callback when the component mounts.\n * Uses useStableCallback internally to ensure the latest version is called.\n *\n * @param callback - The function to run when the component mounts.\n *\n * @example\n * ```tsx\n * useOnMount(() => {\n *   console.log(\"Component mounted!\");\n * });\n * ```\n */\nexport const useOnMount = (callback: React.EffectCallback): void => {\n  const stableCallback = useStableCallback(callback);\n  const isRun = useRef(false);\n\n  useEffect(() => {\n    if (!isRun.current) {\n      isRun.current = true;\n      return stableCallback();\n    }\n  }, [stableCallback]);\n};\n\n/**\n * Calls the given async callback when the component mounts.\n * Uses useStableCallback internally to ensure the latest version is called.\n * Unlike useOnMount, this does not support cleanup functions.\n *\n * @param callback - The async function to run when the component mounts.\n *\n * @example\n * ```tsx\n * useAsyncOnMount(async () => {\n *   const data = await fetchData();\n *   console.log(\"Data loaded:\", data);\n * });\n * ```\n */\nexport const useAsyncOnMount = (callback: () => Promise<void>): void => {\n  const stableCallback = useStableCallback(callback);\n  const isRun = useRef(false);\n\n  useEffect(() => {\n    if (!isRun.current) {\n      isRun.current = true;\n      stableCallback();\n    }\n  }, [stableCallback]);\n};\n","import { useEffect } from \"react\";\r\nimport { useStableCallback } from \"./useStableCallback\";\r\n\r\n/**\r\n * Calls the given callback when the component unmounts.\r\n * Uses useStableCallback internally to ensure the latest version is called.\r\n */\r\nexport const useOnUnmount = (callback: () => void): void => {\r\n  const stableCallback = useStableCallback(callback);\r\n\r\n  useEffect(() => {\r\n    return () => {\r\n      stableCallback();\r\n    };\r\n  }, [stableCallback]);\r\n};\r\n"],"mappings":";;;;;;;;AAYA,MAAa,qBAA4C,aAAmB;CAC1E,MAAM,cAAc,OAAO,SAAS;AAGpC,aAAY,UAAU;AAEtB,QAAO,aAAa,GAAG,SAAkB;AACvC,SAAO,YAAY,QAAQ,GAAG,KAAK;IAClC,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;ACFR,MAAa,WAAW,WAAoB,aAA+B;CACzE,MAAM,YAAY,OAAO,MAAM;CAC/B,MAAM,iBAAiB,kBAAkB,SAAS;AAElD,iBAAgB;AACd,MAAI,QAAQ,UAAU,IAAI,CAAC,UAAU,SAAS;AAC5C,aAAU,UAAU;AACpB,mBAAgB;;IAEjB,CAAC,WAAW,eAAe,CAAC;;;;;;;;;;;;;;;;;;;;;;;ACNjC,MAAa,gBAAgB,WAAoB,aAA+B;CAC9E,MAAM,YAAY,OAAO,MAAM;CAC/B,MAAM,iBAAiB,kBAAkB,SAAS;AAElD,KAAI,QAAQ,UAAU,IAAI,CAAC,UAAU,SAAS;AAC5C,YAAU,UAAU;AACpB,kBAAgB;;;;;;;;;;;;;;;;;;;ACXpB,MAAa,cAAc,aAAyC;CAClE,MAAM,iBAAiB,kBAAkB,SAAS;CAClD,MAAM,QAAQ,OAAO,MAAM;AAE3B,iBAAgB;AACd,MAAI,CAAC,MAAM,SAAS;AAClB,SAAM,UAAU;AAChB,UAAO,gBAAgB;;IAExB,CAAC,eAAe,CAAC;;;;;;;;;;;;;;;;;AAkBtB,MAAa,mBAAmB,aAAwC;CACtE,MAAM,iBAAiB,kBAAkB,SAAS;CAClD,MAAM,QAAQ,OAAO,MAAM;AAE3B,iBAAgB;AACd,MAAI,CAAC,MAAM,SAAS;AAClB,SAAM,UAAU;AAChB,mBAAgB;;IAEjB,CAAC,eAAe,CAAC;;;;;;;;;AC7CtB,MAAa,gBAAgB,aAA+B;CAC1D,MAAM,iBAAiB,kBAAkB,SAAS;AAElD,iBAAgB;AACd,eAAa;AACX,mBAAgB;;IAEjB,CAAC,eAAe,CAAC"}

package/package.json

@@ -51,7 +51,7 @@
     "typescript": "5.9.3",
     "vitest": "4.0.15"
   },
-  "version": "0.0.85",
+  "version": "0.0.86",
   "scripts": {
     "dev": "tsdown --watch",
     "test": "vitest run",