The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
import dayjs from 'dayjs'
import type { CodeBlockLang } from 'ui-patterns/CodeBlock'
import type {
NotebookCellDiffEntry,
OperationResultCell,
} from '@/data/content/notebooks/notebook-operations'
import type { ChartConfig, TimeRange } from '@/data/content/notebooks/notebook-schema'
import type { Database } from '@/data/read-replicas/replicas-query'
type DatabaseDetails = Pick<Database, 'identifier'>
export type NotebookDatabaseContext = { projectRef?: string } & (
| { status: 'loading' }
| { status: 'error' }
| { status: 'success'; databasesByIdentifier: ReadonlyMap<string, DatabaseDetails> }
)
export type NotebookDatabaseTarget =
| { status: 'primary' }
| { status: 'loading' }
| { status: 'replica' }
| { status: 'unknown' }
| { status: 'error' }
export type NotebookCellFields =
| { status: 'hidden' }
| { status: 'loading' }
| { status: 'ready'; source?: string; view?: string }
export type NotebookCellMetadata =
| { status: 'hidden' }
| { status: 'loading' }
| { status: 'ready'; text: string }
/** React key for a diff entry. Added/replaced cells have no `_id`, so they key off the operation. */
export function getEntryKey(entry: NotebookCellDiffEntry): string {
switch (entry._tag) {
case 'unchanged':
case 'removed':
case 'moved':
return entry.cell._id
case 'added':
case 'replaced':
return `op-${entry.operationIndex}`
}
}
/** Whether any cell needs the database list before its target can be classified. */
export function notebookEntriesNeedDatabaseLookup(
entries: NotebookCellDiffEntry[],
projectRef?: string
): boolean {
return entries.some((entry) => {
const cells = entry._tag === 'replaced' ? [entry.before, entry.after] : [entry.cell]
return cells.some(
(cell) =>
cell._tag === 'database_cell' &&
cell.database_identifier !== undefined &&
cell.database_identifier !== projectRef
)
})
}
/** Human label for a collapsed/badge row. */
export function getCellLabel(cell: OperationResultCell): string {
switch (cell._tag) {
case 'markdown_cell':
return 'Markdown cell'
case 'database_cell':
case 'log_cell':
return `Query: ${cell.title ?? 'Untitled query'}`
}
}
/** The cell's underlying source text, regardless of backend. */
export function getCellSourceText(cell: OperationResultCell): string {
switch (cell._tag) {
case 'markdown_cell':
return cell.text
case 'database_cell':
case 'log_cell':
return cell.sql
}
}
/** Language for rendering the cell's source via `CodeBlock`. */
export function getCellCodeBlockLanguage(cell: OperationResultCell): CodeBlockLang {
switch (cell._tag) {
case 'markdown_cell':
return 'markdown'
case 'database_cell':
case 'log_cell':
return 'sql'
}
}
/** Monaco language id for rendering the cell's source via `DiffEditor`. */
export function getCellMonacoLanguage(cell: OperationResultCell): string {
switch (cell._tag) {
case 'markdown_cell':
return 'markdown'
case 'database_cell':
case 'log_cell':
return 'pgsql'
}
}
/** Formats a `TimeRange` as plain text, e.g. "Last 7 days" or an absolute bound pair. */
export function formatTimeRange(range: TimeRange): string {
if (range._tag === 'relative_time_range') {
return `Last ${range.amount} ${range.unit}${range.amount === 1 ? '' : 's'}`
}
const format = (value: string) => dayjs(value).format('MMM D, YYYY h:mm A')
return `${format(range.start)} → ${format(range.end)}`
}
export function resolveNotebookDatabaseTarget(
identifier: string | undefined,
context: NotebookDatabaseContext
): NotebookDatabaseTarget {
if (identifier === undefined || identifier === context.projectRef) return { status: 'primary' }
if (context.status === 'loading') return { status: 'loading' }
if (context.status === 'error') return { status: 'error' }
const database = context.databasesByIdentifier.get(identifier)
if (database === undefined) return { status: 'unknown' }
if (database.identifier === context.projectRef) return { status: 'primary' }
return { status: 'replica' }
}
function formatDatabaseTarget(target: Exclude<NotebookDatabaseTarget, { status: 'loading' }>) {
switch (target.status) {
case 'primary':
return 'Database: Primary'
case 'replica':
return 'Database: Replica'
case 'unknown':
return 'Database: Unknown'
case 'error':
return 'Database unavailable'
}
}
function formatChartConfig(chart: ChartConfig): string {
const parts = [chart.type, `x: ${chart.x_column}`, `y: ${chart.y_series.join(', ')}`]
if (chart.cumulative) parts.push('cumulative')
if (chart.scale !== 'linear') parts.push(chart.scale)
if (chart.show_labels) parts.push('labels')
return parts.join(', ')
}
function formatCellView(
cell: Extract<OperationResultCell, { _tag: 'database_cell' | 'log_cell' }>
): string {
if ((cell.view ?? 'table') !== 'chart') return 'Table'
return `Chart (${cell.chart !== undefined ? formatChartConfig(cell.chart) : 'unconfigured'})`
}
export function getCellMetadata(
cell: OperationResultCell,
databaseContext: NotebookDatabaseContext
): NotebookCellFields {
switch (cell._tag) {
case 'markdown_cell':
return { status: 'hidden' }
case 'database_cell': {
const target = resolveNotebookDatabaseTarget(cell.database_identifier, databaseContext)
if (target.status === 'loading') return { status: 'loading' }
return { status: 'ready', source: formatDatabaseTarget(target), view: formatCellView(cell) }
}
case 'log_cell':
return {
status: 'ready',
source: `Time range: ${formatTimeRange(cell.time_range)}`,
view: formatCellView(cell),
}
}
}
/** Joins a cell's fields into display text, dropping the view when it's just the default table. */
function formatCellFieldsText(fields: { source?: string; view?: string }): string {
return [fields.source, fields.view === 'Table' ? undefined : fields.view]
.filter((part): part is string => part !== undefined)
.join(' · ')
}
/** A field that's identical before and after carries no information about what changed, so it's dropped. */
function diffField(before: string | undefined, after: string | undefined): string | undefined {
if (before === after) return undefined
return `${before ?? 'Not configured'} → ${after ?? 'Not configured'}`
}
/** Header metadata for a diff row. On a replacement, only the fields that actually changed are shown. */
export function getEntryMetadata(
entry: NotebookCellDiffEntry,
databaseContext: NotebookDatabaseContext
): NotebookCellMetadata {
if (entry._tag !== 'replaced') {
const fields = getCellMetadata(entry.cell, databaseContext)
if (fields.status !== 'ready') return fields
const text = formatCellFieldsText(fields)
return text === '' ? { status: 'hidden' } : { status: 'ready', text }
}
const before = getCellMetadata(entry.before, databaseContext)
const after = getCellMetadata(entry.after, databaseContext)
if (before.status === 'loading' || after.status === 'loading') return { status: 'loading' }
const beforeSource = before.status === 'ready' ? before.source : undefined
const afterSource = after.status === 'ready' ? after.source : undefined
const beforeView = before.status === 'ready' ? before.view : undefined
const afterView = after.status === 'ready' ? after.view : undefined
const parts = [diffField(beforeSource, afterSource), diffField(beforeView, afterView)].filter(
(part): part is string => part !== undefined
)
return parts.length > 0 ? { status: 'ready', text: parts.join(' · ') } : { status: 'hidden' }
}
export type NotebookDiffSummary =
| { mode: 'create'; cellCount: number }
| { mode: 'run'; cellCount: number }
| { mode: 'update'; counts: { added: number; removed: number; replaced: number; moved: number } }
/** Summarizes a set of diff entries into counts suitable for a header line. */
export function summarizeNotebookDiff(
entries: NotebookCellDiffEntry[],
mode: 'create' | 'update' | 'run'
): NotebookDiffSummary {
if (mode === 'create' || mode === 'run') {
return { mode, cellCount: entries.length }
}
const counts = { added: 0, removed: 0, replaced: 0, moved: 0 }
for (const entry of entries) {
switch (entry._tag) {
case 'added':
counts.added++
break
case 'removed':
counts.removed++
break
case 'replaced':
counts.replaced++
break
case 'moved':
counts.moved++
break
case 'unchanged':
break
}
}
return { mode: 'update', counts }
}
/** Formats a `NotebookDiffSummary` into the header string. */
export function formatNotebookDiffSummary(summary: NotebookDiffSummary): string {
if (summary.mode === 'create' || summary.mode === 'run') {
const { cellCount } = summary
return `${cellCount} cell${cellCount === 1 ? '' : 's'}`
}
const { added, removed, replaced, moved } = summary.counts
const parts: string[] = []
if (added > 0) parts.push(`+${added}`)
if (removed > 0) parts.push(`−${removed}`)
if (replaced > 0) parts.push(`~${replaced}`)
if (moved > 0) parts.push(`↕${moved}`)
return parts.length > 0 ? parts.join(' ') : 'No changes'
}