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

package/src/client/state.ts

@@ -0,0 +1,218 @@
+/**
+ * What the explorer is looking at, and how that fits in a URL.
+ *
+ * **Pure.** `encodeView`/`decodeView` are a round trip over a string and are
+ * tested as one. The store below is a plain mutable object with no DOM in it;
+ * the hash is written by the entry module, which is the only place that knows
+ * about `location`.
+ *
+ * The view lives in the **hash** rather than the query string on purpose. The
+ * explorer is reached with `?db-key=…` on a first visit, the client scrubs that
+ * parameter out of the URL immediately, and a view state sharing the query
+ * string would be scrubbed along with it — or worse, would have to be
+ * reconstructed by an edit to the same `URLSearchParams` the credential was
+ * just removed from. A hash also never reaches the server, which is the right
+ * place for "which row am I on".
+ */
+
+import type { Filter } from '../shared/filters'
+import { isFilterOp } from '../shared/filters'
+import type { SchemaGraph, SchemaReport, SchemaTable } from './meta'
+
+export const PAGE_SIZE = 50
+
+/** The three views a table has. One level of nesting, and only one. */
+export type TableView = 'data' | 'structure' | 'relations'
+
+const TABLE_VIEWS: readonly TableView[] = ['data', 'structure', 'relations']
+
+export interface ViewState {
+  table: string
+  /** Which of Data / Structure / Relations is showing. */
+  view: TableView
+  page: number
+  sortBy: string | null
+  sortOrder: 'ASC' | 'DESC'
+  /**
+   * Column, operator and operand — several, each removable.
+   *
+   * A **list** rather than a record, because the builder lets a filter exist
+   * before it has a column or a value and a record cannot hold a half-built
+   * one. `toWire` is what collapses it to the record `getData` takes.
+   */
+  filters: Filter[]
+}
+
+export function defaultView(table = ''): ViewState {
+  return {
+    table,
+    view: 'data',
+    page: 1,
+    sortBy: null,
+    sortOrder: 'ASC',
+    filters: [],
+  }
+}
+
+/**
+ * `t` table, `v` view, `p` page, `s` sort column, `o` order, `f` filters.
+ *
+ * Short keys because several of these are encoded per open tab and the whole
+ * thing has to stay something a person can paste into chat. Defaults are
+ * omitted rather than written, so the common case is `t=parcels`.
+ *
+ * There is no `r` any more. It carried a row identity because a filter could
+ * not name a row — `id=1` matched `11` under a substring `LIKE` — and with `eq`
+ * available a foreign-key jump is just a filter. An old link with `r=` decodes
+ * to the same page it always did, minus the highlight.
+ */
+export function encodeView(view: ViewState): string {
+  const params = new URLSearchParams()
+  if (view.table) params.set('t', view.table)
+  if (view.view !== 'data') params.set('v', view.view)
+  if (view.page > 1) params.set('p', String(view.page))
+  if (view.sortBy) {
+    params.set('s', view.sortBy)
+    if (view.sortOrder === 'DESC') params.set('o', 'DESC')
+  }
+  if (view.filters.length) params.set('f', JSON.stringify(view.filters))
+  return params.toString()
+}
+
+export function decodeView(hash: string): ViewState {
+  const params = new URLSearchParams(hash.replace(/^#/, ''))
+  const view = defaultView(params.get('t') ?? '')
+  view.view = readTableView(params.get('v'))
+  const page = Number.parseInt(params.get('p') ?? '1', 10)
+  view.page = Number.isFinite(page) && page > 0 ? page : 1
+  view.sortBy = params.get('s')
+  view.sortOrder = params.get('o') === 'DESC' ? 'DESC' : 'ASC'
+  view.filters = readFilters(params.get('f'))
+  return view
+}
+
+function readTableView(raw: string | null): TableView {
+  return TABLE_VIEWS.find(name => name === raw) ?? 'data'
+}
+
+/**
+ * Filters out of a URL, or none.
+ *
+ * Nothing here is trusted: the hash is user-supplied, and a filter carrying an
+ * operator the ORM does not know would be *dropped* server-side and quietly
+ * widen the result. Anything that does not typecheck as a filter is discarded
+ * here, before it can be sent.
+ */
+function readFilters(raw: string | null): Filter[] {
+  if (!raw) return []
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    // A truncated or hand-edited link. Falling back to "no filters" renders
+    // the table the link asked for, which beats an error page.
+    return []
+  }
+  if (!Array.isArray(parsed)) return []
+  return parsed.filter(isFilter)
+}
+
+function isFilter(value: unknown): value is Filter {
+  if (typeof value !== 'object' || value === null) return false
+  const entry = value as Record<string, unknown>
+  return (
+    typeof entry.column === 'string' &&
+    entry.column !== '' &&
+    isFilterOp(entry.op) &&
+    (entry.value === undefined || typeof entry.value === 'string')
+  )
+}
+
+/** Everything the running client holds. One object, mutated in place. */
+export interface AppState {
+  report: SchemaReport | null
+  graph: SchemaGraph | null
+  /** Views to return to, pushed by a foreign-key jump. */
+  trail: ViewState[]
+  /** Whether the sidebar lists the framework's own tables. Off by default. */
+  showSystem: boolean
+}
+
+export function createState(): AppState {
+  return { report: null, graph: null, trail: [], showSystem: false }
+}
+
+export function tableOf(
+  state: AppState,
+  name: string,
+): SchemaTable | undefined {
+  return state.report?.tables.find(table => table.name === name)
+}
+
+/**
+ * The ORM's own bookkeeping, which is not the user's data.
+ *
+ * `__bakery_schema` is the sync ledger (`orm/src/sync/ledger.ts`), and
+ * `__bakery` is the reserved prefix convention 10 names. Matching the prefix
+ * rather than the one literal name means a second ledger table would be hidden
+ * on the day it lands rather than on the day someone notices.
+ *
+ * Matched against the **raw** database name, which is what the schema report
+ * carries: `introspect()` builds from `getSchema()`, and that speaks raw names.
+ * (`getConstraints()` camel-cases, so the same table is `bakerySchema` there —
+ * that spelling never reaches this client, and matching it here would risk
+ * hiding a user table that happens to be called `bakerySchema`.)
+ */
+const SYSTEM_PREFIX = '__bakery'
+
+export function isSystemTable(name: string): boolean {
+  return name.startsWith(SYSTEM_PREFIX)
+}
+
+/**
+ * The tables the sidebar shows.
+ *
+ * Hidden behind a checkbox rather than removed outright, because every real
+ * client offers the toggle: a ledger row is occasionally exactly what someone
+ * needs to look at, and a table that cannot be reached at all is a support
+ * question.
+ */
+export function visibleTables(
+  tables: readonly SchemaTable[],
+  showSystem: boolean,
+): SchemaTable[] {
+  return showSystem ? [...tables] : tables.filter(t => !isSystemTable(t.name))
+}
+
+/** How many are being hidden, for the checkbox's own label. */
+export function systemTableCount(tables: readonly SchemaTable[]): number {
+  return tables.filter(table => isSystemTable(table.name)).length
+}
+
+/**
+ * Whether this table may be edited, decided **once, before first paint**.
+ *
+ * Two independent reasons it may not be, and the client is told both by
+ * `/api/_db/schema` rather than discovering them at save time: the session may
+ * be `read`, or the table may have no identity. Drawing an editable grid and
+ * then refusing the save is the failure this answers early.
+ */
+export function editableTable(
+  state: AppState,
+  table: SchemaTable | undefined,
+): boolean {
+  if (!table) return false
+  return state.report?.access === 'write' && table.writable
+}
+
+/** Why not, in the words the server used. Never invented here. */
+export function readOnlyReason(
+  state: AppState,
+  table: SchemaTable | undefined,
+): string {
+  if (!table) return 'no table selected'
+  if (state.report?.access !== 'write') {
+    return table.reason ?? 'this session may read but not write'
+  }
+  return table.reason ?? table.identity.reason ?? 'this table is read-only'
+}

package/src/client/statusbar.ts

@@ -0,0 +1,130 @@
+/**
+ * The bar along the bottom: what is on screen, what it cost, what may be done
+ * to it.
+ *
+ * Every database client has one, and it earns its space by answering three
+ * questions that otherwise need a round trip through the developer tools: how
+ * many rows there really are, how long the server took, and whether this
+ * session can write at all. The last one is the reason it exists here — the
+ * access level used to be a line of sidebar text that scrolled away.
+ *
+ * `statusParts` is **pure** and is where the wording lives, so the segments are
+ * asserted rather than read off a screenshot.
+ */
+
+import { box, el } from './dom'
+
+export interface StatusFacts {
+  table: string | null
+  totalRows?: number
+  page: number
+  totalPages?: number
+  /** Milliseconds the server reported for the last table-data call. */
+  ms: number | null
+  access: 'read' | 'write' | false
+  dirtyRows: number
+  /** Filters currently applied, so a surprising row count has an explanation. */
+  filterCount: number
+}
+
+/**
+ * The segments, in order, already worded.
+ *
+ * Absent facts are **omitted rather than rendered as a placeholder** — a
+ * `page 1 / ?` teaches nobody anything, and `getData` genuinely does not always
+ * return a total. An empty array is the honest answer for "nothing is open".
+ */
+export function statusParts(facts: StatusFacts): string[] {
+  if (!facts.table) return []
+  const parts: string[] = []
+
+  if (facts.totalRows !== undefined) {
+    parts.push(`${formatCount(facts.totalRows)} row${plural(facts.totalRows)}`)
+  }
+  parts.push(
+    facts.totalPages !== undefined
+      ? `page ${facts.page} / ${facts.totalPages}`
+      : `page ${facts.page}`,
+  )
+  if (facts.filterCount > 0) {
+    parts.push(`${facts.filterCount} filter${plural(facts.filterCount)}`)
+  }
+  if (facts.ms !== null) parts.push(`${formatMs(facts.ms)} ms`)
+  parts.push(accessLabel(facts.access))
+  if (facts.dirtyRows > 0) {
+    parts.push(`${facts.dirtyRows} unsaved row${plural(facts.dirtyRows)}`)
+  }
+  return parts
+}
+
+function plural(count: number): string {
+  return count === 1 ? '' : 's'
+}
+
+/** Thousands separated, because a six-figure row count is unreadable without. */
+function formatCount(count: number): string {
+  return count.toLocaleString('en-US')
+}
+
+/**
+ * Sub-millisecond timings keep one decimal.
+ *
+ * `getElapsed` returns a float, and a fast query rounding to `0 ms` reads as
+ * "not measured" rather than "fast" — which is the opposite of what it means.
+ */
+function formatMs(ms: number): string {
+  return ms < 10 ? ms.toFixed(1) : String(Math.round(ms))
+}
+
+function accessLabel(access: 'read' | 'write' | false): string {
+  if (access === 'write') return 'read · write'
+  if (access === 'read') return 'read-only'
+  return 'no access'
+}
+
+export class StatusBar {
+  readonly node: HTMLElement
+  private readonly line: HTMLElement
+  /**
+   * The last facts painted.
+   *
+   * Kept so `bumpDirty` can repaint one segment without the caller having to
+   * reconstruct the row count, the page and the timing — which it cannot,
+   * since a staged edit does not re-fetch and the alternative would be showing
+   * a stale count or none.
+   */
+  private facts: StatusFacts = {
+    table: null,
+    page: 1,
+    ms: null,
+    access: false,
+    dirtyRows: 0,
+    filterCount: 0,
+  }
+
+  constructor() {
+    this.line = el('span', { class: 'status-parts' })
+    this.node = box('statusbar', this.line)
+    this.node.setAttribute('role', 'status')
+  }
+
+  paint(facts: StatusFacts): void {
+    this.facts = facts
+    this.render()
+  }
+
+  /** A staged or saved edit. Everything else on the bar is unchanged. */
+  bumpDirty(dirtyRows: number): void {
+    if (this.facts.dirtyRows === dirtyRows) return
+    this.facts = { ...this.facts, dirtyRows }
+    this.render()
+  }
+
+  private render(): void {
+    this.line.textContent = statusParts(this.facts).join(' · ')
+    // The dirty count is the one segment worth colouring, and it is always
+    // last — so the class goes on the bar rather than on a span nobody can see
+    // when the bar is empty.
+    this.node.classList.toggle('dirty', this.facts.dirtyRows > 0)
+  }
+}

package/src/client/structure.ts

@@ -0,0 +1,231 @@
+/**
+ * The Structure view: what the table *is*, as opposed to what is in it.
+ *
+ * Every serious client — DBeaver, DataGrip, Devart — splits a table into Data
+ * and its structure, and keeps them apart. This one was the single biggest
+ * omission: `GET /api/_db/schema` has always returned the type, nullability,
+ * default, enum values, auto-increment flag and resolved row identity of every
+ * column, and the client used all of it *only* to pick which editor widget to
+ * open. None of it was ever on screen. The reason a table is read-only was the
+ * worst of it — it existed, in the server's own words, and appeared nowhere
+ * except a tooltip on a padlock.
+ *
+ * `structureRows` is **pure** and is the whole derivation, so what each column
+ * is said to be is asserted rather than eyeballed.
+ */
+
+import { box, el } from './dom'
+import type { SchemaColumn, SchemaIndex, SchemaTable } from './meta'
+
+/** One row of the columns table, already worded. */
+export interface StructureRow {
+  name: string
+  type: string
+  nullable: string
+  /** `AUTO`, a literal `DEFAULT`, or empty — never a guess. */
+  default: string
+  /** `PK`, `unique`, or empty. */
+  key: string
+  /** The enum members, comma-joined, or empty. */
+  values: string
+  /** Whether this column is part of the row identity. */
+  identity: boolean
+}
+
+/**
+ * A column as the Structure table shows it.
+ *
+ * Two decisions worth naming, because both are places a plausible shortcut is
+ * wrong:
+ *
+ *  - **`hasDefault` and `autoIncrement` are different facts**, and an
+ *    auto-increment column is reported as such rather than as "has a default".
+ *    They differ in the one place it matters — `omittableOnInsert` — and
+ *    conflating them on screen would teach the reader the wrong model.
+ *  - **`notnull` is not the negation of `nullable` here.** The server sends
+ *    both, from two different introspection calls (`getConstraints()` when it
+ *    says anything, `getSchema()`'s flag otherwise), and `nullable` is the
+ *    richer one. It is the one the editors obey, so it is the one shown.
+ */
+export function structureRow(
+  column: SchemaColumn,
+  identityCols: readonly string[],
+  indexes: readonly SchemaIndex[] = [],
+): StructureRow {
+  return {
+    name: column.name,
+    // The length is appended only when the database's own type string does not
+    // already carry it. `getSchema()` reports `VARCHAR(255)` on every dialect
+    // that has sized text, so appending unconditionally rendered
+    // `VARCHAR(255)(255)`. SQLite's `TEXT` with a declared length is the case
+    // that still needs the suffix.
+    type:
+      column.length && !column.type.includes('(')
+        ? `${column.type}(${column.length})`
+        : column.type,
+    nullable: column.nullable ? 'NULL' : 'NOT NULL',
+    default: defaultOf(column),
+    key: keyOf(column, indexes),
+    values: column.enum?.length ? column.enum.join(', ') : '',
+    identity: identityCols.includes(column.name),
+  }
+}
+
+function defaultOf(column: SchemaColumn): string {
+  if (column.autoIncrement) return 'AUTO'
+  return column.hasDefault ? 'DEFAULT' : ''
+}
+
+/**
+ * Primary key first, then unique-index membership.
+ *
+ * Only `unique` indexes are reported as a key. A plain index makes a column
+ * faster to look up and does nothing to make a row nameable, and calling both
+ * "key" is how someone concludes a table is addressable when it is not.
+ */
+function keyOf(column: SchemaColumn, indexes: readonly SchemaIndex[]): string {
+  if (column.pk) return 'PK'
+  const unique = indexes.some(
+    index => index.type === 'unique' && index.cols.includes(column.name),
+  )
+  return unique ? 'unique' : ''
+}
+
+export function structureRows(table: SchemaTable): StructureRow[] {
+  return table.columns.map(column =>
+    structureRow(column, table.identity.cols, table.indexes ?? []),
+  )
+}
+
+// --------------------------------------------------------------------- render
+
+const HEADINGS = [
+  'column',
+  'type',
+  'null',
+  'default',
+  'key',
+  'values',
+  'identity',
+] as const
+
+export interface StructureContext {
+  table: SchemaTable
+  editable: boolean
+  /** Why not, in the server's words. Shown prominently when not editable. */
+  reason: string
+}
+
+export function renderStructure(ctx: StructureContext): HTMLElement {
+  const node = box('structure')
+  const parts: (HTMLElement | null)[] = [
+    identitySection(ctx),
+    columnsSection(ctx.table),
+    indexesSection(ctx.table),
+  ]
+  for (const part of parts) if (part) node.appendChild(part)
+  return node
+}
+
+/**
+ * How a row of this table is named — and, when it cannot be, why.
+ *
+ * First rather than last, and a banner rather than a footnote. "This table is
+ * read-only" with no reason is the message that generates support questions;
+ * the reason has always existed and is the server's own sentence.
+ */
+function identitySection(ctx: StructureContext): HTMLElement {
+  const section = box('structure-section')
+  section.appendChild(el('h3', { text: 'Row identity' }))
+
+  const identity = ctx.table.identity
+  if (identity.mode === 'none') {
+    section.appendChild(
+      el('p', {
+        class: 'banner warn',
+        text: `no row of this table can be named — ${ctx.reason}`,
+      }),
+    )
+    return section
+  }
+
+  section.appendChild(
+    el('p', {
+      class: 'note',
+      text:
+        `a row is named by its ${identity.mode === 'pk' ? 'primary key' : 'unique index'}: ` +
+        identity.cols.join(', '),
+    }),
+  )
+  if (!ctx.editable) {
+    section.appendChild(el('p', { class: 'banner warn', text: ctx.reason }))
+  }
+  return section
+}
+
+function columnsSection(table: SchemaTable): HTMLElement {
+  const section = box('structure-section')
+  section.appendChild(el('h3', { text: `Columns (${table.columns.length})` }))
+
+  const grid = el('table', { class: 'grid structure-grid' })
+  const head = el('tr')
+  for (const heading of HEADINGS) head.appendChild(el('th', { text: heading }))
+  grid.appendChild(head)
+  for (const row of structureRows(table)) grid.appendChild(columnRow(row))
+
+  section.appendChild(box('scroll', grid))
+  return section
+}
+
+function columnRow(row: StructureRow): HTMLElement {
+  const tr = el('tr')
+  const cells = [
+    row.name,
+    row.type,
+    row.nullable,
+    row.default,
+    row.key,
+    row.values,
+    row.identity ? '✓' : '',
+  ]
+  for (const text of cells) tr.appendChild(el('td', { class: 'cell', text }))
+  return tr
+}
+
+/**
+ * Indexes, or an explicit statement that there are none.
+ *
+ * An empty section beats an absent one: "this table has no indexes" is an
+ * answer, and a missing heading reads as a client that failed to load them.
+ */
+function indexesSection(table: SchemaTable): HTMLElement {
+  const section = box('structure-section')
+  const indexes = table.indexes ?? []
+  section.appendChild(el('h3', { text: `Indexes (${indexes.length})` }))
+
+  if (!indexes.length) {
+    section.appendChild(
+      el('p', { class: 'note', text: 'no indexes are declared on this table' }),
+    )
+    return section
+  }
+
+  const grid = el('table', { class: 'grid structure-grid' })
+  const head = el('tr')
+  for (const heading of ['index', 'type', 'columns']) {
+    head.appendChild(el('th', { text: heading }))
+  }
+  grid.appendChild(head)
+  for (const index of indexes) grid.appendChild(indexRow(index))
+
+  section.appendChild(box('scroll', grid))
+  return section
+}
+
+function indexRow(index: SchemaIndex): HTMLElement {
+  const tr = el('tr')
+  for (const text of [index.name, index.type, index.cols.join(', ')]) {
+    tr.appendChild(el('td', { class: 'cell', text }))
+  }
+  return tr
+}