@buenos-nachos/time-sync 0.5.4 → 0.6.0

package/dist/index.d.ts

@@ -0,0 +1,315 @@
+//#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.
+ */
+interface Configuration {
+  /**
+   * Indicates whether the TimeSync instance should be frozen for Snapshot
+   * tests. Highly encouraged that you use this together with
+   * `initialDate`.
+   *
+   * Defaults to false.
+   */
+  readonly 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 can make the event loop
+   * get really hot and really tank performance elsewhere in an application.
+   *
+   * Defaults to 200ms.
+   */
+  readonly minimumRefreshIntervalMs: number;
+  /**
+   * Indicates whether the same `onUpdate` callback (by reference) should be
+   * called multiple time if registered by multiple systems.
+   *
+   * 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;
+}
+/**
+ * The set of options that can be used to instantiate a TimeSync.
+ */
+interface InitOptions extends Configuration {
+  /**
+   * 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.
+ */
+interface SubscriptionInitOptions {
+  /**
+   * 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.
+   */
+  readonly targetRefreshIntervalMs: number;
+  /**
+   * The callback to call when a new state update needs to be flushed amongst
+   * all subscribers.
+   */
+  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.
+ */
+interface Snapshot {
+  /**
+   * The date that TimeSync last processed. This will always match the date that
+   * was last dispatched to all subscribers, but if no updates have been issued,
+   * this value will match the date used to instantiate the TimeSync.
+   */
+  readonly date: ReadonlyDate;
+  /**
+   * The monotonic milliseconds that elapsed between the TimeSync being
+   * instantiated and the last update being dispatched.
+   *
+   * Will be null if no updates have ever been dispatched.
+   */
+  readonly lastUpdatedAtMs: number | null;
+  /**
+   * The number of subscribers registered with TimeSync.
+   */
+  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.
+   */
+  readonly config: Configuration;
+}
+/**
+ * An object with information about a specific subscription registered with
+ * TimeSync. The entire context is frozen at runtime.
+ */
+interface SubscriptionContext {
+  /**
+   * A reference to the TimeSync instance that the subscription was registered
+   * with.
+   */
+  readonly timeSync: TimeSync;
+  /**
+   * The effective interval that the subscription is updating at. This may be a
+   * value larger than than the target refresh interval, depending on whether
+   * TimeSync was configured with a minimum refresh value.
+   */
+  readonly refreshIntervalMs: number;
+  /**
+   * The unsubscribe callback associated with a subscription. This is the same
+   * callback returned by `TimeSync.subscribe`.
+   */
+  readonly unsubscribe: () => void;
+  /**
+   * The monotonic milliseconds that elapsed between the TimeSync being
+   * instantiated and the subscription being registered.
+   */
+  readonly registeredAtMs: number;
+}
+/**
+ * The callback to call when a new state update is ready to be dispatched.
+ */
+type OnTimeSyncUpdate = (newDate: ReadonlyDate, context: SubscriptionContext) => void;
+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.
+   *
+   * 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.
+   */
+  subscribe: (options: SubscriptionInitOptions) => () => 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(options: SubscriptionInitOptions): () => void;
+  getStateSnapshot(): Snapshot;
+  clearAll(): void;
+}
+//#endregion
+export { type Configuration, type InitOptions, type OnTimeSyncUpdate, ReadonlyDate, type Snapshot, type SubscriptionContext, type SubscriptionInitOptions, TimeSync, refreshRates };