@antelopejs/dms-database 0.1.1 → 0.2.0

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

@@ -0,0 +1,8 @@
+// What the renderer imports of Inertia, which a server render of a component
+// does not reach: the browser's page, links and visits.
+export const Link = {}
+export const router = {
+	visit: () => undefined,
+	on: () => () => undefined,
+}
+export const usePage = () => ({ url: undefined })

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

@@ -0,0 +1,219 @@
+/**
+ * Server renders of the module's components on the renderer's real data
+ * layer (`#dms/frontend-module`) and the DMS's real `useApiData`, as the
+ * generated application runs them: what each render reads from the backend,
+ * and what it hands the browser with the page.
+ */
+import * as vue from 'vue'
+import { createSSRApp, h, type Component } from 'vue'
+import { renderToString } from 'vue/server-renderer'
+import { vi } from 'vitest'
+import type { DmsPayload } from '#dms/frontend-module'
+
+const engine = await import('#dms/frontend-module')
+const regional = await import('#dms-core/app/utils/regional')
+
+/** A backend request a render made. */
+export interface BackendRead {
+	url: string
+	method: string
+	query: Record<string, unknown>
+}
+
+export type Backend = (read: BackendRead) => unknown
+
+interface FetchOptions {
+	method?: string
+	query?: Record<string, unknown>
+	signal?: AbortSignal
+}
+
+let backend: Backend = () => ({})
+const reads: BackendRead[] = []
+/** The options each read was made with, as `useDmsFetch` passed them. */
+const readOptions = new WeakMap<BackendRead, FetchOptions>()
+
+const $authFetch = async (url: string, options: FetchOptions = {}) => {
+	const read = {
+		url,
+		method: (options.method ?? 'GET').toUpperCase(),
+		query: options.query ?? {},
+	}
+	reads.push(read)
+	readOptions.set(read, options)
+	return backend(read)
+}
+
+const noop = () => undefined
+
+// The application's auto-imports: Vue's API, the renderer's, the DMS
+// layers' the module calls, and the module's own composables.
+for (const [name, value] of Object.entries(vue))
+	if (/^[a-z]/.test(name)) vi.stubGlobal(name, value)
+vi.stubGlobal('useDmsFetch', engine.useDmsFetch)
+vi.stubGlobal('useDmsAsyncData', engine.useDmsAsyncData)
+vi.stubGlobal('useDmsState', engine.useDmsState)
+vi.stubGlobal('useDmsRoute', engine.useDmsRoute)
+vi.stubGlobal('useDmsRouter', engine.useDmsRouter)
+const { useApiData } = await import('#dms-core/app/composables/auth/useApiData')
+vi.stubGlobal('useApiData', useApiData)
+// `useFetchAuth`: the former name of `useApiData`.
+vi.stubGlobal('useAuthFetch', () => ({ $authFetch, useFetchAuth: useApiData }))
+vi.stubGlobal('useI18n', () => ({
+	t: (key: string, params?: Record<string, unknown>) =>
+		params ? `${key} ${Object.values(params).join(' ')}` : key,
+	n: (value: number) => String(value),
+	locale: vue.ref('en'),
+}))
+vi.stubGlobal('useRegionalFormat', () => ({
+	locale: vue.ref('en'),
+	dateTimeFormat: (options: Intl.DateTimeFormatOptions) =>
+		regional.regionalDateTimeFormat('en', options),
+}))
+vi.stubGlobal('regionalDayKey', regional.regionalDayKey)
+vi.stubGlobal('regionalDayNumber', regional.regionalDayNumber)
+vi.stubGlobal('useToast', () => ({ add: noop }))
+vi.stubGlobal('useConfirm', () => ({ confirm: async () => false }))
+vi.stubGlobal('useDrawer', () => ({ open: noop }))
+vi.stubGlobal('useUnsavedChanges', noop)
+vi.stubGlobal('useDmsUserSession', () => ({
+	user: vue.ref({ _id: 'me' }),
+	loggedIn: vue.ref(true),
+}))
+for (const [name, module] of Object.entries({
+	useDataBrowserGrid:
+		await import('../../app/build/composables/useDataBrowserGrid'),
+	useDataBrowserTabs:
+		await import('../../app/build/composables/useDataBrowserTabs'),
+	useStagedEdits: await import('../../app/build/data/stagedEdits'),
+	useDatabaseSchemas:
+		await import('../../app/build/composables/useDatabaseSchemas'),
+}))
+	vi.stubGlobal(name, (module as Record<string, unknown>)[name])
+
+// The DMS's and Nuxt UI's components the module's templates use: each
+// renders its default slot, its props as attributes.
+const UI_COMPONENTS = [
+	'DmsAutoLink',
+	'DmsCard',
+	'DmsChart',
+	'DmsCodeSnippet',
+	'DmsEmptyState',
+	'DmsEyebrow',
+	'DmsFieldRow',
+	'DmsFlowCanvas',
+	'DmsFormErrorText',
+	'DmsFormRequiredLegend',
+	'DmsInputCode',
+	'DmsInputText',
+	'DmsSaveBar',
+	'DmsSegmented',
+	'DmsStatusSummary',
+	'DmsSwitch',
+	'DmsTextarea',
+	'I18nT',
+	'UAlert',
+	'UAvatar',
+	'UBadge',
+	'UButton',
+	'UFormField',
+	'UIcon',
+	'UInput',
+	'UKbd',
+	'UModal',
+	'UPopover',
+	'UProgress',
+	'USelect',
+	'USelectMenu',
+	'USkeleton',
+	'USlideover',
+	'UTabs',
+	'UTooltip',
+]
+
+const uiStub = (name: string): Component =>
+	vue.defineComponent({
+		name,
+		setup:
+			(_, { slots }) =>
+			() =>
+				h('div', { 'data-stub': name }, slots.default?.()),
+	})
+
+export interface ServerRender {
+	html: string
+	payload: DmsPayload
+	/** Every backend request the render made. */
+	reads: BackendRead[]
+	/** The requests made whose response the payload does not carry. */
+	untransferred: BackendRead[]
+}
+
+/**
+ * The key a `useApiData(url)` read is transferred under, as the renderer
+ * gives it (`dmsRequestKey`): a digest of the request, which the payload
+ * shows instead of the URL.
+ */
+function transferKey(read: BackendRead): string | null {
+	const { method, query } = readOptions.get(read) ?? {}
+	return engine.dmsRequestKey(read.url, { method, query }) ?? null
+}
+
+/**
+ * Renders `component` with `props` as a server renders the page `url`,
+ * answering each backend request with `respond`.
+ */
+export async function serverRender(
+	component: Component,
+	props: Record<string, unknown> = {},
+	options: { url?: string; respond?: Backend } = {},
+): Promise<ServerRender> {
+	backend = options.respond ?? (() => ({}))
+	reads.length = 0
+	const runtime = engine.createDmsFrontendRuntime(undefined, {}, true)
+	runtime.route.fullPath = options.url ?? '/'
+	const app = createSSRApp({ render: () => h(component, props) })
+	engine.provideDmsFrontendRuntime(app, runtime)
+	app.component('DmsClientOnly', engine.DmsClientOnly)
+	for (const name of UI_COMPONENTS) app.component(name, uiStub(name))
+	app.config.warnHandler = noop
+	const html = await renderToString(app)
+	const payload = engine.serializeDmsPayload(runtime)
+	const transferred = new Set(
+		Object.keys({ ...payload.data, ...payload.errors }),
+	)
+	const made = [...reads]
+	return {
+		html,
+		payload,
+		reads: made,
+		untransferred: made.filter(
+			(read) => !transferred.has(transferKey(read) ?? ''),
+		),
+	}
+}
+
+/** What a browser's app context gives a composable, and what it read. */
+export interface BrowserContext<T> {
+	value: T
+	/** Every backend request made since, live. */
+	reads: BackendRead[]
+}
+
+/**
+ * Runs `setup` in a browser's app context (no server render to hydrate),
+ * answering each backend request with `respond`.
+ */
+export function inBrowser<T>(
+	setup: () => T,
+	respond: Backend,
+): BrowserContext<T> {
+	backend = respond
+	reads.length = 0
+	const runtime = engine.createDmsFrontendRuntime(undefined, undefined, false)
+	const app = createSSRApp({ render: () => null })
+	engine.provideDmsFrontendRuntime(app, runtime)
+	const scope = vue.effectScope()
+	const value = app.runWithContext(() => scope.run(setup) as T)
+	return { value, reads }
+}

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

