@buenos-nachos/time-sync 0.1.1 → 0.2.0

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.
+	 */
+	timeSync: TimeSync | null;
+
+	/**
+	 * Indicates whether the subscription is still live. Will be mutated to be
+	 * false when a subscription is
+	 */
+	isLive: 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> = {
+			isLive: 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.isLive = 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.isLive = 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.isLive = 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] };