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

package/src/shared/csv.ts

@@ -0,0 +1,186 @@
+/**
+ * CSV, RFC 4180-ish, with the delimiter sniffed rather than assumed.
+ *
+ * **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`
+ *
+ * It was read first, and reusing it was the intent. Four things stop it, and
+ * the first two are correctness rather than taste:
+ *
+ * 1. **A quote anywhere opens a quoted field.** `he said "hi", ok` parses as
+ *    one field `he said hi, ok` rather than two, because the branch is
+ *    `if (c === '"') inQuotes = true` with no check that the field is empty.
+ *    RFC 4180 only gives `"` meaning at the start of a field.
+ * 2. **No BOM handling.** A file saved by Excel begins ``, so the first
+ *    header comes back as `id` and matches no column — the single most
+ *    common import failure there is.
+ * 3. Comma only. A European export is `;`-delimited and a database dump is
+ *    often tab-delimited; both parse as one column per row and then fail with
+ *    a message about the header.
+ * 4. It returns `string[][]` with a blank final row dropped by a heuristic
+ *    (`row.length === 1 && row[0] === ''`), which also drops a legitimate
+ *    single-column row whose value is empty.
+ *
+ * Fixing it in place would change `importCSV`'s behaviour for every existing
+ * caller of the ORM, which is a separate decision from adding an importer to
+ * the explorer. This parser is the explorer's; if the ORM's is ever replaced,
+ * this is the implementation to move.
+ */
+
+/** The delimiters `sniffDelimiter` will consider, in preference order. */
+const CANDIDATE_DELIMITERS = [',', ';', '\t', '|'] as const
+
+export type Delimiter = (typeof CANDIDATE_DELIMITERS)[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
+}
+
+/**
+ * Which delimiter this file uses.
+ *
+ * Counts occurrences **outside quotes** in the first few lines and takes the
+ * candidate whose count is both non-zero and most consistent line to line. A
+ * naive `indexOf` count picks `,` for a `;`-delimited file the moment one
+ * quoted address contains a comma, which is the common case rather than an
+ * exotic one.
+ */
+export function sniffDelimiter(text: string): Delimiter {
+  const sample = stripBOM(text)
+  let best: Delimiter = ','
+  let bestScore = -1
+
+  for (const candidate of CANDIDATE_DELIMITERS) {
+    const counts = countPerLine(sample, candidate, 20)
+    if (!counts.length || counts[0] === 0) continue
+    // Consistency first, frequency second: a delimiter that appears the same
+    // number of times on every line is a delimiter; one that appears a varying
+    // number of times is text.
+    const consistent = counts.every(n => n === counts[0])
+    const score = (consistent ? 1000 : 0) + counts[0]!
+    if (score > bestScore) {
+      bestScore = score
+      best = candidate
+    }
+  }
+  return best
+}
+
+/** Occurrences of `delimiter` per line, outside quotes, for the first `max` lines. */
+function countPerLine(text: string, delimiter: string, max: number): number[] {
+  const counts: number[] = []
+  let inQuotes = false
+  let count = 0
+  let atFieldStart = true
+
+  for (let i = 0; i < text.length && counts.length < max; i++) {
+    const c = text[i]
+    if (inQuotes) {
+      if (c === '"' && text[i + 1] === '"') i++
+      else if (c === '"') inQuotes = false
+      continue
+    }
+    if (c === '"' && atFieldStart) {
+      inQuotes = true
+      atFieldStart = false
+    } else if (c === delimiter) {
+      count++
+      atFieldStart = true
+    } else if (c === '\n') {
+      counts.push(count)
+      count = 0
+      atFieldStart = true
+    } else if (c !== '\r') {
+      atFieldStart = false
+    }
+  }
+  if (count > 0 || counts.length === 0) counts.push(count)
+  return counts
+}
+
+/**
+ * Rows of fields, with nothing interpreted.
+ *
+ * No trimming and no type guessing: `"01"` and `01` are both the three-, then
+ * two-character strings they look like, and turning either into a number is
+ * `coerce.ts`'s job once a column is known. A field is only ever `''` when the
+ * file said so — this parser has no concept of NULL.
+ */
+export function parseCSVRows(text: string, delimiter = ','): string[][] {
+  const csv = stripBOM(text)
+  const rows: string[][] = []
+  let row: string[] = []
+  let field = ''
+  let inQuotes = false
+  let atFieldStart = true
+  /** Did any field of the current row open with a quote? */
+  let rowQuoted = false
+  /** Has anything at all been read since the last row ended? */
+  let pending = false
+
+  const endField = () => {
+    row.push(field)
+    field = ''
+    atFieldStart = true
+    pending = true
+  }
+
+  const endRow = () => {
+    endField()
+    // A blank line is not a row: it is what a trailing newline, or a stray one
+    // in the middle of a file, leaves behind. One field, empty, and never
+    // quoted is the only shape it can take — a line reading `""` is a real row
+    // holding one empty value, which is why `rowQuoted` is tracked.
+    const blank = row.length === 1 && row[0] === '' && !rowQuoted
+    if (!blank) rows.push(row)
+    row = []
+    rowQuoted = false
+    pending = false
+  }
+
+  for (let i = 0; i < csv.length; i++) {
+    const c = csv[i]
+    if (inQuotes) {
+      if (c === '"' && csv[i + 1] === '"') {
+        field += '"'
+        i++
+      } else if (c === '"') {
+        inQuotes = false
+      } else {
+        // Includes newlines: a quoted field spans lines, which is the reason
+        // a line-splitting "parser" cannot be used for CSV at all.
+        field += c
+      }
+      continue
+    }
+
+    if (c === '"' && atFieldStart) {
+      inQuotes = true
+      rowQuoted = true
+      atFieldStart = false
+      pending = true
+    } else if (c === delimiter) {
+      endField()
+    } else if (c === '\n' || c === '\r') {
+      if (c === '\r' && csv[i + 1] === '\n') i++
+      endRow()
+    } else {
+      field += c
+      atFieldStart = false
+      pending = true
+    }
+  }
+
+  // Anything still buffered is a final row with no line terminator.
+  if (pending) endRow()
+
+  return rows
+}

