@antelopejs/dms-database 0.0.13 → 0.1.0

package/frontend-vue/app/build/utils/fieldTypes.ts

@@ -0,0 +1,198 @@
+import type { FieldDescriptor } from '../composables/useDatabaseSchemas'
+
+// How a column's type reads in the inspector, the diagram and the grid: an
+// icon and a mono label. Colour never encodes the type (D-09): it is kept for
+// structure, primary keys and relations, which `columnRole` names.
+
+interface FieldTypeView {
+	icon: string
+	label: string
+}
+
+type DescriptorOf<K extends FieldDescriptor['kind']> = Extract<
+	FieldDescriptor,
+	{ kind: K }
+>
+type DescriptorViews = {
+	[K in FieldDescriptor['kind']]: (descriptor: DescriptorOf<K>) => FieldTypeView
+}
+
+const UNKNOWN: FieldTypeView = { icon: 'i-ph-question', label: 'unknown' }
+const STRING_ICON = 'i-ph-text-aa'
+const NUMBER_ICON = 'i-ph-hash'
+const BOOLEAN_ICON = 'i-ph-toggle-right'
+const LIST_ICON = 'i-ph-brackets-square'
+const OBJECT_ICON = 'i-ph-brackets-curly'
+const ENUM_ICON = 'i-ph-list-checks'
+const UNION_ICON = 'i-ph-split'
+
+const NAMED_FIELDS: Record<string, FieldTypeView> = {
+	email: { icon: 'i-ph-at', label: 'email' },
+	password: { icon: 'i-ph-lock', label: 'password' },
+	secret: { icon: 'i-ph-lock', label: 'secret' },
+}
+
+const LITERAL_ICONS: Record<string, string> = {
+	string: STRING_ICON,
+	number: NUMBER_ICON,
+	boolean: BOOLEAN_ICON,
+}
+
+function literalLabel(value: string | number | boolean): string {
+	return typeof value === 'string' ? `"${value}"` : String(value)
+}
+
+function label(descriptor: FieldDescriptor): string {
+	return describeField(descriptor).label
+}
+
+const VIEWS: DescriptorViews = {
+	string: () => ({ icon: STRING_ICON, label: 'string' }),
+	number: () => ({ icon: NUMBER_ICON, label: 'number' }),
+	boolean: () => ({ icon: BOOLEAN_ICON, label: 'boolean' }),
+	date: () => ({ icon: 'i-ph-calendar-blank', label: 'date' }),
+	any: () => ({ icon: 'i-ph-asterisk', label: 'any' }),
+	unknown: () => UNKNOWN,
+	null: () => ({ icon: 'i-ph-circle-dashed', label: 'null' }),
+	undefined: () => ({ icon: 'i-ph-circle-dashed', label: 'undefined' }),
+	literal: (d) => ({
+		icon: LITERAL_ICONS[typeof d.value] ?? STRING_ICON,
+		label: literalLabel(d.value),
+	}),
+	array: (d) => ({
+		icon: LIST_ICON,
+		label: `${d.element ? label(d.element) : 'any'}[]`,
+	}),
+	tuple: (d) => ({
+		icon: LIST_ICON,
+		label: `[${d.elements.map(label).join(', ')}]`,
+	}),
+	object: (d) => ({
+		icon: OBJECT_ICON,
+		label: d.partial ? 'partial object' : 'object',
+	}),
+	record: (d) => ({
+		icon: OBJECT_ICON,
+		label: `Record<${d.key ? label(d.key) : 'string'}, ${label(d.value)}>`,
+	}),
+	union: (d) => ({
+		icon:
+			d.members.length > 0 && d.members.every((m) => m.kind === 'literal')
+				? ENUM_ICON
+				: UNION_ICON,
+		label: d.members.map(label).join(' | '),
+	}),
+	intersection: (d) => ({
+		icon: UNION_ICON,
+		label: d.members.map(label).join(' & '),
+	}),
+	keyof: (d) => ({
+		icon: ENUM_ICON,
+		label:
+			d.keys.length > 0 ? d.keys.map((k) => `"${k}"`).join(' | ') : 'keyof',
+	}),
+	refinement: (d) => ({ icon: describeField(d.base).icon, label: d.name }),
+	recursive: (d) => ({ icon: UNKNOWN.icon, label: d.name }),
+}
+
+function isDescriptor(value: unknown): value is FieldDescriptor {
+	return (
+		value !== null &&
+		typeof value === 'object' &&
+		typeof (value as { kind?: unknown }).kind === 'string' &&
+		(value as { kind: string }).kind in VIEWS
+	)
+}
+
+/** Icon and label of a schema-declared type. */
+export function describeField(
+	descriptor: unknown,
+	fieldName = '',
+): FieldTypeView {
+	const named = NAMED_FIELDS[fieldName.toLowerCase()]
+	if (named) return named
+	if (!isDescriptor(descriptor)) return UNKNOWN
+	const view = VIEWS[descriptor.kind] as (d: FieldDescriptor) => FieldTypeView
+	return view(descriptor)
+}
+
+const RUNTIME_KINDS = new Set([
+	'string',
+	'number',
+	'boolean',
+	'array',
+	'object',
+	'null',
+	'undefined',
+])
+
+/**
+ * Icon and label of a type sampled at run time by the browse `/columns`
+ * route (string, number, boolean, object, array, null), so sampled and
+ * declared columns share one vocabulary.
+ */
+export function describeRuntimeType(
+	type: string,
+	fieldName: string,
+): FieldTypeView {
+	if (type === 'date') return describeField({ kind: 'date' }, fieldName)
+	if (type === 'object')
+		return describeField({ kind: 'object', fields: {} }, fieldName)
+	if (type === 'array') return describeField({ kind: 'array' }, fieldName)
+	return describeField(
+		RUNTIME_KINDS.has(type)
+			? ({ kind: type } as FieldDescriptor)
+			: { kind: 'unknown' },
+		fieldName,
+	)
+}
+
+const PRIMARY_KEY_NAMES = new Set(['id', '_id'])
+const PRIMARY_KEY_INDEXES = ['pk', 'primary'] as const
+
+export function isPrimaryKey(
+	fieldName: string,
+	indexes: Record<string, { fields?: string[] }>,
+): boolean {
+	if (PRIMARY_KEY_NAMES.has(fieldName)) return true
+	return PRIMARY_KEY_INDEXES.some((name) =>
+		indexes[name]?.fields?.includes(fieldName),
+	)
+}
+
+/** What a column is for the structure: its colour role in every view. */
+export type ColumnRole = 'key' | 'relation' | 'plain'
+
+/** The CSS colour class of each role: warning for keys, primary for relations. */
+export const COLUMN_ROLE_CLASSES: Record<ColumnRole, string> = {
+	key: 'text-warning',
+	relation: 'text-primary',
+	plain: 'text-muted',
+}
+
+interface ModifierView {
+	icon: string
+	/** i18n key of the modifier's name. */
+	labelKey?: string
+	/** The modifier id, shown when it has no name of its own. */
+	id: string
+}
+
+const MODIFIERS: Record<string, Omit<ModifierView, 'id'>> = {
+	HashModifier: {
+		icon: 'i-ph-fingerprint',
+		labelKey: 'dms_database.modifiers.hashed',
+	},
+	LocalizationModifier: {
+		icon: 'i-ph-translate',
+		labelKey: 'dms_database.modifiers.localized',
+	},
+	EncryptionModifier: {
+		icon: 'i-ph-lock-key',
+		labelKey: 'dms_database.modifiers.encrypted',
+	},
+}
+
+export function describeModifier(id: string): ModifierView {
+	return { id, ...(MODIFIERS[id] ?? { icon: 'i-ph-sliders' }) }
+}

