@buenos-nachos/time-sync 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @buenos-nachos/time-sync
 
+## 0.4.0
+
+### Breaking Changes
+
+- 663479e: Removed `isSubscribed` property from context and made all other context properties readonly.
+
+## 0.3.2
+
+### Patch Changes
+
+- b8fbaf8: cleanup up comments and types for exported class, methods, and types.
+
 ## 0.3.1
 
 ### Patch Changes
@@ -8,7 +20,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.1",
+  "version": "0.4.0",
   "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

@@ -30,7 +30,8 @@ export const refreshRates = Object.freeze({
 export interface Configuration {
 	/**
 	 * Indicates whether the TimeSync instance should be frozen for Snapshot
-	 * tests.
+	 * tests. Highly encouraged that you use this together with
+	 * `initialDate`.
 	 *
 	 * Defaults to false.
 	 */
@@ -44,7 +45,7 @@ export interface Configuration {
 	 * subscription, this minimum will be used instead.
 	 *
 	 * It is highly recommended that you only modify this value if you have a
-	 * good reason. Updating this value to be too low and make the event loop
+	 * good reason. Updating this value to be too low can make the event loop
 	 * get really hot and really tank performance elsewhere in an application.
 	 *
 	 * Defaults to 200ms.
@@ -55,9 +56,11 @@ export interface Configuration {
 	 * Indicates whether the same `onUpdate` callback (by reference) should be
 	 * called multiple time if registered by multiple systems.
 	 *
-	 * 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.
+	 * If this value is flipped to false, each onUpdate callback will receive
+	 * the subscription context for the FIRST subscriber that registered the
+	 * onUpdate callback.
+	 *
+	 * Defaults to true.
 	 */
 	readonly allowDuplicateOnUpdateCalls: boolean;
 }
@@ -66,16 +69,6 @@ export interface Configuration {
  * The set of options that can be used to instantiate a TimeSync.
  */
 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 Date object to use when initializing TimeSync to make the
 	 * constructor more pure and deterministic.
@@ -142,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 {
 	/**
@@ -169,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".
@@ -183,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;
 }
 
 /**
@@ -203,8 +189,16 @@ interface TimeSyncApi {
 	 * intervals. Depending on how TimeSync is instantiated, it may choose to
 	 * de-duplicate these function calls on each round of updates.
 	 *
-	 * @throws {RangeError} If the provided interval is not either a positive
-	 * integer or positive infinity.
+	 * If a value of Number.POSITIVE_INFINITY is used, the subscription will be
+	 * considered "idle". Idle subscriptions cannot trigger updates on their
+	 * own, but can stay in the loop as otherupdates get dispatched from via
+	 * other subscriptions.
+	 *
+	 * Consider using the refreshRates object from this package for a set of
+	 * commonly-used intervals.
+	 *
+	 * @throws {RangeError} If the provided interval is neither a positive
+	 * integer nor positive infinity.
 	 * @returns An unsubscribe callback. Calling the callback more than once
 	 * results in a no-op.
 	 */
@@ -438,7 +432,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
@@ -447,17 +441,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;
 				}
 			}
@@ -585,7 +577,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(),
@@ -603,7 +594,6 @@ export class TimeSync implements TimeSyncApi {
 		const subsOnSetup = this.#subscriptions;
 		const unsubscribe = (): void => {
 			if (!subscribed || this.#subscriptions !== subsOnSetup) {
-				context.isSubscribed = false;
 				subscribed = false;
 				return;
 			}
@@ -630,7 +620,6 @@ export class TimeSync implements TimeSyncApi {
 				subscriberCount: Math.max(0, this.#latestSnapshot.subscriberCount - 1),
 			});
 
-			context.isSubscribed = false;
 			subscribed = false;
 		};
 		context.unsubscribe = unsubscribe;
@@ -670,12 +659,6 @@ 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