@bakery-framework/plugin-db-explorer 2.0.0-alpha.11

package/src/client.ts

@@ -0,0 +1,409 @@
+/**
+ * The explorer's browser entry: boot, then wiring. Nothing else.
+ *
+ * This file used to be the whole client — 197 lines, one `renderTable` that
+ * fetched, built a header, built a body and built a pager, and scored **34**
+ * against biome's ceiling of 25. Growing that into a data editor would have
+ * meant growing that one function, so the shape changed first. The pieces live
+ * under `client/`, each obeying two mechanical rules — **no function both
+ * fetches and renders**, and **every loop body is a named function** — and what
+ * is left here is the composition: state, routing, and which callback goes
+ * where.
+ *
+ * The layout is the one a database client is expected to have: a table list, a
+ * strip of table tabs with VS Code preview semantics, Data / Structure /
+ * Relations under it — **one level of nesting and no more** — and a status bar.
+ * Tab state lives in `client/tabs.ts` and is pure; this module owns the hash.
+ *
+ * What is deliberately *not* here, and is not anywhere: a SQL console, an ER
+ * diagram, and grid virtualisation. The first is refused by the plugin's
+ * contract — no raw SQL, structurally — and the other two are not what a row
+ * editor is for.
+ */
+
+import {
+  adoptUrlKey,
+  fetchGraph,
+  fetchPage,
+  fetchSchema,
+  messageOf,
+} from './client/api'
+import { confirmChoice, notify } from './client/confirm'
+import { el } from './client/dom'
+import { EditSession, UndoStack } from './client/edit-session'
+import { equalityFilters } from './client/filter-builder'
+import { FkResolver, type FkTarget } from './client/fk'
+import type { SchemaColumn, SchemaTable } from './client/meta'
+import { Page } from './client/page'
+import { openPanel } from './client/panel'
+import { saveRow } from './client/save'
+import { renderSidebar } from './client/sidebar'
+import {
+  type AppState,
+  createState,
+  defaultView,
+  isSystemTable,
+  type TableView,
+  tableOf,
+  type ViewState,
+} from './client/state'
+import {
+  activeTab,
+  activeView,
+  closeTab,
+  createTabs,
+  decodeTabs,
+  encodeTabs,
+  openPermanent,
+  openPreview,
+  promoteActive,
+  pruneTabs,
+  replaceActiveView,
+  selectTab,
+  type TabsState,
+} from './client/tabs'
+import {
+  renderNewTabPage,
+  renderTabStrip,
+  renderViewTabs,
+} from './client/tabstrip'
+import type { Filter } from './shared/filters'
+
+const app = document.getElementById('app')!
+
+const state: AppState = createState()
+const session = new EditSession()
+const resolver = new FkResolver()
+const undoStack = new UndoStack(20)
+
+let tabs: TabsState = createTabs()
+
+/** Set while `writeHash` writes, so the `hashchange` listener ignores itself. */
+let selfNavigation = false
+
+const page = new Page(state, session, resolver, undoStack, {
+  goto: view => void goto(view),
+  saveRow: (table, id) => void save(table, id),
+  openRow: openRowPanel,
+  followFk: (target, key) => void followFk(target, key),
+  reload: () => renderMain(),
+  openTable: (table, filters) => void openTable(table, filters),
+  onEdit: () => {
+    if (!activeTab(tabs)?.preview) return
+    tabs = promoteActive(tabs)
+    writeHash()
+    renderChrome()
+  },
+  rewind: depth => {
+    state.trail = state.trail.slice(0, depth)
+    void goto(state.trail[depth] ?? defaultView(currentTable()))
+  },
+})
+
+function currentTable(): string {
+  return activeView(tabs)?.table ?? ''
+}
+
+function save(table: SchemaTable, id: string): void {
+  void saveRow(table, id, {
+    session,
+    surface: () => page.grid,
+    reload: renderMain,
+    onDirtyChange: () => page.paintDirty(),
+  })
+}
+
+// ------------------------------------------------------------------- routing
+
+function writeHash(): void {
+  selfNavigation = true
+  location.hash = encodeTabs(tabs)
+  // `hashchange` fires as a task, so the flag has to survive at least until
+  // the next one — a microtask would clear it before the listener ran.
+  setTimeout(() => {
+    selfNavigation = false
+  }, 0)
+}
+
+/**
+ * Ask before losing typed values.
+ *
+ * The navigation half of the unload guard: losing typed values to a mis-click
+ * on a table name is the same loss as losing them to a closed tab, and only one
+ * of the two was ever guarded by the browser.
+ */
+async function confirmDiscard(): Promise<boolean> {
+  if (session.dirtyRows() === 0) return true
+  const ok = await confirmChoice({
+    verb: 'discard',
+    count: session.dirtyRows(),
+    table: currentTable() || '—',
+    detail: 'unsaved edits will be thrown away',
+  })
+  if (ok) session.clear()
+  return ok
+}
+
+/** Move the active tab to a new view of the same table. */
+async function goto(view: ViewState): Promise<void> {
+  if (!(await confirmDiscard())) return
+  tabs = replaceActiveView(tabs, view)
+  writeHash()
+  await renderMain()
+}
+
+/** Switch which tab is showing. Each tab keeps its own page, sort and filters. */
+async function select(index: number): Promise<void> {
+  if (index === tabs.active) return
+  if (!(await confirmDiscard())) return
+  tabs = selectTab(tabs, index)
+  writeHash()
+  await renderAll()
+}
+
+/** Single click in the sidebar: a replaceable preview tab. */
+async function preview(table: string): Promise<void> {
+  if (!(await confirmDiscard())) return
+  tabs = openPreview(tabs, defaultView(table))
+  writeHash()
+  await renderAll()
+}
+
+/** Double click, or a link from Relations: a tab that stays. */
+async function openTable(table: string, filters: Filter[] = []): Promise<void> {
+  if (!(await confirmDiscard())) return
+  tabs = openPermanent(tabs, { ...defaultView(table), filters })
+  // A link that carries filters is a deliberate destination, so it replaces
+  // whatever the tab held rather than restoring the tab's old view.
+  if (filters.length) {
+    tabs = replaceActiveView(tabs, { ...defaultView(table), filters })
+  }
+  writeHash()
+  await renderAll()
+}
+
+async function close(index: number): Promise<void> {
+  if (index === tabs.active && !(await confirmDiscard())) return
+  tabs = closeTab(tabs, index)
+  writeHash()
+  await renderAll()
+}
+
+function switchView(view: TableView): void {
+  const current = activeView(tabs)
+  if (!current) return
+  void goto({ ...current, view })
+}
+
+// ------------------------------------------------------------------ painting
+
+/**
+ * The four regions, built **once**.
+ *
+ * The slots matter: `renderChrome` repaints the sidebar and the strip in
+ * place, and `#main` is not one of them. Rebuilding the whole shell on every
+ * tab-strip change would tear down the grid — including any editor open in it
+ * and the focus inside that editor — every time a staged edit promoted a
+ * preview tab, which is precisely when it must not.
+ */
+const sideSlot = el('div', { class: 'side-slot' })
+const stripSlot = el('div', { class: 'strip-slot' })
+const mainSlot = el('main', { class: 'main', id: 'main' })
+
+function renderShell(): void {
+  const column = el('div', { class: 'column' })
+  column.append(stripSlot, mainSlot, page.status.node)
+  app.replaceChildren(sideSlot, column)
+}
+
+/** Sidebar and tab strip. Repainted whenever the *set* of tabs changes. */
+function renderChrome(): void {
+  sideSlot.replaceChildren(
+    renderSidebar({
+      tables: state.report?.tables ?? [],
+      showSystem: state.showSystem,
+      activeTable: activeView(tabs)?.table ?? null,
+      onPreview: table => void preview(table),
+      onOpen: table => void openTable(table),
+      onToggleSystem: show => {
+        state.showSystem = show
+        renderChrome()
+      },
+    }),
+  )
+
+  const strip = renderTabStrip({
+    tabs,
+    onSelect: index => void select(index),
+    onPromote: index => {
+      tabs = selectTab(tabs, index)
+      tabs = promoteActive(tabs)
+      writeHash()
+      renderChrome()
+    },
+    onClose: index => void close(index),
+    onNew: () => {
+      tabs = { ...tabs, active: -1 }
+      writeHash()
+      void renderAll()
+    },
+  })
+
+  const current = activeView(tabs)
+  stripSlot.replaceChildren(strip)
+  if (current) {
+    stripSlot.appendChild(
+      renderViewTabs({ current: current.view, onSelect: switchView }),
+    )
+  }
+}
+
+async function renderAll(): Promise<void> {
+  renderChrome()
+  await renderMain()
+}
+
+/** Fetch, then render — the two never live in one function. */
+async function renderMain(): Promise<void> {
+  const main = mainSlot
+  const view = activeView(tabs)
+  if (!view) {
+    page.paintEmpty(main, renderNewTabPage())
+    return
+  }
+
+  const table = tableOf(state, view.table)
+  if (!table) {
+    page.paintEmpty(
+      main,
+      el('p', { class: 'note', text: `${view.table} is not in this schema.` }),
+    )
+    return
+  }
+
+  // Structure and Relations render from the schema report the client already
+  // holds — no request, so no loading state and no failure path.
+  if (view.view !== 'data') {
+    page.paintMeta(main, view, table)
+    return
+  }
+
+  main.replaceChildren(
+    el('p', { class: 'note', text: `loading ${table.name}…` }),
+  )
+  try {
+    const answer = await fetchPage(view)
+    page.paint(main, view, table, answer.data, answer.ms)
+  } catch (error) {
+    main.replaceChildren(el('p', { class: 'error', text: messageOf(error) }))
+  }
+}
+
+// ----------------------------------------------------------- panel and links
+
+function openRowPanel(
+  table: SchemaTable,
+  columns: SchemaColumn[],
+  editable: boolean,
+  row: Record<string, unknown>,
+): void {
+  const handle = openPanel({
+    table,
+    columns,
+    row,
+    editable,
+    graph: state.graph,
+    session,
+    onSave: id => {
+      handle.close()
+      save(table, id)
+    },
+    // A real edit is what makes a preview tab permanent — VS Code's rule, and
+    // the one that matters: nobody wants the tab they just typed into replaced
+    // by the next single click in the sidebar.
+    onDirtyChange: () => {
+      tabs = promoteActive(tabs)
+      page.paintDirty()
+      renderChrome()
+    },
+    onNavigate: (name, filters) => void openTable(name, filters),
+  })
+}
+
+/**
+ * Follow a foreign key.
+ *
+ * One `eq` filter per referenced column, which *is* the row identity — so the
+ * destination page holds exactly the referenced row. This used to need a
+ * second mechanism: `filters` was a substring `LIKE`, `id=1` also matched `11`,
+ * so a link carried a separate `focus` identity and the grid highlighted it.
+ * `eq` removed the need and `focus` went with it.
+ *
+ * The current view is pushed first, so Back returns to where the reference was
+ * followed from — the breadcrumb, which stays.
+ */
+async function followFk(
+  target: FkTarget,
+  key: Record<string, unknown>,
+): Promise<void> {
+  const current = activeView(tabs)
+  if (current) state.trail.push(current)
+  await openTable(target.refTable, equalityFilters(key))
+}
+
+// ------------------------------------------------------------------ plumbing
+
+/**
+ * The unload guard.
+ *
+ * `preventDefault` is the modern spelling and `returnValue` is what Safari
+ * still reads. Both, because losing an edit to a closed tab is the failure this
+ * exists for and the second line costs a line.
+ */
+function guardUnload(event: BeforeUnloadEvent): void {
+  if (session.dirtyRows() === 0) return
+  event.preventDefault()
+  event.returnValue = ''
+}
+
+async function boot(): Promise<void> {
+  adoptUrlKey()
+  try {
+    // `{access, tables}`: the client has to know its posture *before* it
+    // renders, so it never draws an edit affordance it cannot honour.
+    state.report = await fetchSchema()
+  } catch (error) {
+    app.replaceChildren(el('p', { class: 'error', text: messageOf(error) }))
+    return
+  }
+
+  // The graph is decoration — a schema with no declared foreign keys is
+  // ordinary, and a failure here must not cost anyone the grid.
+  state.graph = await fetchGraph().catch(() => null)
+
+  // A hash can name a table that has since been dropped; pruning here means
+  // the strip never carries a tab that can only ever render an error.
+  const known = new Set((state.report.tables ?? []).map(table => table.name))
+  tabs = pruneTabs(decodeTabs(location.hash), known)
+
+  // A system table reached by link opens with the sidebar toggle already on,
+  // so the tab it lands in is visible in the list beside it rather than
+  // appearing to have come from nowhere.
+  if (tabs.tabs.some(tab => isSystemTable(tab.view.table))) {
+    state.showSystem = true
+  }
+
+  renderShell()
+  await renderAll()
+
+  window.addEventListener('beforeunload', guardUnload)
+  window.addEventListener('hashchange', () => {
+    if (selfNavigation) return
+    tabs = pruneTabs(decodeTabs(location.hash), known)
+    void renderAll()
+  })
+}
+
+void boot().catch(error => {
+  notify(messageOf(error), 'error')
+})

