@reddb-io/ui 0.1.1

package/src/lib/renderers/queue-render.ts

@@ -0,0 +1,197 @@
+import type { QueryResult } from '#reddb'
+
+export interface QueueMessage {
+  index: number
+  id: string
+  messageColumn: string | null
+  message: unknown
+  state: string
+  consumer: string | null
+  dlc: string | null
+  values: Record<string, unknown>
+}
+
+export interface QueueEvent {
+  messageId: string
+  collection: string
+  op: string
+  entityId: string
+  lsn: number | null
+  ts: number | null
+  before: unknown
+  after: unknown
+  payload: Record<string, unknown>
+}
+
+export interface QueueCommand {
+  label: string
+  query: string
+  mutates: boolean
+  note: string
+}
+
+const MESSAGE_COLUMNS = ['message', 'payload', 'body', 'value', 'data']
+const STATE_COLUMNS = ['state', 'status', 'delivery_state']
+const CONSUMER_COLUMNS = ['consumer', 'consumer_id', 'worker', 'lease_owner']
+const DLC_COLUMNS = ['dlc', 'dlq', 'dead_letter_collection', 'dead_letter_queue']
+
+function pick(values: Record<string, unknown>, names: string[]): [string, unknown] | null {
+  for (const name of names) {
+    if (name in values) return [name, values[name]]
+  }
+  const lowered = Object.entries(values).find(([k]) => names.includes(k.toLowerCase()))
+  return lowered ?? null
+}
+
+export function extractQueueMessages(result: QueryResult): QueueMessage[] {
+  return result.result.records.map((record, index) => {
+    const values = record.values ?? {}
+    const message = pick(values, MESSAGE_COLUMNS)
+    const state = pick(values, STATE_COLUMNS)
+    const consumer = pick(values, CONSUMER_COLUMNS)
+    const dlc = pick(values, DLC_COLUMNS)
+    return {
+      index,
+      id: String(values.message_id ?? values.id ?? values.rid ?? index + 1),
+      messageColumn: message?.[0] ?? null,
+      message: message?.[1] ?? values,
+      state: String(state?.[1] ?? 'ready'),
+      consumer: consumer?.[1] === undefined || consumer?.[1] === null ? null : String(consumer[1]),
+      dlc: dlc?.[1] === undefined || dlc?.[1] === null ? null : String(dlc[1]),
+      values,
+    }
+  })
+}
+
+export function hasQueueShape(result: QueryResult): boolean {
+  if (result.capability === 'queue') return true
+  return result.result.records.some((record) => {
+    const keys = Object.keys(record.values ?? {}).map((k) => k.toLowerCase())
+    if (keys.includes('message_id') && MESSAGE_COLUMNS.some((c) => keys.includes(c))) return true
+    return MESSAGE_COLUMNS.some((c) => keys.includes(c)) && (
+      STATE_COLUMNS.some((c) => keys.includes(c)) ||
+      CONSUMER_COLUMNS.some((c) => keys.includes(c)) ||
+      DLC_COLUMNS.some((c) => keys.includes(c))
+    )
+  })
+}
+
+export function queueSummary(messages: QueueMessage[]) {
+  const active = new Set<string>()
+  const states = new Map<string, number>()
+  const dlcs = new Set<string>()
+  const operations = new Map<string, number>()
+  const sources = new Set<string>()
+  for (const msg of messages) {
+    states.set(msg.state, (states.get(msg.state) ?? 0) + 1)
+    if (msg.consumer && /active|leased|processing|running/i.test(msg.state)) active.add(msg.consumer)
+    if (msg.dlc) dlcs.add(msg.dlc)
+    if (msg.message && typeof msg.message === 'object' && !Array.isArray(msg.message)) {
+      const payload = msg.message as Record<string, unknown>
+      const op = payload.op
+      const source = payload.collection
+      if (typeof op === 'string') operations.set(op, (operations.get(op) ?? 0) + 1)
+      if (typeof source === 'string') sources.add(source)
+    }
+  }
+  return {
+    activeConsumers: active.size,
+    states: [...states.entries()],
+    dlcs: [...dlcs],
+    operations: [...operations.entries()].sort((a, b) => a[0].localeCompare(b[0])),
+    sources: [...sources].sort(),
+  }
+}
+
+function numberOrNull(v: unknown): number | null {
+  if (typeof v === 'number' && Number.isFinite(v)) return v
+  if (typeof v === 'string') {
+    const n = Number(v)
+    if (Number.isFinite(n)) return n
+  }
+  return null
+}
+
+export function extractQueueEvents(messages: QueueMessage[]): QueueEvent[] {
+  const events: QueueEvent[] = []
+  for (const msg of messages) {
+    if (!msg.message || typeof msg.message !== 'object' || Array.isArray(msg.message)) continue
+    const payload = msg.message as Record<string, unknown>
+    const collection = payload.collection
+    const op = payload.op
+    if (typeof collection !== 'string' || typeof op !== 'string') continue
+    const id = payload.id ?? (payload.after && typeof payload.after === 'object' && !Array.isArray(payload.after)
+      ? (payload.after as Record<string, unknown>).id
+      : undefined)
+    events.push({
+      messageId: msg.id,
+      collection,
+      op,
+      entityId: id === undefined || id === null ? String(payload.rid ?? msg.id) : String(id),
+      lsn: numberOrNull(payload.lsn),
+      ts: numberOrNull(payload.ts),
+      before: payload.before,
+      after: payload.after,
+      payload,
+    })
+  }
+  return events
+}
+
+export function queueCommandPlan(queue: string): QueueCommand[] {
+  const safeQueue = queue.replace(/[^A-Za-z0-9_./-]/g, '')
+  const consumer = 'red-ui-preview'
+  const group = 'showcase'
+  return [
+    {
+      label: 'Backlog depth',
+      query: `QUEUE LEN ${safeQueue}`,
+      mutates: false,
+      note: 'Read-only count of messages currently stored in the queue.',
+    },
+    {
+      label: 'Peek messages',
+      query: `QUEUE PEEK ${safeQueue} 25`,
+      mutates: false,
+      note: 'Read-only inspection. Does not lease, ack, or remove messages.',
+    },
+    {
+      label: 'Read as fanout consumer',
+      query: `QUEUE READ ${safeQueue} CONSUMER ${consumer} COUNT 5`,
+      mutates: true,
+      note: 'Leases messages for this consumer. ACK/NACK decides what happens next.',
+    },
+    {
+      label: 'Read through explicit group',
+      query: `QUEUE READ ${safeQueue} GROUP ${group} CONSUMER worker-a COUNT 5`,
+      mutates: true,
+      note: 'Creates/uses consumer group delivery state for an application tier.',
+    },
+    {
+      label: 'Inspect pending group messages',
+      query: `QUEUE PENDING ${safeQueue} GROUP ${group}`,
+      mutates: false,
+      note: 'Shows leased-but-unacked messages for a group.',
+    },
+    {
+      label: 'Ack a delivered message',
+      query: `QUEUE ACK ${safeQueue} GROUP ${group} 'message-id'`,
+      mutates: true,
+      note: 'Removes a successfully processed message for that group.',
+    },
+    {
+      label: 'Nack a delivered message',
+      query: `QUEUE NACK ${safeQueue} GROUP ${group} 'message-id'`,
+      mutates: true,
+      note: 'Returns or retries a failed message according to queue policy.',
+    },
+  ]
+}
+
+export function queuePushQuery(queue: string, payload: unknown): string {
+  const safeQueue = queue.replace(/[^A-Za-z0-9_./-]/g, '')
+  const rendered = typeof payload === 'string'
+    ? `'${payload.replace(/'/g, "''")}'`
+    : JSON.stringify(payload ?? null)
+  return `QUEUE PUSH ${safeQueue} ${rendered}`
+}

