@avelonjs/postgres 0.1.0

package/src/normalize.ts

@@ -0,0 +1,50 @@
+import type { Predicate, QueryIR } from '@avelonjs/core'
+
+/** Normalizes a predicate using the contract's empty-list and constant identities. */
+export function normalizePredicate(predicate: Predicate): Predicate {
+  switch (predicate.kind) {
+    case 'const':
+    case 'compare':
+    case 'null':
+      return predicate
+    case 'in':
+      return predicate.values.length === 0 ? { kind: 'const', value: predicate.negated } : predicate
+    case 'not': {
+      const child = normalizePredicate(predicate.predicate)
+      if (child.kind === 'const') return { kind: 'const', value: !child.value }
+      if (child.kind === 'not') return normalizePredicate(child.predicate)
+      return { kind: 'not', predicate: child }
+    }
+    case 'and':
+      return normalizeGroup('and', predicate.predicates)
+    case 'or':
+      return normalizeGroup('or', predicate.predicates)
+  }
+}
+
+function normalizeGroup(kind: 'and' | 'or', input: readonly Predicate[]): Predicate {
+  const identity = kind === 'and'
+  const predicates: Predicate[] = []
+
+  for (const raw of input) {
+    const predicate = normalizePredicate(raw)
+    if (predicate.kind === 'const') {
+      if (predicate.value !== identity) return predicate
+      continue
+    }
+    if (predicate.kind === kind) predicates.push(...predicate.predicates)
+    else predicates.push(predicate)
+  }
+
+  if (predicates.length === 0) return { kind: 'const', value: identity }
+  if (predicates.length === 1) return predicates[0] as Predicate
+  return { kind, predicates }
+}
+
+/** Combines `where` and optional `ward` with AND, then normalizes. */
+export function combinedPredicate(ir: Pick<QueryIR, 'where' | 'ward'>): Predicate {
+  return normalizePredicate({
+    kind: 'and',
+    predicates: ir.ward === undefined ? ir.where : [...ir.where, ir.ward],
+  })
+}

package/src/schema.ts

@@ -0,0 +1,123 @@
+import type { SQL } from 'bun'
+import { Invalid, type QueryIR, type RelationLoad } from '@avelonjs/core'
+import { mapPostgresError } from './errors'
+
+/** Cached public-schema column sets keyed by table name. */
+export type SchemaCache = Map<string, Set<string>>
+
+/** Loads every public base table and its columns. */
+export async function loadSchemaCache(sql: SQL): Promise<SchemaCache> {
+  try {
+    const rows = (await sql.unsafe(`
+      SELECT table_name, column_name
+      FROM information_schema.columns
+      WHERE table_schema = 'public'
+      ORDER BY table_name, ordinal_position
+    `)) as Array<{ table_name: string; column_name: string }>
+
+    const cache: SchemaCache = new Map()
+    for (const row of rows) {
+      const columns = cache.get(row.table_name) ?? new Set<string>()
+      columns.add(row.column_name)
+      cache.set(row.table_name, columns)
+    }
+    return cache
+  } catch (error) {
+    mapPostgresError(error, 'schema.load')
+  }
+}
+
+function invalid(message: string, field: string, detail: string): never {
+  throw new Invalid(message, { metadata: { fields: { [field]: [detail] } } })
+}
+
+function assertTable(cache: SchemaCache, table: string, field: string): Set<string> {
+  const columns = cache.get(table)
+  if (columns === undefined) {
+    invalid(`Unknown table ${table}.`, field, 'Unknown identifier')
+  }
+  return columns
+}
+
+function assertColumn(columns: Set<string>, table: string, column: string, field: string): void {
+  if (!columns.has(column)) {
+    invalid(`Unknown column ${column} on ${table}.`, field, `Unknown identifier: ${column}`)
+  }
+}
+
+function assertProjection(
+  columns: Set<string>,
+  table: string,
+  projection: string[] | '*',
+  field: string,
+): void {
+  if (projection === '*') return
+  for (const column of projection) assertColumn(columns, table, column, field)
+}
+
+function assertRelation(cache: SchemaCache, parentTable: string, relation: RelationLoad): void {
+  const parentColumns = assertTable(cache, parentTable, 'relations')
+  assertColumn(parentColumns, parentTable, relation.localKey, 'relations')
+  const relatedColumns = assertTable(cache, relation.table, 'relations')
+  assertColumn(relatedColumns, relation.table, relation.foreignKey, 'relations')
+  assertProjection(relatedColumns, relation.table, relation.select, 'relations')
+  for (const term of relation.order) {
+    assertColumn(relatedColumns, relation.table, term.column, 'relations')
+  }
+  for (const nested of relation.relations) assertRelation(cache, relation.table, nested)
+}
+
+/**
+ * Rejects unknown tables and columns before a statement is sent.
+ *
+ * Needed so empty parent row sets cannot skip a relation table that does not exist.
+ */
+export function assertQueryAgainstSchema(cache: SchemaCache, query: QueryIR): void {
+  const columns = assertTable(cache, query.table, 'table')
+  assertProjection(columns, query.table, query.select, 'select')
+  if (query.returning !== undefined) {
+    assertProjection(columns, query.table, query.returning, 'returning')
+  }
+  for (const term of query.order) assertColumn(columns, query.table, term.column, 'order')
+
+  const checkPredicateColumns = (predicate: QueryIR['where'][number]): void => {
+    switch (predicate.kind) {
+      case 'compare':
+      case 'null':
+      case 'in':
+        assertColumn(columns, query.table, predicate.column, 'where')
+        return
+      case 'and':
+      case 'or':
+        predicate.predicates.forEach(checkPredicateColumns)
+        return
+      case 'not':
+        checkPredicateColumns(predicate.predicate)
+        return
+      case 'const':
+        return
+    }
+  }
+  query.where.forEach(checkPredicateColumns)
+  if (query.ward) checkPredicateColumns(query.ward)
+
+  if (query.values !== undefined) {
+    const rows = Array.isArray(query.values) ? query.values : [query.values]
+    for (const row of rows) {
+      for (const column of Object.keys(row)) assertColumn(columns, query.table, column, 'values')
+    }
+  }
+
+  if (query.conflict !== undefined) {
+    for (const column of query.conflict.columns) {
+      assertColumn(columns, query.table, column, 'conflict')
+    }
+    if (query.conflict.update !== '*') {
+      for (const column of query.conflict.update) {
+        assertColumn(columns, query.table, column, 'conflict')
+      }
+    }
+  }
+
+  for (const relation of query.relations) assertRelation(cache, query.table, relation)
+}

