@buenos-nachos/time-sync 0.3.2 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @buenos-nachos/time-sync
 
+## 0.4.1
+
+### Patch Changes
+
+- 5f37f1a: refactored class to remove private setSnapshost method
+
+## 0.4.0
+
+### Breaking Changes
+
+- 663479e: Removed `isSubscribed` property from context and made all other context properties readonly.
+
 ## 0.3.2
 
 ### Patch Changes
@@ -14,7 +26,7 @@
 
 ## 0.3.0
 
-### Minor Changes
+### Breaking Changes
 
 - 122f6c1: Updated `SubscriptionContext.timeSync` type to be readonly and non-nullable, and renamed `SubscriptionContext.isLive` to `SubscriptionContext.isSubscribed`.
 

package/package.json

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

package/src/TimeSync.test.ts

@@ -131,7 +131,6 @@ describe(TimeSync, () => {
 
 				const expectedCtx: SubscriptionContext = {
 					unsubscribe,
-					isSubscribed: true,
 					timeSync: sync,
 					intervalLastFulfilledAt: dateAfter,
 					registeredAt: dateBefore,
@@ -563,28 +562,6 @@ 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", () => {
@@ -827,7 +804,6 @@ describe(TimeSync, () => {
 
 			await vi.advanceTimersByTimeAsync(refreshRates.oneSecond);
 			expect(ejectedContext).toEqual<SubscriptionContext>({
-				isSubscribed: true,
 				intervalLastFulfilledAt: null,
 				registeredAt: snapBefore,
 				targetRefreshIntervalMs: refreshRates.oneHour,
@@ -840,7 +816,6 @@ describe(TimeSync, () => {
 
 			const snapAfter = sync.getStateSnapshot().date;
 			expect(ejectedContext).toEqual<SubscriptionContext>({
-				isSubscribed: true,
 				intervalLastFulfilledAt: snapAfter,
 				registeredAt: snapBefore,
 				targetRefreshIntervalMs: refreshRates.oneHour,
@@ -1086,28 +1061,6 @@ 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);
-		});
 	});
 
 	/**

package/src/TimeSync.ts

@@ -135,9 +135,8 @@ export interface Snapshot {
  * 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.
+ * runtime. All properties are defined as readonly at the type level, but an
+ * accidental mutation can still slip through.
  */
 export interface SubscriptionContext {
 	/**
@@ -162,12 +161,6 @@ export interface SubscriptionContext {
 	 */
 	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".
@@ -176,7 +169,7 @@ export interface SubscriptionContext {
 	 * the active interval is set to fire every second, you may need to know
 	 * which update actually happened five minutes later.
 	 */
-	intervalLastFulfilledAt: ReadonlyDate | null;
+	readonly intervalLastFulfilledAt: ReadonlyDate | null;
 }
 
 /**
@@ -237,6 +230,23 @@ interface TimeSyncApi {
    actually want a completely empty function body. */
 function noOp(..._: readonly unknown[]): void {}
 
+/**
+ * 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 {
+	Object.freeze(snap.config);
+	return Object.freeze(snap);
+}
+
 const defaultMinimumRefreshIntervalMs = 200;
 
 /**
@@ -370,43 +380,17 @@ export class TimeSync implements TimeSyncApi {
 		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 {
+	#processSubscriptionUpdate(): 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;
 		}
@@ -439,7 +423,7 @@ export class TimeSync implements TimeSyncApi {
 			// 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) {
+			for (const ctx of subs as readonly Writeable<SubscriptionContext>[]) {
 				// 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
@@ -448,17 +432,15 @@ export class TimeSync implements TimeSyncApi {
 					break outer;
 				}
 
-				const comparisonDate =
-					context.intervalLastFulfilledAt ?? context.registeredAt;
+				const comparisonDate = ctx.intervalLastFulfilledAt ?? ctx.registeredAt;
 				const isIntervalMatch =
-					dateTime - comparisonDate.getTime() >=
-					context.targetRefreshIntervalMs;
+					dateTime - comparisonDate.getTime() >= ctx.targetRefreshIntervalMs;
 				if (isIntervalMatch) {
-					context.intervalLastFulfilledAt = date;
+					ctx.intervalLastFulfilledAt = date;
 				}
 
 				if (shouldCallOnUpdate) {
-					onUpdate(date, context);
+					onUpdate(date, ctx);
 					shouldCallOnUpdate = config.allowDuplicateOnUpdateCalls;
 				}
 			}
@@ -474,18 +456,24 @@ 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;
+		const { config, date } = 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();
+		const newDate = new ReadonlyDate();
+		if (newDate.getTime() === date.getTime()) {
+			return;
 		}
+
+		this.#latestSnapshot = freezeSnapshot({
+			...this.#latestSnapshot,
+			date: newDate,
+		});
+		this.#processSubscriptionUpdate();
 	};
 
 	#onFastestIntervalChange(): void {
@@ -506,10 +494,15 @@ export class TimeSync implements TimeSyncApi {
 		clearInterval(this.#intervalId);
 
 		if (timeBeforeNextUpdate <= 0) {
-			const wasChanged = this.#setSnapshot({ date: new ReadonlyDate() });
-			if (wasChanged) {
-				this.#notifyAllSubscriptions();
+			const newDate = new ReadonlyDate();
+			if (newDate.getTime() !== date.getTime()) {
+				this.#latestSnapshot = freezeSnapshot({
+					...this.#latestSnapshot,
+					date: newDate,
+				});
+				this.#processSubscriptionUpdate();
 			}
+
 			this.#intervalId = setInterval(this.#onTick, fastest);
 			return;
 		}
@@ -586,7 +579,6 @@ 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> = {
-			isSubscribed: true,
 			timeSync: this,
 			unsubscribe: noOp,
 			registeredAt: new ReadonlyDate(),
@@ -604,7 +596,6 @@ export class TimeSync implements TimeSyncApi {
 		const subsOnSetup = this.#subscriptions;
 		const unsubscribe = (): void => {
 			if (!subscribed || this.#subscriptions !== subsOnSetup) {
-				context.isSubscribed = false;
 				subscribed = false;
 				return;
 			}
@@ -627,11 +618,11 @@ export class TimeSync implements TimeSyncApi {
 				subsOnSetup.set(onUpdate, filtered);
 			}
 
-			void this.#setSnapshot({
+			this.#latestSnapshot = freezeSnapshot({
+				...this.#latestSnapshot,
 				subscriberCount: Math.max(0, this.#latestSnapshot.subscriberCount - 1),
 			});
 
-			context.isSubscribed = false;
 			subscribed = false;
 		};
 		context.unsubscribe = unsubscribe;
@@ -651,7 +642,8 @@ export class TimeSync implements TimeSyncApi {
 			(e1, e2) => e1.targetRefreshIntervalMs - e2.targetRefreshIntervalMs,
 		);
 
-		void this.#setSnapshot({
+		this.#latestSnapshot = freezeSnapshot({
+			...this.#latestSnapshot,
 			subscriberCount: this.#latestSnapshot.subscriberCount + 1,
 		});
 
@@ -671,17 +663,14 @@ export class TimeSync implements TimeSyncApi {
 		// 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();
-		void this.#setSnapshot({ subscriberCount: 0 });
+		this.#latestSnapshot = freezeSnapshot({
+			...this.#latestSnapshot,
+			subscriberCount: 0,
+		});
 	}
 }