package/src/lib/renderers/queue.ts

@@ -0,0 +1,9 @@
+import type { CapabilityRenderer } from './types'
+import { hasQueueShape } from './queue-render'
+import QueueRenderer from './QueueRenderer.svelte'
+
+export const queueRenderer: CapabilityRenderer = {
+  capability: 'queue',
+  renders: (result) => hasQueueShape(result),
+  component: QueueRenderer,
+}

package/src/lib/renderers/registry.ts

@@ -0,0 +1,68 @@
+// CapabilityRenderer registry — deep module behind a tiny surface.
+//
+// Each renderer declares which capability it handles. pick() takes a
+// capability hint (from the query result, slice metadata, or an override)
+// and picks the right renderer; if no renderer matches the hint, it falls
+// back to the renderer that `renders(result)` accepts, and finally to the
+// 'table' renderer which is the universal default.
+
+import type { QueryResult } from '#reddb'
+import type { Capability, CapabilityRenderer } from './types'
+
+export class RendererRegistry {
+  private renderers: CapabilityRenderer[] = []
+
+  register(renderer: CapabilityRenderer): void {
+    const idx = this.renderers.findIndex((r) => r.capability === renderer.capability)
+    if (idx >= 0) this.renderers[idx] = renderer
+    else this.renderers.push(renderer)
+  }
+
+  unregister(capability: Capability): void {
+    this.renderers = this.renderers.filter((r) => r.capability !== capability)
+  }
+
+  list(): readonly CapabilityRenderer[] {
+    return this.renderers
+  }
+
+  has(capability: Capability): boolean {
+    return this.renderers.some((r) => r.capability === capability)
+  }
+
+  /**
+   * Pick a renderer for this result.
+   *
+   * Resolution order:
+   *  1. `override` capability if present and registered.
+   *  2. `capability` hint if present, registered, and `renders(result)` agrees.
+   *  3. First renderer whose `renders(result)` returns true.
+   *  4. The 'table' renderer (universal fallback).
+   *
+   * Throws if no renderer matches and no 'table' renderer is registered.
+   */
+  pick(
+    capability: Capability | undefined,
+    result: QueryResult,
+    override?: Capability,
+  ): CapabilityRenderer {
+    if (override) {
+      const r = this.renderers.find((r) => r.capability === override)
+      if (r) return r
+    }
+    if (capability) {
+      const r = this.renderers.find((r) => r.capability === capability)
+      if (r && r.renders(result)) return r
+    }
+    const shapeMatch = this.renderers.find((r) => r.renders(result))
+    if (shapeMatch) return shapeMatch
+    const fallback = this.renderers.find((r) => r.capability === 'table')
+    if (!fallback) {
+      throw new Error('No renderer matched and no table fallback is registered')
+    }
+    return fallback
+  }
+}
+
+/** Shared singleton — renderers self-register into this from ./index.ts. */
+export const registry = new RendererRegistry()

