@buenos-nachos/time-sync 0.5.5 → 0.6.0

package/dist/index.d.ts

@@ -312,5 +312,4 @@ declare class TimeSync implements TimeSyncApi {
   clearAll(): void;
 }
 //#endregion
-export { type Configuration, type InitOptions, type OnTimeSyncUpdate, ReadonlyDate, type Snapshot, type SubscriptionContext, type SubscriptionInitOptions, TimeSync, refreshRates };
-//# sourceMappingURL=index.d.ts.map
+export { type Configuration, type InitOptions, type OnTimeSyncUpdate, ReadonlyDate, type Snapshot, type SubscriptionContext, type SubscriptionInitOptions, TimeSync, refreshRates };

package/dist/index.js

@@ -468,5 +468,4 @@ var TimeSync = class {
 };
 
 //#endregion
-export { ReadonlyDate, TimeSync, refreshRates };
-//# sourceMappingURL=index.js.map
+export { ReadonlyDate, TimeSync, refreshRates };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buenos-nachos/time-sync",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "license": "MIT",
   "type": "module",
   "author": "Michael Smith <hello@nachos.dev> (https://www.nachos.dev)",
@@ -16,10 +16,7 @@
     "ui"
   ],
   "files": [
-    "./src",
-    "./dist",
-    "CHANGELOG.md",
-    "!*.test.ts"
+    "./dist"
   ],
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -29,6 +26,6 @@
   "scripts": {
     "check:types": "tsc --noEmit"
   },
-  "module": "./dist/index.mjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts"
 }

package/CHANGELOG.md

@@ -1,97 +0,0 @@
-# @buenos-nachos/time-sync
-
-## 0.5.5
-
-### Patch Changes
-
-- 1862a8b: Added explicit build process when preparing NPM scripts to ensure ./dist files can't be omitted
-
-## 0.5.4
-
-### Patch Changes
-
-- 3f130f1: updated `files` in package.json to include accidentally removed files
-
-## 0.5.3
-
-### Patch Changes
-
-- e401ae4: further updated which files are included in NPM packages
-
-## 0.5.2
-
-### Patch Changes
-
-- a2a6843: Removed test files from NPM builds.
-
-## 0.5.1
-
-### Patch Changes
-
-- 5fdc201: Updated wording on `Snapshot.date` to be less misleading.
-
-## 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
-
-- 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
-
-- 5fce018: switched internal implementations to use Date.now more often to reduce memory usage
-
-## 0.3.0
-
-### Breaking 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
-
-- 6189eb2: add README to root directory
-
-## 0.1.1
-
-### Patch Changes
-
-- f18d71c: fix: specified module type as ESM
-
-## 0.1.0
-
-### Minor Changes
-
-- 8be4b26: Initial release

package/dist/index.cjs

