feat: add dependencies argument to reset the value

Author: littensy

src/use-lifetime/README.md

@@ -1,15 +1,19 @@
 ## 🪝 `useLifetime`
 
 ```ts
-function useLifetime(): Roact.Binding<number>;
+function useLifetime(dependencies?: unknown[]): Roact.Binding<number>;
 ```
 
 Returns the amount of time that has passed since the component mounted. The binding is updated every frame on Heartbeat.
 
+If dependencies are provided, the binding will reset to `0` whenever any of the dependencies change.
+
 Useful for mapping time to procedural animations and other time-based effects.
 
 ### 📕 Parameters
 
+-   `dependencies` - An optional array of dependencies. If provided, the binding will reset to `0` whenever any of the dependencies change.
+
 ### 📗 Returns
 
 -   A binding that will update with the amount of time that has passed since the component mounted.

src/use-lifetime/use-lifetime.spec.ts

@@ -8,8 +8,27 @@ export = () => {
 		const { result, unmount } = renderHook(() => useLifetime());
 
 		expect(result.current.getValue()).to.equal(0);
+
+		const timePassed = task.wait(0.1);
+		expect(result.current.getValue()).to.be.near(timePassed, 0.05);
+
+		unmount();
+	});
+
+	it("should reset when dependencies change", () => {
+		const { result, rerender, unmount } = renderHook((props: { value: number }) => useLifetime([props.value]), {
+			initialProps: { value: 0 },
+		});
+
+		expect(result.current.getValue()).to.equal(0);
+
 		const timePassed = task.wait(0.1);
-		expect(result.current.getValue()).to.be.near(timePassed, 0.03);
+		rerender({ value: 0 });
+		expect(result.current.getValue()).to.be.near(timePassed, 0.05);
+
+		rerender({ value: 1 });
+		expect(result.current.getValue()).to.equal(0);
+
 		unmount();
 	});
 };

src/use-lifetime/use-lifetime.ts

@@ -1,18 +1,27 @@
-import { useBinding } from "@rbxts/roact-hooked";
+import { useBinding, useEffect } from "@rbxts/roact-hooked";
 import { RunService } from "@rbxts/services";
 import { useEventListener } from "../use-event-listener";
 
 /**
  * Returns the lifetime of the component in seconds. Updates every frame on
  * the Heartbeat event.
+ *
+ * If the dependency array is provided, the lifetime timer will reset when
+ * any of the dependencies change.
+ *
+ * @param dependencies An optional array of dependencies to reset the timer.
  * @returns A binding of the component's lifetime.
  */
-export function useLifetime() {
+export function useLifetime(dependencies: unknown[] = []) {
 	const [lifetime, setLifetime] = useBinding(0);
 
 	useEventListener(RunService.Heartbeat, (deltaTime) => {
 		setLifetime(lifetime.getValue() + deltaTime);
 	});
 
+	useEffect(() => {
+		setLifetime(0);
+	}, dependencies);
+
 	return lifetime;
 }