@bakery-framework/plugin-db-explorer 2.0.0-alpha.4 → 2.0.0-alpha.6

package/src/client/relations.ts

@@ -0,0 +1,205 @@
+/**
+ * The Relations view: what this table points at, and what points back.
+ *
+ * `GET /api/_db/graph` has always returned every declared foreign key. The grid
+ * used it to turn a cell into a link, which is the per-row question; nobody
+ * could see the *table's* shape without clicking through a row that happened to
+ * have the reference filled in. Both directions are listed here, and both are
+ * clickable, because "which tables reference this one" is the question you ask
+ * before deleting anything.
+ *
+ * `relationsFor` is **pure** and does the grouping; the render half only turns
+ * it into buttons.
+ */
+
+import type { Filter } from '../shared/filters'
+import { box, button, each, el } from './dom'
+import { equalityFilters } from './filter-builder'
+import { reverseFks } from './fk'
+import type { ForeignKeyInfo, SchemaGraph } from './meta'
+import { sameTable } from './meta'
+
+export interface Relation {
+  /** The columns on the near side — this table's, for `outgoing`. */
+  cols: string[]
+  /** The table at the other end. */
+  table: string
+  /** The columns at the other end. */
+  refCols: string[]
+  name?: string
+}
+
+export interface Relations {
+  /** Foreign keys declared *on* this table. */
+  outgoing: Relation[]
+  /** Foreign keys on other tables that point *at* this one. */
+  incoming: Relation[]
+}
+
+/**
+ * Both directions, grouped.
+ *
+ * `sameTable` rather than `===` throughout, and that is not defensive
+ * programming: `getForeignKeys()` reports whatever the database calls a table
+ * while `getConstraints()` is camel-keyed, and the graph endpoint passes both
+ * through untouched. Comparing literally makes every foreign key on a
+ * `snake_case` schema invisible — the whole feature silently absent, which is
+ * exactly what `meta.ts`'s own note on `sameTable` records.
+ *
+ * A self-reference — a `manager_id` pointing at the same table's `id` — appears
+ * in **both** lists, which is correct: it is genuinely a key this table
+ * declares and genuinely a key that points here.
+ */
+export function relationsFor(
+  graph: SchemaGraph | null,
+  table: string,
+): Relations {
+  if (!graph) return { outgoing: [], incoming: [] }
+
+  const outgoing = Object.values(graph.foreignKeys)
+    .filter(fk => sameTable(fk.table, table))
+    .map(toOutgoing)
+  const incoming = reverseFks(graph, table).map(toIncoming)
+  return { outgoing, incoming }
+}
+
+function toOutgoing(fk: ForeignKeyInfo): Relation {
+  return {
+    cols: fk.cols,
+    table: fk.refTable,
+    refCols: fk.refCols,
+    name: fk.name,
+  }
+}
+
+/**
+ * An incoming key, read from the far side.
+ *
+ * `cols` are the *referencing* table's columns and `refCols` are ours, which is
+ * the reverse of the outgoing shape and is what makes the two lists read the
+ * same way on screen: near columns first, far table second.
+ */
+function toIncoming(fk: ForeignKeyInfo): Relation {
+  return {
+    cols: fk.cols,
+    table: fk.table,
+    refCols: fk.refCols,
+    name: fk.name,
+  }
+}
+
+// --------------------------------------------------------------------- render
+
+export interface RelationsContext {
+  table: string
+  graph: SchemaGraph | null
+  /** Open a table in a tab, optionally filtered. */
+  onOpen: (table: string, filters: Filter[]) => void
+}
+
+export function renderRelations(ctx: RelationsContext): HTMLElement {
+  const relations = relationsFor(ctx.graph, ctx.table)
+  const node = box('relations')
+
+  node.appendChild(
+    section(
+      `References (${relations.outgoing.length})`,
+      'columns of this table that point elsewhere',
+      relations.outgoing,
+      relation => outgoingRow(ctx, relation),
+    ),
+  )
+  node.appendChild(
+    section(
+      `Referenced by (${relations.incoming.length})`,
+      'tables whose rows point at this one',
+      relations.incoming,
+      relation => incomingRow(ctx, relation),
+    ),
+  )
+  return node
+}
+
+function section(
+  title: string,
+  blurb: string,
+  relations: readonly Relation[],
+  make: (relation: Relation) => HTMLElement,
+): HTMLElement {
+  const node = box('structure-section')
+  node.appendChild(el('h3', { text: title }))
+  node.appendChild(el('p', { class: 'note', text: blurb }))
+  if (!relations.length) {
+    node.appendChild(el('p', { class: 'note', text: 'none declared' }))
+    return node
+  }
+  const list = box('relation-list')
+  each(list, relations, make)
+  node.appendChild(list)
+  return node
+}
+
+/**
+ * `this.col → that.col`, opening the referenced table unfiltered.
+ *
+ * Unfiltered on purpose: an outgoing key is a statement about the *schema*, not
+ * about a row. Which row it points at depends on which row you are looking at,
+ * and that link is the one in the grid cell.
+ */
+function outgoingRow(ctx: RelationsContext, relation: Relation): HTMLElement {
+  const row = box('relation')
+  row.appendChild(
+    el('span', {
+      class: 'relation-cols',
+      text: `${relation.cols.join(', ')} →`,
+    }),
+  )
+  row.appendChild(
+    button(
+      `${relation.table}.${relation.refCols.join(', ')}`,
+      () => ctx.onOpen(relation.table, []),
+      { class: 'btn', title: `open ${relation.table}` },
+    ),
+  )
+  if (relation.name) {
+    row.appendChild(el('span', { class: 'note', text: relation.name }))
+  }
+  return row
+}
+
+function incomingRow(ctx: RelationsContext, relation: Relation): HTMLElement {
+  const row = box('relation')
+  row.appendChild(
+    button(
+      `${relation.table}.${relation.cols.join(', ')}`,
+      () => ctx.onOpen(relation.table, []),
+      { class: 'btn', title: `open ${relation.table}` },
+    ),
+  )
+  row.appendChild(
+    el('span', {
+      class: 'relation-cols',
+      text: `→ ${relation.refCols.join(', ')}`,
+    }),
+  )
+  return row
+}
+
+/**
+ * The filters that open the rows of `relation.table` pointing at one row.
+ *
+ * Exported for the row panel, which is where "referenced by *this row*" lives.
+ * `eq` per column, so the count and the page are exact — this used to be a
+ * substring `LIKE` and the panel had to label its counts "approximate".
+ */
+export function filtersForIncoming(
+  relation: Relation,
+  row: Record<string, unknown>,
+): Filter[] {
+  const key: Record<string, unknown> = {}
+  relation.refCols.forEach((refCol, index) => {
+    const column = relation.cols[index]
+    if (column) key[column] = row[refCol]
+  })
+  return equalityFilters(key)
+}

