Trigger an optional function after any counter, stopwatch or timer finishes

README.md

@@ -35,6 +35,7 @@ It takes three arguments:
 - `min` (number): the initial value of the counter.
 - `max`(number): the final value of the counter. It has to be greater than `min`.
 - `startPaused` (optional boolean): a boolean flag that determines whether the counter should start in a paused state. Defaults to false.
+- `onFinish` (optional function): a function that will be called when the counter reaches the final value.
 
 It returns an object with the following props:
 
@@ -83,6 +84,7 @@ It takes three arguments:
 - `min` (number): the initial value of the counter.
 - `max`(number): the final value of the counter. It has to be greater than `min`.
 - `startPaused` (optional boolean): a boolean flag that determines whether the counter should start in a paused state. Defaults to false.
+- `onFinish` (optional function): a function that will be called when the counter reaches the final value.
 
 It returns an object with the following props:
 
@@ -134,6 +136,7 @@ It takes six arguments:
 - `seconds` (number): the final value of the seconds. The value must be between 0 (inclusive) and 60 (exclusive).
 - `startPaused` (optional boolean): a boolean flag that determines whether the stopwatch should start in a paused state. Defaults to false.
 - `separator` (optional string): a string that specifies the separator to be used between days, hours, minutes, and seconds when the time is represented as a string. By default, colon (:) is used as a separator.
+- `onFinish` (optional function): a function that will be called when the stopwatch reaches the final value.
 
 It returns an object with the following props:
 
@@ -282,6 +285,7 @@ It takes six arguments:
 - `seconds` (number): the initial value of the seconds. The value must be between 0 (inclusive) and 60 (exclusive).
 - `startPaused` (optional boolean): a boolean flag that determines whether the timer should start in a paused state. Defaults to false.
 - `separator` (optional string): a string that specifies the separator to be used between days, hours, minutes, and seconds when the time is represented as a string. By default, colon (:) is used as a separator.
+- `onFinish` (optional function): a function that will be called when the timer reaches the final value.
 
 It returns an object with the following props:
 

src/App.tsx

@@ -1,7 +1,7 @@
-import { useCountDown } from "./hooks";
+import { useTimer } from "./hooks";
 
 const App = () => {
-  const counter = useCountDown(0, 10);
+  const counter = useTimer(0, 0, 0, 2);
 
   return (
     <div>

src/helpers/useCounter.ts

@@ -6,7 +6,8 @@ export const useCounter = (
   min: number,
   max: number,
   isCountingUp: boolean,
-  startPaused?: boolean
+  startPaused?: boolean,
+  onFinish?: () => void
 ): BaseCounter => {
   if (min >= max) {
     throw new Error("The min parameter has to be less than the max parameter.");
@@ -36,6 +37,10 @@ export const useCounter = (
     return () => clearInterval(interval);
   }, [count, min, max, paused, isCountingUp]);
 
+  useEffect(() => {
+    isOver && onFinish && onFinish();
+  }, [isOver]);
+
   return {
     current: {
       withLeadingZero: addLeadingZero(count),

src/helpers/useInternalStopwatch.ts

@@ -8,7 +8,8 @@ export const useInternalStopwatch = (
   minutes: number,
   seconds: number,
   startPaused?: boolean,
-  separator?: string
+  separator?: string,
+  onFinish?: () => void
 ): InternalCounter => {
   const [time, setTime] = useState({
     days: 0,
@@ -67,6 +68,10 @@ export const useInternalStopwatch = (
     return () => clearInterval(interval);
   }, [days, hours, minutes, seconds, time, paused]);
 
+  useEffect(() => {
+    isOver && onFinish && onFinish();
+  }, [isOver]);
+
   return {
     current: {
       withLeadingZero: `${addLeadingZero(time.days)}${divider}${addLeadingZero(

src/helpers/useInternalTimer.ts

@@ -8,7 +8,8 @@ export const useInternalTimer = (
   minutes: number,
   seconds: number,
   startPaused?: boolean,
-  separator?: string
+  separator?: string,
+  onFinish?: () => void
 ): InternalCounter => {
   const [time, setTime] = useState({ days, hours, minutes, seconds });
   const [paused, setPaused] = useState(startPaused ?? false);
@@ -64,6 +65,10 @@ export const useInternalTimer = (
     return () => clearInterval(interval);
   }, [days, hours, minutes, seconds, time, paused]);
 
+  useEffect(() => {
+    isOver && onFinish && onFinish();
+  }, [isOver]);
+
   return {
     current: {
       withLeadingZero: `${addLeadingZero(time.days)}${divider}${addLeadingZero(

src/hooks/useCountDown.ts

@@ -4,5 +4,6 @@ import { useCounter } from "../helpers";
 export const useCountDown = (
   min: number,
   max: number,
-  startPaused?: boolean
-): BaseCounter => useCounter(min, max, false, startPaused);
+  startPaused?: boolean,
+  onFinish?: () => void
+): BaseCounter => useCounter(min, max, false, startPaused, onFinish);

src/hooks/useCountUp.ts

@@ -4,5 +4,6 @@ import { useCounter } from "../helpers";
 export const useCountUp = (
   min: number,
   max: number,
-  startPaused?: boolean
-): BaseCounter => useCounter(min, max, true, startPaused);
+  startPaused?: boolean,
+  onFinish?: () => void
+): BaseCounter => useCounter(min, max, true, startPaused, onFinish);

src/hooks/useStopwatch.ts

@@ -15,7 +15,8 @@ export const useStopwatch = (
   minutes: number,
   seconds: number,
   startPaused?: boolean,
-  separator?: string
+  separator?: string,
+  onFinish?: () => void
 ): Stopwatch => {
   handleTimerErrors(days, hours, minutes, seconds);
 
@@ -25,7 +26,8 @@ export const useStopwatch = (
     minutes,
     seconds,
     startPaused,
-    separator
+    separator,
+    onFinish
   );
   const timer = useInternalTimer(
     days,

src/hooks/useTimer.ts

@@ -5,7 +5,7 @@ import {
   handleTimerErrors,
 } from "../helpers";
 
-export interface Timer extends BaseCounter, BaseCounterStatus {
+interface Timer extends BaseCounter, BaseCounterStatus {
   elapsedTime: Zero;
 }
 
@@ -15,7 +15,8 @@ export const useTimer = (
   minutes: number,
   seconds: number,
   startPaused?: boolean,
-  separator?: string
+  separator?: string,
+  onFinish?: () => void
 ): Timer => {
   handleTimerErrors(days, hours, minutes, seconds);
 
@@ -25,7 +26,8 @@ export const useTimer = (
     minutes,
     seconds,
     startPaused,
-    separator
+    separator,
+    onFinish
   );
   const stopwatch = useInternalStopwatch(
     days,