@@ -0,0 +1,4 @@
+// The renderer's `useI18n` wraps vue-i18n's; the tests stub `useI18n` itself.
+export const useI18n = () => {
+	throw new Error('vue-i18n is not available in these tests')
+}

package/frontend-vue/tests/helpers.test.ts

@@ -151,6 +151,7 @@ describe('query console helpers', () => {
 				entry({ id: 'b', executedAt: '2026-10-06T10:00:00' }),
 			],
 			(run) => run.executedAt,
+			(date) => date.toISOString().slice(0, 10),
 		)
 		expect(groups.map((group) => group.items.map((run) => run.id))).toEqual([
 			['a'],

package/frontend-vue/tests/locales.test.ts

@@ -54,3 +54,27 @@ describe('locale messages', () => {
 		)
 	})
 })
+
+// `<i18n-t>` looks for its component's own messages first; the module's
+// components have none, and vue-i18n warns on each page that renders one
+// ("Not found parent scope"). The module's messages are global: say so.
+const COMPONENTS_DIR = join(import.meta.dirname, '../app')
+
+function vueFiles(dir: string): string[] {
+	return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
+		const path = join(dir, entry.name)
+		if (entry.isDirectory()) return vueFiles(path)
+		return entry.name.endsWith('.vue') ? [path] : []
+	})
+}
+
+describe('translated templates', () => {
+	it('reads every <i18n-t> from the global messages', () => {
+		const unscoped = vueFiles(COMPONENTS_DIR).flatMap((file) =>
+			(readFileSync(file, 'utf8').match(/<i18n-t\b[^>]*>/g) ?? [])
+				.filter((tag) => !/\sscope="global"/.test(tag))
+				.map((tag) => `${file.slice(COMPONENTS_DIR.length)}: ${tag}`),
+		)
+		expect(unscoped).toEqual([])
+	})
+})

