// Single responsibility: a JS array bound as a statement parameter, rendered as the Postgres array // literal `Bun.SQL` does not render. // // WHAT IS BROKEN WITHOUT IT. `Bun.SQL`'s positional form serialises an array by JOINING ITS // ELEMENTS WITH COMMAS, so `unsafe('select $1::text[]', [['x', 'y']])` sends the string `x,y` and // Postgres answers `malformed array literal: "x,y"` (SQLSTATE 22P02). Measured on Bun 1.4.0 // against Postgres 17. Three shipped statements bound an array through that path and every one // of them failed — `SQL_CLAIM` (the worker's claim loop), `SQL_OUTBOX_RELEASE` and // `SQL_NOTIFY_INBOX_MARK_READ`. Issue #384. // // WHY HERE AND NOT AT THE THREE CALL SITES. `sendOn` is the one place this driver's `unsafe` is // called, so one encoder here is every caller fixed and none of them has to remember — a helper // each site imports is three chances to forget and a fourth site tomorrow that does. Axiom 1. // // WHY PGLITE IS UNTOUCHED. `pglite.ts` is a separate driver with its own `send`, and it encodes an // array parameter correctly already — which is exactly why nothing caught this: `x dev` runs the // embedded default, so the framework's own dev loop is systematically blind to a defect that only // appears once `DATABASE_URL` selects `Bun.SQL`. A container is where it bites. import { assert } from '@ultimat3/core'; /** * One element, quoted only when it has to be. * * `NULL` unquoted is the array NULL and `"NULL"` is the four-character string, so a JS `null` * MUST render bare and a string that happens to spell it must not. Everything else is quoted when * it holds a character the literal grammar reads as structure — a comma, a brace, a quote, a * backslash, or leading/trailing whitespace the parser would strip — plus the empty string, which * unquoted is not an element at all. */ const hexOf = (bytes: Uint8Array): string => Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0')).join(''); /** * A `Date` as the instant Postgres reads, or `X_INVARIANT` for one that holds no instant. * `toISOString()` on an Invalid Date is a bare `RangeError`, and inside the funnel that became * "cannot reach the database". `position` names the parameter when the caller knows it. */ export function instantText(value: Date, position?: number): string { // Inside the `if`, never as `assert`'s condition: the refusal's text is a template, and as an // argument it was built for every valid Date too — every bound timestamp of every statement. if (!Number.isNaN(value.getTime())) return value.toISOString(); assert( false, `${position === undefined ? 'an array element' : `parameter $${position}`} is an Invalid Date, which names no instant Postgres could store`, 'new Date(input) answers Invalid Date for text it cannot parse — parse it with t.date first, or bind null: Number.isNaN(value.getTime()) ? null : value', ); } function element(value: unknown): string { if (value === null || value === undefined) return 'NULL'; // A Date is ALWAYS quoted, even though an ISO-8601 instant carries no character the grammar // reads as structure. A timestamp element is conventionally quoted, and the alternative is a // rule that holds only while nothing ever renders a timestamp with a space in it. if (value instanceof Date) return `"${instantText(value)}"`; // BYTEA's hex form, never `String(bytes)` — that is `1,2,3`, three elements where one was bound, // and no error anywhere. The backslash is doubled because a quoted element reads `\\` as one. if (value instanceof Uint8Array) return `"\\\\x${hexOf(value)}"`; const text = String(value); const structural = /[{},"\\\s]/.test(text) || text.length === 0 || text.toUpperCase() === 'NULL'; if (!structural) return text; return `"${text.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`; } /** The extents along a value's FIRST path, `2x3` for two rows of three — `''` for a scalar. */ function extentsOf(value: unknown): string { if (!Array.isArray(value)) return ''; const inner = extentsOf(value[0]); return inner === '' ? String(value.length) : `${value.length}x${inner}`; } /** * The array literal for one parameter: `{a,b,c}`, elements escaped. * * NESTED ARRAYS ARE RENDERED, not refused: Postgres reads `{{a,b},{c,d}}` as a 2-dimensional * array, and rendering one is strictly closer to right than sending `a,b,c,d`. Nothing in this * tree binds one today. * * A RAGGED nest is REFUSED, never rendered. Postgres has no jagged array — every extent of a * dimension must match — and `{{a,b},{c}}` is `22P02 malformed array literal`, measured on 17 * beside the rectangular `{{a,b},{c,d}}` that parses (`array-parameter.live.test.ts`). So a * literal this function is willing to emit is one the server is willing to read: rendering the * jagged one puts the fault two layers away, in the driver's words, naming neither the parameter * nor which row is short. `X_INVARIANT` through core's `assert`, the code this package already * borrows for a value this build cannot honour (`createIndex`'s unique GIN, `generatedClause`'s * generated-and-defaulted column). */ export function pgArrayLiteral(values: readonly unknown[]): string { const nested = values.filter((value): value is readonly unknown[] => Array.isArray(value)); // Mixed depth is ragged too — `{a,{b,c}}` is a scalar beside a dimension, which Postgres reads // as the same malformed literal. Comparing counts alone would let it through. assert( nested.length === 0 || nested.length === values.length, 'a nested array parameter mixes scalars and arrays at one level, and Postgres has no such array', 'bind one array of scalars, or one array whose every element is an array of equal length', ); const width = nested[0]?.length; assert( nested.every((row) => row.length === width), `a nested array parameter is ragged — its rows are ${nested.map((row) => row.length).join(', ')} long, and Postgres has no jagged array`, 'give every row the same length, or bind one array per row', ); // Every extent, not only this level's: `[[['a']], [['b', 'c']]]` is two rows of one element each, // each rectangular on its own, and `{{{a}},{{b,c}}}` is the same 22P02 — measured on 17. Each // row is checked against itself by the recursion below, so comparing one path's extents per row // is comparing all of them. const depth = extentsOf(nested[0]); assert( nested.every((row) => extentsOf(row) === depth), `a nested array parameter is ragged below its first level — its rows have the extents ${nested.map((row) => extentsOf(row)).join(' | ')}, and Postgres has no jagged array`, 'give every branch the same length at every depth, or bind one array per row', ); return `{${values.map((value) => (Array.isArray(value) ? pgArrayLiteral(value) : element(value))).join(',')}}`; }