@buenos-nachos/time-sync 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @buenos-nachos/time-sync
 
+## 0.5.0
+
+### Breaking Changes
+
+- c3986e9: revamped all state management and APIs to be based on monotonic time
+- c3986e9: Removed `registeredAt` and `intervalLastFulfilledAt` properties from `SubscriptionContext` and added monotonic `registeredAtMs`
+- c3986e9: Added monotonic `lastUpdatedAt` property to `Snapshot` type.
+
+## 0.4.1
+
+### Patch Changes
+
+- 5f37f1a: refactored class to remove private setSnapshost method
+
 ## 0.4.0
 
 ### Breaking Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buenos-nachos/time-sync",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "MIT",
   "type": "module",
   "author": "Michael Smith <hello@nachos.dev> (https://www.nachos.dev)",

package/src/TimeSync.test.ts

@@ -7,7 +7,6 @@ import {
 	type SubscriptionContext,
 	TimeSync,
 } from "./TimeSync";
-import type { Writeable } from "./utilities";
 
 const invalidIntervals: readonly number[] = [
 	Number.NaN,
@@ -132,9 +131,8 @@ describe(TimeSync, () => {
 				const expectedCtx: SubscriptionContext = {
 					unsubscribe,
 					timeSync: sync,
-					intervalLastFulfilledAt: dateAfter,
-					registeredAt: dateBefore,
-					targetRefreshIntervalMs: rate,
+					refreshIntervalMs: rate,
+					registeredAtMs: 0,
 				};
 				expect(onUpdate).toHaveBeenCalledWith(dateAfter, expectedCtx);
 
@@ -588,20 +586,19 @@ describe(TimeSync, () => {
 			expect,
 		}) => {
 			const sync = new TimeSync();
-			const interval = refreshRates.oneMinute;
 
 			let ejectedInterval: number | undefined;
 			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
-				ejectedInterval = ctx.targetRefreshIntervalMs;
+				ejectedInterval = ctx.refreshIntervalMs;
 			});
 
-			void sync.subscribe({
+			sync.subscribe({
 				onUpdate,
-				targetRefreshIntervalMs: interval,
+				targetRefreshIntervalMs: refreshRates.oneMinute,
 			});
 
-			await vi.advanceTimersByTimeAsync(interval);
-			expect(ejectedInterval).toBe(interval);
+			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
+			expect(ejectedInterval).toBe(refreshRates.oneMinute);
 		});
 
 		it("Exposes exact same unsubscribe callback as the one returned from the subscribe call", async ({
@@ -623,48 +620,32 @@ describe(TimeSync, () => {
 			expect(ejectedUnsub).toBe(unsub);
 		});
 
-		it("Exposes when the subscription was first set up", async ({ expect }) => {
+		it("Exposes when the subscription was first set up, relative to the TimeSync instantiation", async ({
+			expect,
+		}) => {
 			const sync = new TimeSync();
-			const start = sync.getStateSnapshot().date;
-
-			let ejectedDate: Date | undefined;
-			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
-				ejectedDate = ctx.registeredAt;
-			});
 
+			let ejectedSetupTime1: number | undefined;
 			void sync.subscribe({
-				onUpdate,
 				targetRefreshIntervalMs: refreshRates.oneMinute,
+				onUpdate: (_, ctx) => {
+					ejectedSetupTime1 = ctx.registeredAtMs;
+				},
 			});
 
 			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
-			expect(ejectedDate).toEqual(start);
-		});
-
-		it("Indicates when the last requested interval was fulfilled", async ({
-			expect,
-		}) => {
-			const sync = new TimeSync();
-
-			const fulfilledValues: (ReadonlyDate | null)[] = [];
-			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
-				fulfilledValues.push(ctx.intervalLastFulfilledAt);
-			});
+			expect(ejectedSetupTime1).toEqual(0);
 
+			let ejectedSetupTime2: number | undefined;
 			void sync.subscribe({
-				onUpdate,
 				targetRefreshIntervalMs: refreshRates.oneMinute,
-			});
-			void sync.subscribe({
-				onUpdate: vi.fn(),
-				targetRefreshIntervalMs: refreshRates.thirtySeconds,
+				onUpdate: (_, ctx) => {
+					ejectedSetupTime2 = ctx.registeredAtMs;
+				},
 			});
 
 			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
-			const snapAfter = sync.getStateSnapshot().date;
-
-			expect(onUpdate).toHaveBeenCalledTimes(2);
-			expect(fulfilledValues).toEqual([null, snapAfter]);
+			expect(ejectedSetupTime2).toEqual(refreshRates.oneMinute);
 		});
 	});
 
@@ -782,45 +763,45 @@ describe(TimeSync, () => {
 			expect,
 		}) => {
 			const sync = new TimeSync();
-			const snapBefore = sync.getStateSnapshot().date;
 
 			let ejectedContext: SubscriptionContext | undefined;
 			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
 				ejectedContext = ctx;
 			});
 
