@antelopejs/dms-database 0.0.13 → 0.1.0

package/frontend-vue/app/build/query/runs.ts

@@ -0,0 +1,168 @@
+import type { HistoryEntry } from '../composables/useQueryStore'
+
+// How the library tells runs apart (D-11): a dot per run — fast, slow,
+// failed or changed data — and day headings.
+
+export type RunKind = 'fast' | 'slow' | 'failed' | 'changed'
+
+// A run slower than this, in milliseconds, is slow; the server flags the
+// recent queries of the overview with the same threshold.
+export const SLOW_QUERY_MS = 100
+
+export function runKind(entry: HistoryEntry): RunKind {
+	if (entry.status === 'error') return 'failed'
+	if (entry.mutation) return 'changed'
+	return entry.durationMs > SLOW_QUERY_MS ? 'slow' : 'fast'
+}
+
+// A run that changed data reads apart from a fast one by its shape too: a
+// ring, as the info and success tones sit close in some themes.
+export const RUN_DOT_CLASSES: Record<RunKind, string> = {
+	fast: 'bg-success',
+	slow: 'bg-warning',
+	failed: 'bg-error',
+	changed: 'bg-default ring-2 ring-inset ring-info',
+}
+
+/** Runs the server keeps per user (MAX_HISTORY_PER_USER). */
+export const HISTORY_KEPT = 500
+
+export interface DayGroup<T> {
+	key: string
+	date: Date
+	items: T[]
+}
+
+function dayKey(date: Date): string {
+	return `${date.getFullYear()}-${date.getMonth()}-${date.getDate()}`
+}
+
+/** Entries by local calendar day, newest day first, in their given order. */
+export function groupByDay<T>(
+	entries: T[],
+	dateOf: (entry: T) => string,
+): DayGroup<T>[] {
+	const groups = new Map<string, DayGroup<T>>()
+	for (const entry of entries) {
+		const date = new Date(dateOf(entry))
+		const key = dayKey(date)
+		const group = groups.get(key) ?? { key, date, items: [] }
+		group.items.push(entry)
+		groups.set(key, group)
+	}
+	return [...groups.values()]
+}
+
+const DAY_MS = 86_400_000
+
+/** "Today", "Yesterday" or the date, in the interface language. */
+export function dayLabel(
+	date: Date,
+	locale: string,
+	words: { today: string; yesterday: string },
+): string {
+	const today = new Date()
+	today.setHours(0, 0, 0, 0)
+	const day = new Date(date)
+	day.setHours(0, 0, 0, 0)
+	const days = Math.round((today.getTime() - day.getTime()) / DAY_MS)
+	if (days === 0) return words.today
+	if (days === 1) return words.yesterday
+	return new Intl.DateTimeFormat(locale, {
+		day: 'numeric',
+		month: 'short',
+	}).format(date)
+}
+
+export type UnknownKind = 'schema' | 'instance' | 'table'
+
+/** A name a query used that its schema does not know. */
+export interface UnknownName {
+	kind: UnknownKind
+	name: string
+}
+
+/** What an "Unknown schema / instance / table" error names, if it names one. */
+export function unknownName(message: string): UnknownName | null {
+	const match = /unknown (schema|instance|table):?\s*["“'«]?\s*([\w$-]+)/i.exec(
+		message,
+	)
+	if (!match) return null
+	return {
+		kind: (match[1] as string).toLowerCase() as UnknownKind,
+		name: match[2] as string,
+	}
+}
+
+function distance(left: string, right: string): number {
+	const previous = Array.from({ length: right.length + 1 }, (_, index) => index)
+	for (let i = 1; i <= left.length; i += 1) {
+		let diagonal = previous[0] as number
+		previous[0] = i
+		for (let j = 1; j <= right.length; j += 1) {
+			const above = previous[j] as number
+			const cost = left[i - 1] === right[j - 1] ? 0 : 1
+			previous[j] = Math.min(
+				above + 1,
+				(previous[j - 1] as number) + 1,
+				diagonal + cost,
+			)
+			diagonal = above
+		}
+	}
+	return previous[right.length] as number
+}
+
+// Two edits away at most: "invoice" for "invoices", "oders" for "orders".
+const MAX_SUGGESTION_DISTANCE = 2
+
+/** The name closest to a mistyped one, when one is close enough. */
+export function closestName(name: string, candidates: string[]): string | null {
+	let best: string | null = null
+	let bestDistance = MAX_SUGGESTION_DISTANCE + 1
+	for (const candidate of candidates) {
+		if (candidate === name) continue
+		const score = distance(name.toLowerCase(), candidate.toLowerCase())
+		if (score < bestDistance) {
+			best = candidate
+			bestDistance = score
+		}
+	}
+	return best
+}
+
+export function escapeRegExp(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+const IDENTIFIER = /^[A-Z_$][\w$]*$/i
+
+/**
+ * The query with a mistyped schema, instance or table name replaced, in the
+ * call or access that names it: `table("oders")`, `instance("zz")`,
+ * `schemas.shoop` or `schemas["shoop"]`.
+ */
+export function replaceName(
+	source: string,
+	kind: UnknownKind,
+	from: string,
+	to: string,
+): string {
+	const name = escapeRegExp(from)
+	if (kind === 'schema') {
+		const access = IDENTIFIER.test(to)
+			? `schemas.${to}`
+			: `schemas[${JSON.stringify(to)}]`
+		return source.replace(
+			new RegExp(
+				`schemas\\s*(?:\\.\\s*${name}(?![\\w$])|\\[\\s*(["'\`])${name}\\1\\s*\\])`,
+				'g',
+			),
+			access,
+		)
+	}
+	return source.replace(
+		new RegExp(`${kind}\\(\\s*(["'\`])${name}\\1\\s*\\)`, 'g'),
+		(_, quote: string) => `${kind}(${quote}${to}${quote})`,
+	)
+}

package/frontend-vue/app/build/query/tableColumns.ts

@@ -0,0 +1,35 @@
+// How the result table lays out its columns: which ones it shows and which
+// it right-aligns. JSON and the CSV export keep every column as it is.
+
+function isEmpty(value: unknown): boolean {
+	return value === null || value === undefined
+}
+
+/**
+ * The columns the result table shows: a column null in every row says
+ * nothing (`_instance` on a single-instance read) and is left out, unless
+ * every column is.
+ */
+export function filledColumns(
+	rows: Record<string, unknown>[],
+	columns: string[],
+): string[] {
+	const filled = columns.filter((column) =>
+		rows.some((row) => !isEmpty(row[column])),
+	)
+	return filled.length ? filled : columns
+}
+
+/** Columns holding numbers and nothing else but nulls: right-aligned. */
+export function numericColumns(
+	rows: Record<string, unknown>[],
+	columns: string[],
+): string[] {
+	return columns.filter(
+		(column) =>
+			rows.some((row) => typeof row[column] === 'number') &&
+			rows.every(
+				(row) => isEmpty(row[column]) || typeof row[column] === 'number',
+			),
+	)
+}

package/frontend-vue/app/build/query/target.ts

@@ -0,0 +1,143 @@
+// The schema, instance and table an encoded query starts from, read from its
+// stages the way the server reads them: what the result header names and the
+// data browser link opens.
+
+import { instanceFromUrl } from '../utils/databaseLinks'
+import { CROSS_INSTANCE_SENTINEL } from '../utils/stagedSerialization'
+import { escapeRegExp } from './runs'
+
+export interface QueryTarget {
+	schema?: string
+	/** `""` for the default instance, `"*"` across every instance. */
+	instance?: string
+	table?: string
+}
+
+interface EncodedStage {
+	stage?: unknown
+	options?: { id?: unknown }
+}
+
+function stageId(stages: EncodedStage[], name: string): unknown {
+	return stages.find((stage) => stage.stage === name)?.options?.id
+}
+
+export function readQueryTarget(
+	encoded: Record<string, unknown> | null,
+): QueryTarget {
+	const stages = Array.isArray(encoded?.stages)
+		? (encoded.stages as EncodedStage[])
+		: []
+	const schema = stageId(stages, 'schema')
+	const table = stageId(stages, 'table')
+	const hasInstance = stages.some((stage) => stage.stage === 'instance')
+	const instance = stageId(stages, 'instance')
+	return {
+		schema: typeof schema === 'string' ? schema : undefined,
+		table: typeof table === 'string' ? table : undefined,
+		instance: !hasInstance
+			? undefined
+			: instance === CROSS_INSTANCE_SENTINEL || typeof instance === 'symbol'
+				? '*'
+				: typeof instance === 'string'
+					? instance
+					: '',
+	}
+}
+
+/** `shop.orders @eu`, or as much of it as the query names. */
+export function describeTarget(target: QueryTarget): string {
+	if (!target.schema) return ''
+	const table = target.table
+		? `${target.schema}.${target.table}`
+		: target.schema
+	return target.instance ? `${table} @${target.instance}` : table
+}
+
+const SCHEMA_ACCESS =
+	/schemas\s*(?:\.\s*([A-Za-z_$][\w$]*)|\[\s*["'`]([\w$-]+)["'`]\s*\])/g
+const INSTANCE_CALL =
+	/\.\s*instance\(\s*(?:(["'`])([^"'`]*)\1|(CROSS_INSTANCE))?\s*\)/g
+const TABLE_CALL = /\.\s*table\(\s*(["'`])([^"'`]+)\1\s*\)/g
+
+function lastMatch(pattern: RegExp, text: string): RegExpExecArray | null {
+	let last: RegExpExecArray | null = null
+	pattern.lastIndex = 0
+	for (let match = pattern.exec(text); match; match = pattern.exec(text))
+		last = match
+	return last
+}
+
+/**
+ * The schema, instance and table the last chain of a query text names, read
+ * from the text itself: for a query that never reached the server, or the
+ * chain the cursor is in.
+ */
+export function targetFromSource(source: string): QueryTarget {
+	const schema = lastMatch(SCHEMA_ACCESS, source)
+	if (!schema) return {}
+	const chain = source.slice(schema.index)
+	const instance = lastMatch(INSTANCE_CALL, chain)
+	const table = lastMatch(TABLE_CALL, chain)
+	return {
+		schema: schema[1] ?? schema[2],
+		instance: !instance ? undefined : instance[3] ? '*' : (instance[2] ?? ''),
+		table: table?.[2],
+	}
+}
+
+/** Where a past run pointed: its encoded query, else its text. */
+export function runTarget(run: {
+	query?: Record<string, unknown> | null
+	source: string
+}): QueryTarget {
+	const encoded = readQueryTarget(run.query ?? null)
+	return encoded.schema ? encoded : targetFromSource(run.source)
+}
+
+/**
+ * The instance a result row lives in, for its data browser link: the
+ * query's, or the row's own `_instance` when the query read every instance.
+ * `''` is the default instance; null when the row does not say.
+ */
+export function rowInstance(
+	target: QueryTarget,
+	row: Record<string, unknown>,
+): string | null {
+	if (target.instance !== '*') return target.instance ?? ''
+	if (!('_instance' in row)) return null
+	const instance = row._instance
+	if (instance === null || instance === undefined || instance === '') return ''
+	return typeof instance === 'string' ? instance : null
+}
+
+/**
+ * The `instance(…)` argument for the instance the URL's `instance` names:
+ * none for the default one, CROSS_INSTANCE for every instance.
+ */
+export function instanceArgument(raw: unknown): string {
+	const choice = instanceFromUrl(raw)
+	if (choice.kind === 'default') return ''
+	if (choice.kind === 'all') return 'CROSS_INSTANCE'
+	return JSON.stringify(choice.id)
+}
+
+/**
+ * The query text with the default instance of a schema, `instance()`, read
+ * in a named instance instead: `instance("eu")`.
+ */
+export function withInstance(
+	source: string,
+	schema: string,
+	instance: string,
+): string {
+	const name = escapeRegExp(schema)
+	const access = new RegExp(
+		`(schemas\\s*(?:\\.\\s*${name}(?![\\w$])|\\[\\s*(["'\`])${name}\\2\\s*\\])\\s*\\.\\s*instance\\()\\s*\\)`,
+		'g',
+	)
+	return source.replace(
+		access,
+		(_, call: string) => `${call}${JSON.stringify(instance)})`,
+	)
+}

package/frontend-vue/app/build/schemas/filterState.ts

@@ -0,0 +1,128 @@
+import type { InstanceChoice } from '../data/instanceOptions'
+import { instanceFromUrl, instanceToUrl } from '../utils/databaseLinks'
+
+// The Schemas page's filter bar keeps its state in the URL, so a filtered
+// list can be shared, reloaded and gone back to: `scope` (a schema),
+// `instance`, `q` (a table or column name) and `has` (relations, modifiers,
+// empty). The table view reads the same keys as hidden filters and sends
+// them to its source route, which reads them back (src/service/schemaFilters.ts
+// holds the same rules).
+// `instance` follows the module's convention (see instanceFromUrl): absent
+// for the default instance, `all` for every instance.
+
+const FILTER_KEYS = ['scope', 'instance', 'q', 'has'] as const
+type FilterKey = (typeof FILTER_KEYS)[number]
+
+export const HAS_FLAGS = ['relations', 'modifiers', 'empty'] as const
+export type HasFlag = (typeof HAS_FLAGS)[number]
+const HAS_SEPARATOR = ','
+
+export type { InstanceChoice }
+
+export interface SchemasFilterState {
+	/** The schema listed; null for every schema. */
+	scope: string | null
+	instance: InstanceChoice
+	/** A part of a table or column name, trimmed; empty for none. */
+	q: string
+	/** Structure the tables must have, all of them, in a fixed order. */
+	has: HasFlag[]
+}
+
+export const EMPTY_FILTER_STATE: SchemasFilterState = {
+	scope: null,
+	instance: { kind: 'default' },
+	q: '',
+	has: [],
+}
+
+type Query = Record<string, unknown>
+
+function text(value: unknown): string {
+	const first = Array.isArray(value) ? value[0] : value
+	return typeof first === 'string' ? first.trim() : ''
+}
+
+/** Known flags only, once each, in their fixed order. */
+export function parseHas(param: string | undefined): HasFlag[] {
+	if (!param) return []
+	const asked = new Set(param.split(HAS_SEPARATOR).map((flag) => flag.trim()))
+	return HAS_FLAGS.filter((flag) => asked.has(flag))
+}
+
+/** The bar's state from a route query; an empty value reads as unset. */
+export function readFilterState(query: Query): SchemasFilterState {
+	return {
+		scope: text(query.scope) || null,
+		instance: instanceFromUrl(query.instance),
+		q: text(query.q),
+		has: parseHas(text(query.has)),
+	}
+}
+
+/** The URL values of a state; undefined for what is unset. */
+export function filterParams(
+	state: SchemasFilterState,
+): Record<FilterKey, string | undefined> {
+	const has = parseHas(state.has.join(HAS_SEPARATOR))
+	return {
+		scope: state.scope || undefined,
+		instance: instanceToUrl(state.instance),
+		q: state.q.trim() || undefined,
+		has: has.length > 0 ? has.join(HAS_SEPARATOR) : undefined,
+	}
+}
+
+/**
+ * A route query carrying this state, the rest of it kept: an unset key is
+ * dropped, empty ones included.
+ */
+export function withFilterState(
+	query: Query,
+	state: SchemasFilterState,
+): Query {
+	const next: Query = { ...query }
+	for (const [key, value] of Object.entries(filterParams(state))) {
+		if (value === undefined) delete next[key]
+		else next[key] = value
+	}
+	return next
+}
+
+/** Whether the bar narrows the list at all. */
+export function isFiltered(state: SchemasFilterState): boolean {
+	return Object.values(filterParams(state)).some((value) => value !== undefined)
+}
+
+/** The source route's query for a state, as the table view sends it. */
+export function sourceQuery(state: SchemasFilterState): Record<string, string> {
+	const query: Record<string, string> = {}
+	for (const [key, value] of Object.entries(filterParams(state))) {
+		if (value !== undefined) query[`filter_${key}`] = `is:${value}`
+	}
+	return query
+}
+
+/** Another schema: a named instance belongs to the one left. */
+export function withScope(
+	state: SchemasFilterState,
+	scope: string | null,
+): SchemasFilterState {
+	const keepsInstance =
+		state.instance.kind !== 'named' || (scope !== null && scope === state.scope)
+	return {
+		...state,
+		scope,
+		instance: keepsInstance ? state.instance : { kind: 'default' },
+	}
+}
+
+export function toggleHas(
+	state: SchemasFilterState,
+	flag: HasFlag,
+): SchemasFilterState {
+	const has = state.has.includes(flag)
+		? state.has.filter((entry) => entry !== flag)
+		: [...state.has, flag]
+	return { ...state, has: HAS_FLAGS.filter((entry) => has.includes(entry)) }
+}

package/frontend-vue/app/build/schemas/useSchemasListing.ts

@@ -0,0 +1,62 @@
+import { computed, ref, watch } from 'vue'
+import {
+	readFilterState,
+	sourceQuery,
+	type SchemasFilterState,
+} from './filterState'
+
+// What the Schemas page's filter bar counts: the tables its state (read from
+// the URL) lists, through the table view's own source route, and the tables
+// registered before any filter ("12 of 40").
+
+const TABLES_SOURCE = '/api/database/tables/source'
+
+interface SourceResponse {
+	total: number
+	all?: number
+}
+
+type ListingStatus = 'idle' | 'pending' | 'success' | 'error'
+
+export function useSchemasListing() {
+	const route = useDmsRoute()
+	const { $authFetch } = useAuthFetch()
+	const state = computed<SchemasFilterState>(() => readFilterState(route.query))
+	const query = computed(() => sourceQuery(state.value))
+
+	// The counts of the last answer stay while the next one loads.
+	const total = ref(0)
+	const all = ref<number | null>(null)
+	const status = ref<ListingStatus>('idle')
+	let latest = 0
+
+	async function load() {
+		const request = ++latest
+		status.value = 'pending'
+		try {
+			const response = await $authFetch<SourceResponse>(TABLES_SOURCE, {
+				query: query.value,
+			})
+			if (request !== latest) return
+			total.value = response.total
+			all.value = response.all ?? null
+			status.value = 'success'
+		} catch {
+			if (request === latest) status.value = 'error'
+		}
+	}
+
+	// In the browser only: the server renders no count.
+	if (typeof window !== 'undefined') {
+		watch(() => JSON.stringify(query.value), load, { immediate: true })
+	}
+
+	return {
+		state,
+		/** Tables the bar's filters list. */
+		total,
+		/** Registered tables before any filter; null until known. */
+		all,
+		status,
+	}
+}

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

@@ -0,0 +1,98 @@
+import type { InstanceChoice } from '../data/instanceOptions'
+
+export type { InstanceChoice }
+
+// Where the module's pages live. Module pages resolve under
+// /modules/<module id>; a link without that prefix 404s.
+const MODULE_ROOT = '/modules/database'
+
+export const DATABASE_PAGES = {
+	overview: `${MODULE_ROOT}/overview`,
+	schemas: `${MODULE_ROOT}/schemas`,
+	diagram: `${MODULE_ROOT}/diagram`,
+	data: `${MODULE_ROOT}/data`,
+	query: `${MODULE_ROOT}/query`,
+} as const
+
+type DatabasePage = keyof typeof DATABASE_PAGES
+
+/** A column value the data browser filters the table on when it opens. */
+interface TableMatch {
+	field: string
+	value: string
+}
+
+interface TableAddress {
+	schema: string
+	table: string
+	/**
+	 * A named instance, none for the default one; a page link also takes
+	 * ALL_INSTANCES_PARAM for every instance.
+	 */
+	instance?: string
+	match?: TableMatch
+}
+
+const MATCH_SEPARATOR = ':'
+
+// The URL's `instance`, the same on every page of the module: absent for the
+// default instance, `all` for every instance at once, any other value for
+// the instance of that name. No escaping: an instance named "all" cannot be
+// linked to.
+
+/** The URL's `instance` for every instance at once. */
+export const ALL_INSTANCES_PARAM = 'all'
+
+/** The instance an `instance` URL parameter names; a missing one is the default. */
+export function instanceFromUrl(param: unknown): InstanceChoice {
+	const first = Array.isArray(param) ? param[0] : param
+	const value = typeof first === 'string' ? first.trim() : ''
+	if (!value) return { kind: 'default' }
+	if (value === ALL_INSTANCES_PARAM) return { kind: 'all' }
+	return { kind: 'named', id: value }
+}
+
+/** The `instance` URL parameter of a choice; undefined (left out) for the default. */
+export function instanceToUrl(choice: InstanceChoice): string | undefined {
+	if (choice.kind === 'default') return undefined
+	if (choice.kind === 'all') return ALL_INSTANCES_PARAM
+	return choice.id
+}
+
+function encodeMatch(match: TableMatch): string {
+	return `${match.field}${MATCH_SEPARATOR}${match.value}`
+}
+
+/** `field:value` back to its parts; the value may hold separators itself. */
+export function decodeMatch(raw: unknown): TableMatch | null {
+	if (typeof raw !== 'string') return null
+	const index = raw.indexOf(MATCH_SEPARATOR)
+	if (index <= 0) return null
+	return { field: raw.slice(0, index), value: raw.slice(index + 1) }
+}
+
+/** A page of the module opened on one table, e.g. the data browser on it. */
+export function tableLink(page: DatabasePage, address: TableAddress): string {
+	const query = new URLSearchParams({
+		schema: address.schema,
+		table: address.table,
+	})
+	if (address.instance) query.set('instance', address.instance)
+	if (address.match) query.set('match', encodeMatch(address.match))
+	return `${DATABASE_PAGES[page]}?${query.toString()}`
+}
+
+const IDENTIFIER = /^[A-Z_$][\w$]*$/i
+
+/** `schemas.shop` or `schemas["dms-core"]`, as the query DSL reaches a schema. */
+export function schemaAccess(schemaId: string): string {
+	return IDENTIFIER.test(schemaId)
+		? `schemas.${schemaId}`
+		: `schemas[${JSON.stringify(schemaId)}]`
+}
+
+/** The DSL reaching a table, for the query console's prefilled snippets. */
+export function tableAccess(address: TableAddress): string {
+	const instance = address.instance ? JSON.stringify(address.instance) : ''
+	return `${schemaAccess(address.schema)}.instance(${instance}).table(${JSON.stringify(address.table)})`
+}