package/src/lib/renderers/stats-render.ts

@@ -0,0 +1,73 @@
+import type { QueryResult } from '#reddb'
+
+export interface StatMetric {
+  key: string
+  label: string
+  value: number
+  unit: string
+  source: Record<string, unknown>
+}
+
+const NAME_COLUMNS = ['metric', 'stat', 'name', 'key']
+const VALUE_COLUMNS = ['value', 'count', 'total', 'avg', 'rate', 'p50', 'p95', 'p99']
+const UNIT_COLUMNS = ['unit', 'units']
+
+function unitFor(key: string): string {
+  if (/bytes?|memory|storage|wal/i.test(key)) return 'bytes'
+  if (/rps|rate|requests?_per_second|writes?_per_second|reads?_per_second/i.test(key)) return '/s'
+  if (/ms|latency|response/i.test(key)) return 'ms'
+  if (/percent|ratio|usage/i.test(key)) return '%'
+  return ''
+}
+
+function explicitUnit(values: Record<string, unknown>): string | null {
+  for (const column of UNIT_COLUMNS) {
+    const value = values[column]
+    if (typeof value === 'string' && value.trim()) return value.trim()
+  }
+  const entry = Object.entries(values).find(([k, v]) =>
+    UNIT_COLUMNS.includes(k.toLowerCase()) && typeof v === 'string' && v.trim(),
+  )
+  return entry ? String(entry[1]).trim() : null
+}
+
+export function extractStats(result: QueryResult): StatMetric[] {
+  const metrics: StatMetric[] = []
+  for (const record of result.result.records) {
+    const values = record.values ?? {}
+    const nameEntry = Object.entries(values).find(([k, v]) =>
+      NAME_COLUMNS.includes(k.toLowerCase()) && (typeof v === 'string' || typeof v === 'number'),
+    )
+    const valueEntry = Object.entries(values).find(([k, v]) =>
+      VALUE_COLUMNS.includes(k.toLowerCase()) && typeof v === 'number' && Number.isFinite(v),
+    )
+    if (nameEntry && valueEntry) {
+      const label = String(nameEntry[1])
+      metrics.push({ key: label, label, value: valueEntry[1] as number, unit: explicitUnit(values) ?? unitFor(label), source: values })
+      continue
+    }
+    for (const [key, value] of Object.entries(values)) {
+      if (typeof value !== 'number' || !Number.isFinite(value)) continue
+      metrics.push({ key, label: key, value, unit: unitFor(key), source: values })
+    }
+  }
+  return metrics
+}
+
+export function hasStatsShape(result: QueryResult): boolean {
+  if (result.capability === 'stats') return true
+  const metrics = extractStats(result)
+  return metrics.length > 0 && metrics.length >= result.result.records.length
+}
+
+export function formatMetric(value: number, unit: string): string {
+  if (unit === 'bytes') {
+    const abs = Math.abs(value)
+    if (abs >= 1024 ** 3) return `${(value / 1024 ** 3).toFixed(1)} GiB`
+    if (abs >= 1024 ** 2) return `${(value / 1024 ** 2).toFixed(1)} MiB`
+    if (abs >= 1024) return `${(value / 1024).toFixed(1)} KiB`
+    return `${value} B`
+  }
+  if (unit === '%' || unit === 'ms' || unit === '/s') return `${value.toLocaleString()}${unit}`
+  return value.toLocaleString()
+}