+			// Registering all three with the exact same callback. That way, if either
+			// of the others get processed, their contexts should overwrite the
+			// ejected context and make the tests fail
 			const unsub = sync.subscribe({
 				onUpdate,
 				targetRefreshIntervalMs: refreshRates.oneHour,
 			});
-			void sync.subscribe({
+			sync.subscribe({
 				onUpdate,
 				targetRefreshIntervalMs: refreshRates.oneMinute,
 			});
-			void sync.subscribe({
+			sync.subscribe({
 				onUpdate,
 				targetRefreshIntervalMs: refreshRates.oneSecond,
 			});
 
 			await vi.advanceTimersByTimeAsync(refreshRates.oneSecond);
 			expect(ejectedContext).toEqual<SubscriptionContext>({
-				intervalLastFulfilledAt: null,
-				registeredAt: snapBefore,
-				targetRefreshIntervalMs: refreshRates.oneHour,
+				refreshIntervalMs: refreshRates.oneHour,
 				timeSync: sync,
 				unsubscribe: unsub,
+				registeredAtMs: 0,
 			});
 
-			const remainingSecondsToOneHour = refreshRates.oneHour - 1000;
+			const remainingSecondsToOneHour =
+				refreshRates.oneHour - refreshRates.oneSecond;
 			await vi.advanceTimersByTimeAsync(remainingSecondsToOneHour);
 
-			const snapAfter = sync.getStateSnapshot().date;
 			expect(ejectedContext).toEqual<SubscriptionContext>({
-				intervalLastFulfilledAt: snapAfter,
-				registeredAt: snapBefore,
-				targetRefreshIntervalMs: refreshRates.oneHour,
+				refreshIntervalMs: refreshRates.oneHour,
 				timeSync: sync,
 				unsubscribe: unsub,
+				registeredAtMs: 0,
 			});
 		});
 	});
