@reddb-io/ui 0.1.1

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

@@ -0,0 +1,320 @@
+// Pure rendering helpers for the hypertable capability.
+//
+// Hypertable result = at least one time-shaped column and one numeric
+// column. The renderer draws an SVG line chart over the time axis with
+// a small data table below for inspection. The metric switcher in the
+// component lets the user flip between numeric columns when there are
+// several; this module exposes the data shape so the test can assert
+// the chart geometry without a browser.
+
+import type { QueryResult } from '#reddb'
+
+export const ALL_METRICS = '__all__'
+
+const TIME_KEYS = ['time', 'timestamp', 'ts', 'event_time', 'bucket', 'created_at']
+const SYSTEM_NUMERIC_KEYS = new Set([
+  'created_at',
+  'updated_at',
+  'time',
+  'timestamp',
+  'timestamp_ns',
+  'rid',
+  'tenant',
+])
+
+export interface HypertablePoint {
+  t: number
+  v: number
+  raw: Record<string, unknown>
+}
+
+export interface HypertableSeries {
+  timeColumn: string
+  metricColumn: string
+  metrics: string[]
+  points: HypertablePoint[]
+  metricNameColumn: string | null
+}
+
+export const CHART_WIDTH = 640
+export const CHART_HEIGHT = 180
+export const CHART_PADDING = 16
+
+function isNumericValue(v: unknown): v is number {
+  if (typeof v === 'number') return Number.isFinite(v)
+  if (typeof v === 'string' && v.trim() !== '') {
+    const n = Number(v)
+    return Number.isFinite(n)
+  }
+  return false
+}
+
+function toNumber(v: unknown): number {
+  if (typeof v === 'number') return v
+  return Number(v)
+}
+
+function toTimestamp(v: unknown): number | null {
+  if (v === null || v === undefined) return null
+  if (typeof v === 'number') return Number.isFinite(v) ? v : null
+  if (v instanceof Date) return v.getTime()
+  if (typeof v === 'string') {
+    const n = Number(v)
+    if (Number.isFinite(n)) return n
+    const d = Date.parse(v)
+    return Number.isNaN(d) ? null : d
+  }
+  return null
+}
+
+export function pickTimeColumn(result: QueryResult): string | null {
+  const cols = result.result?.columns ?? []
+  for (const key of TIME_KEYS) {
+    const found = cols.find((c) => c.toLowerCase() === key)
+    if (found) return found
+  }
+  const records = result.result?.records ?? []
+  if (records.length === 0) return null
+  // Fallback: any column whose first non-null value parses as a date.
+  for (const c of cols) {
+    const sample = records.find((r) => r.values[c] !== null && r.values[c] !== undefined)
+    if (!sample) continue
+    if (toTimestamp(sample.values[c]) !== null && !isNumericValue(sample.values[c])) {
+      return c
+    }
+  }
+  return null
+}
+
+export function numericColumns(result: QueryResult, exclude: string | null): string[] {
+  const cols = result.result?.columns ?? []
+  const records = result.result?.records ?? []
+  if (records.length === 0) return []
+  const out: string[] = []
+  for (const c of cols) {
+    if (c === exclude) continue
+    if (c.startsWith('red_')) continue
+    if (SYSTEM_NUMERIC_KEYS.has(c.toLowerCase())) continue
+    const sample = records.find((r) => r.values[c] !== null && r.values[c] !== undefined)
+    if (!sample) continue
+    if (isNumericValue(sample.values[c])) out.push(c)
+  }
+  return out
+}
+
+export function hasHypertableShape(result: QueryResult): boolean {
+  const t = pickTimeColumn(result)
+  if (!t) return false
+  return numericColumns(result, t).length > 0
+}
+
+export function extractSeries(
+  result: QueryResult,
+  metric?: string,
+): HypertableSeries | null {
+  const timeColumn = pickTimeColumn(result)
+  if (!timeColumn) return null
+  const metricNameColumn = result.result.columns.find((c) => c.toLowerCase() === 'metric') ?? null
+  const valueColumn = result.result.columns.find((c) => c.toLowerCase() === 'value') ?? null
+  if (metricNameColumn && valueColumn) {
+    const names = new Set<string>()
+    const allPoints: HypertablePoint[] = []
+    for (const rec of result.result.records) {
+      const name = rec.values[metricNameColumn]
+      const value = rec.values[valueColumn]
+      if ((typeof name === 'string' || typeof name === 'number') && isNumericValue(value)) {
+        names.add(String(name))
+        const t = toTimestamp(rec.values[timeColumn])
+        if (t !== null) allPoints.push({ t, v: toNumber(value), raw: rec.values })
+      }
+    }
+    const metrics = [...names].sort()
+    if (metrics.length > 0) {
+      if (!metric || metric === ALL_METRICS) {
+        allPoints.sort((a, b) => a.t - b.t)
+        return {
+          timeColumn,
+          metricColumn: valueColumn,
+          metrics: [ALL_METRICS, ...metrics],
+          points: allPoints,
+          metricNameColumn,
+        }
+      }
+      const selectedMetric = metrics.includes(metric) ? metric : metrics[0]
+      const points: HypertablePoint[] = []
+      for (const rec of result.result.records) {
+        if (String(rec.values[metricNameColumn]) !== selectedMetric) continue
+        const t = toTimestamp(rec.values[timeColumn])
+        if (t === null) continue
+        const vRaw = rec.values[valueColumn]
+        if (!isNumericValue(vRaw)) continue
+        points.push({ t, v: toNumber(vRaw), raw: rec.values })
+      }
+      points.sort((a, b) => a.t - b.t)
+      return { timeColumn, metricColumn: valueColumn, metrics: [ALL_METRICS, ...metrics], points, metricNameColumn }
+    }
+  }
+
+  const metrics = numericColumns(result, timeColumn)
+  if (metrics.length === 0) return null
+  const metricColumn = metric && metrics.includes(metric) ? metric : metrics[0]
+  const points: HypertablePoint[] = []
+  for (const rec of result.result.records) {
+    const tRaw = rec.values[timeColumn]
+    const vRaw = rec.values[metricColumn]
+    const t = toTimestamp(tRaw)
+    if (t === null) continue
+    if (!isNumericValue(vRaw)) continue
+    points.push({ t, v: toNumber(vRaw), raw: rec.values })
+  }
+  points.sort((a, b) => a.t - b.t)
+  return { timeColumn, metricColumn, metrics, points, metricNameColumn: null }
+}
+
+export interface ChartGeometry {
+  width: number
+  height: number
+  padding: number
+  path: string
+  minT: number
+  maxT: number
+  minV: number
+  maxV: number
+}
+
+export function chartGeometry(
+  series: HypertableSeries,
+  width = CHART_WIDTH,
+  height = CHART_HEIGHT,
+  padding = CHART_PADDING,
+): ChartGeometry | null {
+  const pts = series.points
+  if (pts.length === 0) return null
+  const minT = pts[0].t
+  const maxT = pts[pts.length - 1].t
+  let minV = Infinity
+  let maxV = -Infinity
+  for (const p of pts) {
+    if (p.v < minV) minV = p.v
+    if (p.v > maxV) maxV = p.v
+  }
+  if (!Number.isFinite(minV) || !Number.isFinite(maxV)) return null
+  const spanT = maxT - minT || 1
+  const spanV = maxV - minV || 1
+  const w = width - padding * 2
+  const h = height - padding * 2
+  const segments: string[] = []
+  pts.forEach((p, i) => {
+    const x = padding + ((p.t - minT) / spanT) * w
+    const y = padding + h - ((p.v - minV) / spanV) * h
+    segments.push(`${i === 0 ? 'M' : 'L'}${x.toFixed(2)},${y.toFixed(2)}`)
+  })
+  return {
+    width,
+    height,
+    padding,
+    path: segments.join(' '),
+    minT,
+    maxT,
+    minV,
+    maxV,
+  }
+}
+
+export interface BucketPoint {
+  /** Bucket start in epoch ms. */
+  t: number
+  /** Number of points falling into this bucket. */
+  count: number
+  /** Sum of metric values in this bucket. */
+  sum: number
+}
+
+/**
+ * Bucket a series into fixed-size windows (default 1 minute). Returns
+ * one BucketPoint per bucket *between* minT and maxT inclusive — empty
+ * buckets get count=0 so the bar chart shows gaps in writes instead of
+ * collapsing them. The user goal is "writes per minute": a bucket whose
+ * count is 0 is meaningful information.
+ */
+export function bucketSeries(series: HypertableSeries, bucketMs = 60_000): BucketPoint[] {
+  if (series.points.length === 0) return []
+  const firstT = series.points[0].t
+  const lastT = series.points[series.points.length - 1].t
+  const start = Math.floor(firstT / bucketMs) * bucketMs
+  const end = Math.floor(lastT / bucketMs) * bucketMs
+  const buckets = new Map<number, BucketPoint>()
+  for (let t = start; t <= end; t += bucketMs) {
+    buckets.set(t, { t, count: 0, sum: 0 })
+  }
+  for (const p of series.points) {
+    const key = Math.floor(p.t / bucketMs) * bucketMs
+    const b = buckets.get(key)
+    if (!b) continue
+    b.count += 1
+    b.sum += p.v
+  }
+  return [...buckets.values()].sort((a, b) => a.t - b.t)
+}
+
+export interface BucketGeometry {
+  width: number
+  height: number
+  padding: number
+  bars: { x: number; y: number; w: number; h: number; bucket: BucketPoint }[]
+  maxCount: number
+}
+
+export function bucketGeometry(
+  buckets: BucketPoint[],
+  width = CHART_WIDTH,
+  height = CHART_HEIGHT,
+  padding = CHART_PADDING,
+): BucketGeometry | null {
+  if (buckets.length === 0) return null
+  const maxCount = buckets.reduce((m, b) => Math.max(m, b.count), 0)
+  if (maxCount === 0) return null
+  const w = width - padding * 2
+  const h = height - padding * 2
+  // Leave a 1-px gutter between bars so dense traces still read as bars.
+  const slot = w / buckets.length
+  const barWidth = Math.max(1, slot - 1)
+  const bars = buckets.map((bucket, i) => {
+    const ratio = bucket.count / maxCount
+    const barH = ratio * h
+    return {
+      x: padding + i * slot,
+      y: padding + h - barH,
+      w: barWidth,
+      h: barH,
+      bucket,
+    }
+  })
+  return { width, height, padding, bars, maxCount }
+}
+
+export function renderHypertableHtml(result: QueryResult, metric?: string): string {
+  const series = extractSeries(result, metric)
+  if (!series) return '<section class="hypertable empty">No timeseries shape detected.</section>'
+  const geom = chartGeometry(series)
+  const lines: string[] = []
+  lines.push('<section class="hypertable">')
+  lines.push(
+    `<header class="summary">${series.points.length} pts · metric <code>${escapeHtml(series.metricColumn)}</code></header>`,
+  )
+  if (geom) {
+    lines.push(
+      `<svg viewBox="0 0 ${geom.width} ${geom.height}" class="chart"><path d="${geom.path}" /></svg>`,
+    )
+  }
+  lines.push('</section>')
+  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/hypertable.ts

@@ -0,0 +1,9 @@
+import type { CapabilityRenderer } from './types'
+import { hasHypertableShape } from './hypertable-render'
+import HypertableRenderer from './HypertableRenderer.svelte'
+
+export const hypertableRenderer: CapabilityRenderer = {
+  capability: 'hypertable',
+  renders: (result) => hasHypertableShape(result),
+  component: HypertableRenderer,
+}

package/src/lib/renderers/index.ts

@@ -0,0 +1,42 @@
+// Renderer registry — registers the bundled renderers on import.
+//
+// Consumers should import { registry } from this module rather than
+// going through ./registry directly, so this side-effect runs and the
+// renderers are always available.
+
+import { registry } from './registry'
+import { tableRenderer } from './table'
+import { graphRenderer } from './graph'
+import { kvRenderer } from './kv'
+import { hypertableRenderer } from './hypertable'
+import { jsonRenderer } from './json'
+import { vectorRenderer } from './vector'
+import { queueRenderer } from './queue'
+import { statsRenderer } from './stats'
+import { diffRenderer } from './diff'
+import { documentRenderer } from './document'
+
+registry.register(tableRenderer)
+registry.register(graphRenderer)
+registry.register(kvRenderer)
+registry.register(hypertableRenderer)
+registry.register(vectorRenderer)
+registry.register(queueRenderer)
+registry.register(statsRenderer)
+registry.register(diffRenderer)
+registry.register(documentRenderer)
+registry.register(jsonRenderer)
+
+export { registry, RendererRegistry } from './registry'
+export type { Capability, CapabilityRenderer, RendererProps } from './types'
+export { tableRenderer } from './table'
+export { graphRenderer } from './graph'
+export { kvRenderer } from './kv'
+export { hypertableRenderer } from './hypertable'
+export { jsonRenderer } from './json'
+export { vectorRenderer } from './vector'
+export { queueRenderer } from './queue'
+export { statsRenderer } from './stats'
+export { diffRenderer } from './diff'
+export { documentRenderer } from './document'
+export * from './table-render'

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

@@ -0,0 +1,89 @@
+// Pure rendering helpers for the JSON capability.
+//
+// JSON is the universal override — the user can switch any tab to JSON
+// to see the raw shape returned by reddb. It is never the default
+// renderer (renders() returns false) so it does not steal results from
+// the more specific capabilities; it only fires when explicitly chosen.
+
+import type { QueryResult } from '#reddb'
+
+export function projectJson(result: QueryResult): unknown {
+  // Strip the verbose envelope to what a developer would actually want
+  // to inspect: the query, capability, count, and the raw records.
+  return {
+    query: result.query,
+    capability: result.capability,
+    record_count: result.record_count,
+    records: result.result.records,
+  }
+}
+
+export function prettyJson(value: unknown): string {
+  return JSON.stringify(value, null, 2)
+}
+
+export function highlightJson(json: string): string {
+  // Tokenize a known-valid JSON string into <span class="…">…</span>
+  // segments. Reads "strings (and keys), numbers, booleans, nulls".
+  // We deliberately do not parse — this runs over the already-formatted
+  // output of JSON.stringify, which is a closed grammar.
+  let out = ''
+  let i = 0
+  const n = json.length
+  while (i < n) {
+    const ch = json[i]
+    if (ch === '"') {
+      let j = i + 1
+      while (j < n) {
+        if (json[j] === '\\') { j += 2; continue }
+        if (json[j] === '"') break
+        j += 1
+      }
+      const slice = json.slice(i, j + 1)
+      // Look ahead past whitespace for a colon → this is a key.
+      let k = j + 1
+      while (k < n && (json[k] === ' ' || json[k] === '\t')) k += 1
+      const isKey = json[k] === ':'
+      out += `<span class="${isKey ? 'k' : 's'}">${escapeHtml(slice)}</span>`
+      i = j + 1
+      continue
+    }
+    if ((ch >= '0' && ch <= '9') || (ch === '-' && json[i + 1] >= '0' && json[i + 1] <= '9')) {
+      let j = i + 1
+      while (j < n && /[0-9eE+\-.]/.test(json[j])) j += 1
+      out += `<span class="n">${escapeHtml(json.slice(i, j))}</span>`
+      i = j
+      continue
+    }
+    if (json.startsWith('true', i) || json.startsWith('false', i)) {
+      const len = json[i] === 't' ? 4 : 5
+      out += `<span class="b">${json.slice(i, i + len)}</span>`
+      i += len
+      continue
+    }
+    if (json.startsWith('null', i)) {
+      out += `<span class="z">null</span>`
+      i += 4
+      continue
+    }
+    out += escapeHtml(ch)
+    i += 1
+  }
+  return out
+}
+
+export function renderJsonHtml(result: QueryResult): string {
+  const payload = projectJson(result)
+  const pretty = prettyJson(payload)
+  return `<pre class="json">${highlightJson(pretty)}</pre>`
+}
+
+function escapeHtml(s: string): string {
+  // JSON tokens are wrapped in <span> bodies, never in attribute values,
+  // so we leave double-quotes literal — they belong to the JSON syntax
+  // and stay readable in the rendered output.
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}

package/src/lib/renderers/json.ts

@@ -0,0 +1,10 @@
+import type { CapabilityRenderer } from './types'
+import JsonRenderer from './JsonRenderer.svelte'
+
+export const jsonRenderer: CapabilityRenderer = {
+  capability: 'json',
+  // JSON never wins by shape detection — it's the universal override.
+  // The registry still picks it when the user selects it explicitly.
+  renders: () => false,
+  component: JsonRenderer,
+}

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

@@ -0,0 +1,193 @@
+// Pure rendering helpers for the KV capability. The KV renderer shows a
+// tree of keys split on `/` plus a per-key value preview, so a user
+// browsing `config/auth/jwt` sees the `config → auth → jwt` hierarchy
+// rather than 800 flat rows.
+
+import type { QueryResult } from '#reddb'
+
+export interface KvEntry {
+  key: string
+  value: unknown
+}
+
+export interface KvNode {
+  /** Last segment of the path (display label). */
+  name: string
+  /** Full key when this node represents an actual entry; null for purely structural nodes. */
+  fullKey: string | null
+  value: unknown
+  /** Direct children indexed by segment name, kept sorted on insert. */
+  children: KvNode[]
+}
+
+function findKeyCol(cols: ReadonlyArray<string>): string | null {
+  // Exact preferred names, then any column ending in `_key` (our seed uses
+  // `fact_key`/`fact_value`; other apps might use `cfg_key`, etc).
+  return (
+    cols.find((c) => c.toLowerCase() === 'key') ??
+    cols.find((c) => c.toLowerCase() === 'k') ??
+    cols.find((c) => /(^|_)key$/i.test(c)) ??
+    null
+  )
+}
+
+function findValueCol(cols: ReadonlyArray<string>): string | null {
+  return (
+    cols.find((c) => c.toLowerCase() === 'value') ??
+    cols.find((c) => c.toLowerCase() === 'v') ??
+    cols.find((c) => /(^|_)value$/i.test(c)) ??
+    null
+  )
+}
+
+export function extractKv(result: QueryResult): KvEntry[] {
+  const cols = result.result.columns
+  const keyCol = findKeyCol(cols)
+  const valueCol = findValueCol(cols)
+  if (!keyCol || !valueCol) return []
+  return result.result.records.map((r) => ({
+    key: String(r.values[keyCol] ?? ''),
+    value: r.values[valueCol],
+  }))
+}
+
+export function hasKvShape(result: QueryResult): boolean {
+  const cols = result.result?.columns ?? []
+  return findKeyCol(cols) !== null && findValueCol(cols) !== null
+}
+
+/**
+ * Flatten a KV tree under `prefix` into a plain object so the toolbar's
+ * JSON view can render the prefix as a single navigable record.
+ */
+export function flattenUnderPrefix(entries: KvEntry[], prefix: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const e of entries) {
+    if (!e.key.startsWith(prefix)) continue
+    const rest = e.key.slice(prefix.length).replace(/^\/+/, '')
+    if (!rest) {
+      // exact match → use a sentinel "$value" so the prefix root has a slot
+      out.$value = e.value
+      continue
+    }
+    out[rest] = e.value
+  }
+  return out
+}
+
+/**
+ * Materialize slash-delimited KV keys as a nested JSON object. Exact prefix
+ * values share space with children through `$value`, so `a=1` and `a/b=2`
+ * remain representable without dropping either value.
+ */
+export function materializeKvJson(entries: KvEntry[], prefix: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {}
+  for (const entry of entries) {
+    if (!entry.key.startsWith(prefix)) continue
+    const rest = entry.key.slice(prefix.length).replace(/^\/+/, '')
+    const segments = rest.split('/').filter(Boolean)
+    if (segments.length === 0) {
+      root.$value = entry.value
+      continue
+    }
+    let cursor = root
+    for (let i = 0; i < segments.length; i += 1) {
+      const segment = segments[i]
+      if (i === segments.length - 1) {
+        const existing = cursor[segment]
+        if (existing && typeof existing === 'object' && !Array.isArray(existing)) {
+          ;(existing as Record<string, unknown>).$value = entry.value
+        } else {
+          cursor[segment] = entry.value
+        }
+        continue
+      }
+      const existing = cursor[segment]
+      if (!existing || typeof existing !== 'object' || Array.isArray(existing)) {
+        const next: Record<string, unknown> = {}
+        if (existing !== undefined) next.$value = existing
+        cursor[segment] = next
+        cursor = next
+      } else {
+        cursor = existing as Record<string, unknown>
+      }
+    }
+  }
+  return root
+}
+
+export function buildTree(entries: KvEntry[]): KvNode {
+  const root: KvNode = { name: '', fullKey: null, value: undefined, children: [] }
+  for (const entry of entries) {
+    const segments = entry.key.split('/').filter((s) => s.length > 0)
+    if (segments.length === 0) continue
+    let cursor = root
+    segments.forEach((seg, i) => {
+      let child = cursor.children.find((c) => c.name === seg)
+      if (!child) {
+        child = { name: seg, fullKey: null, value: undefined, children: [] }
+        // Insert in sorted order so output is deterministic.
+        const idx = cursor.children.findIndex((c) => c.name > seg)
+        if (idx < 0) cursor.children.push(child)
+        else cursor.children.splice(idx, 0, child)
+      }
+      if (i === segments.length - 1) {
+        child.fullKey = entry.key
+        child.value = entry.value
+      }
+      cursor = child
+    })
+  }
+  return root
+}
+
+export function formatValue(v: unknown): string {
+  if (v === null || v === undefined) return 'null'
+  if (typeof v === 'object') return JSON.stringify(v)
+  return String(v)
+}
+
+export function renderKvHtml(result: QueryResult): string {
+  const entries = extractKv(result)
+  const tree = buildTree(entries)
+  const lines: string[] = []
+  lines.push('<section class="kv">')
+  lines.push(`<header class="summary">${entries.length} keys</header>`)
+  lines.push('<ul class="tree">')
+  for (const child of tree.children) {
+    walk(child, 0, lines)
+  }
+  lines.push('</ul>')
+  lines.push('</section>')
+  return lines.join('')
+}
+
+function walk(node: KvNode, depth: number, out: string[]): void {
+  const hasValue = node.fullKey !== null
+  const cls = ['node']
+  if (hasValue) cls.push('leaf')
+  out.push(`<li class="${cls.join(' ')}" data-depth="${depth}">`)
+  out.push(`<span class="seg">${escapeHtml(node.name)}</span>`)
+  if (hasValue) {
+    out.push(`<span class="val">${escapeHtml(truncate(formatValue(node.value)))}</span>`)
+  }
+  if (node.children.length > 0) {
+    out.push('<ul class="children">')
+    for (const child of node.children) walk(child, depth + 1, out)
+    out.push('</ul>')
+  }
+  out.push('</li>')
+}
+
+function truncate(s: string, max = 80): string {
+  if (s.length <= max) return s
+  return s.slice(0, max - 1) + '…'
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}

package/src/lib/renderers/kv.ts

@@ -0,0 +1,9 @@
+import type { CapabilityRenderer } from './types'
+import { hasKvShape } from './kv-render'
+import KvRenderer from './KvRenderer.svelte'
+
+export const kvRenderer: CapabilityRenderer = {
+  capability: 'kv',
+  renders: (result) => hasKvShape(result),
+  component: KvRenderer,
+}