package/src/endpoints/common.ts

@@ -0,0 +1,122 @@
+/**
+ * The preamble every write endpoint shares, in the order the checks have to
+ * happen.
+ *
+ *   1. **`currentCanWrite()`** — a `read` caller is refused before the body is
+ *      even parsed, so nothing about the request can influence the answer.
+ *   2. **The body** — JSON, an object, naming a table.
+ *   3. **The table** — 404 if it is not there.
+ *   4. **The identity** — 409 if the table has none. A table with no primary
+ *      key and no all-NOT-NULL unique index is read-only for everyone,
+ *      including a `write` caller, because there is no way to name one of its
+ *      rows. See `identity.ts`.
+ *
+ * Bounds (413) and validation (400) come after, in each endpoint, because they
+ * are about the request's own shape rather than about who is asking.
+ */
+
+import { Case, Try } from '@bakery-framework/core/utils'
+import type { JsonResponseData } from '@bakery-framework/core/utils/common'
+import { response } from '@bakery-framework/core/utils/http'
+import { currentCanWrite } from '../access'
+import { introspect, type TableFacts } from '../identity'
+import type { FieldError } from '../validate'
+
+export type Envelope = JsonResponseData<unknown>
+
+export type WriteStart =
+  | { ok: true; table: TableFacts; body: Record<string, unknown> }
+  | { ok: false; response: Envelope }
+
+/** A 400 carrying every field error, never only the first. */
+export function invalid(errors: FieldError[]): Envelope {
+  return response.json.error(400, 'Invalid request', { errors })
+}
+
+/**
+ * The request body as an object, or `null`.
+ *
+ * `req.json()` rather than core's `processBody`, which answers `{}` for a body
+ * it could not parse — indistinguishable from an empty one, so a truncated
+ * upload would be reported as a missing `table` field.
+ */
+export async function readBody(
+  req: Request,
+): Promise<Record<string, unknown> | null> {
+  const body = await Try.return(
+    async () => (await req.json()) as unknown,
+    null as unknown,
+  )
+  return typeof body === 'object' && body !== null && !Array.isArray(body)
+    ? (body as Record<string, unknown>)
+    : null
+}
+
+/**
+ * Find a table by the name the caller used.
+ *
+ * Raw database name first — that is what `/api/_db/schema` renders and what the
+ * grid sends back. The camel spelling is accepted as well, because a script
+ * written against a typed schema has `orderItems` where the database has
+ * `order_items`, and refusing that would be refusing the ORM's own vocabulary.
+ */
+export function findTable(
+  tables: Map<string, TableFacts>,
+  name: string,
+): TableFacts | undefined {
+  const exact = tables.get(name)
+  if (exact) return exact
+  const camel = Case.camel(name)
+  for (const table of tables.values()) {
+    if (table.camel === camel) return table
+  }
+  return undefined
+}
+
+export async function beginWrite(req: Request): Promise<WriteStart> {
+  // First, and before the body is read. Convention 2: the guard returns the
+  // rejection, and it is the caller's job to return it unchanged.
+  if (!currentCanWrite()) {
+    return {
+      ok: false,
+      response: response.json.error(403, 'This session may read but not write'),
+    }
+  }
+
+  const body = await readBody(req)
+  if (!body) {
+    return {
+      ok: false,
+      response: response.json.error(400, 'Expected a JSON object body'),
+    }
+  }
+
+  const name = body.table
+  if (typeof name !== 'string' || !name) {
+    return {
+      ok: false,
+      response: response.json.error(400, 'table is required'),
+    }
+  }
+
+  const tables = await introspect()
+  const table = findTable(tables, name)
+  if (!table) {
+    return {
+      ok: false,
+      response: response.json.error(404, `No table named ${name}`),
+    }
+  }
+
+  if (table.identity.mode === 'none') {
+    return {
+      ok: false,
+      response: response.json.error(
+        409,
+        `${table.name} is read-only: ${table.identity.reason}`,
+      ),
+    }
+  }
+
+  return { ok: true, table, body }
+}

