@antelopejs/dms 0.7.7 → 0.7.9

package/frontend-vue/tests/page-live-gate.test.ts

@@ -0,0 +1,241 @@
+// @vitest-environment jsdom
+/**
+ * The Direct / Pause valve of a page declared with `live`: in Direct a block
+ * refetches on its events at most once per `maxRate` (the last event of a
+ * burst included), paused it requests nothing and counts what it missed, and
+ * resuming refetches once each block that missed something. The choice is
+ * kept per page in the browser, and a page without `live` is untouched.
+ */
+import { createApp, defineComponent, h } from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import type { RealtimeTopicHandler } from "../layers/dms-core/app/composables/realtime/useUserRealtime";
+import {
+  refreshLivePageBlocks,
+  refreshPageBlocks,
+} from "../layers/dms-ui/app/utils/blockRefresh";
+import {
+  createPageLiveController,
+  type PageLiveController,
+} from "../layers/dms-ui/app/build/composables/live/pageLiveController";
+import { setCurrentPageLive } from "../layers/dms-ui/app/build/composables/live/currentPageLive";
+import { usePageLive } from "../layers/dms-ui/app/composables/live/usePageLive";
+
+const topicHandlers = new Map<string, RealtimeTopicHandler[]>();
+
+vi.mock("../layers/dms-core/app/composables/realtime/useRealtimeTopic", () => ({
+  useRealtimeTopic: (topic: string, handler: RealtimeTopicHandler) => {
+    topicHandlers.set(topic, [...(topicHandlers.get(topic) ?? []), handler]);
+  },
+}));
+
+const { useRefreshTriggers } = await import(
+  "../layers/dms-ui/app/build/composables/blocks/useRefreshTriggers"
+);
+
+const PAGE = "monitoring.logs";
+const TOPIC = "api:requests";
+const MAX_RATE_SECONDS = 5;
+const MAX_RATE_MS = MAX_RATE_SECONDS * 1000;
+const mounted: Array<{ unmount: () => void }> = [];
+const controllers: PageLiveController[] = [];
+
+function publish(topic = TOPIC) {
+  const event = { topic, type: "request", ts: Date.now() };
+  for (const handler of topicHandlers.get(topic) ?? []) handler(event);
+}
+
+function mountBlock(topic: string | undefined = TOPIC) {
+  const onRefresh = vi.fn();
+  const app = createApp(
+    defineComponent({
+      setup() {
+        useRefreshTriggers(topic, onRefresh);
+        return () => h("div");
+      },
+    }),
+  );
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+  return onRefresh;
+}
+
+function installLive(maxRate?: number): PageLiveController {
+  const controller = createPageLiveController(PAGE, { maxRate });
+  controllers.push(controller);
+  setCurrentPageLive(controller);
+  return controller;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  topicHandlers.clear();
+  window.localStorage.clear();
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+  controllers.splice(0).forEach((controller) => controller.dispose());
+  setCurrentPageLive(null);
+  vi.useRealTimers();
+});
+
+it("leaves a page without live as it was: every event refetches", () => {
+  const onRefresh = mountBlock();
+  publish();
+  publish();
+  refreshPageBlocks();
+  refreshLivePageBlocks();
+  expect(onRefresh).toHaveBeenCalledTimes(4);
+  expect(usePageLive().isEnabled.value).toBe(false);
+  expect(usePageLive().isLive.value).toBe(true);
+});
+
+it("refetches on each event in Direct when no maxRate is set", () => {
+  installLive();
+  const onRefresh = mountBlock();
+  publish();
+  publish();
+  expect(onRefresh).toHaveBeenCalledTimes(2);
+});
+
+it("in Direct, refetches at most once per maxRate, the last event trailing", () => {
+  installLive(MAX_RATE_SECONDS);
+  const onRefresh = mountBlock();
+
+  publish();
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(1000);
+  publish();
+  vi.advanceTimersByTime(1000);
+  publish();
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(MAX_RATE_MS - 2000);
+  expect(onRefresh).toHaveBeenCalledTimes(2);
+
+  vi.advanceTimersByTime(MAX_RATE_MS * 2);
+  expect(onRefresh).toHaveBeenCalledTimes(2);
+});
+
+it("caps each block on its own", () => {
+  installLive(MAX_RATE_SECONDS);
+  const first = mountBlock();
+  const second = mountBlock("api:routes");
+  publish();
+  publish("api:routes");
+  expect(first).toHaveBeenCalledTimes(1);
+  expect(second).toHaveBeenCalledTimes(1);
+});
+
+it("in Pause, requests nothing and counts the events per block", () => {
+  const live = installLive();
+  const logs = mountBlock();
+  const chart = mountBlock();
+  const routes = mountBlock("api:routes");
+  live.pause();
+
+  publish();
+  publish();
+  refreshLivePageBlocks();
+  vi.advanceTimersByTime(60_000);
+
+  expect(logs).not.toHaveBeenCalled();
+  expect(chart).not.toHaveBeenCalled();
+  expect(routes).not.toHaveBeenCalled();
+  // Two events and a live refresh, each counted once for the page although
+  // two blocks (three for the refresh) received them.
+  expect(live.missedCount.value).toBe(3);
+  expect(usePageLive().isPaused.value).toBe(true);
+});
+
+it("refreshes on a user's refreshPageBlocks even while paused", () => {
+  const live = installLive(MAX_RATE_SECONDS);
+  const onRefresh = mountBlock();
+  live.pause();
+  publish();
+  expect(live.missedCount.value).toBe(1);
+
+  refreshPageBlocks();
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+  expect(live.isPaused.value).toBe(true);
+
+  // Read by the user, the block has nothing left to read on resume.
+  live.resume();
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+});
+
+it("caps a live refresh like a realtime event in Direct", () => {
+  installLive(MAX_RATE_SECONDS);
+  const onRefresh = mountBlock(undefined);
+  refreshLivePageBlocks();
+  refreshLivePageBlocks();
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+  vi.advanceTimersByTime(MAX_RATE_MS);
+  expect(onRefresh).toHaveBeenCalledTimes(2);
+});
+
+it("on resume, refetches once each block that missed an event", () => {
+  const live = installLive(MAX_RATE_SECONDS);
+  const logs = mountBlock();
+  const routes = mountBlock("api:routes");
+  publish("api:routes");
+  routes.mockClear();
+  live.pause();
+
+  publish();
+  publish();
+  publish();
+  live.resume();
+
+  expect(logs).toHaveBeenCalledTimes(1);
+  expect(routes).not.toHaveBeenCalled();
+  expect(live.missedCount.value).toBe(0);
+  vi.advanceTimersByTime(MAX_RATE_MS);
+  expect(logs).toHaveBeenCalledTimes(1);
+});
+
+it("keeps a trailing refetch the pause interrupted for the resume", () => {
+  const live = installLive(MAX_RATE_SECONDS);
+  const onRefresh = mountBlock();
+  publish();
+  publish();
+  live.pause();
+  vi.advanceTimersByTime(MAX_RATE_MS);
+  expect(onRefresh).toHaveBeenCalledTimes(1);
+  expect(live.missedCount.value).toBe(1);
+
+  live.resume();
+  expect(onRefresh).toHaveBeenCalledTimes(2);
+});
+
+it("dates the page's last update from its refetches", () => {
+  const live = installLive();
+  mountBlock();
+  const before = live.lastUpdatedAt.value;
+  vi.advanceTimersByTime(4000);
+  publish();
+  expect(live.lastUpdatedAt.value).toBe(before + 4000);
+});
+
+it("remembers the choice per page in the browser", () => {
+  installLive().pause();
+  expect(createPageLiveController(PAGE, {}).isPaused.value).toBe(true);
+  expect(createPageLiveController("monitoring.routes", {}).isPaused.value).toBe(
+    false,
+  );
+
+  createPageLiveController(PAGE, {}).resume();
+  expect(createPageLiveController(PAGE, {}).isPaused.value).toBe(false);
+});
+
+it("follows the page through usePageLive", () => {
+  installLive();
+  const state = usePageLive();
+  expect(state.isEnabled.value).toBe(true);
+  state.pause();
+  expect(state.isPaused.value).toBe(true);
+  expect(state.isLive.value).toBe(false);
+  state.toggle();
+  expect(state.isPaused.value).toBe(false);
+});