package/src/lib/renderers/stats.ts

@@ -0,0 +1,9 @@
+import type { CapabilityRenderer } from './types'
+import { hasStatsShape } from './stats-render'
+import StatsRenderer from './StatsRenderer.svelte'
+
+export const statsRenderer: CapabilityRenderer = {
+  capability: 'stats',
+  renders: (result) => hasStatsShape(result),
+  component: StatsRenderer,
+}

package/src/lib/renderers/table-render.ts

@@ -0,0 +1,156 @@
+// Pure rendering helpers for the table capability. Used by both the
+// Svelte TableRenderer component (for live UI) and the golden snapshot
+// test (which needs a DOM-free representation).
+
+import type { QueryResult } from '#reddb'
+
+export const TABLE_ROW_LIMIT = 80
+export const ELLIPSIS_AT = 64
+
+/**
+ * reddb's reserved public item fields. The server enforces these as
+ * unwritable by users (see `crates/reddb-server/src/reserved_fields.rs`)
+ * and stamps them onto every read. The UI hides them by default so the
+ * user-defined shape is visible; a toggle reintroduces them as a
+ * prefix block.
+ */
+export const SYSTEM_FIELDS = [
+  'rid',
+  'collection',
+  'kind',
+  'tenant',
+  'created_at',
+  'updated_at',
+] as const
+const SYSTEM_SET = new Set<string>(SYSTEM_FIELDS)
+
+export function isSystemField(column: string): boolean {
+  return SYSTEM_SET.has(column.toLowerCase())
+}
+
+export interface VisibleColumnsOptions {
+  /** When true, reddb system fields lead; when false (default) they're hidden. */
+  showSystem?: boolean
+}
+
+export function visibleColumns(
+  result: QueryResult,
+  opts: VisibleColumnsOptions = {},
+): string[] {
+  const all = result.result.columns
+  // `red_*` and `body` are noise even in show-system mode — the row is
+  // already unrolled, and red_* are internal-only.
+  const usable = all.filter((c) => !c.startsWith('red_') && c !== 'body')
+
+  const userCols = usable.filter((c) => !isSystemField(c))
+  const id = userCols.find((c) => c.toLowerCase() === 'id')
+  const userRest = userCols.filter((c) => c !== id)
+  const userOrdered = [id, ...userRest].filter((c): c is string => Boolean(c))
+
+  if (!opts.showSystem) {
+    return userOrdered.length > 0 ? userOrdered : all
+  }
+
+  // System block, in canonical order (rid first — it's the actual address).
+  const systemOrdered = SYSTEM_FIELDS.filter((f) => usable.includes(f))
+  return [...systemOrdered, ...userOrdered]
+}
+
+export type IdentityKind = 'rid' | 'id'
+
+export function identityKind(column: string): IdentityKind | null {
+  const c = column.toLowerCase()
+  if (c === 'rid') return 'rid'
+  if (c === 'id') return 'id'
+  return null
+}
+
+export function inferPkColumn(columns: string[]): string | null {
+  // rid wins — it's the system-assigned row id and the actual key
+  // reddb uses to address documents. id is user-defined and may not be unique.
+  return (
+    columns.find((c) => c.toLowerCase() === 'rid') ??
+    columns.find((c) => c.toLowerCase() === 'id') ??
+    columns.find((c) => c.toLowerCase().endsWith('_id')) ??
+    columns[0] ??
+    null
+  )
+}
+
+export function formatCell(v: unknown): string {
+  if (v === null || v === undefined) return ''
+  if (typeof v === 'object') return JSON.stringify(v)
+  return String(v)
+}
+
+export function isNull(v: unknown): boolean {
+  return v === null || v === undefined
+}
+
+export function ellipsize(s: string, max = ELLIPSIS_AT): string {
+  if (s.length <= max) return s
+  return s.slice(0, max - 1) + '…'
+}
+
+export function visibleRows(result: QueryResult, limit = TABLE_ROW_LIMIT): Array<Record<string, unknown>> {
+  return result.result.records.slice(0, limit).map((rec) => rec.values)
+}
+
+/**
+ * Produce a stable, DOM-free HTML string for the given query result.
+ * Used by the golden snapshot test. Intentionally minimal: no inline
+ * styles, no event handlers, no editing affordances — those live in the
+ * Svelte component.
+ */
+export function renderTableHtml(
+  result: QueryResult,
+  opts: VisibleColumnsOptions = {},
+): string {
+  const columns = visibleColumns(result, opts)
+  const pk = inferPkColumn(columns)
+  const rows = visibleRows(result)
+  const lines: string[] = []
+  lines.push('<table>')
+  lines.push('<thead><tr>')
+  lines.push('<th class="num">#</th>')
+  for (const c of columns) {
+    const kind = identityKind(c)
+    const mark = kind === 'rid'
+      ? '<span class="badge sys">sys</span>'
+      : kind === 'id'
+        ? '<span class="badge pk">pk</span>'
+        : c === pk
+          ? '<span class="badge pk">pk</span>'
+          : ''
+    const cls = kind ? ` class="id ${kind}"` : ''
+    lines.push(`<th${cls}>${escapeHtml(c)}${mark}</th>`)
+  }
+  lines.push('</tr></thead>')
+  lines.push('<tbody>')
+  rows.forEach((row, i) => {
+    lines.push('<tr>')
+    lines.push(`<td class="num">${i + 1}</td>`)
+    for (const c of columns) {
+      const v = row[c]
+      const kind = identityKind(c)
+      const cls = kind ? ` class="id ${kind}"` : ''
+      if (isNull(v)) {
+        lines.push(`<td${cls}><span class="null">NULL</span></td>`)
+      } else {
+        lines.push(`<td${cls}><span class="cell">${escapeHtml(ellipsize(formatCell(v)))}</span></td>`)
+      }
+    }
+    lines.push('</tr>')
+  })
+  lines.push('</tbody>')
+  lines.push('</table>')
+  return lines.join('')
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}

