pipework 0.280.0 → 0.282.0

package/src/data/db/rows.ts

@@ -0,0 +1,120 @@
+import { sql } from './sql.js'
+import type { SQL } from './types.js'
+import { Subquery } from '../query/subquery.js'
+import { SelectionProxyHandler } from '../query/selection-proxy.js'
+
+const CAST = /^[a-z_][a-z0-9_]*( [a-z_][a-z0-9_]*)*(\([0-9, ]+\))?$/i
+const COLUMN_NAME = /^[a-z_][a-z0-9_]*$/i
+
+type TextLike = 'text' | 'uuid' | 'varchar' | 'char' | 'citext'
+type NumberLike = 'int' | 'integer' | 'int4' | 'smallint' | 'int2' | 'real' | 'float4' | 'double precision' | 'float8'
+type DateLike = 'timestamptz' | 'timestamp' | 'date'
+
+/** The JS type a column of this SQL type reads as: text and uuid as string, ints and floats as number, bigint and numeric as string (as postgres.js returns them), dates as Date, boolean as boolean; any other type name as unknown. A cell may be null. */
+export type RowsColumnValue<T extends string> =
+  T extends TextLike ? string
+  : T extends NumberLike ? number
+  : T extends 'bigint' | 'int8' | 'numeric' ? string
+  : T extends 'boolean' | 'bool' ? boolean
+  : T extends DateLike ? Date | string
+  : unknown
+
+/** Column name to SQL type name: `{ g: 'text', id: 'int' }`. */
+export type RowsColumns = Readonly<Record<string, string>>
+
+/** One array per column, all the same length: `{ g: ['a', 'b'], id: [1, 2] }` is two rows. */
+export type RowsData<TColumns extends RowsColumns> = { readonly [K in keyof TColumns]: ReadonlyArray<RowsColumnValue<TColumns[K]> | null> }
+
+type RowsFields<TColumns extends RowsColumns> = {
+  [K in keyof TColumns]: SQL<RowsColumnValue<TColumns[K]> | null>
+}
+
+/** A rowset usable in `.from()` and joins; its columns are properties of it. */
+export type RowsSource<TAlias extends string, TColumns extends RowsColumns> =
+  & Subquery<TAlias, RowsFields<TColumns>>
+  & RowsFields<TColumns>
+  & {
+    /** The same rowset under another alias, to use it twice in a query. */
+    as<TNew extends string>(alias: TNew): RowsSource<TNew, TColumns>
+  }
+
+function fail(problem: string, fix: string): never {
+  throw new Error(`[pipework] rows: ${problem}\n\n  Fix: ${fix}\n`)
+}
+
+function quote(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`
+}
+
+// One column as a Postgres array literal, sent as a single text parameter and cast to `T[]`. postgres.js
+// serialises a JS array only for the few element types it knows (text, int, uuid ...), so a `timestamptz[]`
+// parameter would throw; a literal string is parsed by Postgres for any type.
+function arrayLiteral(cells: readonly unknown[]): string {
+  const item = (v: unknown): string => {
+    if (v === null || v === undefined) return 'NULL'
+    const text = v instanceof Date ? v.toISOString()
+      : typeof v === 'string' ? v
+      : typeof v === 'number' || typeof v === 'bigint' || typeof v === 'boolean' ? String(v)
+      : JSON.stringify(v)
+    return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+  }
+  return `{${cells.map(item).join(',')}}`
+}
+
+/**
+ * A typed rowset from parallel array parameters, as a source for `.from()` and joins:
+ * `rows({ g: 'text', id: 'int' }, { g: ['a', 'b'], id: [1, 2] })` renders
+ * `(select * from unnest($1::text[], $2::int[]) as "rows"("g", "id")) "rows"`, one parameter per column
+ * whatever the row count, so a 5,000-row key list is two parameters. Each column is read by name, like a
+ * table's: `rs.g`. Nulls in an array are NULL cells. Zero rows is valid and returns no rows. Each column
+ * is sent as one array-literal text parameter, so any element type Postgres can parse works: Dates as ISO text,
+ * objects as JSON (for jsonb). Column names are used as written (not snake-cased); the default alias is `rows`, change it with `.as()`.
+ * Throws when the columns are empty, a type is not a plain type name, the data and columns name different keys,
+ * or the arrays differ in length.
+ */
+export function rows<const TColumns extends RowsColumns>(columns: TColumns, data: RowsData<TColumns>): RowsSource<'rows', TColumns> {
+  const names = Object.keys(columns)
+  if (names.length === 0) fail('the column spec is empty.', "declare at least one column, e.g. { id: 'uuid' }.")
+  for (const name of names) {
+    if (!COLUMN_NAME.test(name) || name === 'as' || name === '_') {
+      fail(`column name "${name}" is not usable.`, 'use letters, digits and underscores, not starting with a digit, and not "as" or "_".')
+    }
+    const type = columns[name]
+    if (typeof type !== 'string' || type === '') fail(`column "${name}" has no type.`, `give it a type name: { ${name}: 'text' }.`)
+    if (!CAST.test(type)) fail(`column "${name}" has type "${type}", which is not a plain type name.`, "pass a type name such as 'uuid' or 'int'.")
+  }
+  const given = Object.keys(data)
+  const unknownKeys = given.filter(k => !names.includes(k))
+  if (unknownKeys.length > 0) fail(`values for ${unknownKeys.map(k => `"${k}"`).join(', ')} have no column in the spec.`, 'add the column to the spec or drop its values.')
+  const missing = names.filter(k => !given.includes(k))
+  if (missing.length > 0) fail(`the spec names ${missing.map(k => `"${k}"`).join(', ')} but the data has no values for it.`, 'pass an array for every column, [] for none.')
+  const lengths = new Set<number>()
+  for (const name of names) {
+    const col = (data as Record<string, unknown>)[name]
+    if (!Array.isArray(col)) fail(`values for "${name}" are not an array.`, 'pass one array per column.')
+    lengths.add(col.length)
+  }
+  if (lengths.size > 1) {
+    const detail = names.map(n => `${n}: ${((data as Record<string, readonly unknown[]>)[n]!).length}`).join(', ')
+    fail(`the column arrays differ in length (${detail}).`, 'pass arrays of one length; row i is the i-th element of each.')
+  }
+
+  const build = (alias: string): RowsSource<string, TColumns> => {
+    const arrays = names.map(n => {
+      return sql`${sql.param(arrayLiteral((data as Record<string, readonly unknown[]>)[n]!))}::${sql.raw(columns[n]!)}[]`
+    })
+    const nameList = sql.raw(names.map(quote).join(', '))
+    const inner = sql`select * from unnest(${sql.join(arrays, sql`, `)}) as ${sql.raw(quote(alias))}(${nameList})`
+    const fields: Record<string, SQL> = {}
+    for (const n of names) fields[n] = sql.raw(`${quote(alias)}.${quote(n)}`)
+    const subquery = new Subquery(inner, fields, alias)
+    const selection = new SelectionProxyHandler<Subquery>({ alias, sqlAliasedBehavior: 'alias', sqlBehavior: 'sql' })
+    return new Proxy(subquery, {
+      get(target, prop) {
+        if (prop === 'as') return (next: string) => build(next)
+        return selection.get(target, prop)
+      },
+    }) as unknown as RowsSource<string, TColumns>
+  }
+  return build('rows') as RowsSource<'rows', TColumns>
+}

package/src/index.ts

@@ -9,6 +9,7 @@ export type { DB, SQL, Table, Column, TransactionConfig } from './data/db/namesp
 export type { WindowSpec, WindowFrame, FrameBound } from './data/db/expressions.js'
 export type { Aggregate, EmptyableAggregate, AggregateOptions, JsonOf } from './data/db/aggregates.js'
 export type { ValueColumnDef } from './data/db/values.js'
+export type { RowsColumns, RowsData, RowsSource, RowsColumnValue } from './data/db/rows.js'
 export type { ArraySource, ElementOf, JsonbElements } from './data/db/array-elements.js'
 export type { FunctionSpec, FunctionSource, FunctionSourceFields } from './data/db/function-source.js'
 export type { SerializableOptions } from './data/db/serializable.js'
@@ -83,7 +84,7 @@ export type { AuditChainHead, AuditChainBreak, AuditChainBreakReason, AuditVerif
 export { jobs } from './async/jobs/namespace.js'
 export { JobAbortedError, JobLaterError, JobPermanentError } from './async/jobs/index.js'
 export { serializeError } from './async/jobs/serialize-error.js'
-export type { ExecuteJobOptions, Queue, QueueConfig, EnqueueOptions, ClaimedJob, JobClaim, JobClaimReason, ReapedJob, FailedAttempt, QueueTotals, QueueTypeTotals, JobResult, BackoffConfig,
+export type { ExecuteJobOptions, Queue, QueueConfig, EnqueueOptions, ClaimedJob, JobClaim, JobClaimReason, ReapedJob, FailedAttempt, FailOptions, QueueTotals, QueueTypeTotals, JobResult, BackoffConfig,
   WaitOptions, WaitResult, ListenClient, ListenHandle, CronSchedule, ScheduleSpec,
   ScheduleInfo, SchedulerOptions } from './async/jobs/index.js'