@buenos-nachos/time-sync 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @buenos-nachos/time-sync
+
+## 0.1.1
+
+### Patch Changes
+
+- f18d71c: fix: specified module type as ESM
+
+## 0.1.0
+
+### Minor Changes
+
+- 8be4b26: Initial release

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 Michael Smith
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,275 @@
+//#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.
+ */
+interface ReadonlyDateApi {
+  /**
+   * Converts a readonly date into a native (mutable) date.
+   */
+  toNativeDate(): Date;
+}
+/**
+ * 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.
+ */
+declare class ReadonlyDate extends Date implements ReadonlyDateApi {
+  constructor();
+  constructor(initValue: number | string | Date);
+  constructor(year: number, monthIndex: number);
+  constructor(year: number, monthIndex: number, day: number);
+  constructor(year: number, monthIndex: number, day: number, hours: number);
+  constructor(year: number, monthIndex: number, day: number, hours: number, seconds: number);
+  constructor(year: number, monthIndex: number, day: number, hours: number, seconds: number, milliseconds: number);
+  toNativeDate(): Date;
+  setDate(_date: number): number;
+  setFullYear(_year: number, _month?: number, _date?: number): number;
+  setHours(_hours: number, _min?: number, _sec?: number, _ms?: number): number;
+  setMilliseconds(_ms: number): number;
+  setMinutes(_min: number, _sec?: number, _ms?: number): number;
+  setMonth(_month: number, _date?: number): number;
+  setSeconds(_sec: number, _ms?: number): number;
+  setTime(_time: number): number;
+  setUTCDate(_date: number): number;
+  setUTCFullYear(_year: number, _month?: number, _date?: number): number;
+  setUTCHours(_hours: number, _min?: number, _sec?: number, _ms?: number): number;
+  setUTCMilliseconds(_ms: number): number;
+  setUTCMinutes(_min: number, _sec?: number, _ms?: number): number;
+  setUTCMonth(_month: number, _date?: number): number;
+  setUTCSeconds(_sec: number, _ms?: number): number;
+}
+//#endregion
+//#region src/TimeSync.d.ts
+/**
+ * A collection of commonly-needed intervals (all defined in milliseconds).
+ */
+declare const refreshRates: Readonly<{
+  /**
+   * Indicates that a subscriber does not strictly need updates, but is still
+   * allowed to be updated if it would keep it in sync with other subscribers.
+   *
+   * If all subscribers use this update interval, TimeSync will never dispatch
+   * any updates.
+   */
+  idle: number;
+  halfSecond: number;
+  oneSecond: number;
+  thirtySeconds: number;
+  oneMinute: number;
+  fiveMinutes: number;
+  oneHour: number;
+}>;
+/**
+ * The set of readonly options that the TimeSync has been configured with.
+ */
+type Configuration = Readonly<{
+  /**
+   * Indicates whether the TimeSync instance should be frozen for Snapshot
+   * tests.
+   *
+   * Defaults to false.
+   */
+  freezeUpdates: boolean;
+  /**
+   * The minimum refresh interval (in milliseconds) to use when dispatching
+   * interval-based state updates.
+   *
+   * If a value smaller than this is specified when trying to set up a new
+   * 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
+   * get really hot and really tank performance elsewhere in an application.
+   *
+   * Defaults to 200ms.
+   */
+  minimumRefreshIntervalMs: number;
+  /**
+   * Indicates whether the same `onUpdate` callback (by reference) should be
+   * called multiple time if registered by multiple systems.
+   *
+   * Defaults to false.
+   */
+  allowDuplicateOnUpdateCalls: boolean;
+}>;
+/**
+ * The set of options that can be used to instantiate a TimeSync.
+ */
+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.
+   */
+  freezeUpdates: boolean;
+  /**
+   * The Date object to use when initializing TimeSync to make the
+   * constructor more pure and deterministic.
+   */
+  initialDate: Date;
+}>;
+/**
+ * The callback to call when a new state update is ready to be dispatched.
+ */
+type OnTimeSyncUpdate = (dateSnapshot: ReadonlyDate) => void;
+/**
+ * An object used to initialize a new subscription for TimeSync.
+ */
+type SubscriptionOptions = Readonly<{
+  /**
+   * The maximum update interval that a subscriber needs. A value of
+   * Number.POSITIVE_INFINITY indicates that the subscriber does not strictly
+   * need any updates (though they may still happen based on other
+   * subscribers).
+   *
+   * TimeSync always dispatches updates based on the lowest update interval
+   * among all subscribers.
+   *
+   * For example, let's say that we have these three subscribers:
+   * 1. A - Needs updates no slower than 500ms
+   * 2. B – Needs updates no slower than 1000ms
+   * 3. C – Uses interval of Infinity (does not strictly need an update)
+   *
+   * A, B, and C will all be updated at a rate of 500ms. If A unsubscribes,
+   * then B and C will shift to being updated every 1000ms. If B unsubscribes
+   * after A, updates will pause completely until a new subscriber gets
+   * added, and it has a non-infinite interval.
+   */
+  targetRefreshIntervalMs: number;
+  /**
+   * The callback to call when a new state update needs to be flushed amongst
+   * all subscribers.
+   */
+  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.
+ */
+type Snapshot = Readonly<{
+  /**
+   * The date that was last dispatched to all subscribers.
+   */
+  date: ReadonlyDate;
+  /**
+   * The number of subscribers registered with TimeSync.
+   */
+  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;
+}>;
+interface TimeSyncApi {
+  /**
+   * Subscribes an external system to TimeSync.
+   *
+   * The same callback (by reference) is allowed to be registered multiple
+   * times, either for the same update interval, or different update
+   * 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.
+   * @returns An unsubscribe callback. Calling the callback more than once
+   * results in a no-op.
+   */
+  subscribe: (options: SubscriptionOptions) => () => void;
+  /**
+   * Allows an external system to pull an immutable snapshot of some of the
+   * internal state inside TimeSync. The snapshot is frozen at runtime and
+   * cannot be mutated.
+   *
+   * @returns An object with multiple properties describing the TimeSync.
+   */
+  getStateSnapshot: () => Snapshot;
+  /**
+   * Resets all internal state in the TimeSync, and handles all cleanup for
+   * subscriptions and intervals previously set up. Configuration values are
+   * retained.
+   *
+   * This method can be used as a dispose method for a locally-scoped
+   * TimeSync (a TimeSync with no subscribers is safe to garbage-collect
+   * without any risks of memory leaks). It can also be used to reset a global
+   * TimeSync to its initial state for certain testing setups.
+   */
+  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
+ * 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.)
+ */
+declare class TimeSync implements TimeSyncApi {
+  #private;
+  constructor(options?: Partial<InitOptions>);
+  subscribe(sh: SubscriptionOptions): () => void;
+  getStateSnapshot(): Snapshot;
+  clearAll(): void;
+}
+//#endregion
+export { type Configuration, type InitOptions, type OnTimeSyncUpdate, ReadonlyDate, type Snapshot, type SubscriptionOptions, TimeSync, refreshRates };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/ReadonlyDate.ts","../src/TimeSync.ts"],"sourcesContent":[],"mappings":";;;AA8CA;;;;;;;;;ACvCA;AAqBA;AAoCA;;;;;AAuBA;AAKA;AAiCA;;;;;AAgBG;AAsFH;;;UDrMU,eAAA,CC2cK;EAuEM;;;kBD9gBJ;;;;;;;;;;;cAYJ,YAAA,SAAqB,IAAA,YAAgB;;2CAKR;;;;;;kBAgLzB;;;;;;;;;;;;;;;;;;;;AArLjB;;AAqLiB,cC5NJ,YD4NI,EC5NQ,QD4NR,CAAA;EArLiB;;;;;;ACvClC;EAqBY,IAAA,EAAA,MAAA;EAoCA,UAAA,EAAA,MAAW;EACtB,SAAA,EAAA,MAAA;EAec,aAAA,EAAA,MAAA;EAhBW,SAAA,EAAA,MAAA;EAAQ,WAAA,EAAA,MAAA;EAuBtB,OAAA,EAAA,MAAA;AAKZ,CAAA,CAAA;AAiCA;;;AAAuB,KAjGX,aAAA,GAAgB,QAiGL,CAAA;EAAQ;AAgB5B;AAsFH;;;;EA6UqB,aAAA,EAAA,OAAA;EA7UY;;;;;;;;;;;;;;;;;;;;;;;;;KAnKrB,WAAA,GAAc,SACzB;;;;;;;;;;;;;eAec;;;;;KAOH,gBAAA,kBAAkC;;;;KAKlC,mBAAA,GAAsB;;;;;;;;;;;;;;;;;;;;;;;;;YA0BvB;;;;;;KAOC,QAAA,GAAW;;;;QAIhB;;;;;;;;;UAWE;;UAGC,WAAA;;;;;;;;;;;;;;uBAcY;;;;;;;;0BASG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6DZ,QAAA,YAAoB;;wBA0CV,QAAQ;gBA4NhB;sBAuEM"}

package/dist/index.d.ts

@@ -0,0 +1,275 @@
+//#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.
+ */
+interface ReadonlyDateApi {
+  /**
+   * Converts a readonly date into a native (mutable) date.
+   */
+  toNativeDate(): Date;
+}
+/**
+ * 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.
+ */
+declare class ReadonlyDate extends Date implements ReadonlyDateApi {
+  constructor();
+  constructor(initValue: number | string | Date);
+  constructor(year: number, monthIndex: number);
+  constructor(year: number, monthIndex: number, day: number);
+  constructor(year: number, monthIndex: number, day: number, hours: number);
+  constructor(year: number, monthIndex: number, day: number, hours: number, seconds: number);
+  constructor(year: number, monthIndex: number, day: number, hours: number, seconds: number, milliseconds: number);
+  toNativeDate(): Date;
+  setDate(_date: number): number;
+  setFullYear(_year: number, _month?: number, _date?: number): number;
+  setHours(_hours: number, _min?: number, _sec?: number, _ms?: number): number;
+  setMilliseconds(_ms: number): number;
+  setMinutes(_min: number, _sec?: number, _ms?: number): number;
+  setMonth(_month: number, _date?: number): number;
+  setSeconds(_sec: number, _ms?: number): number;
+  setTime(_time: number): number;
+  setUTCDate(_date: number): number;
+  setUTCFullYear(_year: number, _month?: number, _date?: number): number;
+  setUTCHours(_hours: number, _min?: number, _sec?: number, _ms?: number): number;
+  setUTCMilliseconds(_ms: number): number;
+  setUTCMinutes(_min: number, _sec?: number, _ms?: number): number;
+  setUTCMonth(_month: number, _date?: number): number;
+  setUTCSeconds(_sec: number, _ms?: number): number;
+}
+//#endregion
+//#region src/TimeSync.d.ts
+/**
+ * A collection of commonly-needed intervals (all defined in milliseconds).
+ */
+declare const refreshRates: Readonly<{
+  /**
+   * Indicates that a subscriber does not strictly need updates, but is still
+   * allowed to be updated if it would keep it in sync with other subscribers.
+   *
+   * If all subscribers use this update interval, TimeSync will never dispatch
+   * any updates.
+   */
+  idle: number;
+  halfSecond: number;
+  oneSecond: number;
+  thirtySeconds: number;
+  oneMinute: number;
+  fiveMinutes: number;
+  oneHour: number;
+}>;
+/**
+ * The set of readonly options that the TimeSync has been configured with.
+ */
+type Configuration = Readonly<{
+  /**
+   * Indicates whether the TimeSync instance should be frozen for Snapshot
+   * tests.
+   *
+   * Defaults to false.
+   */
+  freezeUpdates: boolean;
+  /**
+   * The minimum refresh interval (in milliseconds) to use when dispatching
+   * interval-based state updates.
+   *
+   * If a value smaller than this is specified when trying to set up a new
+   * 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
+   * get really hot and really tank performance elsewhere in an application.
+   *
+   * Defaults to 200ms.
+   */
+  minimumRefreshIntervalMs: number;
+  /**
+   * Indicates whether the same `onUpdate` callback (by reference) should be
+   * called multiple time if registered by multiple systems.
+   *
+   * Defaults to false.
+   */
+  allowDuplicateOnUpdateCalls: boolean;
+}>;
+/**
+ * The set of options that can be used to instantiate a TimeSync.
+ */
+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.
+   */
+  freezeUpdates: boolean;
+  /**
+   * The Date object to use when initializing TimeSync to make the
+   * constructor more pure and deterministic.
+   */
+  initialDate: Date;
+}>;
+/**
+ * The callback to call when a new state update is ready to be dispatched.
+ */
+type OnTimeSyncUpdate = (dateSnapshot: ReadonlyDate) => void;
+/**
+ * An object used to initialize a new subscription for TimeSync.
+ */
+type SubscriptionOptions = Readonly<{
+  /**
+   * The maximum update interval that a subscriber needs. A value of
+   * Number.POSITIVE_INFINITY indicates that the subscriber does not strictly
+   * need any updates (though they may still happen based on other
+   * subscribers).
+   *
+   * TimeSync always dispatches updates based on the lowest update interval
+   * among all subscribers.
+   *
+   * For example, let's say that we have these three subscribers:
+   * 1. A - Needs updates no slower than 500ms
+   * 2. B – Needs updates no slower than 1000ms
+   * 3. C – Uses interval of Infinity (does not strictly need an update)
+   *
+   * A, B, and C will all be updated at a rate of 500ms. If A unsubscribes,
+   * then B and C will shift to being updated every 1000ms. If B unsubscribes
+   * after A, updates will pause completely until a new subscriber gets
+   * added, and it has a non-infinite interval.
+   */
+  targetRefreshIntervalMs: number;
+  /**
+   * The callback to call when a new state update needs to be flushed amongst
+   * all subscribers.
+   */
+  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.
+ */
+type Snapshot = Readonly<{
+  /**
+   * The date that was last dispatched to all subscribers.
+   */
+  date: ReadonlyDate;
+  /**
+   * The number of subscribers registered with TimeSync.
+   */
+  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;
+}>;
+interface TimeSyncApi {
+  /**
+   * Subscribes an external system to TimeSync.
+   *
+   * The same callback (by reference) is allowed to be registered multiple
+   * times, either for the same update interval, or different update
+   * 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.
+   * @returns An unsubscribe callback. Calling the callback more than once
+   * results in a no-op.
+   */
+  subscribe: (options: SubscriptionOptions) => () => void;
+  /**
+   * Allows an external system to pull an immutable snapshot of some of the
+   * internal state inside TimeSync. The snapshot is frozen at runtime and
+   * cannot be mutated.
+   *
+   * @returns An object with multiple properties describing the TimeSync.
+   */
+  getStateSnapshot: () => Snapshot;
+  /**
+   * Resets all internal state in the TimeSync, and handles all cleanup for
+   * subscriptions and intervals previously set up. Configuration values are
+   * retained.
+   *
+   * This method can be used as a dispose method for a locally-scoped
+   * TimeSync (a TimeSync with no subscribers is safe to garbage-collect
+   * without any risks of memory leaks). It can also be used to reset a global
+   * TimeSync to its initial state for certain testing setups.
+   */
+  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
+ * 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.)
+ */
+declare class TimeSync implements TimeSyncApi {
+  #private;
+  constructor(options?: Partial<InitOptions>);
+  subscribe(sh: SubscriptionOptions): () => void;
+  getStateSnapshot(): Snapshot;
+  clearAll(): void;
+}
+//#endregion
+export { type Configuration, type InitOptions, type OnTimeSyncUpdate, ReadonlyDate, type Snapshot, type SubscriptionOptions, TimeSync, refreshRates };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/ReadonlyDate.ts","../src/TimeSync.ts"],"sourcesContent":[],"mappings":";;;AA8CA;;;;;;;;;ACvCA;AAqBA;AAoCA;;;;;AAuBA;AAKA;AAiCA;;;;;AAgBG;AAsFH;;;UDrMU,eAAA,CC2cK;EAuEM;;;kBD9gBJ;;;;;;;;;;;cAYJ,YAAA,SAAqB,IAAA,YAAgB;;2CAKR;;;;;;kBAgLzB;;;;;;;;;;;;;;;;;;;;AArLjB;;AAqLiB,cC5NJ,YD4NI,EC5NQ,QD4NR,CAAA;EArLiB;;;;;;ACvClC;EAqBY,IAAA,EAAA,MAAA;EAoCA,UAAA,EAAA,MAAW;EACtB,SAAA,EAAA,MAAA;EAec,aAAA,EAAA,MAAA;EAhBW,SAAA,EAAA,MAAA;EAAQ,WAAA,EAAA,MAAA;EAuBtB,OAAA,EAAA,MAAA;AAKZ,CAAA,CAAA;AAiCA;;;AAAuB,KAjGX,aAAA,GAAgB,QAiGL,CAAA;EAAQ;AAgB5B;AAsFH;;;;EA6UqB,aAAA,EAAA,OAAA;EA7UY;;;;;;;;;;;;;;;;;;;;;;;;;KAnKrB,WAAA,GAAc,SACzB;;;;;;;;;;;;;eAec;;;;;KAOH,gBAAA,kBAAkC;;;;KAKlC,mBAAA,GAAsB;;;;;;;;;;;;;;;;;;;;;;;;;YA0BvB;;;;;;KAOC,QAAA,GAAW;;;;QAIhB;;;;;;;;;UAWE;;UAGC,WAAA;;;;;;;;;;;;;;uBAcY;;;;;;;;0BASG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA6DZ,QAAA,YAAoB;;wBA0CV,QAAQ;gBA4NhB;sBAuEM"}