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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakery-framework/plugin-db-explorer",
-  "version": "2.0.0-alpha.6",
+  "version": "2.0.0-alpha.7",
   "description": "Bakery database explorer plugin — browse and edit rows — no raw SQL, no DDL.",
   "keywords": [
     "bakery",
@@ -33,8 +33,8 @@
     "!src/tests"
   ],
   "dependencies": {
-    "@bakery-framework/core": "^2.0.0-alpha.6",
-    "@bakery-framework/orm": "^2.0.0-alpha.6"
+    "@bakery-framework/core": "^2.0.0-alpha.7",
+    "@bakery-framework/orm": "^2.0.0-alpha.7"
   },
   "engines": {
     "bun": ">=1.3.14"

package/src/client/api.ts

@@ -30,6 +30,24 @@ export class ApiError extends Error {
   }
 }
 
+/**
+ * What to show a user when a call threw.
+ *
+ * Here rather than in `dom.ts` because the thing it knows about is `ApiError`,
+ * whose `message` is the server's own sentence from the envelope — the reason
+ * a failed write reads as "row was modified by someone else" instead of
+ * "Request failed (409)". `String(error)` is the fallback for the two throws
+ * that are not ours: an abort and a network failure.
+ *
+ * There used to be three of these — one exported from `bulk.ts`, a private
+ * near-copy in `save.ts`, and a third inlined at the `notify` call in
+ * `csv-commit.ts` — so improving the wording in one left the other two alone.
+ */
+export function messageOf(error: unknown): string {
+  const api = error as Partial<ApiError>
+  return api?.message ?? String(error)
+}
+
 const KEY_STORAGE = '__db_key'
 const KEY_PARAM = 'db-key'
 
