@antelopejs/dms 0.8.3 → 0.9.1

package/frontend-vue/tests/file-read-urls.test.ts

@@ -1,31 +1,116 @@
-import { effectScope, onScopeDispose, ref } from "vue";
+// @vitest-environment jsdom
+/**
+ * Stored files' read URLs through the runtime's real async data: a key
+ * resolved in a component's setup is read with the page (the server waits for
+ * it and hands it over), every component showing a file shares its read, and
+ * in the browser the URL is read again before it expires and a failure that
+ * may heal is retried.
+ */
+import {
+  computed,
+  defineComponent,
+  effectScope,
+  h,
+  inject,
+  nextTick,
+  onScopeDispose,
+  ref,
+  shallowReactive,
+  watch,
+  type App,
+} from "vue";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  browserRuntime,
+  hydrate,
+  mountInBrowser,
+  serverRender,
+  stubApiData,
+} from "./helpers/api-data-runtime";
 import { useFileReadUrls } from "../layers/dms-ui/app/composables/useFileReadUrls";
+import { FORM_CONTENT_LANGUAGE_KEY } from "../layers/dms-ui/app/composables/form/types/content-language";
 
 const RESOURCE_KEY = "localized/private.png";
 const START_TIME = new Date("2026-09-14T12:00:00Z");
 const URL_TTL_MS = 60000;
 
 const authFetch = vi.fn();
+const mounted: App[] = [];
 
