🏁 auto start (#30)

* bump version.

* update docs.

* add auto start property.

* add tests.

* add start function. adjust tests. improve example.

* bump version to alpha.

* update license.

* update npmrc.

* bump version.

---------

Co-authored-by: Brad Garropy <[email protected]>

.npmrc

@@ -1 +1,2 @@
 legacy-peer-deps=true
+registry=https://registry.npmjs.org/

example/index.tsx

@@ -8,11 +8,16 @@ const App = () => {
         minutes: 1,
         seconds: 30,
         format: "mm:ss",
+        autoStart: false,
         onCompleted: () => console.log("onCompleted"),
     })
 
     console.log(countdown)
 
+    const onStart = () => {
+        countdown.start()
+    }
+
     const onPause = () => {
         countdown.pause()
     }
@@ -33,10 +38,12 @@ const App = () => {
         <>
             <h1>⏳ useCountdown hook</h1>
             <h2>{countdown.formatted}</h2>
+            <button onClick={onStart}>Start</button>
             <button onClick={onPause}>Pause</button>
             <button onClick={onResume}>Resume</button>
             <button onClick={onReset}>Reset</button>
             <button onClick={onResetChange}>Reset to 2:00</button>
+            <pre>{JSON.stringify(countdown, null, 2)}</pre>
         </>
     )
 }

license

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Brad Garropy
+Copyright (c) 2023 Brad Garropy
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bradgarropy/use-countdown",
-    "version": "1.5.2",
+    "version": "2.0.0",
     "description": "⏳ useCountdown hook",
     "keywords": [
         "javascript",

readme.md

@@ -38,6 +38,7 @@ const App = () => {
         minutes: 1,
         seconds: 30,
         format: "mm:ss",
+        autoStart: true,
         onCompleted: () => console.log("onCompleted"),
     })
 
@@ -56,12 +57,13 @@ const App = () => {
 
 ### `useCountdown({minutes, seconds})`
 
-| Name          | Required |   Default   |  Example   | Description                                |
-| :------------ | :------: | :---------: | :--------: | :----------------------------------------- |
-| `minutes`     | `false`  |     `0`     |    `1`     | Countdown minutes.                         |
-| `seconds`     | `false`  |     `0`     |    `30`    | Countdown seconds.                         |
-| `format`      | `false`  |   `mm:ss`   | `mm:ss:SS` | Format string ([reference][format]).       |
-| `onCompleted` | `false`  | `undefined` | `function` | Function to call when countdown completes. |
+| Name          | Required |   Default   |  Example   | Description                                          |
+| :------------ | :------: | :---------: | :--------: | :--------------------------------------------------- |
+| `minutes`     | `false`  |     `0`     |    `1`     | Countdown minutes.                                   |
+| `seconds`     | `false`  |     `0`     |    `30`    | Countdown seconds.                                   |
+| `format`      | `false`  |   `mm:ss`   | `mm:ss:SS` | Format string ([reference][format]).                 |
+| `autoStart`   | `false`  |   `false`   |   `true`   | Whether or not to automatically start the countdown. |
+| `onCompleted` | `false`  | `undefined` | `function` | Function to call when countdown completes.           |
 
 Starts a countdown timer based on the number of minutes and seconds provided. The returned `countdown` object updates once per second and stops when the timer hits zero.
 
@@ -76,6 +78,7 @@ const countdown = useCountdown({
     minutes: 1,
     seconds: 30,
     format: "mm:ss:SS",
+    autoStart: true,
     onCompleted: () => console.log("onCompleted"),
 })
 

src/countdown.tsx

@@ -12,6 +12,7 @@ type useCountdownParams = {
     minutes?: number
     seconds?: number
     format?: string
+    autoStart?: boolean
     onCompleted?: VoidFunction
 }
 
@@ -23,6 +24,7 @@ const useCountdown = ({
     minutes = 0,
     seconds = 0,
     format = "mm:ss",
+    autoStart = false,
     onCompleted,
 }: useCountdownParams = {}): Countdown => {
     const id = useRef(0)
@@ -40,12 +42,14 @@ const useCountdown = ({
 
     useEffect(
         () => {
-            id.current = window.setInterval(calculateRemainingTime, 1000)
+            if (autoStart) {
+                id.current = window.setInterval(calculateRemainingTime, 1000)
 
-            setIsActive(true)
-            setIsInactive(false)
-            setIsRunning(true)
-            setIsPaused(false)
+                setIsActive(true)
+                setIsInactive(false)
+                setIsRunning(true)
+                setIsPaused(false)
+            }
 
             return () => window.clearInterval(id.current)
         },
@@ -85,7 +89,7 @@ const useCountdown = ({
         setIsPaused(true)
     }
 
-    const resume = (): void => {
+    const start = (): void => {
         if (isRunning) {
             return
         }
@@ -100,12 +104,20 @@ const useCountdown = ({
 
     const reset = (time: Time = {minutes, seconds}) => {
         window.clearInterval(id.current)
-        id.current = window.setInterval(calculateRemainingTime, 1000)
 
-        setIsActive(true)
-        setIsInactive(false)
-        setIsRunning(true)
-        setIsPaused(false)
+        if (autoStart) {
+            id.current = window.setInterval(calculateRemainingTime, 1000)
+
+            setIsActive(true)
+            setIsInactive(false)
+            setIsRunning(true)
+            setIsPaused(false)
+        } else {
+            setIsActive(false)
+            setIsInactive(true)
+            setIsRunning(false)
+            setIsPaused(false)
+        }
 
         setRemainingTime(calculateInitialTime(time))
     }
@@ -118,8 +130,9 @@ const useCountdown = ({
         isInactive,
         isRunning,
         isPaused,
+        start,
         pause,
-        resume,
+        resume: start,
         reset,
     }
 

src/types.ts

@@ -19,6 +19,7 @@ type Countdown = {
     isInactive: boolean
     isRunning: boolean
     isPaused: boolean
+    start: VoidFunction
     pause: VoidFunction
     resume: VoidFunction
     reset: (time?: Time) => void