package/src/lib/renderers/table.ts

@@ -0,0 +1,11 @@
+import type { CapabilityRenderer } from './types'
+import TableRenderer from './TableRenderer.svelte'
+
+export const tableRenderer: CapabilityRenderer = {
+  capability: 'table',
+  // Table is the universal fallback — it can paint any shaped result that
+  // has `columns` and `records`. The registry uses this both for hint
+  // matches and as the last-resort default.
+  renders: (result) => !!result?.result && Array.isArray(result.result.columns),
+  component: TableRenderer,
+}

package/src/lib/renderers/types.ts

@@ -0,0 +1,33 @@
+import type { Component } from 'svelte'
+import type { QueryResult, RedClient } from '#reddb'
+
+export type Capability =
+  | 'table'
+  | 'graph'
+  | 'hypertable'
+  | 'kv'
+  | 'vector'
+  | 'queue'
+  | 'stats'
+  | 'diff'
+  | 'document'
+  | 'json'
+
+export interface RendererProps {
+  result: QueryResult
+  collection?: string
+  client?: RedClient
+  subpage?: string
+  /** When true, reddb system fields (rid, collection, kind, tenant,
+   * created_at, updated_at) are shown ahead of user fields. Default false:
+   * the user-defined shape is what they're trying to read. */
+  showSystem?: boolean
+}
+
+export interface CapabilityRenderer {
+  capability: Capability
+  /** Result-shape disambiguation: does this renderer claim this result? */
+  renders(result: QueryResult): boolean
+  /** Svelte component that paints the result. */
+  component: Component<RendererProps>
+}