package/src/shared/filters.ts

@@ -0,0 +1,200 @@
+/**
+ * The filter vocabulary, written once and read by both halves.
+ *
+ * **Pure, and deliberately in `shared/`** — the client builds filters and the
+ * endpoint validates them, and a vocabulary that lived on only one side would
+ * drift. Like the rest of `shared/`, this is compiled into the browser bundle,
+ * so it imports nothing from `@bakery-framework/*` (see `client/safety.test.ts`).
+ *
+ * The list mirrors `filterClause` in `packages/orm/src/adapters/base.ts`. That
+ * method ends with:
+ *
+ *   > An operator this dialect does not know is dropped rather than guessed at
+ *   > … the caller validates the vocabulary before it gets here.
+ *
+ * This is that caller. Validating matters more than it looks: a *dropped*
+ * filter widens the result set, so a typo'd operator would silently show more
+ * rows than were asked for — and the explorer's Delete acts on a selection made
+ * from exactly that view. Failing the request is the only safe direction
+ * (convention 2).
+ */
+
+export type FilterOp =
+  | 'eq'
+  | 'ne'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'contains'
+  | 'starts'
+  | 'ends'
+  | 'null'
+  | 'notnull'
+
+/** In menu order: equality, then ordering, then text, then the two nullary. */
+export const FILTER_OPS: readonly FilterOp[] = [
+  'eq',
+  'ne',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'contains',
+  'starts',
+  'ends',
+  'null',
+  'notnull',
+] as const
+
+/**
+ * The two operators that bind nothing.
+ *
+ * `IS NULL` has no parameter, which is the whole reason a filter cannot be
+ * modelled as a plain column/value pair — the value input is *hidden* for
+ * these rather than ignored, because an input whose contents do nothing is a
+ * lie about what the query will do.
+ */
+const NULLARY: ReadonlySet<string> = new Set<string>(['null', 'notnull'])
+
+export function isFilterOp(value: unknown): value is FilterOp {
+  return (
+    typeof value === 'string' &&
+    (FILTER_OPS as readonly string[]).includes(value)
+  )
+}
+
+export function opTakesValue(op: FilterOp): boolean {
+  return !NULLARY.has(op)
+}
+
+/** How a chip reads in the UI. Same order as `FILTER_OPS`. */
+export const OP_LABELS: Readonly<Record<FilterOp, string>> = {
+  eq: '=',
+  ne: '≠',
+  gt: '>',
+  gte: '≥',
+  lt: '<',
+  lte: '≤',
+  contains: 'contains',
+  starts: 'starts with',
+  ends: 'ends with',
+  null: 'is NULL',
+  notnull: 'is not NULL',
+}
+
+/** One filter as the user built it. `value` is unused when the op is nullary. */
+export interface Filter {
+  column: string
+  op: FilterOp
+  value: string
+}
+
+/** One filter as it crosses the wire. */
+export interface WireFilter {
+  op: FilterOp
+  value?: string
+}
+
+export function filter(
+  column: string,
+  op: FilterOp = 'eq',
+  value = '',
+): Filter {
+  return { column, op, value }
+}
+
+/**
+ * Filters as `getData` wants them: keyed by column.
+ *
+ * **The wire shape is a record, so a column can carry only one filter** — the
+ * ORM iterates `Object.entries(options.filters)`. Two chips on one column
+ * therefore cannot both be sent, and the last one wins rather than the first,
+ * because the last is the one the user just touched. `duplicateColumns` exists
+ * so the builder can say so out loud instead of quietly dropping half of what
+ * is on screen.
+ *
+ * A value-taking op with an empty value is omitted entirely: that is a chip the
+ * user has added but not filled in, and sending `col LIKE '%%'` would match
+ * every row while looking like a filter.
+ */
+export function toWire(filters: readonly Filter[]): Record<string, WireFilter> {
+  const wire: Record<string, WireFilter> = {}
+  for (const entry of filters) {
+    if (!entry.column) continue
+    if (!opTakesValue(entry.op)) {
+      wire[entry.column] = { op: entry.op }
+      continue
+    }
+    if (entry.value === '') continue
+    wire[entry.column] = { op: entry.op, value: entry.value }
+  }
+  return wire
+}
+
+/** Columns named by more than one filter — the ones the wire cannot carry. */
+export function duplicateColumns(filters: readonly Filter[]): string[] {
+  const seen = new Set<string>()
+  const twice = new Set<string>()
+  for (const entry of filters) {
+    if (!entry.column) continue
+    if (seen.has(entry.column)) twice.add(entry.column)
+    seen.add(entry.column)
+  }
+  return [...twice]
+}
+
+export type ParsedFilters =
+  | { ok: true; filters: Record<string, WireFilter | string> }
+  | { ok: false; error: string }
+
+/**
+ * Validate what arrived on the query string.
+ *
+ * Both forms are accepted, because both are in use: a **bare scalar** means
+ * `contains` and is what every caller sent before operators existed, and
+ * `{op, value}` is the new one. An unknown operator is an error rather than a
+ * dropped clause, for the reason in this module's header.
+ */
+export function parseFilters(raw: unknown): ParsedFilters {
+  if (raw === null || raw === undefined) return { ok: true, filters: {} }
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    return { ok: false, error: 'filters must be an object' }
+  }
+
+  const filters: Record<string, WireFilter | string> = {}
+  for (const [column, value] of Object.entries(
+    raw as Record<string, unknown>,
+  )) {
+    const parsed = parseOne(column, value)
+    if ('error' in parsed) return { ok: false, error: parsed.error }
+    if (parsed.filter !== null) filters[column] = parsed.filter
+  }
+  return { ok: true, filters }
+}
+
+function parseOne(
+  column: string,
+  value: unknown,
+): { filter: WireFilter | string | null } | { error: string } {
+  // The pre-operator form. An empty string is "no filter", which is what a
+  // cleared text box has always sent.
+  if (value === null || typeof value !== 'object') {
+    if (value === null || value === undefined || value === '') {
+      return { filter: null }
+    }
+    return { filter: String(value) }
+  }
+
+  const { op, value: operand } = value as { op?: unknown; value?: unknown }
+  if (!isFilterOp(op)) {
+    return {
+      error: `unknown filter operator ${JSON.stringify(op)} on ${column} — expected one of ${FILTER_OPS.join(', ')}`,
+    }
+  }
+  if (!opTakesValue(op)) return { filter: { op } }
+  if (operand === null || operand === undefined || operand === '') {
+    return { filter: null }
+  }
+  return { filter: { op, value: String(operand) } }
+}