package/frontend-vue/tests/period-live-pause.test.ts

@@ -0,0 +1,120 @@
+// @vitest-environment jsdom
+/**
+ * A rolling period (`last-hour`, `last-24h`) slides every minute, and every
+ * block reading it refetches. On a paused live page the period holds still,
+ * so nothing refetches on the clock; a period the user picks still applies at
+ * once, and resuming catches the skipped minutes up in one read.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createApp, defineComponent, h, ref } from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import { createPageLiveController } from "../layers/dms-ui/app/build/composables/live/pageLiveController";
+import { setCurrentPageLive } from "../layers/dms-ui/app/build/composables/live/currentPageLive";
+import { usePageLive } from "../layers/dms-ui/app/composables/live/usePageLive";
+import {
+  usePeriod,
+  type UsePeriodReturn,
+} from "../layers/dms-core/app/composables/period/usePeriod";
+import { registerPeriodScope } from "../layers/dms-core/app/composables/period/usePeriodScope";
+
+const requests: string[] = [];
+
+vi.stubGlobal("useAuthFetch", () => ({
+  $authFetch: async (url: string) => {
+    requests.push(url);
+    return { value: requests.length };
+  },
+}));
+vi.stubGlobal("useDmsRoute", () => ({ query: {} }));
+vi.stubGlobal("ref", ref);
+
+const { useChartFetch } = await import(
+  "../layers/dms-ui/app/composables/chart/useChartFetch"
+);
+
+const SCOPE = "live-period";
+const MINUTE_MS = 60_000;
+const apps: Array<() => void> = [];
+
+function mountPageWithChart(): UsePeriodReturn {
+  let period: UsePeriodReturn | undefined;
+  const app = createApp(
+    defineComponent({
+      setup() {
+        const { isPaused } = usePageLive();
+        // As the PeriodSelector wires it.
+        period = usePeriod({
+          defaultPreset: "last-hour",
+          holdClock: () => isPaused.value,
+        });
+        registerPeriodScope(SCOPE, period.state);
+        useChartFetch({ fetchUrl: "/api/chart", periodScope: SCOPE });
+        return () => h("div");
+      },
+    }),
+  );
+  app.mount(document.createElement("div"));
+  apps.push(() => app.unmount());
+  return period!;
+}
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  requests.length = 0;
+  window.localStorage.clear();
+});
+
+afterEach(() => {
+  apps.splice(0).forEach((unmount) => unmount());
+  setCurrentPageLive(null);
+  vi.useRealTimers();
+});
+
+it("slides and refetches every minute in Direct", async () => {
+  setCurrentPageLive(createPageLiveController("api.overview", {}));
+  mountPageWithChart();
+  await vi.advanceTimersByTimeAsync(1000);
+  expect(requests).toHaveLength(1);
+
+  await vi.advanceTimersByTimeAsync(2 * MINUTE_MS);
+  expect(requests).toHaveLength(3);
+});
+
+it("holds the period while paused, but follows the user's pick", async () => {
+  const live = createPageLiveController("api.overview", {});
+  setCurrentPageLive(live);
+  const period = mountPageWithChart();
+  await vi.advanceTimersByTimeAsync(1000);
+  expect(requests).toHaveLength(1);
+
+  live.pause();
+  const heldKey = period.state.value.key;
+  await vi.advanceTimersByTimeAsync(3 * MINUTE_MS);
+  expect(requests).toHaveLength(1);
+  expect(period.state.value.key).toBe(heldKey);
+
+  period.setPreset("last-24h");
+  await vi.advanceTimersByTimeAsync(1000);
+  expect(requests).toHaveLength(2);
+  expect(requests[1]).toContain("preset=last-24h");
+
+  await vi.advanceTimersByTimeAsync(2 * MINUTE_MS);
+  expect(requests).toHaveLength(2);
+
+  live.resume();
+  await vi.advanceTimersByTimeAsync(1000);
+  expect(requests).toHaveLength(3);
+  expect(period.state.value.key).not.toBe(heldKey);
+});
+
+it("holds the selector's period on the page's pause", () => {
+  const source = readFileSync(
+    resolve(
+      __dirname,
+      "../layers/dms-ui/app/components/period/PeriodSelector.vue",
+    ),
+    "utf8",
+  );
+  expect(source).toContain("holdClock: () => isPagePaused.value,");
+});

package/frontend-vue/tests/period-selector-url.test.ts

@@ -0,0 +1,268 @@
+// @vitest-environment jsdom
+/**
+ * A PeriodSelector keeps its period in the page URL: the period it starts
+ * from (the URL, then the user's last choice, then its default), the server
+ * render (no flash of the default), the in-place write on a change (no new
+ * history entry), and the period following a route changed from outside.
+ */
+import {
+  createApp,
+  createSSRApp,
+  defineComponent,
+  h,
+  nextTick,
+  reactive,
+  type App,
+} from "vue";
+import { renderToString } from "vue/server-renderer";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { PeriodPreset } from "../layers/dms-core/app/composables/period/types";
+
+const route = reactive<{ query: Record<string, string> }>({ query: {} });
+const preferences = new Map<string, unknown>();
+
+vi.stubGlobal("useDmsRoute", () => route);
+// Inertia's client-side replace moves its page URL, which the DMS route
+// follows: the route then holds the query the browser shows.
+const { inertiaReplace } = vi.hoisted(() => ({
+  inertiaReplace: vi.fn(({ url }: { url: string }) => {
+    route.query = Object.fromEntries(
+      new URL(url, "http://dms.local").searchParams,
+    );
+  }),
+}));
+vi.mock("@inertiajs/vue3", () => ({ router: { replace: inertiaReplace } }));
+vi.stubGlobal("usePreferences", () => ({
+  getPreference: <T>(key: string, fallback?: T) =>
+    (preferences.get(key) as T | undefined) ?? fallback,
+  setPreference: (key: string, value: unknown) => preferences.set(key, value),
+}));
+
+const { usePeriod } = await import(
+  "../layers/dms-core/app/composables/period/usePeriod"
+);
+const { usePeriodLocation, PERIOD_PREFERENCE_KEY } = await import(
+  "../layers/dms-ui/app/build/composables/period/usePeriodLocation"
+);
+
+type Period = ReturnType<typeof usePeriod>;
+
+const PAGE_ID = "dashboard";
+const PAGE_PATH = "/dashboard";
+const handles: Record<string, Period> = {};
+
+/** The selector's state wiring, as PeriodSelector.vue does it in setup. */
+function selector(id: string, defaultPreset: PeriodPreset = "this-month") {
+  return defineComponent({
+    setup() {
+      const period = usePeriod({
+        defaultPreset,
+        presets: ["last-7-days", "last-30-days", "this-month", "custom"],
+      });
+      usePeriodLocation(period, {
+        id,
+        pageId: PAGE_ID,
+        fallback: {
+          preset: period.preset.value,
+          comparison: period.comparison.value,
+          customRange: null,
+          customCompareRange: null,
+        },
+      });
+      handles[id] = period;
+      return () =>
+        h("span", `${period.preset.value}|${period.comparison.value}`);
+    },
+  });
+}
+
+const mounted: App[] = [];
+
+function mount(...ids: string[]): void {
+  const app = createApp({
+    setup: () => () =>
+      h(
+        "div",
+        ids.map((id) => h(selector(id))),
+      ),
+  });
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+}
+
+const search = () => new URLSearchParams(window.location.search);
+
+const remember = (query: Record<string, string>) =>
+  preferences.set(PERIOD_PREFERENCE_KEY, { [`${PAGE_ID}#page`]: query });
+
+beforeEach(() => {
+  route.query = {};
+  preferences.clear();
+  inertiaReplace.mockClear();
+  window.history.replaceState(null, "", PAGE_PATH);
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+});
+
+describe("the period a selector starts from", () => {
+  it("is the URL's", () => {
+    route.query = {
+      "page.period": "last-7-days",
+      "page.compare": "previous-year",
+    };
+    remember({
+      period: "last-30-days",
+    });
+    mount("page");
+    expect(handles.page!.preset.value).toBe("last-7-days");
+    expect(handles.page!.comparison.value).toBe("previous-year");
+  });
+
+  it("is the user's last choice when the URL names none", () => {
+    remember({
+      period: "last-30-days",
+      compare: "previous-period",
+    });
+    mount("page");
+    expect(handles.page!.preset.value).toBe("last-30-days");
+    expect(handles.page!.comparison.value).toBe("previous-period");
+  });
+
+  it("is the default when neither names a valid one", () => {
+    route.query = { "page.period": "next-century" };
+    remember({
+      period: "ytd",
+    });
+    mount("page");
+    expect(handles.page!.preset.value).toBe("this-month");
+    expect(handles.page!.comparison.value).toBe("none");
+  });
+
+  it("is a custom range read from the URL", () => {
+    route.query = { "page.from": "2026-10-01", "page.to": "2026-10-15" };
+    mount("page");
+    expect(handles.page!.preset.value).toBe("custom");
+    expect(handles.page!.state.value.range).toEqual({
+      from: new Date(2026, 9, 1),
+      to: new Date(2026, 9, 15, 23, 59, 59, 999),
+    });
+  });
+
+  it("is rendered by the server, so the default never flashes", async () => {
+    route.query = { "page.period": "last-7-days" };
+    const html = await renderToString(createSSRApp(selector("page")));
+    expect(html).toContain("last-7-days|none");
+  });
+});
+
+describe("the URL on load", () => {
+  it("carries the period the selector starts from, the default included", () => {
+    window.history.replaceState(null, "", `${PAGE_PATH}?requests.tab=get`);
+    mount("page");
+    expect(Object.fromEntries(search())).toEqual({
+      "requests.tab": "get",
+      "page.period": "this-month",
+      "page.compare": "none",
+    });
+  });
+
+  it("is left alone when it already names the period", () => {
+    window.history.replaceState(
+      null,
+      "",
+      `${PAGE_PATH}?page.period=this-month&page.compare=none`,
+    );
+    route.query = { "page.period": "this-month", "page.compare": "none" };
+    mount("page");
+    expect(inertiaReplace).not.toHaveBeenCalled();
+  });
+});
+
+describe("a change of period", () => {
+  it("reaches the route, so a tab written from it keeps the new period", async () => {
+    mount("page");
+    handles.page!.setPreset("last-7-days");
+    await nextTick();
+    // What useTab does: the route's query, plus its own key.
+    const query = { ...route.query, tab: "2" };
+    window.history.replaceState(
+      null,
+      "",
+      `${PAGE_PATH}?${new URLSearchParams(query)}`,
+    );
+    expect(search().get("tab")).toBe("2");
+    expect(search().get("page.period")).toBe("last-7-days");
+    expect(handles.page!.preset.value).toBe("last-7-days");
+  });
+
+  it("replaces the URL in place and remembers the choice", async () => {
+    mount("page");
+    const entries = window.history.length;
+    handles.page!.setPreset("last-7-days");
+    handles.page!.setComparison("previous-period");
+    await nextTick();
+    expect(search().get("page.period")).toBe("last-7-days");
+    expect(search().get("page.compare")).toBe("previous-period");
+    expect(window.history.length).toBe(entries);
+    expect(
+      (preferences.get(PERIOD_PREFERENCE_KEY) as Record<string, unknown>)[
+        `${PAGE_ID}#page`
+      ],
+    ).toEqual({ period: "last-7-days", compare: "previous-period" });
+  });
+
+  it("swaps the preset key for the custom range keys", async () => {
+    window.history.replaceState(
+      null,
+      "",
+      `${PAGE_PATH}?page.period=last-7-days`,
+    );
+    mount("page");
+    handles.page!.setCustomRange({
+      from: new Date(2026, 9, 1),
+      to: new Date(2026, 9, 2, 23, 59, 59, 999),
+    });
+    await nextTick();
+    expect(search().get("page.period")).toBeNull();
+    expect(search().get("page.from")).toBe("2026-10-01");
+    expect(search().get("page.to")).toBe("2026-10-02");
+  });
+
+  it("leaves another selector's keys and the other parameters alone", async () => {
+    window.history.replaceState(null, "", `${PAGE_PATH}?requests.tab=get`);
+    mount("sales", "traffic");
+    handles.sales!.setPreset("last-7-days");
+    await nextTick();
+    handles.traffic!.setPreset("last-30-days");
+    await nextTick();
+    expect(Object.fromEntries(search())).toEqual({
+      "requests.tab": "get",
+      "sales.period": "last-7-days",
+      "sales.compare": "none",
+      "traffic.period": "last-30-days",
+      "traffic.compare": "none",
+    });
+    expect(handles.sales!.preset.value).toBe("last-7-days");
+  });
+});
+
+describe("a route changed from outside", () => {
+  it("moves the period of the selector it names", async () => {
+    mount("sales", "traffic");
+    route.query = { "sales.period": "last-30-days" };
+    await nextTick();
+    expect(handles.sales!.preset.value).toBe("last-30-days");
+    expect(handles.traffic!.preset.value).toBe("this-month");
+  });
+
+  it("keeps the period when it names an invalid one", async () => {
+    mount("page");
+    handles.page!.setPreset("last-7-days");
+    await nextTick();
+    route.query = { "page.period": "last-decade" };
+    await nextTick();
+    expect(handles.page!.preset.value).toBe("last-7-days");
+  });
+});