feat: add useTimer

Author: littensy

src/index.ts

@@ -35,6 +35,7 @@ export * from "./use-throttle-callback";
 export * from "./use-throttle-effect";
 export * from "./use-throttle-state";
 export * from "./use-timeout";
+export * from "./use-timer";
 export * from "./use-unmount-effect";
 export * from "./use-update";
 export * from "./use-update-effect";

src/use-timer/README.md

@@ -0,0 +1,40 @@
+## 🪝 `useTimer`
+
+```ts
+function useTimer(initialValue?: number): Timer;
+```
+
+Returns a timer whose `value` field is a binding that will update every frame on Heartbeat. The timer's `value` field will start at `initialValue` if provided, or `0` otherwise.
+
+By default, the timer will start when the component mounts. If you want to start or stop the timer later, you can use the `start` and `stop` methods.
+
+### 📕 Parameters
+
+-   `initialValue` - An optional initial value for the timer. Defaults to `0`.
+
+### 📗 Returns
+
+-   A `Timer` object:
+    -   `value` - A binding that will update every frame.
+    -   `start()` - Starts the timer if it is not already running.
+    -   `stop()` - Stops the timer if it is running.
+    -   `reset()` - Resets the value to `0`.
+    -   `set(value)` - Sets the value to a new value.
+
+### 📘 Example
+
+```tsx
+function Blink() {
+	const timer = useTimer();
+	const transparency = timer.value.map((t) => math.sin(t) * 0.5 + 0.5);
+
+	return (
+		<textbutton
+			BackgroundTransparency={transparency}
+			Event={{
+				Activated: () => timer.reset(),
+			}}
+		/>
+	);
+}
+```

src/use-timer/index.ts

@@ -0,0 +1 @@
+export * from "./use-timer";

src/use-timer/use-timer.spec.ts

@@ -0,0 +1,59 @@
+/// <reference types="@rbxts/testez/globals" />
+
+import { renderHook } from "../utils/testez";
+import { useTimer } from "./use-timer";
+
+export = () => {
+	it("should start the timer on mount", () => {
+		const { result, unmount } = renderHook(() => useTimer());
+
+		expect(result.current.value.getValue()).to.equal(0);
+
+		const timePassed = task.wait(0.2);
+		expect(result.current.value.getValue()).to.be.near(timePassed, 0.08);
+
+		unmount();
+	});
+
+	it("should return functions to start and stop the timer", () => {
+		const { result, unmount } = renderHook(() => useTimer());
+
+		expect(result.current.value.getValue()).to.equal(0);
+
+		const timePassed = task.wait(0.2);
+		const timerValue = result.current.value.getValue();
+		expect(timerValue).to.be.near(timePassed, 0.08);
+
+		result.current.stop();
+
+		task.wait(0.2);
+		expect(result.current.value.getValue()).to.equal(timerValue);
+
+		result.current.start();
+
+		const timePassedAfterStart = task.wait(0.2);
+		expect(result.current.value.getValue()).to.be.near(timePassed + timePassedAfterStart, 0.08);
+
+		unmount();
+	});
+
+	it("should return a function to set the timer", () => {
+		const { result, unmount } = renderHook(() => useTimer());
+
+		expect(result.current.value.getValue()).to.equal(0);
+
+		const timePassed = task.wait(0.2);
+		expect(result.current.value.getValue()).to.be.near(timePassed, 0.08);
+
+		result.current.reset();
+		expect(result.current.value.getValue()).to.equal(0);
+
+		result.current.set(1);
+		expect(result.current.value.getValue()).to.equal(1);
+
+		const timePassedAfterSet = task.wait(0.2);
+		expect(result.current.value.getValue()).to.be.near(timePassedAfterSet + 1, 0.08);
+
+		unmount();
+	});
+};

src/use-timer/use-timer.ts

@@ -0,0 +1,63 @@
+import Roact from "@rbxts/roact";
+import { useBinding, useCallback, useMutable } from "@rbxts/roact-hooked";
+import { RunService } from "@rbxts/services";
+import { useEventListener } from "../use-event-listener";
+
+export interface Timer {
+	/**
+	 * A binding that represents the current value of the timer.
+	 */
+	readonly value: Roact.Binding<number>;
+	/**
+	 * Starts the timer if it is not already running.
+	 */
+	readonly start: () => void;
+	/**
+	 * Pauses the timer if it is running.
+	 */
+	readonly stop: () => void;
+	/**
+	 * Resets the timer to 0.
+	 */
+	readonly reset: () => void;
+	/**
+	 * Sets the timer to a specific value.
+	 * @param value The value to set the timer to.
+	 */
+	readonly set: (value: number) => void;
+}
+
+/**
+ * Creates a timer that can be used to track a value over time.
+ * @param initialValue The initial value of the timer.
+ * @returns A timer object.
+ */
+export function useTimer(initialValue = 0): Timer {
+	const [value, setValue] = useBinding(initialValue);
+
+	const started = useMutable(true);
+
+	useEventListener(RunService.Heartbeat, (deltaTime) => {
+		if (started.current) {
+			setValue(value.getValue() + deltaTime);
+		}
+	});
+
+	const start = useCallback(() => {
+		started.current = true;
+	}, []);
+
+	const stop = useCallback(() => {
+		started.current = false;
+	}, []);
+
+	const reset = useCallback(() => {
+		setValue(0);
+	}, []);
+
+	const set = useCallback((value: number) => {
+		setValue(value);
+	}, []);
+
+	return { value, start, stop, reset, set };
+}