@@ -1,475 +0,0 @@
-
-//#region src/ReadonlyDate.ts
-/**
-* A readonly version of a Date object. To maximize compatibility with existing
-* libraries, all methods are the same as the native Date object at the type
-* level. But crucially, all methods prefixed with `set` have all mutation logic
-* removed.
-*
-* If you need a mutable version of the underlying date, ReadonlyDate exposes a
-* .toNativeDate method to do a runtime conversion to a native/mutable date.
-*/
-var ReadonlyDate = class extends Date {
-	constructor(initValue, monthIndex, day, hours, minutes, seconds, milliseconds) {
-		if (initValue instanceof Date && initValue.toString() === "Invalid Date") throw new RangeError("Cannot instantiate ReadonlyDate via invalid date object");
-		if ([...arguments].some((el) => {
-			/**
-			* You almost never see them in practice, but native dates do
-			* support using negative AND fractional values for instantiation.
-			* Negative values produce values before 1970.
-			*/
-			return typeof el === "number" && !Number.isFinite(el);
-		})) throw new RangeError("Cannot instantiate ReadonlyDate via invalid number(s)");
-		/**
-		* This guard clause looks incredibly silly, but we need to do this to
-		* make sure that the readonly class works properly with Jest, Vitest,
-		* and anything else that supports fake timers. Critically, it makes
-		* this possible without introducing any extra runtime dependencies.
-		*
-		* Basically:
-		* 1. We need to make sure that ReadonlyDate extends the Date prototype,
-		*    so that instanceof checks work correctly, and so that the class
-		*    can interop with all libraries that rely on vanilla Dates
-		* 2. In ECMAScript, this linking happens right as the module is
-		*    imported
-		* 3. Jest and Vitest will do some degree of hoisting before the
-		*    imports get evaluated, but most of the mock functionality happens
-		*    at runtime. useFakeTimers is NOT hoisted
-		* 4. A Vitest test file might import the readonly class at some point
-		*    (directly or indirectly), which establishes the link
-		* 5. useFakeTimers can then be called after imports, and that updates
-		*    the global scope so that when any FUTURE code references the
-		*    global Date object, the fake version is used instead
-		* 6. But because the linking already happened before the call,
-		*    ReadonlyDate will still be bound to the original Date object
-		* 7. When super is called (which is required when extending classes),
-		*    the original date object will be instantiated and then linked to
-		*    the readonly instance via the prototype chain
-		* 8. None of this is a problem when you're instantiating the class by
-		*    passing it actual inputs, because then the date result will always
-		*    be deterministic. The problem happens when you make the date with
-		*    no arguments, because that causes a new date to be created with
-		*    the true system time, instead of the fake system time.
-		* 9. So, to bridge the gap, we make a separate Date with `new Date()`
-		*    (after it's been turned into the fake version), and then use it to
-		*    overwrite the contents of the real date created with super
-		*/
-		if (initValue === void 0) {
-			super();
-			const overrideForTestCorrectness = Date.now();
-			super.setTime(overrideForTestCorrectness);
-			return;
-		}
-		if (typeof initValue === "string") {
-			super(initValue);
-			if (super.toString() === "Invalid Date") throw new RangeError("Cannot instantiate ReadonlyDate via invalid string");
-			return;
-		}
-		if (monthIndex === void 0) {
-			super(initValue);
-			return;
-		}
-		if (typeof initValue !== "number") throw new TypeError(`Impossible case encountered: init value has type of '${typeof initValue}, but additional arguments were provided after the first`);
-		/**
-		* biome-ignore lint:complexity/noArguments -- Native dates are super
-		* wonky, and they actually check arguments.length to define behavior
-		* at runtime. We can't pass all the arguments in via a single call,
-		* because then the constructor will create an invalid date the moment
-		* it finds any single undefined value.
-		*/
-		const argCount = arguments.length;
-		switch (argCount) {
-			case 2:
-				super(initValue, monthIndex);
-				return;
-			case 3:
-				super(initValue, monthIndex, day);
-				return;
-			case 4:
-				super(initValue, monthIndex, day, hours);
-				return;
-			case 5:
-				super(initValue, monthIndex, day, hours, minutes);
-				return;
-			case 6:
-				super(initValue, monthIndex, day, hours, minutes, seconds);
-				return;
-			case 7:
-				super(initValue, monthIndex, day, hours, minutes, seconds, milliseconds);
-				return;
-			default: throw new Error(`Cannot instantiate new Date with ${argCount} arguments`);
-		}
-	}
-	toNativeDate() {
-		const time = super.getTime();
-		return new Date(time);
-	}
-	setDate(_date) {
-		return super.getTime();
-	}
-	setFullYear(_year, _month, _date) {
-		return super.getTime();
-	}
-	setHours(_hours, _min, _sec, _ms) {
-		return super.getTime();
-	}
-	setMilliseconds(_ms) {
-		return super.getTime();
-	}
-	setMinutes(_min, _sec, _ms) {
-		return super.getTime();
-	}
-	setMonth(_month, _date) {
-		return super.getTime();
-	}
-	setSeconds(_sec, _ms) {
-		return super.getTime();
-	}
-	setTime(_time) {
-		return super.getTime();
-	}
-	setUTCDate(_date) {
-		return super.getTime();
-	}
-	setUTCFullYear(_year, _month, _date) {
-		return super.getTime();
-	}
-	setUTCHours(_hours, _min, _sec, _ms) {
-		return super.getTime();
-	}
-	setUTCMilliseconds(_ms) {
-		return super.getTime();
-	}
-	setUTCMinutes(_min, _sec, _ms) {
-		return super.getTime();
-	}
-	setUTCMonth(_month, _date) {
-		return super.getTime();
-	}
-	setUTCSeconds(_sec, _ms) {
-		return super.getTime();
-	}
-};
-
-//#endregion
-//#region src/TimeSync.ts
-/**
-* A collection of commonly-needed intervals (all defined in milliseconds).
-*/
-const refreshRates = Object.freeze({
-	idle: Number.POSITIVE_INFINITY,
-	halfSecond: 500,
-	oneSecond: 1e3,
-	thirtySeconds: 3e4,
-	oneMinute: 60 * 1e3,
-	fiveMinutes: 300 * 1e3,
-	oneHour: 3600 * 1e3
-});
-/**
-* 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() {
-	if (typeof window === "undefined") {
-		const timeInNanoseconds = process.hrtime.bigint();
-		return Number(timeInNanoseconds / 1000n);
-	}
-	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) {
-	if (!Object.isFrozen(snap.config)) Object.freeze(snap.config);
-	if (!Object.isFrozen(snap)) Object.freeze(snap);
-	return snap;
-}
-const defaultMinimumRefreshIntervalMs = 200;
-/**
-* One thing that was considered was giving TimeSync the ability to flip which
-* kinds of dates it uses, and let it use native dates instead of readonly
-* dates. We type readonly dates as native dates for better interoperability
-* with pretty much every JavaScript library under the sun, but there is still a
-* big difference in runtime behavior. There is a risk that blocking mutations
-* could break some other library in other ways.
-*
-* That might be worth revisiting if we get user feedback, but right now, it
-* seems like an incredibly bad idea.
-*
-* 1. Any single mutation has a risk of breaking the entire integrity of the
-*    system. If a consumer would try to mutate them, things SHOULD blow up by
-*    default.
-* 2. Dates are a type of object that are far more read-heavy than write-heavy,
-*    so the risks of breaking are generally lower
-* 3. If a user really needs a mutable version of the date, they can make a
-*    mutable copy first via `const mutable = readonlyDate.toNativeDate()`
-*
-* The one case when turning off the readonly behavior would be good would be
-* if you're on a server that really needs to watch its garbage collection
-* output, and you the overhead from the readonly date is causing too much
-* pressure on resources. In that case, you could switch to native dates, but
-* you'd still need a LOT of trigger discipline to avoid mutations, especially
-* if you rely on outside libraries.
-*/
-/**
-* TimeSync provides a centralized authority for working with time values in a
-* more structured way. It ensures all dependents for the time values stay in
-* sync with each other.
-*
-* (e.g., In a React codebase, you want multiple components that rely on time
-* values to update together, to avoid screen tearing and stale data for only
-* some parts of the screen.)
-*/
-var TimeSync = class {
-	/**
-	* The monotonic time in milliseconds from when the TimeSync instance was
-	* first instantiated.
-	*/
-	#initializedAtMs;
-	/**
-	* Stores all refresh intervals actively associated with an onUpdate
-	* callback (along with their associated unsubscribe callbacks).
-	*
-	* Supports storing the exact same callback-interval pairs multiple times,
-	* in case multiple external systems need to subscribe with the exact same
-	* data concerns. Because the functions themselves are used as keys, that
-	* ensures that each callback will only be called once per update, no matter
-	* how subscribers use it.
-	*
-	* 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;
-	/**
-	* The latest public snapshot of TimeSync's internal state. The snapshot
-	* should always be treated as an immutable value.
-	*/
-	#latestSnapshot;
-	/**
-	* A cached version of the fastest interval currently registered with
-	* TimeSync. Should always be derived from #subscriptions
-	*/
-	#fastestRefreshInterval;
-	/**
-	* Used for both its intended purpose (creating interval), but also as a
-	* 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
-	* things getting out of sync.
-	*
-	* Type defined like this to support client and server behavior. Node.js
-	* uses its own custom timeout type, but Deno, Bun, and the browser all use
-	* the number type.
-	*/
-	#intervalId;
-	constructor(options) {
-		const { initialDate, freezeUpdates = false, allowDuplicateOnUpdateCalls = true, minimumRefreshIntervalMs = defaultMinimumRefreshIntervalMs } = options ?? {};
-		if (!(Number.isInteger(minimumRefreshIntervalMs) && minimumRefreshIntervalMs > 0)) throw new RangeError(`Minimum refresh interval must be a positive integer (received ${minimumRefreshIntervalMs} ms)`);
-		this.#subscriptions = /* @__PURE__ */ new Map();
-		this.#fastestRefreshInterval = Number.POSITIVE_INFINITY;
-		this.#intervalId = void 0;
-		this.#initializedAtMs = getMonotonicTimeMs();
-		let date;
-		if (initialDate instanceof ReadonlyDate) date = initialDate;
-		else if (initialDate instanceof Date) date = new ReadonlyDate(initialDate);
-		else date = new ReadonlyDate();
-		this.#latestSnapshot = freezeSnapshot({
-			date,
-			subscriberCount: 0,
-			lastUpdatedAtMs: null,
-			config: {
-				freezeUpdates,
-				minimumRefreshIntervalMs,
-				allowDuplicateOnUpdateCalls
-			}
-		});
-	}
-	#notifyAllSubscriptions() {
-		const { date, config } = this.#latestSnapshot;
-		if (config.freezeUpdates || this.#subscriptions.size === 0 || this.#fastestRefreshInterval === Number.POSITIVE_INFINITY) return;
-		/**
-		* 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 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.
-		*/
-		const subsBeforeUpdate = this.#subscriptions;
-		const localEntries = Array.from(subsBeforeUpdate);
-		outer: for (const [onUpdate, subs] of localEntries) for (const ctx of subs) {
-			if (subsBeforeUpdate.size === 0) break outer;
-			onUpdate(date, ctx);
-			if (!config.allowDuplicateOnUpdateCalls) continue outer;
-		}
-	}
-	/**
-	* The logic that should happen at each step in TimeSync's active interval.
-	*
-	* Defined as an arrow function so that we can just pass it directly to
-	* setInterval without needing to make a new wrapper function each time. We
-	* don't have many situations where we can lose the `this` context, but this
-	* is one of them.
-	*/
-	#onTick = () => {
-		const { config } = this.#latestSnapshot;
-		if (config.freezeUpdates) {
-			clearInterval(this.#intervalId);
-			this.#intervalId = void 0;
-			return;
-		}
-		this.#latestSnapshot = freezeSnapshot({
-			...this.#latestSnapshot,
-			date: new ReadonlyDate(),
-			lastUpdatedAtMs: getMonotonicTimeMs() - this.#initializedAtMs
-		});
-		this.#notifyAllSubscriptions();
-	};
-	#onFastestIntervalChange() {
-		const fastest = this.#fastestRefreshInterval;
-		const { lastUpdatedAtMs, config } = this.#latestSnapshot;
-		if (config.freezeUpdates || this.#subscriptions.size === 0 || fastest === Number.POSITIVE_INFINITY) {
-			clearInterval(this.#intervalId);
-			this.#intervalId = void 0;
-			return;
-		}
-		const timeBeforeNextUpdate = fastest - (getMonotonicTimeMs() - (lastUpdatedAtMs ?? this.#initializedAtMs));
-		clearInterval(this.#intervalId);
-		if (timeBeforeNextUpdate <= 0) {
-			this.#onTick();
-			this.#intervalId = setInterval(this.#onTick, fastest);
-			return;
-		}
-		if (timeBeforeNextUpdate === fastest) {
-			this.#intervalId = setInterval(this.#onTick, timeBeforeNextUpdate);
-			return;
-		}
-		this.#intervalId = setInterval(() => {
-			clearInterval(this.#intervalId);
-			this.#intervalId = setInterval(this.#onTick, fastest);
-			this.#onTick();
-		}, timeBeforeNextUpdate);
-	}
-	#updateFastestInterval() {
-		const { config } = this.#latestSnapshot;
-		if (config.freezeUpdates) {
-			this.#fastestRefreshInterval = Number.POSITIVE_INFINITY;
-			return;
-		}
-		const prevFastest = this.#fastestRefreshInterval;
-		let newFastest = Number.POSITIVE_INFINITY;
-		for (const contexts of this.#subscriptions.values()) {
-			const subFastest = contexts[0]?.refreshIntervalMs ?? Number.POSITIVE_INFINITY;
-			if (subFastest < newFastest) newFastest = subFastest;
-		}
-		this.#fastestRefreshInterval = newFastest;
-		if (prevFastest !== newFastest) this.#onFastestIntervalChange();
-	}
-	subscribe(options) {
-		const { targetRefreshIntervalMs, onUpdate } = options;
-		const { minimumRefreshIntervalMs } = this.#latestSnapshot.config;
-		if (!(targetRefreshIntervalMs === Number.POSITIVE_INFINITY || Number.isInteger(targetRefreshIntervalMs) && targetRefreshIntervalMs > 0)) throw new Error(`Target refresh interval must be positive infinity or a positive integer (received ${targetRefreshIntervalMs} ms)`);
-		const subsOnSetup = this.#subscriptions;
-		let subscribed = true;
-		const ctx = {
-			timeSync: this,
-			registeredAtMs: getMonotonicTimeMs() - this.#initializedAtMs,
-			refreshIntervalMs: Math.max(minimumRefreshIntervalMs, targetRefreshIntervalMs),
-			unsubscribe: () => {
-				try {
-					if (!subscribed || this.#subscriptions !== subsOnSetup) return;
-					const contexts = subsOnSetup.get(onUpdate);
-					if (contexts === void 0) 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) subsOnSetup.set(onUpdate, filtered);
-					else subsOnSetup.delete(onUpdate);
-					this.#updateFastestInterval();
-				} finally {
-					subscribed = false;
-				}
-			}
-		};
-		Object.freeze(ctx);
-		let newContexts;
-		const prevContexts = subsOnSetup.get(onUpdate);
-		if (prevContexts !== void 0) newContexts = [...prevContexts, ctx];
-		else newContexts = [ctx];
-		subsOnSetup.set(onUpdate, newContexts);
-		newContexts.sort((c1, c2) => c1.refreshIntervalMs - c2.refreshIntervalMs);
-		this.#latestSnapshot = freezeSnapshot({
-			...this.#latestSnapshot,
-			subscriberCount: this.#latestSnapshot.subscriberCount + 1
-		});
-		this.#updateFastestInterval();
-		return ctx.unsubscribe;
-	}
-	getStateSnapshot() {
-		return this.#latestSnapshot;
-	}
-	clearAll() {
-		clearInterval(this.#intervalId);
-		this.#intervalId = void 0;
-		this.#fastestRefreshInterval = Number.POSITIVE_INFINITY;
-		this.#subscriptions.clear();
-		this.#subscriptions = /* @__PURE__ */ new Map();
-		this.#latestSnapshot = freezeSnapshot({
-			...this.#latestSnapshot,
-			subscriberCount: 0
-		});
-	}
-};
-
-//#endregion
-exports.ReadonlyDate = ReadonlyDate;
-exports.TimeSync = TimeSync;
-exports.refreshRates = refreshRates;
-//# sourceMappingURL=index.cjs.map