package/src/client/save.ts

@@ -0,0 +1,209 @@
+/**
+ * Saving one row, and the conflict that is the interesting half.
+ *
+ * Kept apart from the page because it is the part with a decision in it: a
+ * rejected write must never be a lost edit, and a 409 must not be answered with
+ * a retry button. "Try again" against a row that moved is precisely how the
+ * other person's edit disappears.
+ */
+
+import type { ColumnKind } from '../shared/coerce'
+import { type ApiError, patchRow } from './api'
+import { box, button, el } from './dom'
+import type { EditSession, RowPlan } from './edit-session'
+import type { SchemaTable } from './meta'
+
+/**
+ * The part of the grid a save needs. Structural, so `Grid` satisfies it
+ * without knowing this module exists.
+ */
+export interface RowSurface {
+  indexOfRow: (id: string) => number
+  setRowMessage: (index: number, message: string) => void
+  setRowBusy: (index: number, busy: boolean) => void
+}
+
+export interface SaveDeps {
+  session: EditSession
+  /** Read late: the grid is replaced on every repaint. */
+  surface: () => RowSurface | null
+  reload: () => Promise<void>
+  onDirtyChange: () => void
+}
+
+function kindLookup(
+  table: SchemaTable,
+): (column: string) => ColumnKind | undefined {
+  const kinds = new Map(table.columns.map(c => [c.name, c.kind as ColumnKind]))
+  return column => kinds.get(column)
+}
+
+function messageOf(error: unknown): string {
+  return (error as Error)?.message ?? String(error)
+}
+
+/**
+ * One row, one PATCH, carrying every changed column and its pre-image.
+ *
+ * The pre-image goes as `expect`, so the statement is `identity ∧ expect` and a
+ * concurrent edit is a 409 rather than a silent overwrite. `force` is sent only
+ * when a changed column is `json` or `buffer` — kinds SQL cannot compare, so
+ * there is no predicate to guard them with.
+ */
+export async function saveRow(
+  table: SchemaTable,
+  id: string,
+  deps: SaveDeps,
+): Promise<void> {
+  const surface = deps.surface()
+  const plan = deps.session.plan(id, table.identity.cols, kindLookup(table))
+  if (!plan || !surface) return
+
+  const index = surface.indexOfRow(id)
+  if (plan.missingIdentity.length) {
+    surface.setRowMessage(
+      index,
+      `this row is missing ${plan.missingIdentity.join(', ')}`,
+    )
+    return
+  }
+
+  surface.setRowBusy(index, true)
+  try {
+    await send(table, plan, plan.expect)
+    deps.session.drop(id)
+    deps.onDirtyChange()
+    await deps.reload()
+  } catch (error) {
+    surface.setRowBusy(index, false)
+    await reportFailure(table, id, index, error, deps)
+  }
+}
+
+function send(
+  table: SchemaTable,
+  plan: RowPlan,
+  expect: Record<string, unknown>,
+): Promise<unknown> {
+  return patchRow({
+    table: table.name,
+    key: plan.where,
+    set: plan.set,
+    expect,
+    force: plan.unguardable.length > 0,
+  })
+}
+
+/** The typed values survive. Anything else would make the buffer pointless. */
+async function reportFailure(
+  table: SchemaTable,
+  id: string,
+  index: number,
+  error: unknown,
+  deps: SaveDeps,
+): Promise<void> {
+  const api = error as ApiError
+  const surface = deps.surface()
+  if (api?.status !== 409) {
+    surface?.setRowMessage(index, messageOf(error))
+    return
+  }
+  const theirs = (api.data as { row?: Record<string, unknown> } | undefined)
+    ?.row
+  surface?.setRowMessage(index, 'this row changed since it was read')
+  await offerResolution(table, id, index, theirs ?? null, deps)
+}
+
+/**
+ * Keep mine / Take theirs, with the server's copy of the row in hand.
+ *
+ * The 409 body carries the row as it now stands — that is why the endpoint
+ * attaches it — so this is a real choice rather than a prompt to guess.
+ */
+function offerResolution(
+  table: SchemaTable,
+  id: string,
+  index: number,
+  theirs: Record<string, unknown> | null,
+  deps: SaveDeps,
+): Promise<void> {
+  let settle: () => void = () => {}
+  const done = new Promise<void>(resolve => {
+    settle = resolve
+  })
+
+  const dialog = el('dialog', { class: 'danger' })
+  dialog.appendChild(
+    el('h3', { text: 'This row changed while you were editing' }),
+  )
+  dialog.appendChild(
+    el('p', {
+      class: 'note',
+      text: theirs
+        ? 'Keep mine re-sends your columns against the row as it is now. ' +
+          'Take theirs discards your edits.'
+        : 'The row is gone. Your edits cannot be applied to it.',
+    }),
+  )
+
+  const takeTheirs = button(
+    'Take theirs',
+    () => {
+      deps.session.drop(id)
+      dialog.close()
+      void deps.reload().then(settle, settle)
+    },
+    { class: 'btn' },
+  )
+
+  const keepMine = button(
+    'Keep mine',
+    () => {
+      dialog.close()
+      void rebase(table, id, index, theirs, deps).then(settle, settle)
+    },
+    { class: 'btn primary' },
+  )
+  keepMine.disabled = theirs === null
+
+  dialog.appendChild(box('row-bar', takeTheirs, keepMine))
+  document.body.appendChild(dialog)
+  dialog.addEventListener('close', () => dialog.remove())
+  dialog.showModal()
+  return done
+}
+
+/**
+ * Keep mine: the same `set`, with `expect` taken from *their* row.
+ *
+ * Not `expect: {}` — that is last-write-wins, which the endpoint refuses to
+ * default to for exactly this reason. Rebasing on the row that was just shown
+ * means a *third* edit arriving between the 409 and this retry is a 409 again,
+ * which is the correct answer rather than an inconvenience.
+ */
+async function rebase(
+  table: SchemaTable,
+  id: string,
+  index: number,
+  theirs: Record<string, unknown> | null,
+  deps: SaveDeps,
+): Promise<void> {
+  const surface = deps.surface()
+  if (!theirs || !surface) return
+  const plan = deps.session.plan(id, table.identity.cols, kindLookup(table))
+  if (!plan) return
+
+  const expect: Record<string, unknown> = {}
+  for (const column of Object.keys(plan.expect)) expect[column] = theirs[column]
+
+  surface.setRowBusy(index, true)
+  try {
+    await send(table, plan, expect)
+    deps.session.drop(id)
+    deps.onDirtyChange()
+    await deps.reload()
+  } catch (error) {
+    surface.setRowBusy(index, false)
+    surface.setRowMessage(index, messageOf(error))
+  }
+}

