@buenos-nachos/time-sync 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @buenos-nachos/time-sync
 
+## 0.3.0
+
+### Minor Changes
+
+- 122f6c1: Updated `SubscriptionContext.timeSync` type to be readonly and non-nullable, and renamed `SubscriptionContext.isLive` to `SubscriptionContext.isSubscribed`.
+
+## 0.2.0
+
+### Breaking Changes
+
+- 2f527dd: Changed the default value of `allowDuplicateFunctionCalls` from `false` to `true`
+
+### Minor Changes
+
+- 5f86fac: Added second parameter to `onUpdate` callback. This value is a value of type `SubscriptionContext` and provides information about the current subscription.
+
 ## 0.1.2
 
 ### Patch Changes

package/package.json

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

package/src/TimeSync.test.ts

@@ -4,8 +4,10 @@ import {
 	type Configuration,
 	refreshRates,
 	type Snapshot,
+	type SubscriptionContext,
 	TimeSync,
 } from "./TimeSync";
+import type { Writeable } from "./utilities";
 
 const invalidIntervals: readonly number[] = [
 	Number.NaN,
@@ -116,17 +118,26 @@ describe(TimeSync, () => {
 				const sync = new TimeSync();
 				const onUpdate = vi.fn();
 
-				void sync.subscribe({
+				const dateBefore = sync.getStateSnapshot().date;
+				const unsubscribe = sync.subscribe({
 					onUpdate,
 					targetRefreshIntervalMs: rate,
 				});
 				expect(onUpdate).not.toHaveBeenCalled();
 
-				const dateBefore = sync.getStateSnapshot().date;
 				await vi.advanceTimersByTimeAsync(rate);
 				const dateAfter = sync.getStateSnapshot().date;
 				expect(onUpdate).toHaveBeenCalledTimes(1);
-				expect(onUpdate).toHaveBeenCalledWith(dateAfter);
+
+				const expectedCtx: SubscriptionContext = {
+					unsubscribe,
+					isSubscribed: true,
+					timeSync: sync,
+					intervalLastFulfilledAt: dateAfter,
+					registeredAt: dateBefore,
+					targetRefreshIntervalMs: rate,
+				};
+				expect(onUpdate).toHaveBeenCalledWith(dateAfter, expectedCtx);
 
 				const diff = dateAfter.getTime() - dateBefore.getTime();
 				expect(diff).toBe(rate);
@@ -171,7 +182,7 @@ describe(TimeSync, () => {
 		it("Always dispatches updates in the order that callbacks were first registered", async ({
 			expect,
 		}) => {
-			const sync = new TimeSync();
+			const sync = new TimeSync({ allowDuplicateOnUpdateCalls: false });
 			const callOrder: number[] = [];
 
 			const onUpdate1 = vi.fn(() => {
@@ -260,7 +271,7 @@ describe(TimeSync, () => {
 			expect(secondOnUpdate).toHaveBeenCalledTimes(1);
 		});
 
-		it("Calls onUpdate callback one time total if callback is registered multiple times for the same time interval", async ({
+		it("Calls onUpdate callback once for each subscription (even if the same callback was registered multiple times)", async ({
 			expect,
 		}) => {
 			const sync = new TimeSync();
@@ -274,59 +285,7 @@ describe(TimeSync, () => {
 			}
 
 			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
-			expect(sharedOnUpdate).toHaveBeenCalledTimes(1);
-		});
-
-		it("Calls onUpdate callback one time total if callback is registered multiple times for different time intervals", async ({
-			expect,
-		}) => {
-			const sync = new TimeSync();
-			const sharedOnUpdate = vi.fn();
-
-			void sync.subscribe({
-				onUpdate: sharedOnUpdate,
-				targetRefreshIntervalMs: refreshRates.oneHour,
-			});
-			void sync.subscribe({
-				onUpdate: sharedOnUpdate,
-				targetRefreshIntervalMs: refreshRates.oneMinute,
-			});
-			void sync.subscribe({
-				onUpdate: sharedOnUpdate,
-				targetRefreshIntervalMs: refreshRates.oneSecond,
-			});
-
-			// Testing like this to ensure that for really, really long spans of
-			// time, the no duplicated calls logic still holds up
-			await vi.advanceTimersByTimeAsync(refreshRates.oneHour);
-			const secondsInOneHour = 3600;
-			expect(sharedOnUpdate).toHaveBeenCalledTimes(secondsInOneHour);
-		});
-
-		it("Calls onUpdate callback one time total if callback is registered multiple times with a mix of redundant/different intervals", async ({
-			expect,
-		}) => {
-			const sync = new TimeSync();
-			const sharedOnUpdate = vi.fn();
-
-			for (let i = 0; i < 10; i++) {
-				void sync.subscribe({
-					onUpdate: sharedOnUpdate,
-					targetRefreshIntervalMs: refreshRates.oneHour,
-				});
-				void sync.subscribe({
-					onUpdate: sharedOnUpdate,
-					targetRefreshIntervalMs: refreshRates.oneMinute,
-				});
-				void sync.subscribe({
-					onUpdate: sharedOnUpdate,
-					targetRefreshIntervalMs: refreshRates.oneSecond,
-				});
-			}
-
-			await vi.advanceTimersByTimeAsync(refreshRates.oneHour);
-			const secondsInOneHour = 3600;
-			expect(sharedOnUpdate).toHaveBeenCalledTimes(secondsInOneHour);
+			expect(sharedOnUpdate).toHaveBeenCalledTimes(3);
 		});
 
 		it("Lets an external system unsubscribe", async ({ expect }) => {
@@ -405,7 +364,7 @@ describe(TimeSync, () => {
 			const snap2 = sync.getStateSnapshot();
 			expect(snap2.subscriberCount).toBe(30);
 			await vi.advanceTimersByTimeAsync(refreshRates.oneSecond);
-			expect(sharedOnUpdate).toHaveBeenCalledTimes(1);
+			expect(sharedOnUpdate).toHaveBeenCalledTimes(30);
 		});
 
 		it("Speeds up interval when new subscriber is added that is faster than all other subscribers", async ({
@@ -604,6 +563,132 @@ describe(TimeSync, () => {
 			const dateAfter = sync.getStateSnapshot().date;
 			expect(dateAfter).not.toEqual(dateBefore);
 		});
+
+		it("Mutates the isLive context value to be false on unsubscribe", async ({
+			expect,
+		}) => {
+			const sync = new TimeSync();
+
+			let ejectedContext: SubscriptionContext | undefined;
+			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
+				ejectedContext = ctx;
+			});
+
+			const unsub = sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: refreshRates.oneMinute,
+			});
+
+			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
+			expect(ejectedContext?.isSubscribed).toBe(true);
+
+			unsub();
+			expect(ejectedContext?.isSubscribed).toBe(false);
+		});
+	});
+
+	describe("Subscriptions: context values", () => {
+		it("Defaults to exposing the TimeSync instance the subscription was registered with", async ({
+			expect,
+		}) => {
+			const sync = new TimeSync();
+
+			let ejectedSync: TimeSync | null = null;
+			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
+				ejectedSync = ctx.timeSync;
+			});
+
+			void sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: refreshRates.oneMinute,
+			});
+
+			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
+			expect(ejectedSync).toBe(sync);
+		});
+
+		it("Exposes refresh interval used on initialization", async ({
+			expect,
+		}) => {
+			const sync = new TimeSync();
+			const interval = refreshRates.oneMinute;
+
+			let ejectedInterval: number | undefined;
+			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
+				ejectedInterval = ctx.targetRefreshIntervalMs;
+			});
+
+			void sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: interval,
+			});
+
+			await vi.advanceTimersByTimeAsync(interval);
+			expect(ejectedInterval).toBe(interval);
+		});
+
+		it("Exposes exact same unsubscribe callback as the one returned from the subscribe call", async ({
+			expect,
+		}) => {
+			const sync = new TimeSync();
+
+			let ejectedUnsub: (() => void) | undefined;
+			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
+				ejectedUnsub = ctx.unsubscribe;
+			});
+
+			const unsub = sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: refreshRates.oneMinute,
+			});
+
+			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
+			expect(ejectedUnsub).toBe(unsub);
+		});
+
+		it("Exposes when the subscription was first set up", 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;
+			});
+
+			void sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: refreshRates.oneMinute,
+			});
+
+			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);
+			});
+
+			void sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: refreshRates.oneMinute,
+			});
+			void sync.subscribe({
+				onUpdate: vi.fn(),
+				targetRefreshIntervalMs: refreshRates.thirtySeconds,
+			});
+
+			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
+			const snapAfter = sync.getStateSnapshot().date;
+
+			expect(onUpdate).toHaveBeenCalledTimes(2);
+			expect(fulfilledValues).toEqual([null, snapAfter]);
+		});
 	});
 
 	describe("Subscriptions: custom `minimumRefreshIntervalMs` value", () => {
@@ -646,11 +731,14 @@ describe(TimeSync, () => {
 		});
 	});
 
