refactor: split useTimeSync into two hooks

Parkreiner · Parkreiner · commit da5803d69c1b · 2025-05-07T18:45:48.000Z
diff --git a/site/src/components/SignInLayout/SignInLayout.tsx b/site/src/components/SignInLayout/SignInLayout.tsx
@@ -1,10 +1,11 @@
 import type { Interpolation, Theme } from "@emotion/react";
-import { useTimeSync } from "hooks/useTimeSync";
+import { useTimeSyncSelect } from "hooks/useTimeSync";
 import type { FC, PropsWithChildren } from "react";
 
 export const SignInLayout: FC<PropsWithChildren> = ({ children }) => {
-	const year = useTimeSync({
+	const year = useTimeSyncSelect({
 		targetRefreshInterval: Number.POSITIVE_INFINITY,
+		selectDependencies: [],
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/hooks/useTimeSync.tsx b/site/src/hooks/useTimeSync.tsx
@@ -25,12 +25,14 @@ import {
 import { useEffectEvent } from "./hookPolyfills";
 
 export {
-	IDEAL_REFRESH_ONE_DAY,
-	IDEAL_REFRESH_ONE_HOUR,
-	IDEAL_REFRESH_ONE_MINUTE,
-	IDEAL_REFRESH_ONE_SECOND,
+	TARGET_REFRESH_ONE_DAY,
+	TARGET_REFRESH_ONE_HOUR,
+	TARGET_REFRESH_ONE_MINUTE,
+	TARGET_REFRESH_ONE_SECOND,
 } from "utils/TimeSync";
 
+type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
+
 type SelectCallback = (newSnapshot: Date) => unknown;
 
 type ReactSubscriptionEntry = Readonly<
@@ -47,6 +49,7 @@ type SelectionCacheEntry = Readonly<{ value: unknown }>;
 
 interface ReactTimeSyncApi {
 	subscribe: (entry: ReactSubscriptionEntry) => () => void;
+	getTimeSnapshot: () => Date;
 	getSelectionSnapshot: <T = unknown>(id: string) => T;
 	invalidateSelection: (id: string, select?: SelectCallback) => void;
 }
@@ -63,15 +66,19 @@ class ReactTimeSync implements ReactTimeSyncApi {
 	// All functions that are part of the public interface must be defined as
 	// arrow functions, so that they work properly with React
 
+	getTimeSnapshot = () => {
+		return this.#timeSync.getTimeSnapshot();
+	};
+
 	subscribe = (entry: ReactSubscriptionEntry): (() => void) => {
-		const { select, id, idealRefreshIntervalMs, onUpdate } = entry;
+		const { select, id, targetRefreshInterval, onUpdate } = entry;
 
 		// Make sure that we subscribe first, in case TimeSync is configured to
 		// invalidate the snapshot on a new subscription. Want to remove risk of
 		// stale data
 		const patchedEntry: SubscriptionEntry = {
 			id,
-			idealRefreshIntervalMs,
+			targetRefreshInterval,
 			onUpdate: (newDate) => {
 				const prevSelection = this.getSelectionSnapshot(id);
 				const newSelection = select?.(newDate) ?? newDate;
@@ -157,7 +164,15 @@ export const TimeSyncProvider: FC<TimeSyncProviderProps> = ({
 	);
 };
 
-type UseTimeSyncOptions<T = Date> = Readonly<{
+function useTimeSyncContext(): ReactTimeSync {
+	const timeSync = useContext(timeSyncContext);
+	if (timeSync === null) {
+		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
+	}
+	return timeSync;
+}
+
+type UseTimeSyncOptions = Readonly<{
 	/**
 	 * targetRefreshInterval is the ideal interval of time, in milliseconds,
 	 * that defines how often the hook should refresh with the newest Date
@@ -172,26 +187,76 @@ type UseTimeSyncOptions<T = Date> = Readonly<{
 	 * sync with other useTimeSync users that are currently mounted on screen.
 	 */
 	targetRefreshInterval: number;
+}>;
 
-	/**
-	 * selectDependencies acts like the dependency array for a useMemo callback.
-	 * Whenever any of the elements in the array change by value, that will
-	 * cause the select callback to re-run synchronously and produce a new,
-	 * up-to-date value for the current render.
-	 */
-	selectDependencies?: readonly unknown[];
+export function useTimeSync(options: UseTimeSyncOptions): Date {
+	const { targetRefreshInterval } = options;
+	const hookId = useId();
+	const timeSync = useTimeSyncContext();
 
-	/**
-	 * Allows you to transform any date values received from the TimeSync class.
-	 * Select functions work similarly to the selects from React Query and Redux
-	 * Toolkit – you don't need to memoize them, and they will only run when the
-	 * underlying TimeSync state has changed.
-	 *
-	 * Select functions must not be async. The hook will error out at the type
-	 * level if you provide one by mistake.
-	 */
-	select?: (latestDatetime: Date) => T extends Promise<unknown> ? never : T;
-}>;
+	const subscribe = useCallback<ReactSubscriptionCallback>(
+		(notifyReact) => {
+			return timeSync.subscribe({
+				targetRefreshInterval,
+				id: hookId,
+				onUpdate: notifyReact,
+			});
+		},
+		[hookId, timeSync, targetRefreshInterval],
+	);
+
+	const snapshot = useSyncExternalStore(subscribe, timeSync.getTimeSnapshot);
+	return snapshot;
+}
+
+function areDepsInvalidated(
+	oldDeps: readonly unknown[] | undefined,
+	newDeps: readonly unknown[] | undefined,
+): boolean {
+	if (oldDeps === undefined) {
+		if (newDeps === undefined) {
+			return false;
+		}
+		return true;
+	}
+
+	const oldRecast = oldDeps as readonly unknown[];
+	const newRecast = oldDeps as readonly unknown[];
+	if (oldRecast.length !== newRecast.length) {
+		return true;
+	}
+
+	for (const [index, el] of oldRecast.entries()) {
+		if (el !== newRecast[index]) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+type UseTimeSyncSelectOptions<T = Date> = Readonly<
+	UseTimeSyncOptions & {
+		/**
+		 * selectDependencies acts like the dependency array for a useMemo
+		 * callback. Whenever any of the elements in the array change by value,
+		 * that will cause the select callback to re-run synchronously and
+		 * produce a new, up-to-date value for the current render.
+		 */
+		selectDependencies: readonly unknown[];
+
+		/**
+		 * Allows you to transform any date values received from the TimeSync
+		 * class. Select functions work similarly to the selects from React
+		 * Query and Redux Toolkit – you don't need to memoize them, and they
+		 * will only run when the underlying TimeSync state has changed.
+		 *
+		 * Select functions must not be async. The hook will error out at the
+		 * type level if you provide one by mistake.
+		 */
+		select: (latestDatetime: Date) => T extends Promise<unknown> ? never : T;
+	}
+>;
 
 /**
  * useTimeSync provides React bindings for the TimeSync class, letting a React
@@ -208,21 +273,12 @@ type UseTimeSyncOptions<T = Date> = Readonly<{
  * frequent update interval, both component instances will update on that
  * interval.
  */
-export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
-	const {
-		select,
-		selectDependencies: selectDeps,
-		targetRefreshInterval: idealRefreshIntervalMs,
-	} = options;
-	const timeSync = useContext(timeSyncContext);
-	if (timeSync === null) {
-		throw new Error("Cannot call useTimeSync outside of a TimeSyncProvider");
-	}
-
-	// Abusing useId a little bit here. It's mainly meant to be used for
-	// accessibility, but it also gives us a globally unique ID associated with
-	// whichever component instance is consuming this hook
+export function useTimeSyncSelect<T = Date>(
+	options: UseTimeSyncSelectOptions<T>,
+): T {
+	const { select, selectDependencies, targetRefreshInterval } = options;
 	const hookId = useId();
+	const timeSync = useTimeSyncContext();
 
 	// This is the one place where we're borderline breaking the React rules.
 	// useEffectEvent is meant to be used only in useEffect calls, and normally
@@ -249,21 +305,20 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// the new callback). All other values need to be included in the dependency
 	// array for correctness, but they should always maintain stable memory
 	// addresses
-	type ReactSubscriptionCallback = (notifyReact: () => void) => () => void;
 	const subscribe = useCallback<ReactSubscriptionCallback>(
 		(notifyReact) => {
 			return timeSync.subscribe({
-				idealRefreshIntervalMs,
+				targetRefreshInterval: targetRefreshInterval,
 				id: hookId,
 				onUpdate: notifyReact,
 				select: selectForOutsideReact,
 			});
 		},
-		[timeSync, hookId, selectForOutsideReact, idealRefreshIntervalMs],
+		[timeSync, hookId, selectForOutsideReact, targetRefreshInterval],
 	);
 
-	const [prevDeps, setPrevDeps] = useState(selectDeps);
-	const depsAreInvalidated = areDepsInvalidated(prevDeps, selectDeps);
+	const [prevDeps, setPrevDeps] = useState(selectDependencies);
+	const depsAreInvalidated = areDepsInvalidated(prevDeps, selectDependencies);
 
 	const selection = useSyncExternalStore<T>(subscribe, () => {
 		if (depsAreInvalidated) {
@@ -279,34 +334,8 @@ export function useTimeSync<T = Date>(options: UseTimeSyncOptions<T>): T {
 	// Setting state mid-render like this is valid, but we just need to make
 	// sure that we wait until after the useSyncExternalStore state getter runs
 	if (depsAreInvalidated) {
-		setPrevDeps(selectDeps);
+		setPrevDeps(selectDependencies);
 	}
 
 	return selection;
 }
-
-function areDepsInvalidated(
-	oldDeps: readonly unknown[] | undefined,
-	newDeps: readonly unknown[] | undefined,
-): boolean {
-	if (oldDeps === undefined) {
-		if (newDeps === undefined) {
-			return false;
-		}
-		return true;
-	}
-
-	const oldRecast = oldDeps as readonly unknown[];
-	const newRecast = oldDeps as readonly unknown[];
-	if (oldRecast.length !== newRecast.length) {
-		return true;
-	}
-
-	for (const [index, el] of oldRecast.entries()) {
-		if (el !== newRecast[index]) {
-			return true;
-		}
-	}
-
-	return false;
-}
diff --git a/site/src/modules/workspaces/activity.ts b/site/src/modules/workspaces/activity.ts
@@ -10,10 +10,11 @@ export type WorkspaceActivityStatus =
 
 export function getWorkspaceActivityStatus(
 	workspace: Workspace,
+	currentDatetime: Date,
 ): WorkspaceActivityStatus {
 	const builtAt = dayjs(workspace.latest_build.created_at);
 	const usedAt = dayjs(workspace.last_used_at);
-	const now = dayjs();
+	const now = dayjs(currentDatetime);
 
 	if (workspace.latest_build.status !== "running") {
 		return "notRunning";
diff --git a/site/src/pages/CliInstallPage/CliInstallPageView.tsx b/site/src/pages/CliInstallPage/CliInstallPageView.tsx
@@ -1,7 +1,7 @@
 import type { Interpolation, Theme } from "@emotion/react";
 import { CodeExample } from "components/CodeExample/CodeExample";
 import { Welcome } from "components/Welcome/Welcome";
-import { useTimeSync } from "hooks/useTimeSync";
+import { useTimeSyncSelect } from "hooks/useTimeSync";
 import type { FC } from "react";
 import { Link as RouterLink } from "react-router-dom";
 
@@ -10,8 +10,9 @@ type CliInstallPageViewProps = {
 };
 
 export const CliInstallPageView: FC<CliInstallPageViewProps> = ({ origin }) => {
-	const year = useTimeSync({
+	const year = useTimeSyncSelect({
 		targetRefreshInterval: Number.POSITIVE_INFINITY,
+		selectDependencies: [],
 		select: (date) => date.getFullYear(),
 	});
 
diff --git a/site/src/pages/LoginPage/LoginPageView.tsx b/site/src/pages/LoginPage/LoginPageView.tsx
@@ -3,7 +3,7 @@ import Button from "@mui/material/Button";
 import type { AuthMethods, BuildInfoResponse } from "api/typesGenerated";
 import { CustomLogo } from "components/CustomLogo/CustomLogo";
 import { Loader } from "components/Loader/Loader";
-import { useTimeSync } from "hooks/useTimeSync";
+import { useTimeSyncSelect } from "hooks/useTimeSync";
 import { type FC, useState } from "react";
 import { useLocation } from "react-router-dom";
 import { SignInForm } from "./SignInForm";
@@ -28,8 +28,9 @@ export const LoginPageView: FC<LoginPageViewProps> = ({
 	onSignIn,
 	redirectTo,
 }) => {
-	const year = useTimeSync({
+	const year = useTimeSyncSelect({
 		targetRefreshInterval: Number.POSITIVE_INFINITY,
+		selectDependencies: [],
 		select: (date) => date.getFullYear(),
 	});
 	const location = useLocation();
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/DateRange.tsx
@@ -17,7 +17,7 @@ import {
 	startOfHour,
 	subDays,
 } from "date-fns";
-import { IDEAL_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
+import { TARGET_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
 import { type ComponentProps, type FC, useRef, useState } from "react";
 import { DateRangePicker, createStaticRanges } from "react-date-range";
 
@@ -44,7 +44,7 @@ interface DateRangeProps {
 
 export const DateRange: FC<DateRangeProps> = ({ value, onChange }) => {
 	const currentTime = useTimeSync({
-		targetRefreshInterval: IDEAL_REFRESH_ONE_MINUTE,
+		targetRefreshInterval: TARGET_REFRESH_ONE_MINUTE,
 	});
 	const selectionStatusRef = useRef<"idle" | "selecting">("idle");
 	const [ranges, setRanges] = useState<RangesState>([
diff --git a/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx b/site/src/pages/TemplatePage/TemplateInsightsPage/TemplateInsightsPage.tsx
@@ -44,7 +44,7 @@ import {
 	subDays,
 } from "date-fns";
 import { useEmbeddedMetadata } from "hooks/useEmbeddedMetadata";
-import { IDEAL_REFRESH_ONE_DAY, useTimeSync } from "hooks/useTimeSync";
+import { TARGET_REFRESH_ONE_DAY, useTimeSyncSelect } from "hooks/useTimeSync";
 import { useTemplateLayoutContext } from "pages/TemplatePage/TemplateLayout";
 import {
 	type FC,
@@ -70,8 +70,8 @@ export default function TemplateInsightsPage() {
 	const [searchParams, setSearchParams] = useSearchParams();
 
 	const paramsInterval = searchParams.get("interval");
-	const insightsInterval = useTimeSync<InsightsInterval>({
-		targetRefreshInterval: IDEAL_REFRESH_ONE_DAY,
+	const insightsInterval = useTimeSyncSelect<InsightsInterval>({
+		targetRefreshInterval: TARGET_REFRESH_ONE_DAY,
 		selectDependencies: [paramsInterval],
 		select: (newDate) => {
 			const templateCreateDate = new Date(template.created_at);
diff --git a/site/src/pages/WorkspacePage/AppStatuses.tsx b/site/src/pages/WorkspacePage/AppStatuses.tsx
@@ -19,7 +19,10 @@ import type {
 } from "api/typesGenerated";
 import { useProxy } from "contexts/ProxyContext";
 import { formatDistance, formatDistanceToNow } from "date-fns";
-import { IDEAL_REFRESH_ONE_MINUTE, useTimeSync } from "hooks/useTimeSync";
+import {
+	TARGET_REFRESH_ONE_MINUTE,
+	useTimeSyncSelect,
+} from "hooks/useTimeSync";
 import type { FC } from "react";
 import { createAppLinkHref } from "utils/apps";
 
@@ -153,8 +156,9 @@ export const AppStatuses: FC<AppStatusesProps> = ({
 	agents,
 	referenceDate,
 }) => {
-	const comparisonDate = useTimeSync({
-		targetRefreshInterval: IDEAL_REFRESH_ONE_MINUTE,
+	const comparisonDate = useTimeSyncSelect({
+		targetRefreshInterval: TARGET_REFRESH_ONE_MINUTE,
+		selectDependencies: [referenceDate],
 		select: (dateState) => referenceDate ?? dateState,
 	});
 	const theme = useTheme();
diff --git a/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx b/site/src/pages/WorkspacePage/WorkspaceScheduleControls.tsx
diff --git a/site/src/utils/TimeSync.ts b/site/src/utils/TimeSync.ts