-describe("file read URLs", () => {
-  beforeEach(() => {
+/** An avatar as the identity cell draws it: resolved from an immediate watcher. */
+const Avatar = defineComponent({
+  props: { fileKey: { type: String, required: true } },
+  setup(props) {
+    const { getUrl, resolve } = useFileReadUrls();
+    watch(
+      () => props.fileKey,
+      (key) => void resolve(key),
+      { immediate: true },
+    );
+    return () => h("img", { src: getUrl(props.fileKey) ?? "" });
+  },
+});
+
+const metadataCalls = () =>
+  authFetch.mock.calls.filter(([url]) => url === "/api/files/metadata");
+
+beforeEach(() => {
+  vi.stubEnv("SSR", false);
+  vi.stubGlobal("CONTENT_LANGUAGE_HEADER", "x-content-language");
+  vi.stubGlobal("computed", computed);
+  vi.stubGlobal("watch", watch);
+  vi.stubGlobal("onScopeDispose", onScopeDispose);
+  vi.stubGlobal("shallowReactive", shallowReactive);
+  vi.stubGlobal("inject", inject);
+  stubApiData(authFetch);
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+  vi.unstubAllEnvs();
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  vi.resetAllMocks();
+});
+
+describe("file read URLs in a server render", () => {
+  it("renders the URL a setup resolves, and the browser hydrates without asking again", async () => {
+    authFetch.mockResolvedValue({
+      url: "https://example.test/avatar",
+      expiresAt: Date.now() + URL_TTL_MS,
+    });
+    const Row = defineComponent({
+      setup: () => () =>
+        h("div", [
+          h(Avatar, { fileKey: RESOURCE_KEY }),
+          h(Avatar, { fileKey: RESOURCE_KEY }),
+        ]),
+    });
+
+    vi.stubEnv("SSR", true);
+    const { html, payload } = await serverRender(Row);
     vi.stubEnv("SSR", false);
-    vi.useFakeTimers();
-    vi.setSystemTime(START_TIME);
-    vi.stubGlobal("ref", ref);
-    vi.stubGlobal("onScopeDispose", onScopeDispose);
-    vi.stubGlobal("inject", () => "*");
-    vi.stubGlobal("FORM_CONTENT_LANGUAGE_KEY", Symbol());
-    vi.stubGlobal("CONTENT_LANGUAGE_HEADER", "x-content-language");
-    vi.stubGlobal("useAuthFetch", () => ({ $authFetch: authFetch }));
+    expect(html).toBe(
+      '<div><img src="https://example.test/avatar"><img src="https://example.test/avatar"></div>',
+    );
+    // Two avatars of one file: one read.
+    expect(metadataCalls()).toHaveLength(1);
+
+    authFetch.mockClear();
+    const { app, container } = hydrate(Row, html, payload);
+    mounted.push(app);
+    await nextTick();
+    await new Promise((done) => setTimeout(done, 0));
+    expect(authFetch).not.toHaveBeenCalled();
+    expect(container.innerHTML).toBe(html);
   });
+});
 
-  afterEach(() => {
-    vi.unstubAllEnvs();
-    vi.useRealTimers();
-    vi.unstubAllGlobals();
-    vi.resetAllMocks();
+describe("file read URLs in the browser", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(START_TIME);
+    browserRuntime();
   });
 
   it("preserves expiry and refreshes a visible URL before it expires", async () => {
@@ -74,15 +159,23 @@ describe("file read URLs", () => {
 
   it("uses the full localized form language for metadata authorization", async () => {
     authFetch.mockResolvedValue({ url: "https://example.test/file" });
-    const scope = effectScope();
-    const urls = scope.run(() => useFileReadUrls("private"))!;
-    await urls.resolve(RESOURCE_KEY);
-
+    const Field = defineComponent({
+      setup() {
+        const { getUrl, resolve } = useFileReadUrls("private");
+        void resolve(RESOURCE_KEY);
+        return () => h("img", { src: getUrl(RESOURCE_KEY) ?? "" });
+      },
+    });
+    const { app } = mountInBrowser(Field, (application) =>
+      application.provide(FORM_CONTENT_LANGUAGE_KEY, "*"),
+    );
+    mounted.push(app);
+    await vi.advanceTimersByTimeAsync(0);
     expect(authFetch).toHaveBeenCalledWith("/api/files/metadata", {
       query: { resourceKey: RESOURCE_KEY, storage: "private" },
       headers: { "x-content-language": "*" },
+      signal: expect.any(AbortSignal),
     });
-    scope.stop();
   });
 
   it("retries the first failed lookup while the component stays mounted", async () => {
@@ -91,13 +184,26 @@ describe("file read URLs", () => {
       .mockResolvedValueOnce({ url: "https://example.test/recovered" });
     const scope = effectScope();
     const urls = scope.run(() => useFileReadUrls())!;
-    await urls.resolve(RESOURCE_KEY);
+    await urls.resolve(RESOURCE_KEY).catch(() => {});
     expect(urls.getUrl(RESOURCE_KEY)).toBeUndefined();
     await vi.advanceTimersByTimeAsync(5000);
     expect(urls.getUrl(RESOURCE_KEY)).toBe("https://example.test/recovered");
     scope.stop();
   });
 
+  it("does not retry a file the server refuses", async () => {
+    authFetch.mockRejectedValue(
+      Object.assign(new Error("Not found"), { statusCode: 404 }),
+    );
+    const scope = effectScope();
+    const urls = scope.run(() => useFileReadUrls())!;
+    await urls.resolve(RESOURCE_KEY).catch(() => {});
+    await vi.advanceTimersByTimeAsync(60000);
+    expect(authFetch).toHaveBeenCalledTimes(1);
+    expect(urls.getUrl(RESOURCE_KEY)).toBeUndefined();
+    scope.stop();
+  });
+
   it("does not restart refresh timers when an in-flight lookup finishes after disposal", async () => {
     let finish!: (value: unknown) => void;
     authFetch.mockReturnValue(
@@ -113,23 +219,28 @@ describe("file read URLs", () => {
       url: "https://example.test/late",
       expiresAt: Date.now() + URL_TTL_MS,
     });
-    await pending;
+    await pending.catch(() => {});
     await vi.advanceTimersByTimeAsync(URL_TTL_MS * 2);
     expect(authFetch).toHaveBeenCalledTimes(1);
     expect(vi.getTimerCount()).toBe(0);
   });
 
-  it("resolves metadata during SSR without scheduling browser refresh timers", async () => {
-    vi.stubEnv("SSR", true);
-    authFetch.mockResolvedValue({
-      url: "https://example.test/ssr",
-      expiresAt: Date.now() + URL_TTL_MS,
+  it("reads a key resolved after the setup, as an upload's", async () => {
+    authFetch.mockResolvedValue({ url: "https://example.test/uploaded" });
+    const key = ref<string | null>(null);
+    const Uploaded = defineComponent({
+      setup() {
+        const { getUrl, resolve } = useFileReadUrls();
+        watch(key, (value) => value && void resolve(value));
+        return () => h("img", { src: key.value ? getUrl(key.value) : "" });
+      },
     });
-    const scope = effectScope();
-    const urls = scope.run(() => useFileReadUrls())!;
-    await urls.resolve(RESOURCE_KEY);
-    expect(urls.getUrl(RESOURCE_KEY)).toBe("https://example.test/ssr");
-    expect(vi.getTimerCount()).toBe(0);
-    scope.stop();
+    const { app, container } = mountInBrowser(Uploaded);
+    mounted.push(app);
+    key.value = "uploads/new.png";
+    await vi.advanceTimersByTimeAsync(0);
+    expect(container.querySelector("img")?.getAttribute("src")).toBe(
+      "https://example.test/uploaded",
+    );
   });
 });

package/frontend-vue/tests/file-unavailable.test.ts

@@ -7,11 +7,13 @@ import {
   inject,
   onScopeDispose,
   ref,
+  shallowReactive,
   watch,
   type App,
 } from "vue";
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
 import File from "../layers/dms-ui/app/components/form/components/File.vue";
+import { browserRuntime, stubApiData } from "./helpers/api-data-runtime";
 
 const STORED_KEY = "files/profile/avatar.pdf";
 const authFetch = vi.fn();
@@ -29,6 +31,7 @@ function mountFile(): { app: App; container: HTMLElement } {
     render: () => h(File, { modelValue: STORED_KEY }),
   });
   app.config.globalProperties.$t = (key: string) => key;
+  browserRuntime(app);
   app.component("UFileUpload", passthrough);
   app.component("ULink", passthrough);
   app.component("UButton", defineComponent({ setup: () => () => h("button") }));
@@ -54,7 +57,8 @@ beforeEach(() => {
   vi.stubGlobal("FORM_FIELD_LOADING_KEY", Symbol());
   vi.stubGlobal("FORM_CONTENT_LANGUAGE_KEY", Symbol());
   vi.stubGlobal("CONTENT_LANGUAGE_HEADER", "x-content-language");
-  vi.stubGlobal("useAuthFetch", () => ({ $authFetch: authFetch }));
+  vi.stubGlobal("shallowReactive", shallowReactive);
+  stubApiData(authFetch);
   vi.stubGlobal("useUploadWithProgress", () => ({
     uploadWithProgress: vi.fn(),
   }));

package/frontend-vue/tests/fixtures/dataEngine.ts

@@ -0,0 +1,44 @@
+/**
+ * The renderer's real data layer for a test: its async data, state and cookie
+ * composables, and dms-core's `useApiData` over the test's `useAuthFetch`
+ * stub, as the auto-imports a layer reaches. Each call starts a fresh runtime
+ * — a browser one under jsdom, a server one otherwise — so no data a test
+ * loaded leaks into the next.
+ */
+import { createApp } from "vue";
+import { vi } from "vitest";
+
+const engine = await import("#dms/frontend-module");
+const { useApiData, useApiPagedData } = await import(
+  "../../layers/dms-core/app/composables/auth/useApiData"
+);
+
+const ENGINE_GLOBALS = {
+  useDmsAsyncData: engine.useDmsAsyncData,
+  useDmsFetch: engine.useDmsFetch,
+  useDmsPagedData: engine.useDmsPagedData,
+  useDmsState: engine.useDmsState,
+  useDmsCookie: engine.useDmsCookie,
+  useApiData,
+  useApiPagedData,
+};
+
+export function useRealDataEngine(): ReturnType<
+  typeof engine.createDmsFrontendRuntime
+> {
+  for (const [name, composable] of Object.entries(ENGINE_GLOBALS))
+    vi.stubGlobal(name, composable);
+  const isServer = typeof window === "undefined";
+  const runtime = engine.createDmsFrontendRuntime(
+    undefined,
+    undefined,
+    isServer,
+  );
+  if (isServer) engine.setDmsServerRuntimeResolver(() => runtime);
+  else
+    engine.provideDmsFrontendRuntime(
+      createApp({ render: () => null }),
+      runtime,
+    );
+  return runtime;
+}

package/frontend-vue/tests/form-load-error.test.ts

@@ -1,5 +1,5 @@
 import { readFileSync } from "node:fs";
-import { createSSRApp, defineComponent, h, ref } from "vue";
+import { createSSRApp, defineComponent, h, nextTick, ref } from "vue";
 import { renderToString } from "vue/server-renderer";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import FormLoadError from "../layers/dms-ui/app/build/components/form/FormLoadError.vue";
@@ -66,6 +66,41 @@ describe("a form's record load", () => {
     expect(apply).toHaveBeenCalledWith(ROW);
   });
 
+  it("takes a later read of the record, its values becoming the saved ones", async () => {
+    const apply = vi.fn();
+    const onReloaded = vi.fn();
+    const source = loadOf(ROW, null);
+    trackFormRecordLoad(source, apply, { onReloaded });
+    const fresh = { values: { email: "fresh@example.com" }, initial: {} };
+    source.data.value = fresh;
+    await nextTick();
+    expect(apply).toHaveBeenLastCalledWith(fresh);
+    expect(onReloaded).toHaveBeenCalledOnce();
+  });
+
+  it("leaves a later read out while the user edits", async () => {
+    const apply = vi.fn();
+    const onReloaded = vi.fn();
+    const source = loadOf(ROW, null);
+    trackFormRecordLoad(source, apply, {
+      isEditing: () => true,
+      onReloaded,
+    });
+    source.data.value = { values: { email: "other@example.com" }, initial: {} };
+    await nextTick();
+    expect(apply).toHaveBeenCalledOnce();
+    expect(onReloaded).not.toHaveBeenCalled();
+  });
+
+  it("stops showing the cached record once a later read is refused", async () => {
+    const apply = vi.fn();
+    const source = loadOf(ROW, null);
+    const load = trackFormRecordLoad(source, apply);
+    source.error.value = FORBIDDEN;
+    await nextTick();
+    expect(load.failure.value).toBe("forbidden");
+  });
+
   it("applies a record that loaded", () => {
     const apply = vi.fn();
     const load = trackFormRecordLoad(loadOf(ROW, null), apply);
@@ -74,6 +109,25 @@ describe("a form's record load", () => {
   });
 });
 
+describe("Form.vue", () => {
+  const source = readFileSync(
+    new URL("../layers/dms-ui/app/components/form/Form.vue", import.meta.url),
+    "utf8",
+  );
+
+  it("leaves reading the record again on mount to the data layer", () => {
+    // The renderer reads cached data again on each mount (stale while
+    // revalidate): no status reset forces it any more.
+    expect(source).not.toMatch(/status\.value\s*=\s*"idle"/);
+  });
+
+  it("keys the record's load on the record it reads", () => {
+    expect(source).toMatch(
+      /`form-\$\{props\.componentId\}-\$\{props\.pageId\}-\$\{resolvedFetchUrl\.value/,
+    );
+  });
+});
+
 describe("a form about a record its address names none of", () => {
   const FETCH_URL = "/api/tasks/get?id={{query.id}}";
 

package/frontend-vue/tests/helpers/api-data-runtime.ts

@@ -0,0 +1,77 @@
+/**
+ * `useApiData` on the runtime's real async data, over a fake `$authFetch`:
+ * what a layer component reads, a server render of it, and the browser
+ * hydrating its HTML.
+ */
+import { createApp, createSSRApp, type App, type Component } from "vue";
+import { renderToString } from "vue/server-renderer";
+import { vi } from "vitest";
+import type { DmsFrontendRuntime, DmsPayload } from "#dms/frontend-module";
+
+export const engine = await import("#dms/frontend-module");
+const { useApiData } = await import(
+  "../../layers/dms-core/app/composables/auth/useApiData"
+);
+
+/** Stubs the globals `useApiData` reads, `$authFetch` being `authFetch`. */
+export function stubApiData(authFetch: (...args: never[]) => unknown): void {
+  vi.stubGlobal("useDmsFetch", engine.useDmsFetch);
+  vi.stubGlobal("useDmsAsyncData", engine.useDmsAsyncData);
+  vi.stubGlobal("useDmsState", engine.useDmsState);
+  vi.stubGlobal("useAuthFetch", () => ({ $authFetch: authFetch }));
+  vi.stubGlobal("useApiData", useApiData);
+}
+
+/** A browser runtime: `useApiData` outside a component reads through it. */
+export function browserRuntime(app: App = createApp({})): DmsFrontendRuntime {
+  const runtime = engine.createDmsFrontendRuntime();
+  engine.provideDmsFrontendRuntime(app, runtime);
+  return runtime;
+}
+
+/** Renders `root` as a server would: its HTML and the payload it hands over. */
+export async function serverRender(
+  root: Component,
+  setup?: (app: App) => void,
+): Promise<{ html: string; payload: DmsPayload }> {
+  const runtime = engine.createDmsFrontendRuntime(undefined, {}, true);
+  const app = createSSRApp(root);
+  engine.provideDmsFrontendRuntime(app, runtime);
+  setup?.(app);
+  const html = await renderToString(app);
+  return {
+    html,
+    payload: structuredClone(engine.serializeDmsPayload(runtime)),
+  };
+}
+
+/** Hydrates the server's `html` with its `payload`, as the browser does. */
+export function hydrate(
+  root: Component,
+  html: string,
+  payload: DmsPayload,
+  setup?: (app: App) => void,
+): { app: App; container: HTMLElement } {
+  const runtime = engine.createDmsFrontendRuntime();
+  engine.restoreDmsPayload(runtime, payload);
+  const container = document.createElement("div");
+  container.innerHTML = html;
+  const app = createSSRApp(root);
+  engine.provideDmsFrontendRuntime(app, runtime);
+  setup?.(app);
+  app.mount(container);
+  return { app, container };
+}
+
+/** Mounts `root` in the browser, past the hydration (a client navigation). */
+export function mountInBrowser(
+  root: Component,
+  setup?: (app: App) => void,
+): { app: App; container: HTMLElement } {
+  const container = document.createElement("div");
+  const app = createApp(root);
+  browserRuntime(app);
+  setup?.(app);
+  app.mount(container);
+  return { app, container };
+}

package/frontend-vue/tests/image-hydration-ids.test.ts

@@ -1,19 +1,20 @@
 // @vitest-environment jsdom
 import {
   computed,
-  createSSRApp,
   defineComponent,
   h,
   inject,
   onBeforeUnmount,
+  onScopeDispose,
   ref,
+  shallowReactive,
   useId,
   watch,
   type App,
 } from "vue";
-import { renderToString } from "vue/server-renderer";
 import { afterEach, beforeEach, expect, it, vi } from "vitest";
 import Image from "../layers/dms-ui/app/components/form/components/Image.vue";
+import { hydrate, serverRender, stubApiData } from "./helpers/api-data-runtime";
 
 const STORED_IMAGE = { key: "files/profile/cover.png", alt: "Cover" };
 
@@ -25,16 +26,14 @@ const passthrough = defineComponent({
       slots.default?.(),
 });
 
-function createImageApp(): App {
-  const app = createSSRApp({
-    render: () => h(Image, { modelValue: STORED_IMAGE }),
-  });
+const Root = { render: () => h(Image, { modelValue: STORED_IMAGE }) };
+
+function register(app: App): void {
   app.component("UButton", defineComponent({ setup: () => () => h("button") }));
   app.component("UIcon", defineComponent({ setup: () => () => h("span") }));
   app.component("UInput", defineComponent({ setup: () => () => h("input") }));
   app.component("UTooltip", passthrough);
   app.component("UModal", defineComponent({ setup: () => () => null }));
-  return app;
 }
 
 beforeEach(() => {
@@ -44,12 +43,17 @@ beforeEach(() => {
   vi.stubGlobal("inject", inject);
   vi.stubGlobal("useId", useId);
   vi.stubGlobal("onBeforeUnmount", onBeforeUnmount);
+  vi.stubGlobal("onScopeDispose", onScopeDispose);
+  vi.stubGlobal("shallowReactive", shallowReactive);
   vi.stubGlobal("FORM_FIELD_LOADING_KEY", Symbol());
   vi.stubGlobal("FORM_CONTENT_LANGUAGE_KEY", Symbol());
   vi.stubGlobal("CONTENT_LANGUAGE_HEADER", "x-content-language");
-  vi.stubGlobal("useAuthFetch", () => ({
-    $authFetch: () => new Promise(() => undefined),
-  }));
+  stubApiData((async () => ({
+    resourceKey: STORED_IMAGE.key,
+    filename: "cover.png",
+    size: 10,
+    url: "https://files.test/cover.png",
+  })) as never);
   vi.stubGlobal("useUploadWithProgress", () => ({
     uploadWithProgress: vi.fn(),
   }));
@@ -72,15 +76,16 @@ afterEach(() => {
 });
 
 it("hydrates a stored single image without an attribute mismatch", async () => {
-  const html = await renderToString(createImageApp());
-  const container = document.createElement("div");
-  container.innerHTML = html;
+  vi.stubEnv("SSR", true);
+  const { html, payload } = await serverRender(Root, register);
+  vi.unstubAllEnvs();
   const warnings: string[] = [];
-  const app = createImageApp();
-  app.config.warnHandler = (message) => warnings.push(message);
   const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
 
-  app.mount(container);
+  const { app, container } = hydrate(Root, html, payload, (application) => {
+    register(application);
+    application.config.warnHandler = (message) => warnings.push(message);
+  });
 
   expect(warnings.filter((message) => message.includes("Hydration"))).toEqual(
     [],