sailfork / t3code-github / packages/ client-runtime/ src/ clock.ts

// @effect-diagnostics globalTimers:off globalDate:off - Render clocks for React hooks, outside an Effect runtime.

/**
 * A `useSyncExternalStore`-shaped clock. Snapshots stay cached between
 * notifications while subscribed, as `useSyncExternalStore` requires.
 */
export interface ClockStore<A> {
  readonly subscribe: (listener: () => void) => () => void;
  readonly getSnapshot: () => A;
}

// setTimeout fires immediately for delays beyond a signed 32-bit int.
const MAX_TIMEOUT_MS = 2_147_483_647;

function makeTickStore<A>(read: () => A, periodMs: number): ClockStore<A> {
  let value = read();
  let timer: ReturnType<typeof setTimeout> | undefined;
  const listeners = new Set<() => void>();

  // Each tick lands on a wall-clock boundary so every subscriber updates in
  // the same frame instead of each drifting on its own phase.
  const schedule = () => {
    timer = setTimeout(
      () => {
        timer = undefined;
        const next = read();
        if (next !== value) {
          value = next;
          for (const listener of listeners) listener();
        }
        // Listeners may unsubscribe (stopping the clock) or resubscribe (arming
        // a fresh timer) while notified; only continue a clock nobody re-armed.
        if (listeners.size > 0 && timer === undefined) schedule();
      },
      periodMs - (Date.now() % periodMs),
    );
  };

  return {
    subscribe: (listener) => {
      if (listeners.size === 0) {
        value = read();
        schedule();
      }
      listeners.add(listener);
      return () => {
        listeners.delete(listener);
        if (listeners.size === 0) {
          clearTimeout(timer);
          timer = undefined;
        }
      };
    },
    getSnapshot: () => {
      if (timer === undefined) value = read();
      return value;
    },
  };
}

/** Epoch ms floored to the second, advancing on each wall-clock second. */
export const secondTick: ClockStore<number> = makeTickStore(
  () => Math.floor(Date.now() / 1000) * 1000,
  1000,
);

/** ISO timestamp truncated to the minute (`YYYY-MM-DDTHH:mm`). */
export const minuteTick: ClockStore<string> = makeTickStore(
  () => new Date().toISOString().slice(0, 16),
  60_000,
);

export interface DeadlineStore extends ClockStore<boolean> {
  /**
   * Re-checks `Date.now()` and notifies if the deadline has passed. For callers
   * that observe the deadline first, e.g. a click after a throttled or slept
   * timer, so the snapshot catches up without waiting for the late timer.
   */
  readonly refresh: () => void;
}

const neverPassed: DeadlineStore = {
  subscribe: () => () => {},
  getSnapshot: () => false,
  refresh: () => {},
};

interface DeadlineEntry {
  readonly store: DeadlineStore;
  readonly listeners: Set<() => void>;
  passed: boolean;
  timer: ReturnType<typeof setTimeout> | undefined;
}

// The single owner of each subscribed deadline. Handles obtained before the
// entry exists join it on subscribe, so they share its timer and notifications.
const deadlines = new Map<number, DeadlineEntry>();

function passDeadline(entry: DeadlineEntry) {
  clearTimeout(entry.timer);
  entry.timer = undefined;
  entry.passed = true;
  for (const listener of entry.listeners) listener();
}

function armDeadline(entry: DeadlineEntry, deadlineMs: number) {
  const delay = deadlineMs - Date.now();
  if (delay <= 0) {
    passDeadline(entry);
    return;
  }
  entry.timer = setTimeout(() => armDeadline(entry, deadlineMs), Math.min(delay, MAX_TIMEOUT_MS));
}

/** The epoch-ms deadline `delayMs` from now, for `deadlineStore`. */
export function deadlineAfter(delayMs: number): number {
  return Date.now() + delayMs;
}

/**
 * Whether `Date.now()` has reached `deadlineMs`. One timer per distinct
 * deadline, shared by its subscribers; once passed the snapshot stays true.
 * Deadlines register only while subscribed, so renders React discards leak nothing.
 * A non-finite deadline never passes.
 */
export function deadlineStore(deadlineMs: number | null): DeadlineStore {
  if (deadlineMs === null || !Number.isFinite(deadlineMs)) return neverPassed;
  const existing = deadlines.get(deadlineMs);
  if (existing !== undefined) return existing.store;

  const store: DeadlineStore = {
    subscribe: (listener) => {
      let entry = deadlines.get(deadlineMs);
      if (entry === undefined) {
        entry = { store, listeners: new Set(), passed: Date.now() >= deadlineMs, timer: undefined };
        deadlines.set(deadlineMs, entry);
        if (!entry.passed) armDeadline(entry, deadlineMs);
      }
      const joined = entry;
      joined.listeners.add(listener);
      return () => {
        joined.listeners.delete(listener);
        if (joined.listeners.size > 0) return;
        clearTimeout(joined.timer);
        joined.timer = undefined;
        if (deadlines.get(deadlineMs) === joined) deadlines.delete(deadlineMs);
      };
    },
    getSnapshot: () => deadlines.get(deadlineMs)?.passed ?? Date.now() >= deadlineMs,
    refresh: () => {
      const entry = deadlines.get(deadlineMs);
      if (entry !== undefined && !entry.passed && Date.now() >= deadlineMs) passDeadline(entry);
    },
  };
  return store;
}