-	describe("Subscriptions: duplicating function calls", () => {
-		it("Defaults to de-duplicating", async ({ expect }) => {
-			const sync = new TimeSync();
+	describe("Subscriptions: turning off duplicate function calls", () => {
+		it("Calls onUpdate callback once for each subscription (even if the same callback was registered multiple times)", async ({
+			expect,
+		}) => {
+			const sync = new TimeSync({ allowDuplicateOnUpdateCalls: false });
 			const sharedOnUpdate = vi.fn();
-			for (let i = 0; i < 100; i++) {
+
+			for (let i = 1; i <= 3; i++) {
 				void sync.subscribe({
 					onUpdate: sharedOnUpdate,
 					targetRefreshIntervalMs: refreshRates.oneMinute,
@@ -661,21 +749,104 @@ describe(TimeSync, () => {
 			expect(sharedOnUpdate).toHaveBeenCalledTimes(1);
 		});
 
-		it("Lets user turn on duplication", async ({ expect }) => {
-			const sync = new TimeSync({
-				allowDuplicateOnUpdateCalls: true,
+		it("Calls onUpdate callback one time total if callback is registered multiple times for different time intervals", async ({
+			expect,
+		}) => {
+			const sync = new TimeSync({ allowDuplicateOnUpdateCalls: false });
+			const sharedOnUpdate = vi.fn();
+
+			void sync.subscribe({
+				onUpdate: sharedOnUpdate,
+				targetRefreshIntervalMs: refreshRates.oneHour,
+			});
+			void sync.subscribe({
+				onUpdate: sharedOnUpdate,
+				targetRefreshIntervalMs: refreshRates.oneMinute,
+			});
+			void sync.subscribe({
+				onUpdate: sharedOnUpdate,
+				targetRefreshIntervalMs: refreshRates.oneSecond,
 			});
 
+			// Testing like this to ensure that for really, really long spans of
+			// time, the no duplicated calls logic still holds up
+			await vi.advanceTimersByTimeAsync(refreshRates.oneHour);
+			const secondsInOneHour = 3600;
+			expect(sharedOnUpdate).toHaveBeenCalledTimes(secondsInOneHour);
+		});
+
+		it("Calls onUpdate callback one time total if callback is registered multiple times with a mix of redundant/different intervals", async ({
+			expect,
+		}) => {
+			const sync = new TimeSync({ allowDuplicateOnUpdateCalls: false });
 			const sharedOnUpdate = vi.fn();
-			for (let i = 0; i < 100; i++) {
+
+			for (let i = 0; i < 10; i++) {
+				void sync.subscribe({
+					onUpdate: sharedOnUpdate,
+					targetRefreshIntervalMs: refreshRates.oneHour,
+				});
 				void sync.subscribe({
 					onUpdate: sharedOnUpdate,
 					targetRefreshIntervalMs: refreshRates.oneMinute,
 				});
+				void sync.subscribe({
+					onUpdate: sharedOnUpdate,
+					targetRefreshIntervalMs: refreshRates.oneSecond,
+				});
 			}
 
-			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
-			expect(sharedOnUpdate).toHaveBeenCalledTimes(100);
+			await vi.advanceTimersByTimeAsync(refreshRates.oneHour);
+			const secondsInOneHour = 3600;
+			expect(sharedOnUpdate).toHaveBeenCalledTimes(secondsInOneHour);
+		});
+
+		it("Always exposes the context for the subscription that first set up onUpdate", async ({
+			expect,
+		}) => {
+			const sync = new TimeSync();
+			const snapBefore = sync.getStateSnapshot().date;
+
+			let ejectedContext: SubscriptionContext | undefined;
+			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
+				ejectedContext = ctx;
+			});
+
+			const unsub = sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: refreshRates.oneHour,
+			});
+			void sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: refreshRates.oneMinute,
+			});
+			void sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: refreshRates.oneSecond,
+			});
+
+			await vi.advanceTimersByTimeAsync(refreshRates.oneSecond);
+			expect(ejectedContext).toEqual<SubscriptionContext>({
+				isSubscribed: true,
+				intervalLastFulfilledAt: null,
+				registeredAt: snapBefore,
+				targetRefreshIntervalMs: refreshRates.oneHour,
+				timeSync: sync,
+				unsubscribe: unsub,
+			});
+
+			const remainingSecondsToOneHour = refreshRates.oneHour - 1000;
+			await vi.advanceTimersByTimeAsync(remainingSecondsToOneHour);
+
+			const snapAfter = sync.getStateSnapshot().date;
+			expect(ejectedContext).toEqual<SubscriptionContext>({
+				isSubscribed: true,
+				intervalLastFulfilledAt: snapAfter,
+				registeredAt: snapBefore,
+				targetRefreshIntervalMs: refreshRates.oneHour,
+				timeSync: sync,
+				unsubscribe: unsub,
+			});
 		});
 	});
 
@@ -685,7 +856,11 @@ describe(TimeSync, () => {
 		}) => {
 			const initialDate = setInitialTime("July 4, 1999");
 			const minimumRefreshIntervalMs = 5_000_000;
-			const sync = new TimeSync({ initialDate, minimumRefreshIntervalMs });
+			const sync = new TimeSync({
+				initialDate,
+				minimumRefreshIntervalMs,
+				allowDuplicateOnUpdateCalls: false,
+			});
 
 			const snap = sync.getStateSnapshot();
 			expect(snap).toEqual<Snapshot>({
@@ -748,9 +923,8 @@ describe(TimeSync, () => {
 			await vi.advanceTimersByTimeAsync(refreshRates.oneHour);
 
 			expect(onUpdate).toHaveBeenCalledTimes(1);
-			expect(onUpdate).toHaveBeenCalledWith(expect.any(Date));
-
 			const newSnap = sync.getStateSnapshot();
+			expect(onUpdate).toHaveBeenCalledWith(newSnap.date, expect.any(Object));
 			expect(newSnap).not.toEqual(initialSnap);
 		});
 
@@ -818,7 +992,6 @@ describe(TimeSync, () => {
 		});
 
 		it("Prevents mutating properties at runtime", ({ expect }) => {
-			type Writeable<T> = { -readonly [Key in keyof T]: T[Key] };
 			const sync = new TimeSync();
 
 			// We have readonly modifiers on the types, but we need to make sure
@@ -913,6 +1086,28 @@ describe(TimeSync, () => {
 			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
 			expect(sharedOnUpdate).not.toHaveBeenCalled();
 		});
+
+		it("Mutates the isLive context value to be false", async ({ expect }) => {
+			const sync = new TimeSync();
+
+			let ejectedContext: SubscriptionContext | undefined;
+			const onUpdate = vi.fn((_: unknown, ctx: SubscriptionContext) => {
+				if (ejectedContext === undefined) {
+					ejectedContext = ctx;
+				}
+			});
+
+			void sync.subscribe({
+				onUpdate,
+				targetRefreshIntervalMs: refreshRates.oneMinute,
+			});
+
+			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
+			expect(ejectedContext?.isSubscribed).toBe(true);
+
+			sync.clearAll();
+			expect(ejectedContext?.isSubscribed).toBe(false);
+		});
 	});
 
 	/**
@@ -1067,5 +1262,31 @@ describe(TimeSync, () => {
 			const snap3 = sync.getStateSnapshot().subscriberCount;
 			expect(snap3).toBe(0);
 		});
+
+		it("Lets consumers detect whether an update corresponds to the subscription they explicitly set up", async ({
+			expect,
+		}) => {
+			const sync = new TimeSync();
+			const innerOnUpdate = vi.fn();
+
+			void sync.subscribe({
+				targetRefreshIntervalMs: refreshRates.oneMinute,
+				onUpdate: (date, ctx) => {
+					const intervalMatches =
+						date.getTime() === ctx.intervalLastFulfilledAt?.getTime();
+					if (intervalMatches) {
+						innerOnUpdate();
+					}
+				},
+			});
+
+			void sync.subscribe({
+				targetRefreshIntervalMs: refreshRates.thirtySeconds,
+				onUpdate: vi.fn(),
+			});
+
+			await vi.advanceTimersByTimeAsync(refreshRates.oneMinute);
+			expect(innerOnUpdate).toHaveBeenCalledTimes(1);
+		});
 	});
 });

package/src/TimeSync.ts

@@ -1,4 +1,5 @@
 import { ReadonlyDate } from "./ReadonlyDate";
+import type { Writeable } from "./utilities";
 
 /**
  * A collection of commonly-needed intervals (all defined in milliseconds).
@@ -26,14 +27,14 @@ export const refreshRates = Object.freeze({
 /**
  * The set of readonly options that the TimeSync has been configured with.
  */
-export type Configuration = Readonly<{
+export interface Configuration {
 	/**
 	 * Indicates whether the TimeSync instance should be frozen for Snapshot
 	 * tests.
 	 *
 	 * Defaults to false.
 	 */
-	freezeUpdates: boolean;
+	readonly freezeUpdates: boolean;
 
 	/**
 	 * The minimum refresh interval (in milliseconds) to use when dispatching
@@ -48,49 +49,44 @@ export type Configuration = Readonly<{
 	 *
 	 * Defaults to 200ms.
 	 */
-	minimumRefreshIntervalMs: number;
+	readonly minimumRefreshIntervalMs: number;
 
 	/**
 	 * Indicates whether the same `onUpdate` callback (by reference) should be
 	 * called multiple time if registered by multiple systems.
 	 *
-	 * Defaults to false.
+	 * Defaults to true. If this value is flipped to false, each onUpdate
+	 * callback will receive the subscription context for the FIRST subscriber
+	 * that registered the onUpdate callback.
 	 */
-	allowDuplicateOnUpdateCalls: boolean;
-}>;
+	readonly allowDuplicateOnUpdateCalls: boolean;
+}
 
 /**
  * The set of options that can be used to instantiate a TimeSync.
  */
-export type InitOptions = Readonly<
-	Configuration & {
-		/**
-		 * Indicates whether the TimeSync instance should be frozen for snapshot
-		 * tests. Highly encouraged that you use this together with
-		 * `initialDate`.
-		 *
-		 *  Defaults to false.
-		 */
-		// Duplicated property to override the LSP comment
-		freezeUpdates: boolean;
-
-		/**
-		 * The Date object to use when initializing TimeSync to make the
-		 * constructor more pure and deterministic.
-		 */
-		initialDate: Date;
-	}
->;
+export interface InitOptions extends Configuration {
+	/**
+	 * Indicates whether the TimeSync instance should be frozen for snapshot
+	 * tests. Highly encouraged that you use this together with
+	 * `initialDate`.
+	 *
+	 *  Defaults to false.
+	 */
+	// Duplicated property to override the LSP comment
+	readonly freezeUpdates: boolean;
 
-/**
- * The callback to call when a new state update is ready to be dispatched.
- */
-export type OnTimeSyncUpdate = (dateSnapshot: ReadonlyDate) => void;
+	/**
+	 * The Date object to use when initializing TimeSync to make the
+	 * constructor more pure and deterministic.
+	 */
+	readonly initialDate: Date;
+}
 
 /**
  * An object used to initialize a new subscription for TimeSync.
  */
-export type SubscriptionOptions = Readonly<{
+export interface SubscriptionInitOptions {
 	/**
 	 * The maximum update interval that a subscriber needs. A value of
 	 * Number.POSITIVE_INFINITY indicates that the subscriber does not strictly
@@ -110,36 +106,93 @@ export type SubscriptionOptions = Readonly<{
 	 * after A, updates will pause completely until a new subscriber gets
 	 * added, and it has a non-infinite interval.
 	 */
-	targetRefreshIntervalMs: number;
+	readonly targetRefreshIntervalMs: number;
 
 	/**
 	 * The callback to call when a new state update needs to be flushed amongst
 	 * all subscribers.
 	 */
-	onUpdate: OnTimeSyncUpdate;
-}>;
+	readonly onUpdate: OnTimeSyncUpdate;
+}
 
 /**
  * A complete snapshot of the user-relevant internal state from TimeSync. This
  * value is treated as immutable at both runtime and compile time.
  */
-export type Snapshot = Readonly<{
+export interface Snapshot {
 	/**
 	 * The date that was last dispatched to all subscribers.
 	 */
-	date: ReadonlyDate;
+	readonly date: ReadonlyDate;
 
 	/**
 	 * The number of subscribers registered with TimeSync.
 	 */
-	subscriberCount: number;
+	readonly subscriberCount: number;
 
 	/**
 	 * The configuration options used when instantiating the TimeSync instance.
 	 * The value is guaranteed to be stable for the entire lifetime of TimeSync.
 	 */
-	config: Configuration;
-}>;
+	readonly config: Configuration;
+}
+
+/**
+ * An object with information about a specific subscription registered with
+ * TimeSync.
+ *
+ * For performance reasons, this object has ZERO readonly guarantees enforced at
+ * runtime. A few properties are flagged as readonly at the type level, but
+ * misuse of this value has a risk of breaking a TimeSync instance's internal
+ * state. Proceed with caution.
+ */
+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`.
+	 */
+	readonly unsubscribe: () => void;
+
+	/**
+	 * A timestamp of when the subscription was first set up.
+	 */
+	readonly registeredAt: ReadonlyDate;
+
+	/**
+	 * A reference to the TimeSync instance that the subscription was registered
+	 * with.
+	 */
+	readonly timeSync: TimeSync;
+
+	/**
+	 * Indicates whether the subscription is still live. Will be mutated to be
+	 * false when a subscription is
+	 */
+	isSubscribed: boolean;
+
+	/**
+	 * 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.
+	 */
+	intervalLastFulfilledAt: ReadonlyDate | null;
+}
+
+/**
+ * The callback to call when a new state update is ready to be dispatched.
+ */
+export type OnTimeSyncUpdate = (
+	newDate: ReadonlyDate,
+	context: SubscriptionContext,
+) => void;
 
 interface TimeSyncApi {
 	/**
@@ -155,7 +208,7 @@ interface TimeSyncApi {
 	 * @returns An unsubscribe callback. Calling the callback more than once
 	 * results in a no-op.
 	 */
-	subscribe: (options: SubscriptionOptions) => () => void;
+	subscribe: (options: SubscriptionInitOptions) => () => void;
 
 	/**
 	 * Allows an external system to pull an immutable snapshot of some of the
@@ -179,11 +232,6 @@ interface TimeSyncApi {
 	clearAll: () => void;
 }
 
-type SubscriptionEntry = Readonly<{
-	targetInterval: number;
-	unsubscribe: () => void;
-}>;
-
 /* biome-ignore lint:suspicious/noEmptyBlockStatements -- Rare case where we do
    actually want a completely empty function body. */
 function noOp(..._: readonly unknown[]): void {}
@@ -238,8 +286,27 @@ export class TimeSync implements TimeSyncApi {
 	 *
 	 * Each map value should stay sorted by refresh interval, in ascending
 	 * order.
+	 *
+	 * ---
+	 *
+	 * This is a rare case where we actually REALLY need the readonly modifier
+	 * to avoid infinite loops. JavaScript's iterator protocol is really great
+	 * for making loops simple and type-safe, but because subscriptions have the
+	 * ability to add more subscriptions, we need to make an immutable version
+	 * of each array at some point to make sure that we're not iterating through
+	 * values forever
+	 *
+	 * We can choose to do that at one of two points:
+	 * 1. When adding a new subscription
+	 * 2. When dispatching a new round of updates
+	 *
+	 * Because this library assumes that dispatches will be much more common
+	 * than new subscriptions (a single subscription that subscribes for one
+	 * second will receive 360 updates in five minutes), operations should be
+	 * done to optimize that use case. So we should move the immutability costs
+	 * to the subscribe and unsubscribe operations.
 	 */
-	#subscriptions: Map<OnTimeSyncUpdate, SubscriptionEntry[]>;
+	#subscriptions: Map<OnTimeSyncUpdate, readonly SubscriptionContext[]>;
 
 	/**
 	 * The latest public snapshot of TimeSync's internal state. The snapshot
@@ -271,7 +338,7 @@ export class TimeSync implements TimeSyncApi {
 		const {
 			initialDate,
 			freezeUpdates = false,
-			allowDuplicateOnUpdateCalls = false,
+			allowDuplicateOnUpdateCalls = true,
 			minimumRefreshIntervalMs = defaultMinimumRefreshIntervalMs,
 		} = options ?? {};
 
@@ -343,50 +410,57 @@ export class TimeSync implements TimeSyncApi {
 			return;
 		}
 
+		const dateTime = date.getTime();
+
 		/**
-		 * Two things for both paths:
-		 * 1. We need to make sure that we do one-time serializations of the map
-		 * entries into an array instead of constantly pulling from the map via
-		 * the iterator protocol in the off chance that subscriptions add new
-		 * subscriptions. We need to make infinite loops impossible. If new
-		 * subscriptions get added, they'll just have to wait until the next
-		 * update round.
+		 * Two things:
+		 * 1. Even though the context arrays are defined as readonly (which
+		 * removes on the worst edge cases during dispatching), the
+		 * subscriptions map itself is still mutable, so there are a few edge
+		 * cases we need to deal with. While the risk of infinite loops should
+		 * be much lower, there's still the risk that an onUpdate callback could
+		 * add a subscriber for an interval that wasn't registered before, which
+		 * the iterator protocol will pick up. Need to make a local,
+		 * fixed-length copy of the map entries before starting iteration. Any
+		 * subscriptions added during update will just have to wait until the
+		 * next round of updates.
 		 *
 		 * 2. The trade off of the serialization is that we do lose the ability
-		 * to auto-break the loops if one of the subscribers ends up resetting
+		 * to auto-break the loop if one of the subscribers ends up resetting
 		 * all state, because we'll still have local copies of entries. We need
 		 * to check on each iteration to see if we should continue.
 		 */
-		if (config.allowDuplicateOnUpdateCalls) {
-			// Not super happy about this, but because each subscription array
-			// is mutable, we have to make an immutable copy of the count of
-			// each sub before starting any dispatches. If we wait until the
-			// inner loop to store the length of the subs before iterating over
-			// them, that's too late. It's possible that a subscription could
-			// cause data to be pushed to an array for a different interval
-			const entries = Array.from(
-				this.#subscriptions,
-				([onUpdate, subs]) => [onUpdate, subs.length] as const,
-			);
-			outer: for (const [onUpdate, subCount] of entries) {
-				for (let i = 0; i < subCount; i++) {
-					const wasCleared = this.#subscriptions.size === 0;
-					if (wasCleared) {
-						break outer;
-					}
-					onUpdate(date);
+		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 context 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) {
+					break outer;
+				}
+
+				const comparisonDate =
+					context.intervalLastFulfilledAt ?? context.registeredAt;
+				const isIntervalMatch =
+					dateTime - comparisonDate.getTime() >=
+					context.targetRefreshIntervalMs;
+				if (isIntervalMatch) {
+					context.intervalLastFulfilledAt = date;
 				}
-			}
-			return;
-		}
 
-		const funcs = [...this.#subscriptions.keys()];
-		for (const onUpdate of funcs) {
-			const wasCleared = this.#subscriptions.size === 0;
-			if (wasCleared) {
-				break;
+				if (shouldCallOnUpdate) {
+					onUpdate(date, context);
+					shouldCallOnUpdate = config.allowDuplicateOnUpdateCalls;
+				}
 			}
-			onUpdate(date);
 		}
 	}
 
@@ -475,7 +549,8 @@ export class TimeSync implements TimeSyncApi {
 		// 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 subFastest = entries[0]?.targetInterval ?? Number.POSITIVE_INFINITY;
+			const subFastest =
+				entries[0]?.targetRefreshIntervalMs ?? Number.POSITIVE_INFINITY;
 			if (subFastest < newFastest) {
 				newFastest = subFastest;
 			}
@@ -487,7 +562,7 @@ export class TimeSync implements TimeSyncApi {
 		}
 	}
 
-	subscribe(sh: SubscriptionOptions): () => void {
+	subscribe(options: SubscriptionInitOptions): () => void {
 		const { config } = this.#latestSnapshot;
 		if (config.freezeUpdates) {
 			return noOp;
@@ -495,7 +570,7 @@ export class TimeSync implements TimeSyncApi {
 
 		// Destructuring properties so that they can't be fiddled with after
 		// this function call ends
-		const { targetRefreshIntervalMs, onUpdate } = sh;
+		const { targetRefreshIntervalMs, onUpdate } = options;
 
 		const isTargetValid =
 			targetRefreshIntervalMs === Number.POSITIVE_INFINITY ||
@@ -507,50 +582,73 @@ export class TimeSync implements TimeSyncApi {
 			);
 		}
 
-		const subsOnSetup = this.#subscriptions;
+		// Have to define this as a writeable to avoid a chicken-and-the-egg
+		// problem for the unsubscribe callback
+		const context: Writeable<SubscriptionContext> = {
+			isSubscribed: true,
+			timeSync: this,
+			unsubscribe: noOp,
+			registeredAt: new ReadonlyDate(),
+			intervalLastFulfilledAt: null,
+			targetRefreshIntervalMs: Math.max(
+				config.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) {
+				context.isSubscribed = false;
 				subscribed = false;
 				return;
 			}
 
-			const entries = subsOnSetup.get(onUpdate);
-			if (entries === undefined) {
+			const contexts = subsOnSetup.get(onUpdate);
+			if (contexts === undefined) {
 				return;
 			}
-			const matchIndex = entries.findIndex(
-				(e) => e.unsubscribe === unsubscribe,
-			);
-			if (matchIndex === -1) {
+			const filtered = contexts.filter((e) => e.unsubscribe !== unsubscribe);
+			if (filtered.length === contexts.length) {
 				return;
 			}
-			// No need to sort on removal because everything gets sorted as it
-			// enters the subscriptions map
-			entries.splice(matchIndex, 1);
-			if (entries.length === 0) {
+
+			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),
 			});
+
+			context.isSubscribed = false;
 			subscribed = false;
 		};
-
-		let entries = subsOnSetup.get(onUpdate);
-		if (entries === undefined) {
-			entries = [];
-			subsOnSetup.set(onUpdate, entries);
+		context.unsubscribe = unsubscribe;
+
+		let contexts: SubscriptionContext[];
+		if (this.#subscriptions.has(onUpdate)) {
+			const prev = this.#subscriptions.get(onUpdate) as SubscriptionContext[];
+			contexts = [...prev];
+		} else {
+			contexts = [];
+			subsOnSetup.set(onUpdate, contexts);
 		}
 
-		const targetInterval = Math.max(
-			config.minimumRefreshIntervalMs,
-			targetRefreshIntervalMs,
+		subsOnSetup.set(onUpdate, contexts);
+		contexts.push(context);
+		contexts.sort(
+			(e1, e2) => e1.targetRefreshIntervalMs - e2.targetRefreshIntervalMs,
 		);
-		entries.push({ unsubscribe, targetInterval });
-		entries.sort((e1, e2) => e1.targetInterval - e2.targetInterval);
 
 		void this.#setSnapshot({
 			subscriberCount: this.#latestSnapshot.subscriberCount + 1,
@@ -567,17 +665,22 @@ export class TimeSync implements TimeSyncApi {
 	clearAll(): void {
 		clearInterval(this.#intervalId);
 		this.#intervalId = undefined;
-		this.#fastestRefreshInterval = 0;
-
-		// If we know for a fact that we're going to toss everything, we don't
-		// need to bother iterating through the unsubscribe callbacks. We can
-		// just swap in a new map, and then completely erase the old map (likely
-		// leaning into more efficient code than we could write). As long as the
-		// unsubscribe callbacks are set up to check a local version of the
-		// subscriptions, this won't ever cause problems.
-		const subsBefore = this.#subscriptions;
+		this.#fastestRefreshInterval = Number.POSITIVE_INFINITY;
+
+		// As long as we clean things the internal state, it's safe not to
+		// bother calling each unsubscribe callback. Not calling them one by
+		// one actually has much better time complexity
+		for (const subArray of this.#subscriptions.values()) {
+			for (const ctx of subArray) {
+				ctx.isSubscribed = false;
+			}
+		}
+
+		this.#subscriptions.clear();
+
+		// We swap the map out so that the unsubscribe callbacks can detect
+		// whether their functionality is still relevant
 		this.#subscriptions = new Map();
-		subsBefore.clear();
 		void this.#setSnapshot({ subscriberCount: 0 });
 	}
 }

package/src/index.ts

@@ -6,6 +6,7 @@ export {
 	type OnTimeSyncUpdate,
 	refreshRates,
 	type Snapshot,
-	type SubscriptionOptions,
+	type SubscriptionContext,
+	type SubscriptionInitOptions,
 	TimeSync,
 } from "./TimeSync";

package/src/utilities.ts

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