feat: add result formatting helpers

src/format.ts

@@ -0,0 +1,37 @@
+export const DEFAULT_ROW_LIMIT = 100
+export const MAX_ROW_LIMIT = 1000
+
+export const clampRowLimit = (requested?: number): number => {
+    if (requested === undefined) return DEFAULT_ROW_LIMIT
+    return Math.max(1, Math.min(Math.trunc(requested), MAX_ROW_LIMIT))
+}
+
+export const truncateRows = <T>(rows: T[], limit: number): { rows: T[]; truncated: boolean } =>
+    rows.length > limit
+        ? { rows: rows.slice(0, limit), truncated: true }
+        : { rows, truncated: false }
+
+export const normalizeCell = (value: unknown): unknown => {
+    if (typeof value === 'bigint') return value.toString()
+    if (value instanceof Date) return value.toISOString()
+    if (Buffer.isBuffer(value)) return `\\x${value.toString('hex')}`
+    return value
+}
+
+type DbErrorShape = Error & {
+    code?: string | number
+    detail?: string
+    hint?: string
+    sqlMessage?: string
+}
+
+export const formatDbError = (engine: string, error: unknown): string => {
+    if (error instanceof Error) {
+        const e = error as DbErrorShape
+        const code = e.code !== undefined && e.code !== null ? ` ${e.code}` : ''
+        const message = e.sqlMessage ?? e.message
+        const extras = [e.detail, e.hint].filter(Boolean).join(' | ')
+        return `[${engine}${code}] ${message}${extras ? ` (${extras})` : ''}`
+    }
+    return `[${engine}] ${String(error)}`
+}