Rework useTimer

docs/use-callback-const.md

@@ -1,3 +1,16 @@
 # `useCallbackConst`
 
-Documentation coming soon...
+Creates a callback with a constant value over the lifecycle of a component.
+
+## Example
+
+```tsx
+const immutableCallback = useCallbackConst(() => {
+  console.log(
+    `I don't have any local state dependencies
+    and I won't trigger unncessary re-renders.`
+  );
+});
+
+<button onClick={immutableCallback}>Click me to increment: {count}</button>
+```

docs/use-callback-ref.md

@@ -1,3 +1,27 @@
 # `useCallbackRef`
 
-Documentation coming soon...
+Converts a callback to a ref to avoid triggering re-renders when passed as a
+prop or avoid re-executing effects when passed as a dependency.
+
+Returns a new callback with a constant value over the lifecycle of a component.
+
+## Example
+
+```tsx
+const [state, setState] = useState(0);
+
+const logState = useCallbackRef(() => {
+  console.log('state:', state);
+});
+
+useEffect(() => {
+  logState();
+  // => "state: 1"
+  // => "state: 2"
+  // => "state: 3"
+  // => "state: 4"
+  // => ...
+}, [state]);
+
+<button onClick={() => setState((curr) => curr + 1)}>Click me to increment: {count}</button>
+```

docs/use-timer.md

@@ -2,19 +2,19 @@
 
 Creates a timer that works inside the React component lifecycle. A timer can be configured with a total `length` (in milliseconds), a `tick` value  (in milliseconds) representing the frequency a timer state updates, and an `autoStart` boolean value indicating whether to immediately initiate the countdown. Returns a `Timer` object with the following fields:
 
-- `start`: A callback function which starts a timer from scratch.
-- `pause`: A callback function which pauses the timer. This function has no effect if the timer has not yet started.
-- `resume`: A callback function which resumes the timer from a paused state. This function has no effect if the timer has not yet started.
-- `reset`: A callback function which resets the timer. An updated timer length and tick value can be provided as arguments. You will need to call `Timer.start()` to restart the countdown.
-- `getRemaining`: A callback function returning the amount of time (in milliseconds) remaining in the timer.
-- `getLength`: A callback function returning the total expected length of the timer (in milliseconds).
-- `isRunning`: A callback function returning a `boolean` indicating whether the timer is currently running.
-- `key`: A static value that updates whenever the timer state changes. You can provide this value to a `useEffect` dependency list to trigger effects.
+- `start`: A callback function which starts the timer ticking. If the timer is currently in a paused state, then it will resume based on the original, remaining length.
+- `pause`: A callback function which pauses the timer. This function has no effect if the timer has not yet started ticking.
+- `resume`: A callback function which resumes the timer from a paused state. This function has no effect if the timer has not yet started ticking.
+- `restart`: A callback function which restarts the timer. An updated timer length and tick value can be provided as arguments.
+- `getRemaining`: A callback function which returns the amount of time (in milliseconds) remaining in the timer. If the timer is idle, this function returns `0`.
+- `getTickCount`: A callback function returning the number of ticks that have accumulated since the start of the currently-running timer
+- `getStatus`: A callback function returning a string enum indicating the current timer state (one of: `"idle"`, `"running"`, `"paused"`, or `"expired"`).
+- `key`: A static value that updates whenever the underlying timer state changes. You can give this value to the dependency list `React.useEffect` to trigger an effect.
 
 The `useTimer` module also exports additional utility hooks to integrate with timers:
 
-- `useTimerEffect`: Executes a side-effect each time the supplied timer "ticks".
-- `useTimerComplete`: Executes a side-effect when the supplied timer finishes its countdown.
+- `useTimerTick`: Executes a side-effect each time the supplied timer "ticks".
+- `useTimerExpire`: Executes a side-effect when the supplied timer finishes its countdown.
 
 ## Examples
 
@@ -29,19 +29,19 @@ const timer = useTimer({
 ```tsx
 const timer = useTimer({ ..., tick: 1000 });
 
-useTimerEffect(timer, () => {
+useTimerTick(timer, () => {
   // logs every 1 second!
   console.log('tick tock tick tock');
-}, [/* effect dependencies */]);
+});
 ```
 
 ```tsx
 const timer = useTimer({ ..., length: 5000 });
 
-useTimerComplete(timer, () => {
+useTimerExpire(timer, () => {
   // logs after 5 seconds!
   console.log('ding ding ding!');
-}, [/* effect dependencies */]);
+});
 ```
 
 

docs/use-value-ref.md

@@ -1,3 +1,11 @@
 # `useValueRef`
 
-Documentation coming soon...
+Converts a given value to a ref to avoid triggering re-renders when passed as a
+prop or avoid re-executing effects when passed as a dependency.
+
+Returns a ref object with a constant value over the lifecycle of a component.
+
+## Example
+
+Example coming soon...
+