package/frontend-vue/tests/onDemandReads.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it } from 'vitest'
+import {
+	inBrowser,
+	serverRender,
+	type BackendRead,
+} from './fixtures/serverRender'
+import { useDiagramPersistence } from '../app/build/composables/useDiagramPersistence'
+import { useQueryStore } from '../app/build/composables/useQueryStore'
+import InstancePicker from '../app/components/InstancePicker.vue'
+import RowDrawer from '../app/components/RowDrawer.vue'
+
+// The reads the module makes on demand go through `useApiData` too
+// (`immediate: false` + `execute()`): nothing on the server, nothing before
+// they are asked for, and a fresh read each time they are.
+
+const NOTE = {
+	id: 'n1',
+	schemaName: 'shop',
+	text: 'Orders',
+	x: 0,
+	y: 0,
+	width: 200,
+	height: 100,
+	color: null,
+	createdAt: '2026-10-01T10:00:00.000Z',
+	updatedAt: '2026-10-01T10:00:00.000Z',
+}
+
+let layoutVersion = 0
+
+function backend({ url }: BackendRead): unknown {
+	if (url === '/api/database/diagram/layout/shop')
+		return { positions: { orders: { x: layoutVersion++, y: 0 } } }
+	if (url === '/api/database/diagram/notes') return { items: [NOTE] }
+	if (url === '/api/database/diagram/layout/broken')
+		throw Object.assign(new Error('Unavailable'), { statusCode: 503 })
+	if (url === '/api/database/query/history/run-1')
+		return { id: 'run-1', source: 'db.schema("shop")' }
+	return { items: [] }
+}
+
+describe('reads on demand', () => {
+	it("the diagram reads a schema's layout and notes when the canvas asks, each time", async () => {
+		layoutVersion = 0
+		const browser = inBrowser(useDiagramPersistence, backend)
+		expect(browser.reads).toEqual([])
+		const first = await browser.value.readDiagram('shop')
+		expect(first).toEqual({
+			schema: 'shop',
+			positions: { orders: { x: 0, y: 0 } },
+			notes: [NOTE],
+		})
+		expect(browser.reads.map((read) => read.url).sort()).toEqual([
+			'/api/database/diagram/layout/shop',
+			'/api/database/diagram/notes',
+		])
+		expect(browser.reads[1]!.query).toEqual({ schema: 'shop' })
+		// The canvas edits a working copy: a new load reads what is stored now.
+		const second = await browser.value.readDiagram('shop')
+		expect(second.positions).toEqual({ orders: { x: 1, y: 0 } })
+	})
+
+	it('the diagram says so when its layout cannot be read', async () => {
+		const browser = inBrowser(useDiagramPersistence, backend)
+		await expect(browser.value.readDiagram('broken')).rejects.toMatchObject({
+			statusCode: 503,
+		})
+	})
+
+	it('the console reads a linked run when it opens it, not before', async () => {
+		const browser = inBrowser(useQueryStore, backend)
+		await browser.value.libraryRead
+		const before = browser.reads.length
+		const entry = await browser.value.fetchHistoryEntry('run-1')
+		expect(entry).toMatchObject({ id: 'run-1' })
+		expect(browser.reads.slice(before).map((read) => read.url)).toEqual([
+			'/api/database/query/history/run-1',
+		])
+	})
+})
+
+describe('server render: what only the browser reads', () => {
+	it("a row's drawer leaves its references to the browser", async () => {
+		const page = await serverRender(
+			RowDrawer,
+			{
+				tab: { id: 't', schema: 'shop', table: 'orders', instance: '' },
+				rowId: 'r1',
+				row: { _id: 'r1' },
+				columns: [],
+				onStage: () => undefined,
+			},
+			{ respond: backend },
+		)
+		expect(page.reads).toEqual([])
+	})
+
+	it('the instance picker reads nothing until its menu opens', async () => {
+		const page = await serverRender(
+			InstancePicker,
+			{ modelValue: { kind: 'default' }, schema: 'shop' },
+			{ respond: backend },
+		)
+		expect(page.reads).toEqual([])
+	})
+})