package/src/endpoints/graph.ts

@@ -0,0 +1,148 @@
+/**
+ * What the grid needs to render a foreign key as something other than a number.
+ *
+ * `/api/_db/graph` is the map, fetched once: every declared foreign key, every
+ * table's identity, and the column worth showing instead of an id.
+ * `/api/_db/lookup` resolves actual references — **batched, one query per
+ * table**, because the shape this replaces is a `fetch` per visible cell, and a
+ * fifty-row page with three foreign keys is a hundred and fifty round trips.
+ */
+
+import { Try } from '@bakery-framework/core/utils'
+import type { JsonResponseData } from '@bakery-framework/core/utils/common'
+import { response } from '@bakery-framework/core/utils/http'
+import { connection } from '@bakery-framework/orm/connection'
+import { qId } from '@bakery-framework/orm/schema-util'
+import { type Identity, introspect, type TableFacts } from '../identity'
+import { overLimit } from '../policy'
+import { findTable, readBody } from './common'
+
+export async function handleGraph(): Promise<JsonResponseData<unknown>> {
+  return await Try.return(
+    async () => {
+      const [tables, foreignKeys] = await Promise.all([
+        introspect(),
+        // Composites are already grouped by the adapter, keyed by the tuple
+        // rather than by constraint name — SQLite reports no name at all.
+        connection.getForeignKeys(),
+      ])
+
+      const identity: Record<string, Identity> = {}
+      const labels: Record<string, string | null> = {}
+      for (const table of tables.values()) {
+        identity[table.name] = table.identity
+        labels[table.name] = table.label
+      }
+
+      return response.json.success('success', {
+        foreignKeys,
+        identity,
+        labels,
+      })
+    },
+    () => response.json.error(500, 'Failed to read the schema graph'),
+  )
+}
+
+export interface LookupRef {
+  table: string
+  key: Record<string, unknown>
+}
+
+export interface LookupResult {
+  table: string
+  key: Record<string, unknown>
+  row: Record<string, unknown> | null
+}
+
+/** A stable string for a set of identity values, for matching rows to refs. */
+function fingerprint(cols: readonly string[], row: Record<string, unknown>) {
+  // `String(...)` rather than the values themselves: the driver may hand back a
+  // `1n` for the `1` that was sent, or a string for a BIGINT, and a lookup that
+  // failed to match on that would render every foreign key as "missing".
+  return cols.map(col => String(row[col] ?? '\0')).join('\x01')
+}
+
+export async function handleLookup(
+  req: Request,
+): Promise<JsonResponseData<unknown>> {
+  const body = await readBody(req)
+  if (!body) return response.json.error(400, 'Expected a JSON object body')
+
+  const refs = body.refs
+  if (!Array.isArray(refs)) {
+    return response.json.error(400, 'refs must be an array')
+  }
+  const over = overLimit('lookupRefs', refs.length)
+  if (over) return response.json.error(413, over)
+  if (!refs.length) return response.json.success('success', { rows: [] })
+
+  return await Try.return(
+    async () => {
+      const tables = await introspect()
+
+      // Grouped first, queried second. One query per *table*, never one per
+      // ref.
+      const byTable = new Map<string, { table: TableFacts; refs: number[] }>()
+      const parsed: (LookupRef | null)[] = refs.map((ref: any, index) => {
+        if (typeof ref?.table !== 'string' || typeof ref?.key !== 'object') {
+          return null
+        }
+        const table = findTable(tables, ref.table)
+        if (!table || table.identity.mode === 'none') return null
+        const group = byTable.get(table.name) ?? { table, refs: [] }
+        group.refs.push(index)
+        byTable.set(table.name, group)
+        return { table: table.name, key: ref.key as Record<string, unknown> }
+      })
+
+      const results: LookupResult[] = refs.map((ref: any, index) => ({
+        table: String(ref?.table ?? ''),
+        key: (parsed[index]?.key ?? {}) as Record<string, unknown>,
+        row: null,
+      }))
+
+      for (const { table, refs: indexes } of byTable.values()) {
+        const cols = table.identity.cols
+        const params: unknown[] = []
+        const groups: string[] = []
+        const wanted = new Map<string, number[]>()
+
+        for (const index of indexes) {
+          const key = parsed[index]!.key
+          // A ref whose key does not name exactly the identity is skipped
+          // rather than widened — a partial key is a predicate over more than
+          // one row, which is the bug `validateKey` refuses for a write and
+          // there is no reason to accept it for a read.
+          if (cols.some(col => !(col in key))) continue
+          groups.push(
+            `(${cols
+              .map(col => {
+                params.push(key[col])
+                return `${qId(col)} = ?`
+              })
+              .join(' AND ')})`,
+          )
+          const print = fingerprint(cols, key)
+          wanted.set(print, [...(wanted.get(print) ?? []), index])
+        }
+        if (!groups.length) continue
+
+        const rows = (await connection
+          .query(
+            `SELECT * FROM ${qId(table.name)} WHERE ${groups.join(' OR ')}`,
+          )
+          .all(...params)) as Record<string, unknown>[]
+
+        for (const row of rows) {
+          for (const index of wanted.get(fingerprint(cols, row)) ?? []) {
+            results[index]!.row = row
+          }
+        }
+      }
+
+      return response.json.success('success', { rows: results })
+    },
+    (error: any) => response.json.error(400, error?.message ?? 'Lookup failed'),
+  )
+}