package/src/validate.ts

@@ -0,0 +1,236 @@
+import { Invalid, type OrderTerm, type Predicate, type QueryIR, type RelationLoad } from '@avelonjs/core'
+
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/
+const COMPARE_OPS = new Set(['=', '!=', '<', '<=', '>', '>=', 'like', 'ilike'] as const)
+const MODES = new Set(['select', 'count', 'insert', 'update', 'delete', 'upsert'] as const)
+const RELATION_KINDS = new Set(['belongsTo', 'hasOne', 'hasMany'] as const)
+
+function invalid(message: string, field: string, detail: string): never {
+  throw new Invalid(message, { metadata: { fields: { [field]: [detail] } } })
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Asserts a value is a simple SQL identifier safe to quote. */
+export function assertIdentifier(value: unknown, path: string): asserts value is string {
+  if (typeof value !== 'string' || !IDENTIFIER.test(value)) {
+    invalid(`${path} must be a simple SQL identifier.`, path, 'Expected a simple identifier')
+  }
+}
+
+function assertNonNegativeInteger(value: unknown, path: string): asserts value is number {
+  if (!Number.isInteger(value) || (value as number) < 0) {
+    invalid(`${path} must be a non-negative integer.`, path, 'Expected a non-negative integer')
+  }
+}
+
+function validateProjection(value: unknown, path: string): asserts value is string[] | '*' {
+  if (value === '*') return
+  // Empty arrays are valid for write/count IR where `select` is unused; select mode still projects
+  // through `*` or an explicit column list supplied by the caller.
+  if (!Array.isArray(value)) {
+    invalid(`${path} must be '*' or a string array.`, path, 'Invalid projection')
+  }
+  for (const [index, column] of value.entries()) assertIdentifier(column, `${path}[${index}]`)
+}
+
+function validateOrder(value: unknown, path: string): asserts value is OrderTerm[] {
+  if (!Array.isArray(value)) invalid(`${path} must be an array.`, path, 'Expected an array')
+  for (const [index, term] of value.entries()) {
+    if (!isRecord(term)) invalid(`${path}[${index}] must be an object.`, path, 'Expected an object')
+    assertIdentifier(term.column, `${path}[${index}].column`)
+    if (term.direction !== 'asc' && term.direction !== 'desc') {
+      invalid(`${path}[${index}].direction is invalid.`, path, 'Expected asc or desc')
+    }
+    if (term.nulls !== undefined && term.nulls !== 'first' && term.nulls !== 'last') {
+      invalid(`${path}[${index}].nulls is invalid.`, path, 'Expected first or last')
+    }
+  }
+}
+
+function validatePredicate(value: unknown, path: string): asserts value is Predicate {
+  if (!isRecord(value) || typeof value.kind !== 'string') {
+    invalid(`${path} must be a predicate.`, path, 'Expected a predicate')
+  }
+
+  switch (value.kind) {
+    case 'const':
+      if (typeof value.value !== 'boolean') {
+        invalid(`${path}.value must be boolean.`, path, 'Expected boolean')
+      }
+      return
+    case 'compare':
+      assertIdentifier(value.column, `${path}.column`)
+      if (!COMPARE_OPS.has(value.op as (typeof COMPARE_OPS extends Set<infer T> ? T : never))) {
+        invalid(`${path}.op is invalid.`, path, 'Unknown comparison operator')
+      }
+      return
+    case 'null':
+      assertIdentifier(value.column, `${path}.column`)
+      if (typeof value.negated !== 'boolean') {
+        invalid(`${path}.negated must be boolean.`, path, 'Expected boolean')
+      }
+      return
+    case 'in':
+      assertIdentifier(value.column, `${path}.column`)
+      if (!Array.isArray(value.values)) {
+        invalid(`${path}.values must be an array.`, path, 'Expected an array')
+      }
+      if (typeof value.negated !== 'boolean') {
+        invalid(`${path}.negated must be boolean.`, path, 'Expected boolean')
+      }
+      return
+    case 'and':
+    case 'or':
+      if (!Array.isArray(value.predicates)) {
+        invalid(`${path}.predicates must be an array.`, path, 'Expected an array')
+      }
+      for (const [index, predicate] of value.predicates.entries()) {
+        validatePredicate(predicate, `${path}.predicates[${index}]`)
+      }
+      return
+    case 'not':
+      validatePredicate(value.predicate, `${path}.predicate`)
+      return
+    default:
+      invalid(`${path}.kind is invalid.`, path, 'Unknown predicate kind')
+  }
+}
+
+function validateRelation(value: unknown, path: string, depth: number, maxDepth: number): void {
+  if (!isRecord(value)) invalid(`${path} must be an object.`, path, 'Expected an object')
+  if (depth > maxDepth) {
+    invalid(
+      `${path} exceeds maxRelationDepth ${maxDepth}.`,
+      'relations',
+      `Maximum relation depth is ${maxDepth}`,
+    )
+  }
+  assertIdentifier(value.relation, `${path}.relation`)
+  if (!RELATION_KINDS.has(value.kind as RelationLoad['kind'])) {
+    invalid(`${path}.kind is invalid.`, path, 'Unknown relation kind')
+  }
+  assertIdentifier(value.table, `${path}.table`)
+  assertIdentifier(value.localKey, `${path}.localKey`)
+  assertIdentifier(value.foreignKey, `${path}.foreignKey`)
+  validateProjection(value.select, `${path}.select`)
+  if (value.where !== null) validatePredicate(value.where, `${path}.where`)
+  validateOrder(value.order, `${path}.order`)
+  if (value.limit !== undefined) assertNonNegativeInteger(value.limit, `${path}.limit`)
+  if (!Array.isArray(value.relations)) {
+    invalid(`${path}.relations must be an array.`, path, 'Expected an array')
+  }
+
+  const names = new Set<string>()
+  for (const [index, relation] of value.relations.entries()) {
+    validateRelation(relation, `${path}.relations[${index}]`, depth + 1, maxDepth)
+    const name = (relation as RelationLoad).relation
+    if (names.has(name)) {
+      invalid(`${path}.relations contains duplicate relation '${name}'.`, path, 'Duplicate relation')
+    }
+    names.add(name)
+  }
+}
+
+function validateValues(ir: QueryIR): void {
+  const rows =
+    ir.values === undefined ? undefined : Array.isArray(ir.values) ? ir.values : [ir.values]
+
+  if (ir.mode === 'insert' || ir.mode === 'upsert') {
+    if (rows === undefined || rows.length === 0) {
+      invalid(`${ir.mode} requires non-empty values.`, 'values', 'Expected one or more rows')
+    }
+  } else if (ir.mode === 'update') {
+    if (rows === undefined || rows.length !== 1 || Array.isArray(ir.values)) {
+      invalid('update requires one values object.', 'values', 'Expected one row')
+    }
+  } else if (ir.values !== undefined) {
+    invalid(`${ir.mode} does not accept values.`, 'values', 'Unexpected values')
+  }
+
+  if (rows === undefined) return
+  const firstColumns = Object.keys(rows[0] ?? {})
+  if (firstColumns.length === 0) {
+    invalid(`${ir.mode} values must not be empty.`, 'values', 'Expected non-empty rows')
+  }
+  for (const [index, row] of rows.entries()) {
+    if (!isRecord(row)) invalid(`values[${index}] must be an object.`, 'values', 'Expected an object')
+    const columns = Object.keys(row)
+    if (
+      columns.length !== firstColumns.length ||
+      columns.some((column) => !firstColumns.includes(column))
+    ) {
+      invalid('all values rows must contain the same columns.', 'values', 'Mismatched columns')
+    }
+    for (const column of columns) assertIdentifier(column, `values[${index}] column`)
+  }
+}
+
+/** Validates a query IR against portable contract rules before compilation. */
+export function validateQueryIR(ir: QueryIR, maxRelationDepth: number): void {
+  if (!isRecord(ir)) invalid('query must be an object.', 'query', 'Expected an object')
+  assertIdentifier(ir.table, 'table')
+  if (!MODES.has(ir.mode)) invalid('mode is invalid.', 'mode', 'Unknown query mode')
+  validateProjection(ir.select, 'select')
+  if (!Array.isArray(ir.where)) invalid('where must be an array.', 'where', 'Expected an array')
+  for (const [index, predicate] of ir.where.entries()) {
+    validatePredicate(predicate, `where[${index}]`)
+  }
+  if (ir.ward !== undefined) validatePredicate(ir.ward, 'ward')
+  validateOrder(ir.order, 'order')
+  if (ir.limit !== undefined) assertNonNegativeInteger(ir.limit, 'limit')
+  if (ir.offset !== undefined) assertNonNegativeInteger(ir.offset, 'offset')
+  if (!Array.isArray(ir.relations)) {
+    invalid('relations must be an array.', 'relations', 'Expected an array')
+  }
+
+  const relationNames = new Set<string>()
+  for (const [index, relation] of ir.relations.entries()) {
+    validateRelation(relation, `relations[${index}]`, 1, maxRelationDepth)
+    if (relationNames.has(relation.relation)) {
+      invalid(
+        `relations contains duplicate relation '${relation.relation}'.`,
+        'relations',
+        'Duplicate relation',
+      )
+    }
+    relationNames.add(relation.relation)
+  }
+
+  if (ir.relations.length > 0 && ir.mode !== 'select') {
+    invalid('relations are only valid for select.', 'relations', 'Select-only field')
+  }
+
+  if (ir.mode === 'count') {
+    if (ir.select === '*' || (Array.isArray(ir.select) && ir.select.length > 0)) {
+      invalid('count does not accept a projection.', 'mode', 'Use an empty select')
+    }
+    if (ir.order.length > 0) invalid('count does not accept an order.', 'mode', 'Remove order')
+    if (ir.limit !== undefined) invalid('count does not accept a limit.', 'mode', 'Remove limit')
+    if (ir.offset !== undefined) invalid('count does not accept an offset.', 'mode', 'Remove offset')
+    if (ir.returning !== undefined) {
+      invalid('count does not accept returning.', 'mode', 'Remove returning')
+    }
+  }
+
+  validateValues(ir)
+
+  if (ir.returning !== undefined) validateProjection(ir.returning, 'returning')
+  if (ir.mode === 'upsert') {
+    if (!isRecord(ir.conflict)) invalid('upsert requires conflict.', 'conflict', 'Required for upsert')
+    if (!Array.isArray(ir.conflict.columns) || ir.conflict.columns.length === 0) {
+      invalid('conflict.columns must be non-empty.', 'conflict', 'Expected one or more columns')
+    }
+    for (const column of ir.conflict.columns) assertIdentifier(column, 'conflict.columns entry')
+    if (ir.conflict.update !== '*') {
+      if (!Array.isArray(ir.conflict.update) || ir.conflict.update.length === 0) {
+        invalid("conflict.update must be '*' or a non-empty array.", 'conflict', 'Invalid update list')
+      }
+      for (const column of ir.conflict.update) assertIdentifier(column, 'conflict.update entry')
+    }
+  } else if (ir.conflict !== undefined) {
+    invalid('conflict is only valid for upsert.', 'conflict', 'Unexpected conflict')
+  }
+}