@buenos-nachos/time-sync 0.6.0 → 0.6.1

package/dist/index.d.ts

@@ -1,30 +1,4 @@
 //#region src/ReadonlyDate.d.ts
-/**
- * @file This comment is here to provide clarity on why proxy objects might
- * always be a dead end for this library, and document failed experiments.
- *
- * Readonly dates need to have a lot of interoperability with native dates
- * (pretty much every JavaScript library uses the built-in type). So, this code
- * originally defined them as a Proxy wrapper over native dates. The handler
- * intercepted all methods prefixed with `set` and turned them into no-ops.
- *
- * That got really close to working, but then development ran into a critical
- * limitation of the Proxy API. Basically, if the readonly date is defined with
- * a proxy, and you try to call Date.prototype.toISOString.call(readonlyDate),
- * that immediately blows up because the proxy itself is treated as the receiver
- * instead of the underlying native date.
- *
- * Vitest uses .call because it's the more airtight thing to do in most
- * situations, but proxy objects only have traps for .apply calls, not .call. So
- * there is no way in the language to intercept these calls and make sure
- * they're going to the right place. It is a hard, HARD limitation.
- *
- * The good news, though, is that having an extended class seems like the better
- * option, because it gives us the ability to define custom convenience methods
- * without breaking instanceof checks or breaking TypeScript assignability for
- * libraries that expect native dates. We just have to do a little bit of extra
- * work to fudge things for test runners.
- */
 /**
  * Any extra methods for readonly dates.
  */
@@ -269,32 +243,6 @@ interface TimeSyncApi {
    */
   clearAll: () => void;
 }
-/**
- * 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

package/dist/index.js

@@ -12,47 +12,8 @@ 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();
@@ -69,13 +30,6 @@ var ReadonlyDate = class extends Date {
 			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:
@@ -164,12 +118,6 @@ const refreshRates = Object.freeze({
 	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();
@@ -178,18 +126,6 @@ function getMonotonicTimeMs() {
 	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);
@@ -197,32 +133,6 @@ function freezeSnapshot(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.
@@ -232,67 +142,10 @@ const defaultMinimumRefreshIntervalMs = 200;
 * 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 ?? {};
@@ -319,24 +172,6 @@ var TimeSync = class {
 	#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) {
@@ -345,14 +180,6 @@ var TimeSync = class {
 			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) {

package/package.json

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