package/src/shared/plan.ts

@@ -0,0 +1,173 @@
+/**
+ * Turning a spreadsheet into statements: which CSV column feeds which database
+ * column, what stops an import before it starts, and what one row edit changes.
+ *
+ * **Pure** — see the note at the top of `coerce.ts`. The import dialog runs
+ * `autoMap` and `blockingIssues` in the browser to show the mapping before
+ * anything is sent, and the server runs the same two functions on what arrives,
+ * because a client-side check is a convenience and never a guarantee.
+ */
+
+import { type ColumnMeta, omittableOnInsert, sameValue } from './coerce'
+
+/** A column as both sides refer to it: the raw database name, plus its meta. */
+export interface PlanColumn {
+  name: string
+  meta: ColumnMeta
+}
+
+/** CSV header → database column name, or `null` for "do not import". */
+export type ColumnMapping = Record<string, string | null>
+
+/**
+ * Match headers to columns without asking the user first.
+ *
+ * Exact name wins, then a case- and separator-insensitive match, so
+ * `Courier Name`, `courier_name` and `courierName` all find `courier_name`.
+ * Nothing fuzzier: a near-miss that silently loads the wrong column is worse
+ * than an unmapped one the dialog can ask about.
+ *
+ * A database column is claimed at most once. Two headers that normalise to the
+ * same name would otherwise both map to it, and the second would quietly win.
+ */
+export function autoMap(
+  csvHeaders: readonly string[],
+  dbColumns: readonly string[],
+): ColumnMapping {
+  const mapping: ColumnMapping = {}
+  const claimed = new Set<string>()
+
+  const byExact = new Map(dbColumns.map(c => [c, c]))
+  const byNormal = new Map<string, string>()
+  for (const c of dbColumns) {
+    const key = normalize(c)
+    // First declaration wins, so the mapping does not depend on column order
+    // among columns that normalise alike.
+    if (!byNormal.has(key)) byNormal.set(key, c)
+  }
+
+  for (const header of csvHeaders) {
+    const match = byExact.get(header) ?? byNormal.get(normalize(header)) ?? null
+    mapping[header] = match && !claimed.has(match) ? match : null
+    if (mapping[header]) claimed.add(match!)
+  }
+  return mapping
+}
+
+/**
+ * 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, '')
+}
+
+export interface PlanIssue {
+  column: string
+  code: 'required_unmapped' | 'unknown_column' | 'duplicate_target'
+  message: string
+}
+
+/**
+ * What makes this mapping unrunnable, as opposed to merely lossy.
+ *
+ * A column left out of the mapping is fine when the database can fill it in —
+ * an auto-increment key, a default, or a nullable column. A NOT NULL column
+ * with no default and no mapping is not: every row would fail at the database,
+ * one at a time, after the import had already started.
+ */
+export function blockingIssues(
+  mapping: ColumnMapping,
+  columns: readonly PlanColumn[],
+): PlanIssue[] {
+  const issues: PlanIssue[] = []
+  const known = new Set(columns.map(c => c.name))
+  const targets = Object.values(mapping).filter(Boolean) as string[]
+
+  for (const target of new Set(targets)) {
+    if (!known.has(target)) {
+      issues.push({
+        column: target,
+        code: 'unknown_column',
+        message: `no column named ${target}`,
+      })
+    }
+    if (targets.filter(t => t === target).length > 1) {
+      issues.push({
+        column: target,
+        code: 'duplicate_target',
+        message: `two headers are mapped to ${target}`,
+      })
+    }
+  }
+
+  const mapped = new Set(targets)
+  for (const column of columns) {
+    if (mapped.has(column.name)) continue
+    if (omittableOnInsert(column.meta)) continue
+    issues.push({
+      column: column.name,
+      code: 'required_unmapped',
+      message: `${column.name} cannot be null and has no default, so it must be mapped`,
+    })
+  }
+
+  return issues
+}
+
+export interface UpdatePlanInput {
+  /** The row as the editor last saw it, keyed by raw column name. */
+  original: Record<string, unknown>
+  /** Edited values. **An absent key means unchanged** — see `coerce.ts`. */
+  edits: Record<string, unknown>
+  /** The identity columns, from `describeIdentity`. */
+  identity: readonly string[]
+}
+
+export interface UpdatePlanResult {
+  /** Columns whose value actually differs, and the value to write. */
+  set: Record<string, unknown>
+  /** The identity predicate, taken from `original`. */
+  where: Record<string, unknown>
+  /** Edited keys that matched what was already there. */
+  unchanged: string[]
+  /** Identity columns `original` does not carry — the plan is unusable. */
+  missingIdentity: string[]
+}
+
+/**
+ * One row edit, as the two halves of an UPDATE.
+ *
+ * `where` comes from `original` and never from `edits`, which is the point of
+ * separating them: editing a primary key has to find the row by its *old* value
+ * and set the new one, and a plan built from the edited row would look for a
+ * row that does not exist yet.
+ *
+ * Unchanged columns are dropped from `set`. That is not only economy — a `set`
+ * carrying every column makes two people editing different columns of the same
+ * row collide, and the whole reason to send a narrow statement is that they
+ * should not.
+ */
+export function updatePlan(input: UpdatePlanInput): UpdatePlanResult {
+  const set: Record<string, unknown> = {}
+  const unchanged: string[] = []
+
+  for (const [column, value] of Object.entries(input.edits)) {
+    if (sameValue(input.original[column], value)) unchanged.push(column)
+    else set[column] = value
+  }
+
+  const where: Record<string, unknown> = {}
+  const missingIdentity: string[] = []
+  for (const column of input.identity) {
+    if (!(column in input.original)) missingIdentity.push(column)
+    else where[column] = input.original[column]
+  }
+
+  return { set, where, unchanged, missingIdentity }
+}