@@ -841,6 +822,7 @@ describe(TimeSync, () => {
 			expect(snap).toEqual<Snapshot>({
 				date: initialDate,
 				subscriberCount: 0,
+				lastUpdatedAtMs: null,
 				config: {
 					freezeUpdates: false,
 					minimumRefreshIntervalMs,
@@ -971,6 +953,7 @@ describe(TimeSync, () => {
 
 			// We have readonly modifiers on the types, but we need to make sure
 			// nothing can break at runtime
+			type Writeable<T> = { -readonly [Key in keyof T]: T[Key] };
 			const snap = sync.getStateSnapshot() as Writeable<Snapshot>;
 			const config = snap.config as Writeable<Configuration>;
 			const copyBeforeMutations = { ...snap, config: { ...config } };
@@ -978,6 +961,7 @@ describe(TimeSync, () => {
 			const mutationSource: Snapshot = {
 				date: new ReadonlyDate("April 1, 1970"),
 				subscriberCount: Number.POSITIVE_INFINITY,
+				lastUpdatedAtMs: 1_000_000,
 				config: {
 					freezeUpdates: true,
 					minimumRefreshIntervalMs: Number.POSITIVE_INFINITY,
@@ -989,6 +973,9 @@ describe(TimeSync, () => {
 				() => {
 					snap.date = mutationSource.date;
 				},
+				() => {
+					snap.lastUpdatedAtMs = mutationSource.lastUpdatedAtMs;
+				},
 				() => {
 					snap.subscriberCount = mutationSource.subscriberCount;
 				},
@@ -1071,7 +1058,7 @@ describe(TimeSync, () => {
 	 * Not sure how to codify that in tests yet, but ideally it should be.
 	 */
 	describe("Freezing updates on init", () => {
-		it("Never updates internal state, no matter how many subscribers subscribe", ({
+		it("Always updates internal state to reflect subscription count", async ({
 			expect,
 		}) => {
 			const initialDate = new Date("August 25, 1832");
@@ -1085,8 +1072,9 @@ describe(TimeSync, () => {
 				});
 			}
 
+			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
 			const snap = sync.getStateSnapshot();
-			expect(snap.subscriberCount).toBe(0);
+			expect(snap.subscriberCount).toBe(1000);
 			expect(snap.date).toEqual(initialDate);
 		});
 	});
@@ -1216,30 +1204,29 @@ describe(TimeSync, () => {
 			expect(snap3).toBe(0);
 		});
 
-		it("Lets consumers detect whether an update corresponds to the subscription they explicitly set up", async ({
+		it("Does not break update cadence if system time jumps around", async ({
 			expect,
 		}) => {
-			const sync = new TimeSync();
-			const innerOnUpdate = vi.fn();
+			const initialDate = setInitialTime("2022-03-15T08:00:00Z");
+			const sync = new TimeSync({ initialDate });
+			const thirtyMinutes = 30 * refreshRates.oneMinute;
 
-			void sync.subscribe({
-				targetRefreshIntervalMs: refreshRates.oneMinute,
-				onUpdate: (date, ctx) => {
-					const intervalMatches =
-						date.getTime() === ctx.intervalLastFulfilledAt?.getTime();
-					if (intervalMatches) {
-						innerOnUpdate();
-					}
-				},
-			});
+			const onUpdate = vi.fn();
+			sync.subscribe({ onUpdate, targetRefreshIntervalMs: thirtyMinutes });
 
-			void sync.subscribe({
-				targetRefreshIntervalMs: refreshRates.thirtySeconds,
-				onUpdate: vi.fn(),
-			});
+			await vi.advanceTimersByTimeAsync(thirtyMinutes);
+			expect(onUpdate).toHaveBeenCalledTimes(1);
 
-			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
-			expect(innerOnUpdate).toHaveBeenCalledTimes(1);
+			// Go one hour into the past and then advance 30 minutes to go back to
+			// where we started
+			vi.setSystemTime("2022-03-15T07:30:00Z");
+			await vi.advanceTimersByTimeAsync(thirtyMinutes);
+			expect(onUpdate).toHaveBeenCalledTimes(2);
+
+			// Go one day into the past and then advance another 30 minutes
+			vi.setSystemTime("2022-03-14T08:00:00Z");
+			await vi.advanceTimersByTimeAsync(thirtyMinutes);
+			expect(onUpdate).toHaveBeenCalledTimes(3);
 		});
 	});
 });

package/src/TimeSync.ts

@@ -1,5 +1,4 @@
 import { ReadonlyDate } from "./ReadonlyDate";
-import type { Writeable } from "./utilities";
 
 /**
  * A collection of commonly-needed intervals (all defined in milliseconds).
@@ -118,6 +117,14 @@ export interface Snapshot {
 	 */
 	readonly date: ReadonlyDate;
 
+	/**
+	 * The monotonic milliseconds that elapsed between the TimeSync being
+	 * instantiated and the last update being dispatched.
+	 *
+	 * Will be null if no updates have ever been dispatched.
+	 */
+	readonly lastUpdatedAtMs: number | null;
+
 	/**
 	 * The number of subscribers registered with TimeSync.
 	 */
@@ -132,44 +139,33 @@ export interface Snapshot {
 
 /**
  * An object with information about a specific subscription registered with
- * TimeSync.
- *
- * For performance reasons, this object has ZERO readonly guarantees enforced at
- * runtime. All properties are defined as readonly at the type level, but an
- * accidental mutation can still slip through.
+ * TimeSync. The entire context is frozen at runtime.
  */
 export interface SubscriptionContext {
 	/**
-	 * The interval that the subscription was registered with.
-	 */
-	readonly targetRefreshIntervalMs: number;
-
-	/**
-	 * The unsubscribe callback associated with a subscription. This is the same
-	 * callback returned by `TimeSync.subscribe`.
+	 * A reference to the TimeSync instance that the subscription was registered
+	 * with.
 	 */
-	readonly unsubscribe: () => void;
+	readonly timeSync: TimeSync;
 
 	/**
-	 * A timestamp of when the subscription was first set up.
+	 * The effective interval that the subscription is updating at. This may be a
+	 * value larger than than the target refresh interval, depending on whether
+	 * TimeSync was configured with a minimum refresh value.
 	 */
-	readonly registeredAt: ReadonlyDate;
+	readonly refreshIntervalMs: number;
 
 	/**
-	 * A reference to the TimeSync instance that the subscription was registered
-	 * with.
+	 * The unsubscribe callback associated with a subscription. This is the same
+	 * callback returned by `TimeSync.subscribe`.
 	 */
-	readonly timeSync: TimeSync;
+	readonly unsubscribe: () => void;
 
 	/**
-	 * Indicates when the last time the subscription had its explicit interval
-	 * "satisfied".
-	 *
-	 * For example, if a subscription is registered for every five minutes, but
-	 * the active interval is set to fire every second, you may need to know
-	 * which update actually happened five minutes later.
+	 * The monotonic milliseconds that elapsed between the TimeSync being
+	 * instantiated and the subscription being registered.
 	 */
-	readonly intervalLastFulfilledAt: ReadonlyDate | null;
+	readonly registeredAtMs: number;
 }
 
 /**
@@ -226,9 +222,47 @@ interface TimeSyncApi {
 	clearAll: () => void;
 }
 
-/* biome-ignore lint:suspicious/noEmptyBlockStatements -- Rare case where we do
-   actually want a completely empty function body. */
-function noOp(..._: readonly unknown[]): void {}
+/**
+ * Even though both the browser and the server are able to give monotonic times
+ * that are at least as precise as a nanosecond, we're using milliseconds for
+ * consistency with useInterval, which cannot be more precise than a
+ * millisecond.
+ */
+function getMonotonicTimeMs(): number {
+	// If we're on the server, we can use process.hrtime, which is defined for
+	// Node, Deno, and Bun
+	if (typeof window === "undefined") {
+		const timeInNanoseconds = process.hrtime.bigint();
+		return Number(timeInNanoseconds / 1000n);
+	}
+
+	// Otherwise, we need to get the high-resolution timestamp from the browser.
+	// This value is fractional and goes to nine decimal places
+	const highResTimestamp = window.performance.now();
+	return Math.floor(highResTimestamp);
+}
+
+/**
+ * This function is just a convenience for us to sidestep some problems around
+ * TypeScript's LSP and Object.freeze. Because Object.freeze can accept any
+ * arbitrary type, it basically acts as a "type boundary" between the left and
+ * right sides of any snapshot assignments.
+ *
+ * That means that if you rename a property a a value that is passed to
+ * Object.freeze, the LSP can't auto-rename it, and you potentially get missing
+ * properties. This is a bit hokey, but because the function is defined strictly
+ * in terms of concrete snapshots, any value passed to this function won't have
+ * to worry about mismatches.
+ */
+function freezeSnapshot(snap: Snapshot): Snapshot {
+	if (!Object.isFrozen(snap.config)) {
+		Object.freeze(snap.config);
+	}
+	if (!Object.isFrozen(snap)) {
+		Object.freeze(snap);
+	}
+	return snap;
+}
 
 const defaultMinimumRefreshIntervalMs = 200;
 
@@ -268,6 +302,12 @@ const defaultMinimumRefreshIntervalMs = 200;
  * some parts of the screen.)
  */
 export class TimeSync implements TimeSyncApi {
+	/**
+	 * The monotonic time in milliseconds from when the TimeSync instance was
+	 * first instantiated.
+	 */
+	readonly #initializedAtMs: number;
+
 	/**
 	 * Stores all refresh intervals actively associated with an onUpdate
 	 * callback (along with their associated unsubscribe callbacks).
@@ -316,7 +356,8 @@ export class TimeSync implements TimeSyncApi {
 
 	/**
 	 * Used for both its intended purpose (creating interval), but also as a
-	 * janky version of setTimeout.
+	 * janky version of setTimeout. Also, all versions of setInterval are
+	 * monotonic, so we don't have to do anything special for it.
 	 *
 	 * There are a few times when we need timeout-like logic, but if we use
 	 * setInterval for everything, we have fewer IDs to juggle, and less risk of
@@ -348,64 +389,44 @@ export class TimeSync implements TimeSyncApi {
 		this.#subscriptions = new Map();
 		this.#fastestRefreshInterval = Number.POSITIVE_INFINITY;
 		this.#intervalId = undefined;
+		this.#initializedAtMs = getMonotonicTimeMs();
+
+		let date: ReadonlyDate;
+		if (initialDate instanceof ReadonlyDate) {
+			date = initialDate;
+		} else if (initialDate instanceof Date) {
+			date = new ReadonlyDate(initialDate);
+		} else {
+			date = new ReadonlyDate();
+		}
 
-		// Not defined inline to avoid wonkiness that Object.freeze introduces
-		// when you rename a property on a frozen object
-		const initialSnapshot: Snapshot = {
+		this.#latestSnapshot = freezeSnapshot({
+			date,
 			subscriberCount: 0,
-			date: initialDate ? new ReadonlyDate(initialDate) : new ReadonlyDate(),
-			config: Object.freeze({
+			lastUpdatedAtMs: null,
+			config: {
 				freezeUpdates,
 				minimumRefreshIntervalMs,
 				allowDuplicateOnUpdateCalls,
-			}),
-		};
-		this.#latestSnapshot = Object.freeze(initialSnapshot);
-	}
-
-	#setSnapshot(update: Partial<Snapshot>): boolean {
-		const { date, subscriberCount, config } = this.#latestSnapshot;
-		if (config.freezeUpdates) {
-			return false;
-		}
-
-		// Avoiding both direct property assignment or spread syntax because
-		// Object.freeze causes weird TypeScript LSP issues around assignability
-		// where trying to rename a property. If you rename a property on a
-		// type, it WON'T rename the runtime properties. Object.freeze
-		// introduces an extra type boundary that break the linking
-		const updated: Snapshot = {
-			// Always reject any new configs because trying to remove them at
-			// the type level isn't worth it for an internal implementation
-			// detail
-			config,
-			date: update.date ?? date,
-			subscriberCount: update.subscriberCount ?? subscriberCount,
-		};
-
-		this.#latestSnapshot = Object.freeze(updated);
-		return true;
+			},
+		});
 	}
 
 	#notifyAllSubscriptions(): void {
 		// It's more important that we copy the date object into a separate
 		// variable here than normal, because need make sure the `this` context
 		// can't magically change between updates and cause subscribers to
-		// receive different values (e.g., one of the subscribers calls the
-		// invalidate method)
+		// receive different values
 		const { date, config } = this.#latestSnapshot;
 
-		// We still need to let the logic go through if the current fastest
-		// interval is Infinity, so that we can support letting any arbitrary
-		// consumer invalidate the date immediately
 		const subscriptionsPaused =
-			config.freezeUpdates || this.#subscriptions.size === 0;
+			config.freezeUpdates ||
+			this.#subscriptions.size === 0 ||
+			this.#fastestRefreshInterval === Number.POSITIVE_INFINITY;
 		if (subscriptionsPaused) {
 			return;
 		}
 
-		const dateTime = date.getTime();
-
 		/**
 		 * Two things:
 		 * 1. Even though the context arrays are defined as readonly (which
@@ -425,32 +446,20 @@ export class TimeSync implements TimeSyncApi {
 		 * to check on each iteration to see if we should continue.
 		 */
 		const subsBeforeUpdate = this.#subscriptions;
-		const entries = Array.from(subsBeforeUpdate);
-		outer: for (const [onUpdate, subs] of entries) {
-			// Even if duplicate onUpdate calls are disabled, we still need to
-			// iterate through everything and update any internal data. If the
-			// first context in a sub array gets removed by unsubscribing, we
-			// want what was the the second element to still be up to date
-			let shouldCallOnUpdate = true;
-			for (const ctx of subs as readonly Writeable<SubscriptionContext>[]) {
+		const localEntries = Array.from(subsBeforeUpdate);
+		outer: for (const [onUpdate, subs] of localEntries) {
+			for (const ctx of subs) {
 				// We're not doing anything more sophisticated here because
 				// we're assuming that any systems that can clear out the
 				// subscriptions will handle cleaning up each context, too
-				const wasCleared = subsBeforeUpdate.size === 0;
-				if (wasCleared) {
+				const wasClearedBetweenUpdates = subsBeforeUpdate.size === 0;
+				if (wasClearedBetweenUpdates) {
 					break outer;
 				}
 
-				const comparisonDate = ctx.intervalLastFulfilledAt ?? ctx.registeredAt;
-				const isIntervalMatch =
-					dateTime - comparisonDate.getTime() >= ctx.targetRefreshIntervalMs;
-				if (isIntervalMatch) {
-					ctx.intervalLastFulfilledAt = date;
-				}
-
-				if (shouldCallOnUpdate) {
-					onUpdate(date, ctx);
-					shouldCallOnUpdate = config.allowDuplicateOnUpdateCalls;
+				onUpdate(date, ctx);
+				if (!config.allowDuplicateOnUpdateCalls) {
+					continue outer;
 				}
 			}
 		}
@@ -465,56 +474,65 @@ export class TimeSync implements TimeSyncApi {
 	 * is one of them.
 	 */
 	readonly #onTick = (): void => {
-		// Defensive step to make sure that an invalid tick wasn't started
 		const { config } = this.#latestSnapshot;
 		if (config.freezeUpdates) {
+			// Defensive step to make sure that an invalid tick wasn't started
 			clearInterval(this.#intervalId);
 			this.#intervalId = undefined;
 			return;
 		}
 
-		const wasChanged = this.#setSnapshot({ date: new ReadonlyDate() });
-		if (wasChanged) {
-			this.#notifyAllSubscriptions();
-		}
+		// onTick is expected to be called in response to monotonic time changes
+		// (either from calculating them manually to decide when to call onTick
+		// synchronously or from letting setInterval handle the calls). So while
+		// this edge case should basically be impossible, we need to make sure that
+		// we always dispatch a date, even if its time is exactly the same.
+		this.#latestSnapshot = freezeSnapshot({
+			...this.#latestSnapshot,
+			date: new ReadonlyDate(),
+			lastUpdatedAtMs: getMonotonicTimeMs() - this.#initializedAtMs,
+		});
+		this.#notifyAllSubscriptions();
 	};
 
 	#onFastestIntervalChange(): void {
 		const fastest = this.#fastestRefreshInterval;
-		const { date, config } = this.#latestSnapshot;
+		const { lastUpdatedAtMs, config } = this.#latestSnapshot;
+
 		const updatesShouldStop =
-			config.freezeUpdates || fastest === Number.POSITIVE_INFINITY;
+			config.freezeUpdates ||
+			this.#subscriptions.size === 0 ||
+			fastest === Number.POSITIVE_INFINITY;
 		if (updatesShouldStop) {
 			clearInterval(this.#intervalId);
 			this.#intervalId = undefined;
 			return;
 		}
 
-		const elapsed = Date.now() - date.getTime();
+		const newTime = getMonotonicTimeMs();
+		const elapsed = newTime - (lastUpdatedAtMs ?? this.#initializedAtMs);
 		const timeBeforeNextUpdate = fastest - elapsed;
 
-		// Clear previous interval sight unseen just to be on the safe side
+		// Clear previous interval no matter what just to be on the safe side
 		clearInterval(this.#intervalId);
 
 		if (timeBeforeNextUpdate <= 0) {
-			const wasChanged = this.#setSnapshot({ date: new ReadonlyDate() });
-			if (wasChanged) {
-				this.#notifyAllSubscriptions();
-			}
+			this.#onTick();
 			this.#intervalId = setInterval(this.#onTick, fastest);
 			return;
 		}
 
 		// Most common case for this branch is the very first subscription
 		// getting added, but there's still the small chance that the fastest
-		// interval could change right after an update got flushed
+		// interval could change right after an update got flushed, so there would
+		// be zero elapsed time to worry about
 		if (timeBeforeNextUpdate === fastest) {
 			this.#intervalId = setInterval(this.#onTick, timeBeforeNextUpdate);
 			return;
 		}
 
-		// Otherwise, use interval as pseudo-timeout, and then go back to using
-		// it as a normal interval afterwards
+		// Otherwise, use setInterval as pseudo-timeout to resolve the remaining
+		// time as a one-time update, and then go back to using normal intervals
 		this.#intervalId = setInterval(() => {
 			clearInterval(this.#intervalId);
 
@@ -535,14 +553,13 @@ export class TimeSync implements TimeSyncApi {
 			return;
 		}
 
-		const prevFastest = this.#fastestRefreshInterval;
-		let newFastest = Number.POSITIVE_INFINITY;
-
 		// This setup requires that every interval array stay sorted. It
 		// immediately falls apart if this isn't guaranteed.
-		for (const entries of this.#subscriptions.values()) {
+		const prevFastest = this.#fastestRefreshInterval;
+		let newFastest = Number.POSITIVE_INFINITY;
+		for (const contexts of this.#subscriptions.values()) {
 			const subFastest =
-				entries[0]?.targetRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
+				contexts[0]?.refreshIntervalMs ?? Number.POSITIVE_INFINITY;
 			if (subFastest < newFastest) {
 				newFastest = subFastest;
 			}
@@ -555,14 +572,10 @@ export class TimeSync implements TimeSyncApi {
 	}
 
 	subscribe(options: SubscriptionInitOptions): () => void {
-		const { config } = this.#latestSnapshot;
-		if (config.freezeUpdates) {
-			return noOp;
-		}
-
 		// Destructuring properties so that they can't be fiddled with after
 		// this function call ends
 		const { targetRefreshIntervalMs, onUpdate } = options;
+		const { minimumRefreshIntervalMs } = this.#latestSnapshot.config;
 
 		const isTargetValid =
 			targetRefreshIntervalMs === Number.POSITIVE_INFINITY ||
@@ -574,77 +587,80 @@ export class TimeSync implements TimeSyncApi {
 			);
 		}
 
-		// Have to define this as a writeable to avoid a chicken-and-the-egg
-		// problem for the unsubscribe callback
-		const context: Writeable<SubscriptionContext> = {
+		const subsOnSetup = this.#subscriptions;
+		let subscribed = true;
+		const ctx: SubscriptionContext = {
 			timeSync: this,
-			unsubscribe: noOp,
-			registeredAt: new ReadonlyDate(),
-			intervalLastFulfilledAt: null,
-			targetRefreshIntervalMs: Math.max(
-				config.minimumRefreshIntervalMs,
+			registeredAtMs: getMonotonicTimeMs() - this.#initializedAtMs,
+			refreshIntervalMs: Math.max(
+				minimumRefreshIntervalMs,
 				targetRefreshIntervalMs,
 			),
-		};
 
-		// Not reading from context value to decide whether to bail out of
-		// unsubscribes in off chance that outside consumer accidentally mutates
-		// the value
-		let subscribed = true;
-		const subsOnSetup = this.#subscriptions;
-		const unsubscribe = (): void => {
-			if (!subscribed || this.#subscriptions !== subsOnSetup) {
-				subscribed = false;
-				return;
-			}
-
-			const contexts = subsOnSetup.get(onUpdate);
-			if (contexts === undefined) {
-				return;
-			}
-			const filtered = contexts.filter((e) => e.unsubscribe !== unsubscribe);
-			if (filtered.length === contexts.length) {
-				return;
-			}
-
-			if (filtered.length === 0) {
-				subsOnSetup.delete(onUpdate);
-				this.#updateFastestInterval();
-			} else {
-				// No need to sort on removal because everything gets sorted as
-				// it enters the subscriptions map
-				subsOnSetup.set(onUpdate, filtered);
-			}
-
-			void this.#setSnapshot({
-				subscriberCount: Math.max(0, this.#latestSnapshot.subscriberCount - 1),
-			});
-
-			subscribed = false;
+			unsubscribe: () => {
+				// Not super conventional, but basically using try/finally as a form of
+				// Go's defer. There are a lot of branches we need to worry about for
+				// the unsubscribe callback, and we need to make sure we flip subscribed
+				// to false after each one
+				try {
+					if (!subscribed || this.#subscriptions !== subsOnSetup) {
+						return;
+					}
+					const contexts = subsOnSetup.get(onUpdate);
+					if (contexts === undefined) {
+						return;
+					}
+					const filtered = contexts.filter(
+						(c) => c.unsubscribe !== ctx.unsubscribe,
+					);
+					if (filtered.length === contexts.length) {
+						return;
+					}
+
+					const dropped = Math.max(0, this.#latestSnapshot.subscriberCount - 1);
+					this.#latestSnapshot = freezeSnapshot({
+						...this.#latestSnapshot,
+						subscriberCount: dropped,
+					});
+
+					if (filtered.length > 0) {
+						// No need to sort on removal because everything gets sorted as
+						// it enters the subscriptions map
+						subsOnSetup.set(onUpdate, filtered);
+					} else {
+						subsOnSetup.delete(onUpdate);
+					}
+
+					this.#updateFastestInterval();
+				} finally {
+					subscribed = false;
+				}
+			},
 		};
-		context.unsubscribe = unsubscribe;
-
-		let contexts: SubscriptionContext[];
-		if (this.#subscriptions.has(onUpdate)) {
-			const prev = this.#subscriptions.get(onUpdate) as SubscriptionContext[];
-			contexts = [...prev];
+		Object.freeze(ctx);
+
+		// We need to make sure that each array for tracking subscriptions is
+		// readonly, and because dispatching updates should be far more common than
+		// adding subscriptions, we're placing the immutable copying here to
+		// minimize overall pressure on the system.
+		let newContexts: SubscriptionContext[];
+		const prevContexts = subsOnSetup.get(onUpdate);
+		if (prevContexts !== undefined) {
+			newContexts = [...prevContexts, ctx];
 		} else {
-			contexts = [];
-			subsOnSetup.set(onUpdate, contexts);
+			newContexts = [ctx];
 		}
 
-		subsOnSetup.set(onUpdate, contexts);
-		contexts.push(context);
-		contexts.sort(
-			(e1, e2) => e1.targetRefreshIntervalMs - e2.targetRefreshIntervalMs,
-		);
+		subsOnSetup.set(onUpdate, newContexts);
+		newContexts.sort((c1, c2) => c1.refreshIntervalMs - c2.refreshIntervalMs);
 
-		void this.#setSnapshot({
+		this.#latestSnapshot = freezeSnapshot({
+			...this.#latestSnapshot,
 			subscriberCount: this.#latestSnapshot.subscriberCount + 1,
 		});
 
 		this.#updateFastestInterval();
-		return unsubscribe;
+		return ctx.unsubscribe;
 	}
 
 	getStateSnapshot(): Snapshot {
@@ -664,6 +680,10 @@ export class TimeSync implements TimeSyncApi {
 		// We swap the map out so that the unsubscribe callbacks can detect
 		// whether their functionality is still relevant
 		this.#subscriptions = new Map();
-		void this.#setSnapshot({ subscriberCount: 0 });
+
+		this.#latestSnapshot = freezeSnapshot({
+			...this.#latestSnapshot,
+			subscriberCount: 0,
+		});
 	}
 }

package/src/utilities.ts

@@ -1 +0,0 @@
-export type Writeable<T> = { -readonly [Key in keyof T]: T[Key] };