chore: countdown options, onStart and onFinish

README.md

@@ -32,9 +32,11 @@ import useCountDown from 'react-countdown-hook';
 
 const initialTime = 60 * 1000; // initial time in milliseconds, defaults to 60000
 const interval = 1000; // interval to change remaining time amount, defaults to 1000
+const onStart = () => console.log("Starting...")
+const onFinish = () => console.log("Finished!")
 
 const render = () => {
-  const [timeLeft, { start, pause, resume, reset }] = useCountDown(initialTime, interval);
+  const [timeLeft, { start, pause, resume, reset }] = useCountDown(initialTime, {interval, onStart, onFinish});
 
   // start the timer during the first render
   React.useEffect(() => {
@@ -70,7 +72,11 @@ or [in the demo project](./demo/index.js "react-countdown-hook demo project")
 #### Parameters
 Takes a default countdown time and interval time.
 * `timeToCount` {`Number`} Time in milliseconds that countdown should start with. **Defaults to `60000`**
-* `interval` {`Number`} Time in milliseconds representing the frequency that countdown should update with. **Defaults to `1000`**
+* `options` {`Object`} Optional configurations for the countdown
+  * `interval` {`Number`} Time in milliseconds representing the frequency that countdown should update with. **Defaults to `1000`**
+  * `onStart` {`Function`} A function to be called once the countdown starts **Defaults to `undefined`**
+  * `onFinish` {`Function`} A function to be called once the countdown finish **Defaults to `undefined`**
+
 
 #### Return value
 Returns an array with remaining time and actions object.

cypress/integration/react-countdown-hook/on-finish.spec.js

@@ -0,0 +1,14 @@
+context('react-use-countdown – on finish', () => {
+  beforeEach(() => {
+    cy.visit('http://localhost:1234');
+  });
+
+  it('should trigger on finish', () => {
+    cy.get('#start').click();
+    cy.get('#times-up').should('not.exist');
+
+    cy.wait(11 * 1000);
+    cy.get('#times-up').should('contain', 'Finished');
+  });
+
+});

cypress/integration/react-countdown-hook/on-start.spec.js

@@ -0,0 +1,18 @@
+context('react-use-countdown – on start', () => {
+  beforeEach(() => {
+    cy.visit('http://localhost:1234');
+  });
+
+  it('should trigger on start', () => {
+    cy.get('#start').click();
+    cy.get('#times-up').should('not.exist');
+
+    cy.wait(11 * 1000);
+    cy.get('#times-up').should('contain', 'Finished');
+
+    cy.get('#start').click();
+    cy.wait(1 * 1000);
+    cy.get('#times-up').should('not.exist');
+  });
+
+});

demo/index.js

@@ -5,7 +5,12 @@ import useCountDown from "../src"
 const buttonStyle = { marginRight: '10px' };
 
 const App = () => {
-  const [timeLeft, actions] = useCountDown(10000, 500);
+  const [isTimesUp, setTimesUp] = React.useState(false);
+  const [timeLeft, actions] = useCountDown(10000, {
+    interval: 500,
+    onFinish: () => setTimesUp(true),
+    onStart: () => setTimesUp(false),
+  });
   return (
     <div style={{ textAlign: 'center' }}>
       <h1 id="time-left">{(timeLeft / 1000).toFixed(2)}</h1>
@@ -43,6 +48,7 @@ const App = () => {
       >
         Reset
       </button>
+      {isTimesUp && <h1 id="times-up">Finished</h1>}
     </div>
   );
 };

package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-countdown-hook",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Dead simple yet powerful countdown hook for React.",
   "keywords": [
     "countdown",

src/index.js

@@ -1,6 +1,6 @@
 import React from 'react';
 
-const useCountDown = (timeToCount = 60 * 1000, interval = 1000) => {
+const useCountDown = (timeToCount = 60 * 1000, {interval = 1000, onFinish, onStart}) => {
   const [timeLeft, setTimeLeft] = React.useState(0);
   const timer = React.useRef({});
 
@@ -24,6 +24,7 @@ const useCountDown = (timeToCount = 60 * 1000, interval = 1000) => {
     } else {
       timer.current = {};
       setTimeLeft(0);
+      onFinish && onFinish();
     }
   }
 
@@ -38,6 +39,7 @@ const useCountDown = (timeToCount = 60 * 1000, interval = 1000) => {
       timer.current.requestId = window.requestAnimationFrame(run);
 
       setTimeLeft(newTimeToCount);
+      onStart && onStart()
     },
     [],
   );

typings.d.ts

@@ -6,8 +6,14 @@ declare module "react-countdown-hook" {
     reset(): void;
   }
 
+  interface Options {
+    interval?: number;
+    onFinish?: () => void;
+    onStart?: () => void;
+  }
+
   interface UseCountDown {
-    (timeToCount: number, interval?: number): [number, Actions];
+    (timeToCount: number, options?: Options): [number, Actions];
   }
 
   const useCountDown: UseCountDown;