@antelopejs/dms 0.7.7 → 0.7.8

package/frontend-vue/layers/dms-ui/app/build/composables/live/currentPageLive.ts

@@ -0,0 +1,107 @@
+import {
+  computed,
+  getCurrentScope,
+  onScopeDispose,
+  shallowRef,
+  type ComputedRef,
+} from "vue";
+import type {
+  LiveSubscription,
+  PageLiveController,
+} from "./pageLiveController";
+
+// Client-only state: the page renderer sets it in the browser, where one app
+// shows one page at a time. The server renders no event and no refetch, so it
+// never needs one, and a module-level value there would be shared between
+// requests.
+const currentController = shallowRef<PageLiveController | null>(null);
+
+/**
+ * The live controller of the page on screen, `null` when the page has no
+ * `live` option (or while server-rendering).
+ *
+ * @internal
+ */
+export function currentPageLive(): PageLiveController | null {
+  return currentController.value;
+}
+
+/**
+ * Installs the controller of the page on screen. The page renderer calls it.
+ *
+ * @internal
+ */
+export function setCurrentPageLive(controller: PageLiveController | null) {
+  if (typeof window === "undefined") return;
+  currentController.value = controller;
+}
+
+/** @internal */
+export interface LiveGate {
+  /** An event behind the block arrived: refetch, now or later, or count it. */
+  trigger(event?: object): void;
+  /** Events the block missed while the page is paused. */
+  missed: ComputedRef<number>;
+  /** When the block last read through the gate (ms), 0 before or without `live`. */
+  lastReadAt: ComputedRef<number>;
+  /** Refetches now and forgets what was missed. */
+  catchUp(): void;
+  /** Records a read the caller makes itself (see LiveSubscription). */
+  acknowledge(): void;
+}
+
+interface BoundSubscription {
+  controller: PageLiveController;
+  subscription: LiveSubscription;
+}
+
+/**
+ * The gate a block's refetch goes through. On a page without `live` it calls
+ * `refresh` at once, as before. Bound lazily, on the first event, to the
+ * controller of the page on screen: a block of the page layout sets up before
+ * the page installs its controller.
+ *
+ * @internal
+ */
+export function useLiveGate(refresh: () => void): LiveGate {
+  const bound = shallowRef<BoundSubscription | null>(null);
+
+  const unbind = () => {
+    bound.value?.subscription.unsubscribe();
+    bound.value = null;
+  };
+
+  const resolve = (): LiveSubscription | null => {
+    const controller = currentController.value;
+    if (bound.value?.controller === controller) {
+      return bound.value?.subscription ?? null;
+    }
+    unbind();
+    if (!controller) return null;
+    bound.value = { controller, subscription: controller.subscribe(refresh) };
+    return bound.value.subscription;
+  };
+
+  if (getCurrentScope()) onScopeDispose(unbind);
+
+  const current = () =>
+    bound.value?.controller === currentController.value
+      ? (bound.value?.subscription ?? null)
+      : null;
+
+  return {
+    trigger: (event) => {
+      const subscription = resolve();
+      if (subscription) subscription.trigger(event);
+      else refresh();
+    },
+    missed: computed(() => current()?.missed.value ?? 0),
+    lastReadAt: computed(() => current()?.lastReadAt.value ?? 0),
+    catchUp: () => {
+      const subscription = resolve();
+      if (subscription) subscription.catchUp();
+      else refresh();
+    },
+    acknowledge: () => resolve()?.acknowledge(),
+  };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/live/formatElapsed.ts

@@ -0,0 +1,25 @@
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+const MINUTES_PER_HOUR = 60;
+
+/** The unit an elapsed time reads in: seconds, then minutes, then hours. */
+export type ElapsedUnit = "seconds" | "minutes" | "hours";
+
+export interface Elapsed {
+  unit: ElapsedUnit;
+  count: number;
+}
+
+/**
+ * A duration as "N s", "N min" or "N h": the largest unit it fills once,
+ * rounded down. A negative duration (a clock set back) reads as 0 s.
+ *
+ * @internal
+ */
+export function formatElapsed(elapsedMs: number): Elapsed {
+  const seconds = Math.max(0, Math.floor(elapsedMs / MS_PER_SECOND));
+  if (seconds < SECONDS_PER_MINUTE) return { unit: "seconds", count: seconds };
+  const minutes = Math.floor(seconds / SECONDS_PER_MINUTE);
+  if (minutes < MINUTES_PER_HOUR) return { unit: "minutes", count: minutes };
+  return { unit: "hours", count: Math.floor(minutes / MINUTES_PER_HOUR) };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/live/pageLiveController.ts

@@ -0,0 +1,229 @@
+import { readonly, ref, type Ref } from "vue";
+import type { PageLiveOptions } from "../../../types/live";
+
+const MS_PER_SECOND = 1000;
+const STORAGE_KEY_PREFIX = "dms.live.paused:";
+const PAUSED_VALUE = "1";
+
+/**
+ * One block or table of a live page: what it reads again, and what it missed
+ * while the page was paused.
+ *
+ * @internal
+ */
+export interface LiveSubscription {
+  /**
+   * An event behind the block arrived. `event` identifies it, so one event
+   * reaching several blocks counts once in the page's `missedCount`.
+   */
+  trigger(event?: object): void;
+  /** Events the block received while paused and has not read yet. */
+  readonly missed: Readonly<Ref<number>>;
+  /** When the block last read through the gate (ms since the epoch), 0 before. */
+  readonly lastReadAt: Readonly<Ref<number>>;
+  /** Reads now, whatever the state, and forgets what was missed. */
+  catchUp(): void;
+  /**
+   * Records a read the block made by itself (one the user asked for): it
+   * forgets what was missed, and a waiting trailing read is dropped.
+   */
+  acknowledge(): void;
+  unsubscribe(): void;
+}
+
+/**
+ * The Direct / Pause state of one page and the gate every refetch of its
+ * blocks goes through (see `PageLiveOptions` in interface-dms).
+ *
+ * @internal
+ */
+export interface PageLiveController {
+  readonly pageId: string;
+  readonly isPaused: Readonly<Ref<boolean>>;
+  /** When the page last read its data (ms since the epoch). */
+  readonly lastUpdatedAt: Readonly<Ref<number>>;
+  /** Distinct events received since the pause. */
+  readonly missedCount: Readonly<Ref<number>>;
+  pause(): void;
+  resume(): void;
+  toggle(): void;
+  subscribe(refresh: () => void): LiveSubscription;
+  dispose(): void;
+}
+
+interface SubscriberState {
+  refresh: () => void;
+  missed: Ref<number>;
+  lastRunAt: Ref<number>;
+  timer: ReturnType<typeof setTimeout> | null;
+  /** The event the trailing call stands for, counted if the page pauses first. */
+  pendingEvent: object | undefined;
+}
+
+/** Browser storage of the paused pages; absent on the server or when denied. */
+function liveStorage(): Storage | undefined {
+  try {
+    return typeof window === "undefined" ? undefined : window.localStorage;
+  } catch {
+    return undefined;
+  }
+}
+
+function readStoredPause(pageId: string): boolean {
+  return liveStorage()?.getItem(STORAGE_KEY_PREFIX + pageId) === PAUSED_VALUE;
+}
+
+function storePause(pageId: string, isPaused: boolean): void {
+  const storage = liveStorage();
+  if (!storage) return;
+  try {
+    if (isPaused) storage.setItem(STORAGE_KEY_PREFIX + pageId, PAUSED_VALUE);
+    else storage.removeItem(STORAGE_KEY_PREFIX + pageId);
+  } catch {
+    // A full or locked storage only loses the memory of the choice.
+  }
+}
+
+class PageLive implements PageLiveController {
+  readonly isPaused: Readonly<Ref<boolean>>;
+  readonly lastUpdatedAt: Readonly<Ref<number>>;
+  readonly missedCount: Readonly<Ref<number>>;
+  private readonly paused: Ref<boolean>;
+  private readonly updatedAt = ref(Date.now());
+  private readonly missedTotal = ref(0);
+  private readonly subscribers = new Set<SubscriberState>();
+  private countedEvents = new WeakSet<object>();
+  private readonly minIntervalMs: number;
+
+  constructor(
+    readonly pageId: string,
+    options: PageLiveOptions,
+  ) {
+    this.minIntervalMs = (options.maxRate ?? 0) * MS_PER_SECOND;
+    this.paused = ref(readStoredPause(pageId));
+    this.isPaused = readonly(this.paused);
+    this.lastUpdatedAt = readonly(this.updatedAt);
+    this.missedCount = readonly(this.missedTotal);
+  }
+
+  pause(): void {
+    if (this.paused.value) return;
+    this.paused.value = true;
+    storePause(this.pageId, true);
+    // A trailing read still waiting stands for an event not shown yet.
+    for (const state of this.subscribers) {
+      if (!state.timer) continue;
+      const event = state.pendingEvent;
+      clearTimer(state);
+      this.countMissed(state, event);
+    }
+  }
+
+  resume(): void {
+    if (!this.paused.value) return;
+    this.paused.value = false;
+    storePause(this.pageId, false);
+    this.missedTotal.value = 0;
+    this.countedEvents = new WeakSet();
+    this.updatedAt.value = Date.now();
+    for (const state of this.subscribers) {
+      if (state.missed.value === 0) continue;
+      state.missed.value = 0;
+      this.run(state);
+    }
+  }
+
+  toggle(): void {
+    if (this.paused.value) this.resume();
+    else this.pause();
+  }
+
+  subscribe(refresh: () => void): LiveSubscription {
+    const state: SubscriberState = {
+      refresh,
+      missed: ref(0),
+      lastRunAt: ref(0),
+      timer: null,
+      pendingEvent: undefined,
+    };
+    this.subscribers.add(state);
+    return {
+      trigger: (event) => this.trigger(state, event),
+      missed: readonly(state.missed),
+      lastReadAt: readonly(state.lastRunAt),
+      catchUp: () => {
+        state.missed.value = 0;
+        this.run(state);
+      },
+      acknowledge: () => {
+        state.missed.value = 0;
+        this.markRead(state);
+      },
+      unsubscribe: () => {
+        clearTimer(state);
+        this.subscribers.delete(state);
+      },
+    };
+  }
+
+  dispose(): void {
+    for (const state of this.subscribers) clearTimer(state);
+    this.subscribers.clear();
+  }
+
+  private trigger(state: SubscriberState, event: object | undefined): void {
+    if (this.paused.value) this.countMissed(state, event);
+    else this.triggerDirect(state, event);
+  }
+
+  // Leading and trailing: the first event of a quiet block reads at once, the
+  // ones within `maxRate` of a read collapse into one read when it ends, so
+  // the last event of a burst is never lost.
+  private triggerDirect(state: SubscriberState, event: object | undefined) {
+    if (state.timer) return;
+    const wait = state.lastRunAt.value + this.minIntervalMs - Date.now();
+    if (wait <= 0) {
+      this.run(state);
+      return;
+    }
+    state.pendingEvent = event;
+    state.timer = setTimeout(() => this.run(state), wait);
+  }
+
+  private run(state: SubscriberState): void {
+    this.markRead(state);
+    state.refresh();
+  }
+
+  private markRead(state: SubscriberState): void {
+    clearTimer(state);
+    state.lastRunAt.value = Date.now();
+    this.updatedAt.value = state.lastRunAt.value;
+  }
+
+  private countMissed(state: SubscriberState, event: object | undefined) {
+    state.missed.value += 1;
+    if (event && this.countedEvents.has(event)) return;
+    if (event) this.countedEvents.add(event);
+    this.missedTotal.value += 1;
+  }
+}
+
+function clearTimer(state: SubscriberState): void {
+  if (state.timer) clearTimeout(state.timer);
+  state.timer = null;
+  state.pendingEvent = undefined;
+}
+
+/**
+ * The controller of a page declared with `live`. Starts in the state the
+ * browser remembers for `pageId`, Direct otherwise.
+ *
+ * @internal
+ */
+export function createPageLiveController(
+  pageId: string,
+  options: PageLiveOptions,
+): PageLiveController {
+  return new PageLive(pageId, options);
+}

package/frontend-vue/layers/dms-ui/app/build/composables/live/shortcuts.ts

@@ -0,0 +1,8 @@
+/** Switches the page between Direct and Pause, while a LiveToggle is on it. */
+export const LIVE_TOGGLE_L_METADATA: ShortcutMetadata = {
+  key: ["l"],
+  descriptionKey: "$dms.shortcuts.livetoggle.l.description",
+  component: "$dms.components.livetoggle",
+};
+
+export const LIVE_TOGGLE_SHORTCUTS_METADATA = [LIVE_TOGGLE_L_METADATA];

package/frontend-vue/layers/dms-ui/app/build/composables/live/useLiveToggleShortcut.ts

@@ -0,0 +1,25 @@
+import { onBeforeUnmount, onMounted } from "vue";
+
+// The toggles mounted on the page, in mount order: the first one owns the L
+// key, so a page showing two toggles still switches once per press.
+const claims: symbol[] = [];
+
+/**
+ * Binds L to `toggle` for the first LiveToggle mounted on the page; the next
+ * one takes over when it goes.
+ *
+ * @internal
+ */
+export function useLiveToggleShortcut(toggle: () => void): void {
+  const claim = Symbol("live-toggle");
+  onMounted(() => claims.push(claim));
+  onBeforeUnmount(() => {
+    const index = claims.indexOf(claim);
+    if (index >= 0) claims.splice(index, 1);
+  });
+  defineShortcuts({
+    l: () => {
+      if (claims[0] === claim) toggle();
+    },
+  });
+}

package/frontend-vue/layers/dms-ui/app/build/composables/live/usePageLiveHost.ts

@@ -0,0 +1,46 @@
+import { onScopeDispose, watch } from "vue";
+import type { PageLiveOptions } from "../../../types/live";
+import { setCurrentPageLive } from "./currentPageLive";
+import {
+  createPageLiveController,
+  type PageLiveController,
+} from "./pageLiveController";
+
+/** The page the renderer shows: its id and its `live` option. */
+export interface PageLiveSource {
+  pageId: string | undefined;
+  live: PageLiveOptions | undefined;
+}
+
+/**
+ * Gives the page on screen its live controller while it declares `live`, and
+ * a new one when the renderer moves to another page. Browser only.
+ *
+ * @internal
+ */
+export function usePageLiveHost(source: () => PageLiveSource): void {
+  if (typeof window === "undefined") return;
+  let controller: PageLiveController | null = null;
+
+  const install = (next: PageLiveController | null) => {
+    controller?.dispose();
+    controller = next;
+    setCurrentPageLive(next);
+  };
+
+  watch(
+    () => {
+      const { pageId, live } = source();
+      return pageId && live ? JSON.stringify([pageId, live]) : "";
+    },
+    (key) => {
+      const { pageId, live } = source();
+      install(
+        key && pageId && live ? createPageLiveController(pageId, live) : null,
+      );
+    },
+    { immediate: true },
+  );
+
+  onScopeDispose(() => install(null));
+}