package/frontend-vue/app/build/utils/relativeTime.ts

@@ -0,0 +1,19 @@
+const MINUTE_MS = 60_000
+const MINUTES_PER_HOUR = 60
+const HOURS_PER_DAY = 24
+
+// Human "3 minutes ago" style label for an ISO timestamp, relative to now, in
+// the interface language. Not named `formatRelativeTime`: the DMS core layer
+// auto-imports a helper of that name, and the two would shadow each other.
+export function formatDatabaseRelativeTime(
+	iso: string,
+	locale?: string,
+): string {
+	const formatter = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
+	const minutes = Math.round((new Date(iso).getTime() - Date.now()) / MINUTE_MS)
+	if (Math.abs(minutes) < MINUTES_PER_HOUR)
+		return formatter.format(minutes, 'minute')
+	const hours = Math.round(minutes / MINUTES_PER_HOUR)
+	if (Math.abs(hours) < HOURS_PER_DAY) return formatter.format(hours, 'hour')
+	return formatter.format(Math.round(hours / HOURS_PER_DAY), 'day')
+}

package/frontend-vue/app/{utils → build/utils}/stagedSerialization.ts

@@ -1,4 +1,5 @@
 import {
+	CROSS_INSTANCE,
 	Datum,
 	Query,
 	Schema,
@@ -10,7 +11,7 @@ import {
 	ValueProxy,
 } from '@antelopejs/interface-database/staged-query'
 
-export interface QueryStage {
+interface QueryStage {
 	stage: string
 	options?: unknown
 	args: unknown[]
@@ -37,7 +38,12 @@ function classNameOf(obj: object): string | undefined {
 	return undefined
 }
 
+// CROSS_INSTANCE is a symbol, which JSON drops: it travels as this sentinel,
+// which the server turns back into the symbol.
+export const CROSS_INSTANCE_SENTINEL = '__CROSS_INSTANCE__'
+
 export function encodeStaged(node: unknown): unknown {
+	if (node === CROSS_INSTANCE) return CROSS_INSTANCE_SENTINEL
 	if (node === null || node === undefined) return node
 	if (typeof node !== 'object') return node
 	if (Array.isArray(node)) return node.map(encodeStaged)

package/frontend-vue/app/components/ConnectionStatus.vue

@@ -0,0 +1,122 @@
+<script setup lang="ts">
+import { useDatabaseHealth } from '../build/composables/useDatabaseHealth'
+import { useIntervalFn, useNow } from '@vueuse/core'
+
+// The overview's health hero: whether the database answers, how fast, and
+// what it holds. The probe runs again every PROBE_INTERVAL_MS while the page
+// is open, so a lost connection shows up without a reload.
+const PROBE_INTERVAL_MS = 30_000
+const SECOND_MS = 1000
+const MINUTE_S = 60
+
+const { t, n, locale } = useI18n()
+const { health, isLoading, error, refresh } = useDatabaseHealth()
+const now = useNow({ interval: SECOND_MS })
+
+useIntervalFn(() => refresh(), PROBE_INTERVAL_MS)
+
+// A failed health request is a lost connection too: the route answers
+// whenever the backend is up.
+const isDown = computed(
+	() => Boolean(error.value) || health.value.status === 'down',
+)
+
+const checkedAgo = computed(() => {
+	const checkedAt = health.value.checkedAt
+	if (!checkedAt) return ''
+	const seconds = Math.max(
+		0,
+		Math.round(
+			(now.value.getTime() - new Date(checkedAt).getTime()) / SECOND_MS,
+		),
+	)
+	return seconds < MINUTE_S
+		? t('dms_database.overview.connection.checked_seconds', { count: seconds })
+		: t('dms_database.overview.connection.checked_minutes', {
+				count: Math.round(seconds / MINUTE_S),
+			})
+})
+
+const since = computed(() => {
+	const parts = [health.value.driver, checkedAgo.value].filter(Boolean)
+	return parts.join(' · ')
+})
+
+function compact(value: number): string {
+	return new Intl.NumberFormat(locale.value, {
+		notation: 'compact',
+		maximumFractionDigits: 1,
+	}).format(value)
+}
+
+const healthyMetrics = computed(() => {
+	const h = health.value
+	return [
+		{
+			label: t('dms_database.overview.connection.latency'),
+			value: h.latencyMs ?? '—',
+			unit: h.latencyMs === null ? undefined : 'ms',
+			sub: t('dms_database.overview.connection.latency_sub'),
+			tone: 'success' as const,
+		},
+		{
+			label: t('dms_database.overview.connection.tables'),
+			value: n(h.tableCount),
+			sub: t('dms_database.overview.connection.tables_sub', h.schemaCount),
+		},
+		{
+			label: t('dms_database.overview.connection.rows'),
+			value: compact(h.totalRows),
+			sub: t('dms_database.overview.connection.rows_sub', h.relationCount),
+		},
+		{
+			label: t('dms_database.overview.connection.indexes'),
+			value: n(h.indexCount),
+			sub: t('dms_database.overview.connection.indexes_sub'),
+		},
+	]
+})
+
+const downMetrics = computed(() => [
+	{
+		label: t('dms_database.overview.connection.last_error'),
+		value:
+			health.value.error ?? t('dms_database.overview.connection.no_answer'),
+		tone: 'error' as const,
+	},
+	{
+		label: t('dms_database.overview.connection.next_probe'),
+		value: Math.round(PROBE_INTERVAL_MS / SECOND_MS),
+		unit: 's',
+		sub: t('dms_database.overview.connection.next_probe_sub'),
+	},
+])
+</script>
+
+<template>
+	<div class="grid gap-2">
+		<DmsStatusSummary
+			:status="isDown ? 'down' : 'ok'"
+			:status-label="t('dms_database.overview.connection.label')"
+			:status-value="
+				isDown
+					? t('dms_database.overview.connection.down')
+					: t('dms_database.overview.connection.healthy')
+			"
+			:since="since"
+			:metrics="isDown ? downMetrics : healthyMetrics"
+			:class="isLoading && !health.checkedAt ? 'animate-pulse' : undefined"
+		/>
+		<div v-if="isDown" class="flex justify-end">
+			<UButton
+				color="neutral"
+				variant="outline"
+				size="sm"
+				icon="i-ph-arrows-clockwise"
+				:loading="isLoading"
+				:label="t('dms_database.overview.connection.retry')"
+				@click="refresh()"
+			/>
+		</div>
+	</div>
+</template>

package/frontend-vue/app/components/DataBrowser.vue

@@ -0,0 +1,126 @@
+<script setup lang="ts">
+import {
+	instanceBadge,
+	useDataBrowserTabs,
+} from '../build/composables/useDataBrowserTabs'
+import { useDatabaseSchemas } from '../build/composables/useDatabaseSchemas'
+import { formatDatabaseRelativeTime } from '../build/utils/relativeTime'
+import { type RecentTable, readRecentTables } from '../build/data/recentTables'
+import { useStagedEdits } from '../build/data/stagedEdits'
+import DataBrowserSidebar from './DataBrowserSidebar.vue'
+import DataBrowserTabBar from './DataBrowserTabBar.vue'
+import DataGrid from './DataGrid.vue'
+
+// The data browser: a table list scoped to one schema and instance, the open
+// tables as tabs, and the grid of the active one. Edits are staged per tab
+// and written only when saved; leaving with staged edits asks first.
+
+const { t, locale } = useI18n()
+const {
+	schemas,
+	findTable,
+	isLoading: schemasLoading,
+	error: schemasError,
+	refresh: refreshSchemas,
+} = useDatabaseSchemas()
+const { tabs, activeTab, restore, openTab, openFromRoute } =
+	useDataBrowserTabs()
+const staged = useStagedEdits()
+const route = useDmsRoute()
+
+onMounted(() => restore())
+// A link from this page to another table (a relation) keeps the page mounted.
+watch(
+	() => route.query,
+	() => openFromRoute(),
+)
+
+const hasStagedEdits = computed(() =>
+	tabs.value.some((tab) => staged.count(tab.id) > 0),
+)
+useUnsavedChanges({ dirty: hasStagedEdits })
+
+// Schema-introspected columns of the active table: the grid falls back to
+// them when sampling finds no row, and reads its relation columns from them.
+const activeTableSummary = computed(() =>
+	activeTab.value
+		? findTable(activeTab.value.schema, activeTab.value.table)
+		: undefined,
+)
+
+// Read once mounted: the server renders without the browser's storage, and
+// a list only the client has would not match its markup.
+const recent = ref<RecentTable[]>([])
+onMounted(() => {
+	recent.value = readRecentTables()
+})
+watch(activeTab, () => {
+	recent.value = readRecentTables()
+})
+
+function instanceLabel(instance: string): string {
+	return instanceBadge(instance, t('dms_database.data.scope.all')) ?? ''
+}
+</script>
+
+<template>
+	<div
+		class="border-default bg-default flex min-h-0 flex-1 overflow-hidden rounded-xl border"
+	>
+		<DataBrowserSidebar
+			:schemas="schemas"
+			:loading="schemasLoading"
+			:error="Boolean(schemasError)"
+			@retry="refreshSchemas()"
+		/>
+		<section class="flex min-w-0 flex-1 flex-col">
+			<DataBrowserTabBar />
+			<DataGrid
+				v-if="activeTab"
+				:key="activeTab.id"
+				:tab="activeTab"
+				:table="activeTableSummary"
+			/>
+			<div v-else class="grid flex-1 place-items-center p-6">
+				<DmsEmptyState
+					icon="i-ph-rows"
+					:title="t('dms_database.data.empty.pick_title')"
+					:description="
+						recent.length
+							? t('dms_database.data.empty.pick_description')
+							: t('dms_database.data.empty.pick_description_first')
+					"
+				>
+					<template v-if="recent.length" #actions>
+						<div class="grid w-full max-w-sm gap-1.5">
+							<DmsEyebrow :label="t('dms_database.data.empty.recent')" />
+							<button
+								v-for="entry in recent"
+								:key="`${entry.schema}.${entry.instance}.${entry.table}`"
+								type="button"
+								class="border-default hover:bg-elevated flex items-center gap-2 rounded-md border px-3 py-2 text-left font-mono text-[12.5px]"
+								@click="
+									openTab(entry.schema, entry.instance, entry.table, false)
+								"
+							>
+								<UIcon name="i-ph-table" class="text-primary size-3.5" />
+								<span class="text-toned">
+									{{ entry.schema }}.{{ entry.table }}
+								</span>
+								<span
+									v-if="instanceLabel(entry.instance)"
+									class="text-primary text-[11px]"
+								>
+									{{ instanceLabel(entry.instance) }}
+								</span>
+								<span class="text-dimmed ml-auto font-sans text-xs">
+									{{ formatDatabaseRelativeTime(entry.openedAt, locale) }}
+								</span>
+							</button>
+						</div>
+					</template>
+				</DmsEmptyState>
+			</div>
+		</section>
+	</div>
+</template>