package/src/client/sidebar.ts

@@ -0,0 +1,110 @@
+/**
+ * The table list, and the one checkbox that decides what is in it.
+ *
+ * Split out of `page.ts` when tabs arrived: the sidebar is the only thing left
+ * that survives a tab switch, so it repaints on a different schedule from
+ * everything else and had no business sharing a module with the grid's chrome.
+ *
+ * A **single click opens a preview tab** and a **double click makes it
+ * permanent** — the two are wired here and defined in `tabs.ts`.
+ */
+
+import { append, box, button, each, el, on } from './dom'
+import type { SchemaTable } from './meta'
+import { systemTableCount, visibleTables } from './state'
+
+export interface SidebarContext {
+  tables: readonly SchemaTable[]
+  showSystem: boolean
+  /** The table showing in the active tab, so it can be marked. */
+  activeTable: string | null
+  /** Single click: a replaceable preview tab. */
+  onPreview: (table: string) => void
+  /** Double click: a tab that stays. */
+  onOpen: (table: string) => void
+  onToggleSystem: (show: boolean) => void
+}
+
+export function renderSidebar(ctx: SidebarContext): HTMLElement {
+  const side = el('nav', { class: 'side' })
+  side.appendChild(el('h1', { class: 'brand', text: 'db explorer' }))
+
+  const shown = visibleTables(ctx.tables, ctx.showSystem)
+  const list = box('table-list')
+  each(list, shown, table => tableButton(ctx, table))
+  side.appendChild(list)
+
+  if (!shown.length) {
+    side.appendChild(el('p', { class: 'note', text: 'no tables' }))
+  }
+  const toggle = systemToggle(ctx)
+  if (toggle) side.appendChild(toggle)
+  return side
+}
+
+/**
+ * The system-tables checkbox, present only when there is something to reveal.
+ *
+ * `__bakery_schema` is the ORM's sync ledger and is not the user's data, so it
+ * is hidden by default — but every real client offers the toggle rather than
+ * hiding such tables outright, because a ledger row is occasionally exactly
+ * what someone needs to see. The count is in the label so the checkbox says
+ * what it would do before it is clicked.
+ */
+function systemToggle(ctx: SidebarContext): HTMLElement | null {
+  const hidden = systemTableCount(ctx.tables)
+  if (!hidden) return null
+
+  const check = el('input', {
+    attrs: { 'aria-label': 'show system tables' },
+  })
+  check.type = 'checkbox'
+  check.checked = ctx.showSystem
+  on(check, 'change', () => ctx.onToggleSystem(check.checked))
+
+  const label = el('label', {
+    class: 'note system-toggle',
+    text: ` show system tables (${hidden})`,
+    title: "the framework's own bookkeeping — the ORM sync ledger",
+  })
+  label.prepend(check)
+  return label
+}
+
+function tableButton(ctx: SidebarContext, table: SchemaTable): HTMLElement {
+  const node = button(table.name, () => ctx.onPreview(table.name), {
+    class: 'table-btn',
+  })
+  // `dblclick` fires *after* its two `click`s, so the single click has already
+  // opened the preview tab and this only promotes it — which is exactly VS
+  // Code's behaviour and needs no suppression of the first click.
+  on(node, 'dblclick', () => ctx.onOpen(table.name))
+
+  if (table.name === ctx.activeTable) node.classList.add('active')
+  append(node, [badgeFor(table)])
+  return node
+}
+
+/**
+ * A padlock for read-only, a different mark for a view.
+ *
+ * On the *list*, so the state is visible before the table is opened rather than
+ * at the first double-click into a cell.
+ */
+function badgeFor(table: SchemaTable): HTMLElement | null {
+  if (table.isView) {
+    return el('span', {
+      class: 'ro',
+      text: '⊞',
+      title: 'a view — it has no rows of its own to address',
+    })
+  }
+  if (!table.writable) {
+    return el('span', {
+      class: 'ro',
+      text: '🔒',
+      title: table.reason ?? 'read-only',
+    })
+  }
+  return null
+}