package/frontend-vue/tests/registration.test.ts

@@ -6,18 +6,6 @@ function source(path: string): string {
 	return readFileSync(new URL(path, import.meta.url), 'utf8')
 }
 
-it('uses the DMS client-only wrapper for the Vue Flow schema diagram', () => {
-	const diagram = source('../app/components/SchemaDiagram.vue')
-	expect(diagram).toContain('<DmsClientOnly')
-	expect(diagram).not.toContain('<ClientOnly>')
-})
-
-it('does not route relation labels through Vue Flow EdgeText measurement', () => {
-	const edge = source('../app/components/DiagramRelationEdge.vue')
-	expect(edge).toContain(':label="undefined"')
-	expect(edge).toContain('<text')
-})
-
 it('registers every component under the module prefix the backend names', async () => {
 	const registerComponent = vi.fn()
 	const registerPage = vi.fn()

package/frontend-vue/tests/serverRender.test.ts

@@ -0,0 +1,235 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { defineComponent, h } from 'vue'
+import { serverRender, type BackendRead } from './fixtures/serverRender'
+import ConnectionStatus from '../app/components/ConnectionStatus.vue'
+import DataBrowser from '../app/components/DataBrowser.vue'
+import QueryConsole from '../app/components/QueryConsole.vue'
+import SchemaDiagram from '../app/components/SchemaDiagram.vue'
+import SchemasFilterBar from '../app/components/SchemasFilterBar.vue'
+import TableInspector from '../app/components/TableInspector.vue'
+
+// What a server render of each page reads, and that the browser is handed
+// every response it read: a read the page does not hand over is made again
+// by the browser, after a server request for nothing.
+
+const table = (name: string) => ({
+	name,
+	fields: { _id: { kind: 'string' } },
+	indexes: {},
+	relations: [],
+})
+const schema = (id: string, instances: string[] = []) => ({
+	id,
+	options: {},
+	tables: [table('orders'), table('customers')],
+	stats: { tableCount: 2, elementCount: 3, instanceCount: instances.length },
+	instances,
+})
+
+function backend({ url, query }: BackendRead): unknown {
+	switch (url) {
+		case '/api/database/schemas':
+			return { schemas: [schema('audit'), schema('shop', ['eu'])] }
+		case '/api/database/browse/tables':
+			return {
+				items: [
+					{ name: 'orders', elementCount: query.filter_instance ? 7 : 4242 },
+					{ name: 'customers', elementCount: 31 },
+				],
+			}
+		case '/api/database/health':
+			return { status: 'ok', latencyMs: 3, driver: 'MongoDB', storage: [] }
+		case '/api/database/query/saved':
+			return {
+				items:
+					query.scope === 'shared'
+						? [query_('team-query', 'Teammate query', 'other')]
+						: [query_('own-query', 'My saved query', 'me')],
+			}
+		case '/api/database/query/history':
+			return {
+				items: [
+					{
+						id: 'run-1',
+						userId: 'me',
+						query: {},
+						source: 'db.schema("shop").table("orders")',
+						language: 'aql',
+						executedAt: '2026-10-14T08:00:00.000Z',
+						durationMs: 12,
+						rowCount: 3,
+						status: 'ok',
+						mutation: false,
+					},
+				],
+			}
+		case '/api/database/browse/count':
+			return { total: 9876 }
+		case '/api/database/tables/source':
+			return { total: 12, all: 40, results: [{ _id: 'shop::orders' }] }
+		default:
+			return {}
+	}
+}
+
+function query_(id: string, name: string, userId: string) {
+	return {
+		id,
+		userId,
+		name,
+		description: '',
+		query: {},
+		source: `db.schema("shop") // ${name}`,
+		language: 'aql',
+		shared: userId !== 'me',
+		createdAt: '2026-10-01T10:00:00.000Z',
+		updatedAt: '2026-10-01T10:00:00.000Z',
+	}
+}
+
+const render = (
+	component: Parameters<typeof serverRender>[0],
+	props: Record<string, unknown> = {},
+	url = '/',
+) => serverRender(component, props, { url, respond: backend })
+
+describe('server render: every read is handed to the browser', () => {
+	it('data browser: the table counts of the first schema', async () => {
+		const page = await render(DataBrowser, {}, '/modules/database/data')
+		expect(page.reads.map((read) => read.url)).toEqual([
+			'/api/database/schemas',
+			'/api/database/browse/tables',
+		])
+		expect(page.reads[1]!.query).toEqual({ filter_schema: 'is:audit' })
+		expect(page.untransferred).toEqual([])
+		expect(page.html).toContain('4242')
+	})
+
+	it('data browser: a table link reads its schema and instance', async () => {
+		const page = await render(
+			DataBrowser,
+			{},
+			'/modules/database/data?schema=shop&table=orders&instance=eu',
+		)
+		expect(page.reads[1]!.query).toEqual({
+			filter_schema: 'is:shop',
+			filter_instance: 'is:eu',
+		})
+		expect(page.untransferred).toEqual([])
+		expect(page.html).toContain('>7<')
+	})
+
+	it('query console: the library, saved, shared and run', async () => {
+		const page = await render(QueryConsole, {}, '/modules/database/query')
+		expect(page.reads.map((read) => read.url).sort()).toEqual([
+			'/api/database/query/history',
+			'/api/database/query/saved',
+			'/api/database/query/saved',
+			'/api/database/schemas',
+		])
+		expect(page.untransferred).toEqual([])
+		expect(page.html).toContain(
+			'db.schema(&quot;shop&quot;).table(&quot;orders&quot;)',
+		)
+	})
+
+	it('diagram: no layout or notes, which only the browser draws', async () => {
+		const page = await render(SchemaDiagram, {}, '/modules/database/diagram')
+		expect(page.reads.map((read) => read.url)).toEqual([
+			'/api/database/schemas',
+		])
+		expect(page.untransferred).toEqual([])
+	})
+
+	it('diagram: no layout or notes either once the schemas are in', async () => {
+		// A block of the page read the schemas before the diagram's setup ran.
+		const SchemasFirst = defineComponent({
+			async setup() {
+				await useApiData('/api/database/schemas')
+				return () => h(SchemaDiagram)
+			},
+		})
+		const page = await render(SchemasFirst, {}, '/modules/database/diagram')
+		expect(page.reads.map((read) => read.url)).toEqual([
+			'/api/database/schemas',
+		])
+		expect(page.untransferred).toEqual([])
+	})
+
+	it('table inspector: the rows of the table in every instance', async () => {
+		const page = await render(
+			TableInspector,
+			{ rowData: { schema: 'shop', name: 'orders' } },
+			'/modules/database/schemas',
+		)
+		expect(page.reads.map((read) => read.url).sort()).toEqual([
+			'/api/database/browse/count',
+			'/api/database/schemas',
+		])
+		expect(page.untransferred).toEqual([])
+		expect(page.html).toContain('9876')
+	})
+
+	it('schemas filter bar: the tables listed out of all', async () => {
+		const page = await render(
+			SchemasFilterBar,
+			{},
+			'/modules/database/schemas?scope=shop',
+		)
+		expect(page.reads).toContainEqual({
+			url: '/api/database/tables/source',
+			method: 'GET',
+			query: { filter_scope: 'is:shop' },
+		})
+		expect(page.untransferred).toEqual([])
+		expect(page.html).toMatch(/12[^<]*40/)
+		// The counts only, not the rows the route lists.
+		expect(Object.values(page.payload.data)).toContainEqual({
+			total: 12,
+			all: 40,
+		})
+	})
+
+	it('overview: the connection health', async () => {
+		const page = await render(
+			ConnectionStatus,
+			{},
+			'/modules/database/overview',
+		)
+		expect(page.reads.map((read) => read.url)).toEqual(['/api/database/health'])
+		expect(page.untransferred).toEqual([])
+	})
+})
+
+describe('server render: what the browser hydrates the same', () => {
+	afterEach(() => {
+		vi.useRealTimers()
+	})
+
+	it('overview: the probe age, whenever the page renders', async () => {
+		// The browser hydrates a few seconds after the server rendered: the age
+		// of the probe must not follow the clock before the page is mounted.
+		const checkedAt = '2026-10-15T20:00:00.000Z'
+		const health = (read: BackendRead) =>
+			read.url === '/api/database/health'
+				? { ...(backend(read) as object), checkedAt }
+				: backend(read)
+		const renderAt = async (time: string) => {
+			vi.useFakeTimers({ toFake: ['Date'] })
+			vi.setSystemTime(new Date(time))
+			const page = await serverRender(
+				ConnectionStatus,
+				{},
+				{
+					url: '/modules/database/overview',
+					respond: health,
+				},
+			)
+			vi.useRealTimers()
+			return page.html
+		}
+		const rendered = await renderAt('2026-10-15T20:00:00.400Z')
+		expect(rendered).toContain('checked_seconds 0')
+		expect(await renderAt('2026-10-15T20:00:07.000Z')).toBe(rendered)
+	})
+})

package/frontend-vue/vitest.config.ts

@@ -1,5 +1,29 @@
+import { resolve } from 'node:path'
+import vue from '@vitejs/plugin-vue'
 import { defineConfig } from 'vitest/config'
 
+// The renderer and the DMS core layer the server-render tests run on: the
+// ones the repository installs at its root (`@antelopejs/dms-frontend`,
+// `@antelopejs/dms`), as `pnpm test:frontend` builds against them.
+const root = resolve(__dirname, '..', 'node_modules', '@antelopejs')
+
 export default defineConfig({
+	plugins: [vue()],
+	resolve: {
+		alias: {
+			'#dms/frontend-module': resolve(
+				root,
+				'dms-frontend/templates/vue/frontend-module.ts',
+			),
+			'#dms-core': resolve(root, 'dms/frontend-vue/layers/dms-core'),
+			// The renderer's own imports, from this package's dependencies: one
+			// Vue for the renderer and the components.
+			vue: resolve(__dirname, 'node_modules/vue'),
+			'@unhead/vue': resolve(__dirname, 'node_modules/@unhead/vue'),
+			// What the renderer reads of Inertia and vue-i18n in the browser only.
+			'@inertiajs/vue3': resolve(__dirname, 'tests/fixtures/inertia.ts'),
+			'vue-i18n': resolve(__dirname, 'tests/fixtures/vueI18n.ts'),
+		},
+	},
 	test: { environment: 'node', include: ['tests/**/*.test.ts'] },
 })