@antelopejs/dms 0.9.8 → 0.10.0

package/frontend-vue/layers/dms-core/app/build/utils/sharedRealtimeConnection.ts

@@ -0,0 +1,410 @@
+import {
+  isUnauthorizedStreamError,
+  openSseStream,
+  type SseStreamHandle,
+} from "../../composables/realtime/useSseStream";
+import {
+  browserCrossTabEnvironment,
+  type CrossTabEnvironment,
+  electLeader,
+  holdLock,
+  openTabBus,
+  type TabBus,
+  tabLockName,
+  whenReleased,
+} from "./crossTab";
+
+/**
+ * The realtime connection one browser shares between its tabs: the elected tab
+ * holds `GET /api/realtime/connection` and relays it, each tab opens its own
+ * session on it. See `crossTab.ts` for why.
+ *
+ * @internal
+ */
+
+const HELLO_EVENT = "hello";
+const SESSION_EVENT = "session";
+const SESSION_HEADER = "x-realtime-session";
+const CONNECTION_HEADER = "x-realtime-connection";
+const RECONNECT_INITIAL_DELAY_MS = 500;
+const RECONNECT_MAX_DELAY_MS = 30_000;
+const RECONNECT_MULTIPLIER = 2;
+
+interface ConnectionMessage {
+  kind: "connection";
+  /** `null` while the leader has no stream open. */
+  connectionId: string | null;
+}
+
+interface FrameMessage {
+  kind: "frame";
+  connectionId: string;
+  /** Unset on a frame of the connection itself, which every tab receives. */
+  sessionId?: string;
+  event: string;
+  data: unknown;
+}
+
+/** A tab joining asks the leader for the connection it holds. */
+interface QueryMessage {
+  kind: "query";
+}
+
+/** A tab's session on the connection, for the leader to end once it goes. */
+interface SessionMessage {
+  kind: "session";
+  connectionId: string;
+  sessionId: string;
+  tabId: string;
+}
+
+/**
+ * A tab whose session request the backend answered without knowing the
+ * connection asks the leader to open a new one.
+ */
+interface ReopenMessage {
+  kind: "reopen";
+  connectionId: string;
+}
+
+type HubMessage =
+  | ConnectionMessage
+  | FrameMessage
+  | QueryMessage
+  | SessionMessage
+  | ReopenMessage;
+
+export interface StreamRecovery {
+  refreshSession: () => Promise<boolean>;
+  redirectToAuth: () => Promise<void>;
+}
+
+export interface SharedRealtimeConnectionOptions extends StreamRecovery {
+  /** Scopes the election and the relay: one connection per name. */
+  name: string;
+  streamUrl: string;
+  sessionCloseUrl: string;
+  /** The connection to open a session on; `undefined` while there is none. */
+  onConnection: (connectionId: string | undefined) => void;
+  /**
+   * A frame of one tab's session, or of the connection itself (the dev
+   * reload signal) when `sessionId` is unset.
+   */
+  onFrame: (
+    sessionId: string | undefined,
+    eventName: string,
+    data: unknown,
+  ) => void;
+  environment?: CrossTabEnvironment;
+}
+
+export interface SharedRealtimeConnection {
+  /** Hands this tab's session to the leader, which ends it once the tab goes. */
+  announceSession: (connectionId: string, sessionId: string) => void;
+  /**
+   * Asks the leader to replace `connectionId` with a new stream: the backend
+   * answered a session request on it as a connection it does not know.
+   */
+  reopen: (connectionId: string) => void;
+  leave: () => void;
+}
+
+export interface Reconnector {
+  isCancelled(): boolean;
+  schedule(open: () => void): void;
+  resetDelay(): void;
+  cancel(): void;
+}
+
+export const createReconnector = (): Reconnector => {
+  let isCancelled = false;
+  let delay = RECONNECT_INITIAL_DELAY_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return {
+    isCancelled: () => isCancelled,
+    schedule: (open) => {
+      // A pending reconnect absorbs concurrent triggers: one attempt at a time.
+      if (isCancelled || timer) return;
+      timer = setTimeout(() => {
+        timer = undefined;
+        open();
+      }, delay);
+      delay = Math.min(delay * RECONNECT_MULTIPLIER, RECONNECT_MAX_DELAY_MS);
+    },
+    resetDelay: () => {
+      delay = RECONNECT_INITIAL_DELAY_MS;
+    },
+    cancel: () => {
+      isCancelled = true;
+      if (timer) clearTimeout(timer);
+      timer = undefined;
+    },
+  };
+};
+
+/** Retries after a failure, refreshing the browser session first on a 401. */
+export const recoverFromError = (
+  error: unknown,
+  retry: () => void,
+  recovery: StreamRecovery,
+): void => {
+  if (!isUnauthorizedStreamError(error)) {
+    retry();
+    return;
+  }
+  void recovery.refreshSession().then((isRefreshed) => {
+    if (isRefreshed) {
+      retry();
+    } else {
+      void recovery.redirectToAuth();
+    }
+  }, retry);
+};
+
+interface StreamCallbacks extends StreamRecovery {
+  onEvent: (eventName: string, data: unknown) => void;
+  onDisconnected: () => void;
+}
+
+interface KeptStream {
+  /** Drops the open stream and opens a new one. */
+  reopen: () => void;
+  stop: () => void;
+}
+
+/**
+ * Keeps one stream open until cancelled. The server ends the stream when it
+ * stops (a dev reload included), so a clean EOF reconnects just like an error
+ * does: the stream has no business completion.
+ */
+const connectWithBackoff = (
+  url: string,
+  callbacks: StreamCallbacks,
+): KeptStream => {
+  const reconnector = createReconnector();
+  let activeHandle: SseStreamHandle | undefined;
+  const open = () => {
+    if (reconnector.isCancelled()) return;
+    activeHandle?.close();
+    const handle: SseStreamHandle = openSseStream({
+      url,
+      onEvent: (eventName, data) => {
+        if (handle !== activeHandle) return;
+        reconnector.resetDelay();
+        callbacks.onEvent(eventName, data);
+      },
+      onError: (error) => {
+        if (!retire(handle)) return;
+        recoverFromError(error, reconnect, callbacks);
+      },
+      onClose: (reason) => {
+        if (reason !== "eof" || !retire(handle)) return;
+        reconnect();
+      },
+    });
+    activeHandle = handle;
+  };
+  const reconnect = () => reconnector.schedule(open);
+  const retire = (handle: SseStreamHandle): boolean => {
+    if (handle !== activeHandle || reconnector.isCancelled()) return false;
+    activeHandle = undefined;
+    callbacks.onDisconnected();
+    return true;
+  };
+  open();
+  return {
+    reopen: () => {
+      const handle = activeHandle;
+      if (!handle || !retire(handle)) return;
+      handle.close();
+      reconnect();
+    },
+    stop: () => {
+      reconnector.cancel();
+      activeHandle?.close();
+      activeHandle = undefined;
+    },
+  };
+};
+
+const readConnectionId = (data: unknown): string | null => {
+  const connectionId = (data as { connectionId?: unknown } | null)
+    ?.connectionId;
+  return typeof connectionId === "string" ? connectionId : null;
+};
+
+interface SessionFrame {
+  sessionId?: unknown;
+  event?: unknown;
+  data?: unknown;
+}
+
+interface LeaderContext {
+  options: SharedRealtimeConnectionOptions;
+  environment: CrossTabEnvironment;
+  bus: TabBus;
+  tabId: string;
+}
+
+const closeSession = (
+  url: string,
+  connectionId: string,
+  sessionId: string,
+): void => {
+  void fetch(url, {
+    method: "POST",
+    headers: { [CONNECTION_HEADER]: connectionId, [SESSION_HEADER]: sessionId },
+    credentials: "include",
+  }).catch(() => {});
+};
+
+/**
+ * The elected tab's share: the stream, relayed on the bus, and the sessions
+ * of the other tabs, each ended once its tab is gone.
+ */
+const lead = ({ options, environment, bus, tabId }: LeaderContext) => {
+  const watchers = new AbortController();
+  const sessionsByTab = new Map<string, Set<string>>();
+  let connectionId: string | null = null;
+
+  const publish = (next: string | null) => {
+    connectionId = next;
+    bus.post({ kind: "connection", connectionId: next });
+  };
+
+  const endSessionsOf = (otherTabId: string) => {
+    const sessionIds = sessionsByTab.get(otherTabId) ?? new Set<string>();
+    sessionsByTab.delete(otherTabId);
+    // The sessions of a connection that went ended with it.
+    if (!connectionId) return;
+    for (const sessionId of sessionIds) {
+      closeSession(options.sessionCloseUrl, connectionId, sessionId);
+    }
+  };
+
+  const watchSession = (message: SessionMessage) => {
+    // This tab's own sessions end with the stream it holds.
+    if (message.tabId === tabId || message.connectionId !== connectionId) {
+      return;
+    }
+    const known = sessionsByTab.get(message.tabId);
+    if (known) {
+      known.add(message.sessionId);
+      return;
+    }
+    sessionsByTab.set(message.tabId, new Set([message.sessionId]));
+    whenReleased(
+      tabLockName(options.name, message.tabId),
+      environment,
+      () => endSessionsOf(message.tabId),
+      watchers.signal,
+    );
+  };
+
+  const unlisten = bus.listen((raw) => {
+    const message = raw as HubMessage;
+    if (message.kind === "query")
+      bus.post({ kind: "connection", connectionId });
+    if (message.kind === "session") watchSession(message);
+    if (message.kind === "reopen" && message.connectionId === connectionId) {
+      stream.reopen();
+    }
+  });
+
+  // The tabs may still hold the connection of a leader that went: they drop it.
+  publish(null);
+  const stream = connectWithBackoff(options.streamUrl, {
+    onEvent: (eventName, data) => {
+      if (eventName === HELLO_EVENT) {
+        sessionsByTab.clear();
+        publish(readConnectionId(data));
+        return;
+      }
+      if (!connectionId) return;
+      if (eventName !== SESSION_EVENT) {
+        bus.post({ kind: "frame", connectionId, event: eventName, data });
+        return;
+      }
+      const frame = data as SessionFrame | null;
+      if (typeof frame?.sessionId !== "string") return;
+      if (typeof frame.event !== "string") return;
+      bus.post({
+        kind: "frame",
+        connectionId,
+        sessionId: frame.sessionId,
+        event: frame.event,
+        data: frame.data,
+      });
+    },
+    onDisconnected: () => publish(null),
+    refreshSession: options.refreshSession,
+    redirectToAuth: options.redirectToAuth,
+  });
+
+  return () => {
+    watchers.abort();
+    unlisten();
+    stream.stop();
+    publish(null);
+  };
+};
+
+const createTabId = (): string =>
+  globalThis.crypto?.randomUUID?.() ??
+  `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
+/**
+ * Joins the browser's realtime connection for `options.name`, electing this
+ * tab to hold it when no other tab does.
+ */
+export function joinSharedRealtimeConnection(
+  options: SharedRealtimeConnectionOptions,
+): SharedRealtimeConnection {
+  const environment = options.environment ?? browserCrossTabEnvironment();
+  const tabId = createTabId();
+  const bus = openTabBus(options.name, environment);
+  // Held before any session is announced: the leader waits on it to learn
+  // that this tab went.
+  const tabLock = holdLock(tabLockName(options.name, tabId), environment);
+  let connectionId: string | undefined;
+
+  const unlisten = bus.listen((raw) => {
+    const message = raw as HubMessage;
+    if (message.kind === "connection") {
+      const next = message.connectionId ?? undefined;
+      if (next === connectionId) return;
+      connectionId = next;
+      options.onConnection(next);
+      return;
+    }
+    if (message.kind === "frame" && message.connectionId === connectionId) {
+      options.onFrame(message.sessionId, message.event, message.data);
+    }
+  });
+
+  const resign = electLeader(options.name, environment, () =>
+    lead({ options, environment, bus, tabId }),
+  );
+  bus.post({ kind: "query" });
+
+  return {
+    announceSession: (sessionConnectionId, sessionId) => {
+      void tabLock.held.then(() =>
+        bus.post({
+          kind: "session",
+          connectionId: sessionConnectionId,
+          sessionId,
+          tabId,
+        }),
+      );
+    },
+    reopen: (reopenedConnectionId) =>
+      bus.post({ kind: "reopen", connectionId: reopenedConnectionId }),
+    leave: () => {
+      resign();
+      unlisten();
+      tabLock.release();
+      bus.close();
+    },
+  };
+}

package/frontend-vue/layers/dms-core/app/composables/auth/useApiData.ts

@@ -6,7 +6,8 @@ import type {
   UseDmsPagedDataOptions,
   UseFetchOptions,
 } from "#dms/frontend-module";
-import type { MaybeRefOrGetter } from "vue";
+import { getCurrentInstance, toValue, watch, type MaybeRefOrGetter } from "vue";
+import { useLivePauseSource } from "../live/livePauseSource";
 
 /** The authenticated fetch `useAuthFetch` returns. */
 type AuthFetch = ReturnType<typeof useAuthFetch>["$authFetch"];
@@ -61,7 +62,9 @@ export type ApiDataResult<T> = DmsAsyncDataResult<T>;
  * - `refreshInterval: ms` reads again on an interval while the caller shows
  *   the data and the page is visible: polling. A ref or a getter changes it,
  *   and `0` or `null` stops it; a call from a plugin polls for as long as
- *   the application runs.
+ *   the application runs. On a page declared with `live`, a component's
+ *   polling stops while the page is paused, and reads once on resume if a
+ *   poll fell due meanwhile.
  * - The page's refreshes (`refreshPageBlocks()`) and the events of its
  *   realtime topics read the data again; `refreshOnPageRefresh: false` opts
  *   out, for data with refresh triggers of its own.
@@ -88,15 +91,74 @@ export function useApiData<T>(
 ): ApiDataResult<T> {
   const { $authFetch } = useAuthFetch();
   if (typeof handlerOrOptions === "function")
-    return useDmsAsyncData<T>(
-      source,
-      ({ signal }) => handlerOrOptions({ $authFetch, signal }),
+    return followLivePause(
+      useDmsAsyncData<T>(
+        source,
+        ({ signal }) => handlerOrOptions({ $authFetch, signal }),
+        gateLivePolling(options),
+      ),
       options,
     );
-  return useDmsFetch<T>(source, {
-    ...handlerOrOptions,
-    $fetch: $authFetch as UseFetchOptions<T>["$fetch"],
+  return followLivePause(
+    useDmsFetch<T>(source, {
+      ...gateLivePolling(handlerOrOptions),
+      $fetch: $authFetch as UseFetchOptions<T>["$fetch"],
+    }),
+    handlerOrOptions,
+  );
+}
+
+/** The options of a read that polls, as far as its live gate goes. */
+interface PolledReadOptions {
+  refreshInterval?: MaybeRefOrGetter<number | null | undefined>;
+  immediate?: boolean;
+}
+
+// A component's polling is one more read nobody asked for: on a live page it
+// stops while the page is paused, as the blocks' refetches do. A plugin's
+// polling (the shell's, outside any page) keeps running. The pause is read
+// through the app's `LIVE_PAUSE_SOURCE`, which the UI layer provides.
+function isGatedPolling(
+  options: PolledReadOptions | undefined,
+): options is PolledReadOptions {
+  return options?.refreshInterval !== undefined && !!getCurrentInstance();
+}
+
+/** `options` with a `refreshInterval` that is `null` while the page is paused. */
+function gateLivePolling<O extends PolledReadOptions>(
+  options: O | undefined,
+): O | undefined {
+  if (!isGatedPolling(options)) return options;
+  const interval = options.refreshInterval;
+  const isPaused = useLivePauseSource();
+  return {
+    ...options,
+    refreshInterval: () => (isPaused() ? null : toValue(interval)),
+  };
+}
+
+/**
+ * Reads once as the page resumes when a poll fell due while it was paused:
+ * the polling restarts with a full interval, which would show the data of
+ * before the pause that long.
+ */
+function followLivePause<
+  R extends Pick<DmsAsyncDataResult<unknown>, "status" | "refresh">,
+>(result: R, options: PolledReadOptions | undefined): R {
+  if (typeof window === "undefined" || !isGatedPolling(options)) return result;
+  let pausedAt = 0;
+  watch(useLivePauseSource(), (isPaused) => {
+    if (isPaused) {
+      pausedAt = Date.now();
+      return;
+    }
+    const period = toValue(options.refreshInterval);
+    if (!period || period <= 0 || Date.now() - pausedAt < period) return;
+    // Data a caller waits to `execute()` is not read before it is.
+    if (result.status.value === "idle" && options.immediate === false) return;
+    void result.refresh({ dedupe: "defer" });
   });
+  return result;
 }
 
 /** What a handler reading one page of API data receives. */
@@ -139,10 +201,13 @@ export function useApiPagedData<TPage, TCursor = unknown>(
   options: UseDmsPagedDataOptions<TPage, TCursor>,
 ): ApiPagedDataResult<TPage, TCursor> {
   const { $authFetch } = useAuthFetch();
-  return useDmsPagedData<TPage, TCursor>(
-    key,
-    ({ cursor, index, signal }) =>
-      handler({ $authFetch, cursor, index, signal }),
+  return followLivePause(
+    useDmsPagedData<TPage, TCursor>(
+      key,
+      ({ cursor, index, signal }) =>
+        handler({ $authFetch, cursor, index, signal }),
+      gateLivePolling(options) ?? options,
+    ),
     options,
   );
 }

package/frontend-vue/layers/dms-core/app/composables/data-types/useDataType.ts

@@ -36,6 +36,24 @@ export type DataTypeValueComparer = (
   options?: unknown,
 ) => boolean;
 
+/**
+ * The value a filter chip's editor holds for a filter value a view declared
+ * as text (`"0"`, `"2026-10-01,2026-10-15"`), under a compare mode: a number
+ * input refuses `"0"`, a date range wants its two days. The filter itself
+ * keeps its text, so the query is unchanged.
+ */
+export type DataTypeFilterEditorValue = (text: string, mode: string) => unknown;
+
+/**
+ * Where the rows a value names are read: the `select` route of the table a
+ * relation points to, and the keys its rows carry their label and value under
+ * (`label` and `value` unless mapped).
+ */
+export interface DataTypeSelectSource {
+  searchUrl: string;
+  keyMapping?: { label?: string; value?: string };
+}
+
 export interface DataType {
   id: string;
   formatter?: RecordWithDefault<DataTypeFormatter>;
@@ -46,6 +64,14 @@ export interface DataType {
    * or whose order does not count. Without it, values compare deeply.
    */
   isSameValue?: DataTypeValueComparer;
+  /** Without it, a filter's editor reads a declared text value as is. */
+  filterEditorValue?: DataTypeFilterEditorValue;
+  /**
+   * For a type whose value holds the ids of rows another table serves (a
+   * relation): where those rows are read, from the options of the type's
+   * control. A filter chip or a read-only list names the ids through it.
+   */
+  selectSource?: (options: unknown) => DataTypeSelectSource | undefined;
   displayComponent?: Component;
 }
 const dataTypes: Record<string, DataType> = {};

package/frontend-vue/layers/dms-core/app/composables/hydration/isHydratingComponent.ts

@@ -0,0 +1,29 @@
+import { getCurrentInstance } from "vue";
+
+/**
+ * Whether the component setting up or rendering now is hydrating the
+ * server's HTML.
+ *
+ * Vue binds a hydrating component's vnode to its server-rendered node before
+ * its setup runs, where a fresh mount has no node until it is mounted; once
+ * mounted, the component no longer hydrates. So this is true from the setup
+ * to the first render of a component the browser takes over from the server,
+ * and false in a client navigation, on a later re-render, on the server, and
+ * outside a component.
+ *
+ * Read it where the browser must draw what the server drew: a part drawn
+ * in the browser only, or a value only the browser knows (local storage, the
+ * clock), waits until mounted while hydrating, and shows at once anywhere
+ * else. Call it before the setup's first `await`, while the component is
+ * still Vue's current instance. Data needs no check: `useApiData` hands the
+ * server's answer to the browser on its own.
+ *
+ * ```ts
+ * const isDrawn = ref(!import.meta.env.SSR && !isHydratingComponent());
+ * onMounted(() => (isDrawn.value = true));
+ * ```
+ */
+export function isHydratingComponent(): boolean {
+  const instance = getCurrentInstance();
+  return !!instance && !instance.isMounted && !!instance.vnode.el;
+}

package/frontend-vue/layers/dms-core/app/composables/live/livePauseSource.ts

@@ -0,0 +1,29 @@
+import { inject, type InjectionKey } from "vue";
+
+/**
+ * Whether the page on screen is paused right now (by the user, a hold or a
+ * hidden tab). Reactive: it reads reactive state, so a `watch` or a
+ * `computed` over it follows the pause.
+ */
+export type LivePauseSource = () => boolean;
+
+/**
+ * The extension point the core layer reads a page's pause through. The core
+ * owns `useApiData` but not the page's live controller: the layer that owns
+ * the controller provides a source at the app level
+ * (`app.provide(LIVE_PAUSE_SOURCE, source)`), so every component reads the
+ * same page, drawers and modals included. Without one, nothing is paused.
+ */
+export const LIVE_PAUSE_SOURCE: InjectionKey<LivePauseSource> = Symbol(
+  "dms-live-pause-source",
+);
+
+const NEVER_PAUSED: LivePauseSource = () => false;
+
+/**
+ * The pause source of the app the calling component belongs to; never
+ * paused without one. Call it in a component setup.
+ */
+export function useLivePauseSource(): LivePauseSource {
+  return inject(LIVE_PAUSE_SOURCE, NEVER_PAUSED);
+}