@@ -79,7 +97,7 @@ interface Envelope {
  * available for "why is this slow": a filter that cannot use an index shows up
  * here immediately.
  */
-export interface Timed<T> {
+interface Timed<T> {
   data: T
   ms: number
 }
@@ -101,7 +119,7 @@ async function unwrap<T>(res: Response): Promise<T> {
   return (await unwrapEnvelope<T>(res)).data
 }
 
-export async function apiGet<T>(
+async function apiGet<T>(
   path: string,
   params?: Record<string, string>,
   signal?: AbortSignal,
@@ -114,7 +132,7 @@ export async function apiGet<T>(
   return await unwrap<T>(res)
 }
 
-export async function apiSend<T>(
+async function apiSend<T>(
   method: 'POST' | 'PATCH' | 'DELETE',
   path: string,
   body: unknown,
@@ -192,7 +210,7 @@ export async function lookupRefs(
   return data.rows ?? []
 }
 
-export interface UpdateResult {
+interface UpdateResult {
   changed: number
   row: Record<string, unknown> | null
 }
@@ -207,7 +225,7 @@ export async function patchRow(payload: {
   return await apiSend<UpdateResult>('PATCH', 'row', payload)
 }
 
-export interface BulkResult {
+interface BulkResult {
   changed: number
   conflicts: { index: number; key: Record<string, unknown>; reason: string }[]
 }
@@ -220,7 +238,7 @@ export async function bulkEdit(payload: {
   return await apiSend<BulkResult>('POST', 'rows/bulk', payload)
 }
 
-export interface DeleteResult {
+interface DeleteResult {
   deleted: number
   conflicts: { index: number; key: Record<string, unknown>; reason: string }[]
 }
@@ -233,7 +251,7 @@ export async function deleteRows(payload: {
   return await apiSend<DeleteResult>('DELETE', 'rows', payload)
 }
 
-export interface InsertResult {
+interface InsertResult {
   inserted: number
   rows?: Record<string, unknown>[]
 }

package/src/client/bulk.ts

@@ -9,7 +9,7 @@
  */
 
 import { coerceValue, omittableOnInsert } from '../shared/coerce'
-import { type ApiError, bulkEdit, deleteRows, insertRows } from './api'
+import { bulkEdit, deleteRows, insertRows, messageOf } from './api'
 import { confirmDanger, notify, offerUndo } from './confirm'
 import { append, box, button, each, el, select } from './dom'
 import type { UndoStack } from './edit-session'
@@ -139,7 +139,7 @@ async function applySetColumn(
     .map(key => ({ key, set: { [column.name]: check.value } }))
   if (!edits.length) return
 
-  const dry = await dryRun(() =>
+  const dry = await run(() =>
     bulkEdit({ table: ctx.table.name, edits, dryRun: true }),
   )
   if (!dry) return
@@ -173,7 +173,7 @@ async function runDelete(ctx: BulkContext): Promise<void> {
   const rows = ctx.selectedRows()
   if (!keys.length) return
 
-  const dry = await dryRun(() =>
+  const dry = await run(() =>
     deleteRows({ table: ctx.table.name, keys, dryRun: true }),
   )
   if (!dry) return
@@ -297,7 +297,7 @@ function insertField(column: SchemaColumn, draft: Map<string, unknown>): Node {
   return wrap
 }
 
-export interface BuiltRows {
+interface BuiltRows {
   rows: Record<string, unknown>[]
   errors: string[]
 }
@@ -305,11 +305,12 @@ export interface BuiltRows {
 /**
  * Drafts to records, with the same coercion the server will apply.
  *
- * Exported because it is the decision in this file that is worth pinning: an
- * untouched omittable column is *absent* from the record, and an untouched
- * required one is an error named here rather than a database exception later.
+ * Named rather than inlined into the submit handler because it is the decision
+ * in this file worth stating: an untouched omittable column is *absent* from
+ * the record, and an untouched required one is an error named here rather than
+ * a database exception later.
  */
-export function buildInsertRows(
+function buildInsertRows(
   columns: readonly SchemaColumn[],
   drafts: readonly Map<string, unknown>[],
 ): BuiltRows {
@@ -337,8 +338,16 @@ export function buildInsertRows(
 
 // ------------------------------------------------------------------ plumbing
 
-/** A dry run, with its failure reported rather than thrown at the click handler. */
-async function dryRun<T>(call: () => Promise<T>): Promise<T | null> {
+/**
+ * Run a call, reporting its failure rather than throwing at the click handler.
+ *
+ * A rejected promise from an event listener is an unhandled rejection and a
+ * silent no-op on screen, which is the one outcome a destructive action must
+ * not have. `null` is the failure, so a dry run's caller checks the result and
+ * an action's caller ignores it — they were two identically-bodied functions
+ * until the second was noticed to be the first with the value discarded.
+ */
+async function run<T>(call: () => Promise<T>): Promise<T | null> {
   try {
     return await call()
   } catch (error) {
@@ -346,16 +355,3 @@ async function dryRun<T>(call: () => Promise<T>): Promise<T | null> {
     return null
   }
 }
-
-async function run(action: () => Promise<void>): Promise<void> {
-  try {
-    await action()
-  } catch (error) {
-    notify(messageOf(error), 'error')
-  }
-}
-
-export function messageOf(error: unknown): string {
-  const api = error as Partial<ApiError>
-  return api?.message ?? String(error)
-}

package/src/client/confirm.ts

@@ -13,7 +13,7 @@
  * own preview is the only number that is the number.
  */
 
-import { el, on } from './dom'
+import { button, el } from './dom'
 
 export type Friction = 'immediate' | 'confirm' | 'typed' | 'refuse'
 
@@ -109,8 +109,15 @@ function openDialog(request: DangerRequest, typed: boolean): Promise<boolean> {
   })
   dialog.append(title, where)
 
-  const confirm = el('button', { class: 'btn danger-btn', text: request.verb })
-  confirm.type = 'button'
+  let accepted = false
+  const confirm = button(
+    request.verb,
+    () => {
+      accepted = true
+      dialog.close()
+    },
+    { class: 'btn danger-btn' },
+  )
 
   if (typed) {
     const prompt = el('p', {
@@ -127,19 +134,11 @@ function openDialog(request: DangerRequest, typed: boolean): Promise<boolean> {
     dialog.append(prompt, input)
   }
 
-  const cancel = el('button', { class: 'btn', text: 'Cancel' })
-  cancel.type = 'button'
+  const cancel = button('Cancel', () => dialog.close(), { class: 'btn' })
   const bar = el('div', { class: 'row-bar' })
   bar.append(cancel, confirm)
   dialog.appendChild(bar)
 
-  let accepted = false
-  on(confirm, 'click', () => {
-    accepted = true
-    dialog.close()
-  })
-  on(cancel, 'click', () => dialog.close())
-
   // `settle` is narrowed to `(value: boolean) => void` rather than used as the
   // executor's own `resolve`, whose parameter is `boolean | PromiseLike<boolean>`
   // — calling that reads as an unhandled promise to the floating-promise rule.
@@ -172,17 +171,20 @@ export function offerUndo(
   const bar = el('div', { class: 'undo-bar', attrs: { role: 'status' } })
   bar.appendChild(el('span', { text: message }))
 
-  const action = el('button', { class: 'btn', text: 'Undo' })
-  action.type = 'button'
   const remove = () => {
     clearTimeout(timer)
     bar.remove()
   }
-  on(action, 'click', () => {
-    remove()
-    void undo()
-  })
-  bar.appendChild(action)
+  bar.appendChild(
+    button(
+      'Undo',
+      () => {
+        remove()
+        void undo()
+      },
+      { class: 'btn' },
+    ),
+  )
 
   const timer = setTimeout(remove, seconds * 1000)
   document.body.appendChild(bar)

package/src/client/csv-commit.ts

@@ -8,7 +8,7 @@
  * are in.
  */
 
-import { type ImportResult, importRows } from './api'
+import { type ImportResult, importRows, messageOf } from './api'
 import { notify } from './confirm'
 import {
   type BadRowPolicy,
@@ -171,7 +171,7 @@ async function sendBatch(
   try {
     return await importRows({ table: ctx.table.name, rows, onBadRow })
   } catch (error) {
-    notify((error as Error)?.message ?? 'import failed', 'error')
+    notify(messageOf(error), 'error')
     return null
   }
 }

package/src/client/csv-map.ts

@@ -16,8 +16,8 @@ import {
 import { append, box, each, el, on, select } from './dom'
 import type { SchemaColumn } from './meta'
 
-export const SKIP_VALUE = ' skip'
-export const CONST_VALUE = ' const'
+const SKIP_VALUE = ' skip'
+const CONST_VALUE = ' const'
 
 export interface MapContext {
   columns: SchemaColumn[]
@@ -95,7 +95,7 @@ function summaryText(model: ImportModel): string {
  * itself contains the *new* delimiter survives the round trip. This is why the
  * wizard can offer a delimiter override at all without holding the file.
  */
-export function rebuildSource(model: ImportModel): string {
+function rebuildSource(model: ImportModel): string {
   const quote = (field: string) =>
     /["\n\r]/.test(field) || field.includes(model.delimiter)
       ? `"${field.replace(/"/g, '""')}"`
@@ -175,7 +175,7 @@ function currentValue(assignment: Assignment): string {
   return assignment.kind === 'constant' ? CONST_VALUE : SKIP_VALUE
 }
 
-export function assignmentFor(value: string, previous: Assignment): Assignment {
+function assignmentFor(value: string, previous: Assignment): Assignment {
   if (value === SKIP_VALUE) return { kind: 'skip' }
   if (value === CONST_VALUE) {
     return {

package/src/client/csv-preview.ts

@@ -17,7 +17,7 @@ import {
   type RowPreview,
   setEmptyToNull,
 } from './csv-model'
-import { box, each, el, on } from './dom'
+import { box, each, el, gridTable, on } from './dom'
 import type { SchemaColumn } from './meta'
 
 export function paintPreview(
@@ -34,11 +34,9 @@ export function paintPreview(
     return
   }
 
-  const table = el('table', { class: 'grid' })
-  const head = el('tr')
   const names = rows[0]!.cells.map(cell => cell.column)
-  each(head, names, column => el('th', { text: column }))
-  table.append(head, nullToggleRow(model, names, update))
+  const table = gridTable(names)
+  table.appendChild(nullToggleRow(model, names, update))
   each(table, rows, row => previewRow(row))
   node.appendChild(box('scroll', table))
 }

package/src/client/dom.ts

@@ -85,6 +85,26 @@ export function each<T>(
   })
 }
 
+/**
+ * A `<table class="grid">` with its heading row already in it.
+ *
+ * The two lines this replaces — build the table, loop `<th>` into a `<tr>` —
+ * had been written out three times, twice in `structure.ts` and once in
+ * `csv-preview.ts`. Rows are appended by the caller, because the three differ
+ * in what a row is: `structure.ts` has plain text cells, and `csv-preview.ts`
+ * puts a checkbox row directly under the headings.
+ */
+export function gridTable(
+  headings: readonly string[],
+  cls = 'grid',
+): HTMLTableElement {
+  const table = el('table', { class: cls })
+  const head = el('tr')
+  each(head, headings, heading => el('th', { text: heading }))
+  table.appendChild(head)
+  return table
+}
+
 export function clear(node: Node): void {
   ;(node as Element).replaceChildren()
 }

package/src/client/fk.ts

@@ -64,7 +64,6 @@ class BoundedCache<V> {
   }
 }
 
-
 export interface FkTarget {
   /** Columns in *this* table that make up the key. */
   cols: string[]
@@ -98,6 +97,34 @@ export function fkForColumn(
   return null
 }
 
+/**
+ * Every foreign-key column of one table, resolved once.
+ *
+ * `fkForColumn` is a linear scan of the whole graph, and the grid asked it per
+ * cell, per paint — a fifty-row page of twenty columns against forty foreign
+ * keys is forty thousand comparisons, each of which had `sameTable` allocate
+ * two lowercased strings, and `repaintRow`/`repaintCell` run it again. The scan
+ * does not depend on the row, so it happens once when the grid is built.
+ *
+ * First declaration wins, exactly as the scan's early `return` does, so a
+ * column named by two keys resolves to the same one either way.
+ */
+export function fkMapFor(
+  graph: SchemaGraph | null,
+  table: string,
+): Map<string, FkTarget> {
+  const map = new Map<string, FkTarget>()
+  if (!graph) return map
+  for (const fk of Object.values(graph.foreignKeys)) {
+    if (!sameTable(fk.table, table)) continue
+    const target = toTarget(fk)
+    for (const column of fk.cols) {
+      if (!map.has(column)) map.set(column, target)
+    }
+  }
+  return map
+}
+
 /** Every key pointing *at* this table. The row panel's "referenced by" list. */
 export function reverseFks(
   graph: SchemaGraph | null,

package/src/client/grid-body.ts

@@ -11,18 +11,20 @@
  */
 
 import { button } from './dom'
-import {
-  type FkResolver,
-  type FkTarget,
-  fkForColumn,
-  fkKeyOf,
-  fkLabel,
-} from './fk'
+import { type FkResolver, type FkTarget, fkKeyOf, fkLabel } from './fk'
 import { cellProps, type SchemaColumn, type SchemaGraph } from './meta'
 
 export interface CellPaintContext {
   table: string
   graph: SchemaGraph | null
+  /**
+   * Which columns of `table` are foreign keys, resolved once by `fkMapFor`.
+   *
+   * Built by the grid rather than looked up here: the answer depends on the
+   * table and not on the row, and asking per cell per paint made a page repaint
+   * quadratic in the size of the schema graph.
+   */
+  fks: ReadonlyMap<string, FkTarget>
   resolver: FkResolver
   onFollowFk: (target: FkTarget, key: Record<string, unknown>) => void
 }
@@ -47,18 +49,19 @@ export function paintCell(
   td.className = props.className
   if (staged) td.classList.add('staged')
   if (props.title) td.title = props.title
-  td.appendChild(cellBody(ctx, row, column, value))
+  // `props.text` is passed down rather than recomputed: `cellBody` wants the
+  // same string, and `cellProps` was being run twice for every cell.
+  td.appendChild(cellBody(ctx, row, column, props.text))
 }
 
 function cellBody(
   ctx: CellPaintContext,
   row: Record<string, unknown>,
   column: SchemaColumn,
-  value: unknown,
+  text: string,
 ): Node {
-  const target = fkForColumn(ctx.graph, ctx.table, column.name)
+  const target = ctx.fks.get(column.name)
   const key = target ? fkKeyOf(target, row) : null
-  const text = cellProps(value, column).text
   if (!target || !key) return document.createTextNode(text)
   return fkButton(ctx, target, key, text)
 }

package/src/client/grid.ts

@@ -27,7 +27,7 @@ import { box, each, el, on, setBusy } from './dom'
 import type { EditSession } from './edit-session'
 import { rowId } from './edit-session'
 import { createEditor, type EditorHandle } from './editors'
-import type { FkResolver, FkTarget } from './fk'
+import { type FkResolver, type FkTarget, fkMapFor } from './fk'
 import { type CellPaintContext, paintCell } from './grid-body'
 import { buildHead } from './grid-header'
 import {
@@ -79,6 +79,8 @@ export class Grid {
     this.paintCtx = {
       table: ctx.table.name,
       graph: ctx.graph,
+      // Once per grid, not once per cell per paint — see `fkMapFor`.
+      fks: fkMapFor(ctx.graph, ctx.table.name),
       resolver: ctx.resolver,
       onFollowFk: ctx.onFollowFk,
     }

package/src/client/meta.ts

@@ -16,6 +16,7 @@
  */
 
 import type { ColumnKind, ColumnMeta } from '../shared/coerce'
+import { normalize } from '../shared/plan'
 
 export interface SchemaColumn {
   name: string
@@ -180,9 +181,5 @@ export function cellProps(value: unknown, column: SchemaColumn): CellProps {
  * `snake_case` schema invisible, which is the entire feature silently absent.
  */
 export function sameTable(a: string, b: string): boolean {
-  return a === b || flatten(a) === flatten(b)
-}
-
-function flatten(name: string): string {
-  return name.toLowerCase().replace(/[\s_-]+/g, '')
+  return a === b || normalize(a) === normalize(b)
 }

package/src/client/save.ts

@@ -8,7 +8,7 @@
  */
 
 import type { ColumnKind } from '../shared/coerce'
-import { type ApiError, patchRow } from './api'
+import { type ApiError, messageOf, patchRow } from './api'
 import { box, button, el } from './dom'
 import type { EditSession, RowPlan } from './edit-session'
 import type { SchemaTable } from './meta'
@@ -38,10 +38,6 @@ function kindLookup(
   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.
  *

package/src/client/structure.ts

@@ -14,7 +14,7 @@
  * is said to be is asserted rather than eyeballed.
  */
 
-import { box, el } from './dom'
+import { append, box, each, el, gridTable } from './dom'
 import type { SchemaColumn, SchemaIndex, SchemaTable } from './meta'
 
 /** One row of the columns table, already worded. */
@@ -109,6 +109,29 @@ const HEADINGS = [
   'identity',
 ] as const
 
+const INDEX_HEADINGS = ['index', 'type', 'columns'] as const
+
+/**
+ * A scrolling table of plain text cells.
+ *
+ * Columns and indexes are the same table twice — headings, then a `<tr>` of
+ * `<td class="cell">` per row — so they are one builder and two `string[][]`.
+ */
+function dataTable(
+  headings: readonly string[],
+  rows: readonly (readonly string[])[],
+): HTMLElement {
+  const grid = gridTable(headings, 'grid structure-grid')
+  each(grid, rows, cells => dataRow(cells))
+  return box('scroll', grid)
+}
+
+function dataRow(cells: readonly string[]): HTMLElement {
+  const tr = el('tr')
+  each(tr, cells, text => el('td', { class: 'cell', text }))
+  return tr
+}
+
 export interface StructureContext {
   table: SchemaTable
   editable: boolean
@@ -118,12 +141,11 @@ export interface StructureContext {
 
 export function renderStructure(ctx: StructureContext): HTMLElement {
   const node = box('structure')
-  const parts: (HTMLElement | null)[] = [
+  append(node, [
     identitySection(ctx),
     columnsSection(ctx.table),
     indexesSection(ctx.table),
-  ]
-  for (const part of parts) if (part) node.appendChild(part)
+  ])
   return node
 }
 
@@ -166,20 +188,15 @@ function identitySection(ctx: StructureContext): HTMLElement {
 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))
+  section.appendChild(
+    dataTable(HEADINGS, structureRows(table).map(columnCells)),
+  )
   return section
 }
 
-function columnRow(row: StructureRow): HTMLElement {
-  const tr = el('tr')
-  const cells = [
+/** A `StructureRow` in `HEADINGS` order. The only place the two are paired. */
+function columnCells(row: StructureRow): string[] {
+  return [
     row.name,
     row.type,
     row.nullable,
@@ -188,8 +205,6 @@ function columnRow(row: StructureRow): HTMLElement {
     row.values,
     row.identity ? '✓' : '',
   ]
-  for (const text of cells) tr.appendChild(el('td', { class: 'cell', text }))
-  return tr
 }
 
 /**
@@ -210,22 +225,10 @@ function indexesSection(table: SchemaTable): HTMLElement {
     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))
+  section.appendChild(dataTable(INDEX_HEADINGS, indexes.map(indexCells)))
   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
+function indexCells(index: SchemaIndex): string[] {
+  return [index.name, index.type, index.cols.join(', ')]
 }

package/src/client/tabs.ts

@@ -21,7 +21,7 @@
  */
 
 import type { ViewState } from './state'
-import { decodeView, defaultView, encodeView } from './state'
+import { decodeView, encodeView } from './state'
 
 export interface Tab {
   view: ViewState
@@ -47,7 +47,7 @@ export function activeView(state: TabsState): ViewState | null {
   return activeTab(state)?.view ?? null
 }
 
-export function indexOfTable(state: TabsState, table: string): number {
+function indexOfTable(state: TabsState, table: string): number {
   return state.tabs.findIndex(tab => tab.view.table === table)
 }
 
@@ -217,8 +217,3 @@ function readIndex(raw: string | null, length: number): number {
   const value = Number.parseInt(raw, 10)
   return Number.isFinite(value) && value >= 0 && value < length ? value : -1
 }
-
-/** A fresh tab for a table, as the sidebar and the relations view make one. */
-export function tabView(table: string): ViewState {
-  return defaultView(table)
-}

package/src/client.ts

@@ -21,7 +21,13 @@
  * editor is for.
  */
 
-import { adoptUrlKey, fetchGraph, fetchPage, fetchSchema } from './client/api'
+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'
@@ -347,10 +353,6 @@ async function followFk(
 
 // ------------------------------------------------------------------ plumbing
 
-function messageOf(error: unknown): string {
-  return (error as Error)?.message ?? String(error)
-}
-
 /**
  * The unload guard.
  *

package/src/endpoints/import.ts

@@ -1,10 +1,10 @@
 /**
  * CSV import — the rows, not the file.
  *
- * The parse happens in `shared/csv.ts`, which the browser runs to show a
- * preview and the server runs on whatever it is sent. This endpoint takes rows
- * that are already records, so the mapping the user confirmed in the dialog is
- * what arrives, rather than a file the server re-guesses the columns of.
+ * The parse happens in the browser, in `shared/csv.ts`, and stays there. This
+ * endpoint takes rows that are already records, so the mapping the user
+ * confirmed in the dialog is what arrives, rather than a file the server
+ * re-guesses the columns of. No CSV text reaches the server at all.
  *
  * Two things separate it from `POST /api/_db/rows`, and both are about scale:
  * the bound is a spreadsheet's worth of rows rather than an edit's, and a bad

package/src/shared/csv.ts

@@ -1,9 +1,13 @@
 /**
  * CSV, RFC 4180-ish, with the delimiter sniffed rather than assumed.
  *
- * **Pure** — see the note at the top of `coerce.ts`. The client parses the file
- * the user dropped and the server re-parses whatever it is sent, and they have
- * to agree, so there is one parser.
+ * **Pure** — see the note at the top of `coerce.ts` — and, unlike the rest of
+ * `shared/`, **browser-only**. It was written when the server re-parsed the
+ * text it was sent; `endpoints/import.ts` takes records that are already mapped
+ * and coerced, so no CSV text ever reaches it. `client/csv-model.ts` is the
+ * only caller. The file stays here because `client/safety.test.ts` holds
+ * `shared/` to the same no-framework-imports rule as `client/`, and because a
+ * server-side importer would want exactly this parser back.
  *
  * ## Why not `parseCSVRows` from `orm/adapters/base.ts:1071`
  *
@@ -31,24 +35,10 @@
  */
 
 /** The delimiters `sniffDelimiter` will consider, in preference order. */
-export const CANDIDATE_DELIMITERS = [',', ';', '\t', '|'] as const
+const CANDIDATE_DELIMITERS = [',', ';', '\t', '|'] as const
 
 export type Delimiter = (typeof CANDIDATE_DELIMITERS)[number]
 
-export interface CSVTable {
-  headers: string[]
-  rows: string[][]
-  delimiter: string
-  /**
-   * Rows whose field count differs from the header count, as
-   * `{row, fields}` — 1-based over the data rows, so it lines up with what a
-   * spreadsheet shows. Ragged rows are still returned in `rows`, padded with
-   * `''` or truncated; refusing the whole file for one short line is not the
-   * importer's call to make.
-   */
-  ragged: { row: number; fields: number }[]
-}
-
 /** Strip a UTF-8 BOM. Excel writes one; nothing downstream expects it. */
 export function stripBOM(text: string): string {
   return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text
@@ -194,42 +184,3 @@ export function parseCSVRows(text: string, delimiter = ','): string[][] {
 
   return rows
 }
-
-/**
- * A whole file: headers, data rows squared off against them, and what the
- * delimiter turned out to be.
- */
-export function parseCSV(
-  text: string,
-  options: { delimiter?: string } = {},
-): CSVTable {
-  const delimiter = options.delimiter ?? sniffDelimiter(text)
-  const all = parseCSVRows(text, delimiter)
-  if (!all.length) return { headers: [], rows: [], delimiter, ragged: [] }
-
-  // Headers are the one place trimming is right: a header is a name, and
-  // `" id "` naming the column `id` is what every spreadsheet means by it.
-  const headers = all[0]!.map(h => h.trim())
-  const ragged: { row: number; fields: number }[] = []
-  const rows = all.slice(1).map((fields, index) => {
-    if (fields.length !== headers.length) {
-      ragged.push({ row: index + 1, fields: fields.length })
-    }
-    const squared = fields.slice(0, headers.length)
-    while (squared.length < headers.length) squared.push('')
-    return squared
-  })
-
-  return { headers, rows, delimiter, ragged }
-}
-
-/** A parsed table as records, keyed by header. */
-export function csvRecords(table: CSVTable): Record<string, string>[] {
-  return table.rows.map(fields => {
-    const record: Record<string, string> = {}
-    for (let i = 0; i < table.headers.length; i++) {
-      record[table.headers[i]!] = fields[i] ?? ''
-    }
-    return record
-  })
-}

package/src/shared/plan.ts

@@ -54,7 +54,16 @@ export function autoMap(
   return mapping
 }
 
-function normalize(name: string): string {
+/**
+ * A name with case and separators removed.
+ *
+ * Exported because `client/meta.ts` compares *table* names the same way and
+ * held a byte-identical private copy called `flatten`. Both are in the browser
+ * bundle, so it was one rule written twice: a change to what counts as "the
+ * same name" would have fixed CSV auto-mapping and left foreign-key visibility
+ * on the old one.
+ */
+export function normalize(name: string): string {
   return name.toLowerCase().replace(/[\s_-]+/g, '')
 }