@ultimabase/postgres 0.0.0-stage → 0.1.0

package/src/filter.ts

@@ -0,0 +1,306 @@
+// A normalized `where` as SQL (D-73): PostgreSQL's three-valued logic is the
+// one `memory()` mimics, and a relation condition is an `exists` subquery.
+import { sql } from 'kysely'
+import type { Condition, Filter, SchemaField } from 'ultimabase'
+import { compares, jsonPath } from './json-filter.ts'
+import type { Sql } from './logic.ts'
+import { all, any, pattern } from './logic.ts'
+import type { Catalog, Kind, Table } from './names.ts'
+
+export type { Sql } from './logic.ts'
+export { all, any } from './logic.ts'
+
+type Relation = Extract<SchemaField, { readonly kind: 'one' | 'many' }>
+
+/** The rows a relation reaches: `from`, then what ties them to the row. */
+export type Reach = { readonly from: Sql; readonly on: Sql }
+
+export const uuid: RegExp =
+	/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+/**
+ * A value as a parameter of its column's type. A date goes in UTC: `pg`
+ * writes it in local time to the minute, and a local offset of an old date
+ * has seconds, as Paris's +00:09:21 before 1911.
+ */
+export function value(kind: Kind, item: unknown): Sql {
+	if (kind === 'json' && item !== null) {
+		return sql`cast(${JSON.stringify(item)} as jsonb)`
+	}
+	if (kind.endsWith('[]')) {
+		return sql`cast(${item} as ${sql.raw(kind)})`
+	}
+	return item instanceof Date ? sql`${item.toISOString()}` : sql`${item}`
+}
+
+export function isFilters(
+	item: Condition | readonly Filter[],
+): item is readonly Filter[] {
+	return Array.isArray(item)
+}
+
+export class Filters {
+	readonly catalog: Catalog
+	/** The tables the compiled conditions reach, besides their own. */
+	readonly tables: Set<string> = new Set()
+	/** A write's change index → the CTE of its delete, for `removedBy`. */
+	readonly removed: ReadonlyMap<number, string>
+	private next = 0
+
+	constructor(
+		catalog: Catalog,
+		removed: ReadonlyMap<number, string> = new Map(),
+	) {
+		this.catalog = catalog
+		this.removed = removed
+	}
+
+	/** A table alias no other part of the statement uses. */
+	alias(): string {
+		this.next += 1
+		return `t${this.next}`
+	}
+
+	column(table: Table, alias: string, name: string): Sql {
+		return sql.id(alias, this.catalog.column(table, name))
+	}
+
+	where(model: string, alias: string, filter: Filter | undefined): Sql {
+		if (filter === undefined) return sql`true`
+		const table = this.catalog.table(model)
+		const parts: Sql[] = []
+		for (const [key, condition] of Object.entries(filter)) {
+			if (condition === undefined) continue
+			if (key === 'AND' || key === 'OR' || key === 'NOT') {
+				const list = (filter[key] ?? []).map((part) =>
+					this.where(model, alias, part),
+				)
+				if (key === 'AND') parts.push(all(list))
+				else if (key === 'OR') parts.push(any(list))
+				else parts.push(all(list.map((part) => sql`(not ${part})`)))
+			} else if (isFilters(condition)) {
+				throw new Error(`${model}.${key} takes a condition, not a list.`)
+			} else if (condition.search !== undefined) {
+				parts.push(
+					sql`${sql.id(alias, '_search')} @@ ${this.query(condition.search)}`,
+				)
+			} else {
+				const field = table.fields.get(key)
+				parts.push(
+					field === undefined || field.kind === 'scalar'
+						? this.scalar(table, alias, key, condition)
+						: this.relation(table, alias, field, condition),
+				)
+			}
+		}
+		return all(parts)
+	}
+
+	/** `text` as `websearch_to_tsquery` reads it, in the catalog's language (D-148). */
+	query(text: string): Sql {
+		return sql`websearch_to_tsquery(cast(${this.catalog.language} as regconfig), ${text})`
+	}
+
+	/** The rows of `field`'s target, aliased `to`, that `alias`'s row reaches. */
+	reach(table: Table, alias: string, field: Relation, to: string): Reach {
+		const target = this.catalog.table(field.target)
+		this.tables.add(target.name)
+		const from = sql`${sql.id(target.name)} as ${sql.id(to)}`
+		if (field.kind === 'one' && field.stored) {
+			return {
+				from,
+				on: sql`${sql.id(to, 'id')} = ${this.column(table, alias, field.name)}`,
+			}
+		}
+		if (field.kind === 'many' && field.join) {
+			// A view reads the join of its relation (D-151).
+			const name = field.from ?? field.name
+			const join = this.catalog.join(table.model.name, name)
+			this.tables.add(join.table)
+			const link = this.alias()
+			return {
+				from: sql`${from} join ${sql.id(join.table)} as ${sql.id(link)} on ${sql.id(link, join.other)} = ${sql.id(to, 'id')}`,
+				on: sql`${sql.id(link, join.self)} = ${sql.id(alias, 'id')}`,
+			}
+		}
+		return {
+			from,
+			on: sql`${this.column(target, to, field.inverse)} = ${sql.id(alias, 'id')}`,
+		}
+	}
+
+	private exists(
+		table: Table,
+		alias: string,
+		field: Relation,
+		filter: Filter,
+		test: (inner: Sql) => Sql = (inner) => inner,
+	): Sql {
+		const to = this.alias()
+		const { from, on } = this.reach(table, alias, field, to)
+		const inner = this.where(field.target, to, filter)
+		return sql`exists (select from ${from} where ${on} and ${test(inner)})`
+	}
+
+	private relation(
+		table: Table,
+		alias: string,
+		field: Relation,
+		condition: Condition,
+	): Sql {
+		const parts: Sql[] = []
+		const exists = (filter: Filter) => this.exists(table, alias, field, filter)
+		if (condition.is !== undefined) {
+			parts.push(
+				condition.is === null ? sql`(not ${exists({})})` : exists(condition.is),
+			)
+		}
+		if (condition.isNot !== undefined) {
+			parts.push(
+				condition.isNot === null
+					? exists({})
+					: sql`(not ${exists(condition.isNot)})`,
+			)
+		}
+		if (condition.some !== undefined) parts.push(exists(condition.some))
+		if (condition.every !== undefined) {
+			const failing = this.exists(
+				table,
+				alias,
+				field,
+				condition.every,
+				(inner) => sql`(${inner}) is false`,
+			)
+			parts.push(sql`(not ${failing})`)
+		}
+		if (condition.none !== undefined) {
+			parts.push(sql`(not ${exists(condition.none)})`)
+		}
+		if (condition.removedBy !== undefined) {
+			// The key names a row an earlier delete of the write removed.
+			const removed = this.removed.get(condition.removedBy)
+			if (removed === undefined) throw new Error('No such delete.')
+			const key = this.column(table, alias, field.name)
+			parts.push(sql`${key} in (select "id" from ${sql.id(removed)})`)
+		}
+		return all(parts)
+	}
+
+	private scalar(
+		table: Table,
+		alias: string,
+		name: string,
+		condition: Condition,
+	): Sql {
+		const column = this.column(table, alias, name)
+		return this.compare(column, this.catalog.kind(table, name), condition)
+	}
+
+	/** A value of `kind`, a column or an aggregate (D-149), meets `condition`. */
+	compare(column: Sql, kind: Kind, condition: Condition): Sql {
+		if (condition.path !== undefined) return jsonPath(column, condition)
+		// An id matches and compares as its string, as in `memory()`.
+		const cast = kind === 'id' ? sql`cast(${column} as text)` : column
+		// A string field's operators ignore case with `ilike` (D-140). Its
+		// `collate "C"` folds ASCII only: the database's locale folds the rest.
+		// `contains` and `endsWith` read the column so in both modes, as a
+		// trigram index does; a B-tree serves the rest (D-141).
+		const insensitive = condition.mode === 'insensitive'
+		const collated = sql`(${cast} collate "default")`
+		const text = insensitive ? collated : cast
+		const like = sql.raw(insensitive ? 'ilike' : 'like')
+		const parts: Sql[] = []
+		for (const [operator, operand] of Object.entries(condition)) {
+			if (operand === undefined || operator === 'mode') continue
+			switch (operator) {
+				case 'equals':
+				case 'not': {
+					const equal =
+						operand === null
+							? sql`${column} is null`
+							: insensitive
+								? sql`${text} ilike ${pattern(operand, '', '')}`
+								: this.equal(column, kind, operand)
+					parts.push(operator === 'equals' ? equal : sql`(not ${equal})`)
+					break
+				}
+				case 'in':
+				case 'notIn': {
+					const found = insensitive
+						? this.like(text, operand)
+						: this.member(column, kind, operand)
+					parts.push(operator === 'in' ? found : sql`(not ${found})`)
+					break
+				}
+				case 'has':
+					parts.push(sql`${column} @> ${value(kind, [operand])}`)
+					break
+				case 'hasSome':
+					parts.push(sql`${column} && ${value(kind, operand)}`)
+					break
+				case 'hasEvery':
+					parts.push(sql`${column} @> ${value(kind, operand)}`)
+					break
+				case 'isEmpty':
+					parts.push(
+						operand === true
+							? sql`cardinality(${column}) = 0`
+							: sql`cardinality(${column}) > 0`,
+					)
+					break
+				case 'contains':
+					parts.push(sql`${collated} ${like} ${pattern(operand, '%', '%')}`)
+					break
+				case 'startsWith':
+					parts.push(sql`${text} ${like} ${pattern(operand, '', '%')}`)
+					break
+				case 'endsWith':
+					parts.push(sql`${collated} ${like} ${pattern(operand, '%', '')}`)
+					break
+				default: {
+					const right = value(kind, operand)
+					const compare = compares[operator]
+					if (compare === undefined) {
+						throw new Error(`Unknown operator ${operator}.`)
+					}
+					parts.push(sql`${text} ${sql.raw(compare)} ${right}`)
+				}
+			}
+		}
+		return all(parts)
+	}
+
+	/** A string that is not an id equals no id, as in `memory()` (D-98). */
+	private equal(column: Sql, kind: Kind, operand: unknown): Sql {
+		if (kind === 'id' && !(typeof operand === 'string' && uuid.test(operand))) {
+			return sql`false`
+		}
+		return sql`${column} = ${value(kind, operand)}`
+	}
+
+	/** `in`: no item is false; an item no known value equals is dropped. */
+	private member(column: Sql, kind: Kind, operand: unknown): Sql {
+		const list: readonly unknown[] = Array.isArray(operand) ? operand : []
+		if (list.length === 0) return sql`false`
+		const items = list.filter(
+			(item) =>
+				item !== null &&
+				(kind !== 'id' || (typeof item === 'string' && uuid.test(item))),
+		)
+		if (items.length === 0) {
+			return sql`(case when ${column} is null then null else false end)`
+		}
+		const values = items.map((item) => value(kind, item))
+		return sql`${column} in (${sql.join(values)})`
+	}
+
+	/** `in` ignoring case: one `ilike` per item (D-140). */
+	private like(text: Sql, operand: unknown): Sql {
+		const list: readonly unknown[] = Array.isArray(operand) ? operand : []
+		if (list.length === 0) return sql`false`
+		const likes = list.map(
+			(item) => sql`${text} ilike ${pattern(item, '', '')}`,
+		)
+		return sql`(${sql.join(likes, sql` or `)})`
+	}
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// `@ultimabase/postgres` (D-47, D-98): the PostgreSQL adapter.
+import type { Postgres } from './adapter.ts'
+import { createAdapter } from './adapter.ts'
+
+export type { Postgres }
+
+/**
+ * Stores the app's models in the PostgreSQL database at `url`. An unset one,
+ * `process.env.DATABASE_URL` perhaps, is refused when the app starts. A query
+ * waits up to 10 seconds for one of its `connections`, 10 by default.
+ * `_search` reads its words in `searchLanguage`, a text search configuration
+ * of the server, `'simple'` by default.
+ */
+export function postgres(options: {
+	readonly url: string | undefined
+	readonly connections?: number
+	readonly searchLanguage?: string
+}): Postgres {
+	return createAdapter(options)
+}

package/src/json-filter.ts

@@ -0,0 +1,74 @@
+// A json value's path filter as SQL (D-149), as `memory()` runs it.
+import { sql } from 'kysely'
+import type { Condition } from 'ultimabase'
+import type { Sql } from './logic.ts'
+import { all, pattern } from './logic.ts'
+
+const jsonb = (item: unknown): Sql =>
+	sql`cast(${JSON.stringify(item)} as jsonb)`
+export const compares: { readonly [operator: string]: string } = {
+	lt: '<',
+	lte: '<=',
+	gt: '>',
+	gte: '>=',
+}
+
+/**
+ * A json value's path filter (D-149): `#>` reaches the value, which an
+ * operator tests when it has the operator's JSON type. A missing value stays
+ * unknown, as in `memory()`.
+ */
+export function jsonPath(column: Sql, condition: Condition): Sql {
+	const path = sql`cast(${condition.path ?? []} as text[])`
+	const at = sql`(${column} #> ${path})`
+	const text = sql`(${column} #>> ${path})`
+	const insensitive = condition.mode === 'insensitive'
+	const folded = insensitive ? sql`(${text} collate "default")` : text
+	const like = sql.raw(insensitive ? 'ilike' : 'like')
+	const typed = (type: string, test: Sql): Sql =>
+		sql`(case when ${at} is null then null when jsonb_typeof(${at}) = ${type} then coalesce(${test}, false) else false end)`
+	const parts: Sql[] = []
+	for (const [operator, operand] of Object.entries(condition)) {
+		if (operand === undefined || operator === 'path' || operator === 'mode') {
+			continue
+		}
+		const strings = (before: string, after: string): Sql =>
+			typed('string', sql`${folded} ${like} ${pattern(operand, before, after)}`)
+		switch (operator) {
+			case 'equals':
+				parts.push(sql`${at} = ${jsonb(operand)}`)
+				break
+			case 'not':
+				parts.push(sql`${at} <> ${jsonb(operand)}`)
+				break
+			case 'stringContains':
+				parts.push(strings('%', '%'))
+				break
+			case 'stringStartsWith':
+				parts.push(strings('', '%'))
+				break
+			case 'stringEndsWith':
+				parts.push(strings('%', ''))
+				break
+			case 'arrayContains':
+				parts.push(typed('array', sql`${at} @> ${jsonb(operand)}`))
+				break
+			case 'arrayStartsWith':
+				parts.push(typed('array', sql`${at} -> 0 = ${jsonb(operand)}`))
+				break
+			case 'arrayEndsWith':
+				parts.push(typed('array', sql`${at} -> -1 = ${jsonb(operand)}`))
+				break
+			default: {
+				const compare = sql.raw(compares[operator] ?? '=')
+				// Strings by code point, as everywhere (D-94).
+				parts.push(
+					typeof operand === 'number'
+						? typed('number', sql`${at} ${compare} ${jsonb(operand)}`)
+						: typed('string', sql`(${text} collate "C") ${compare} ${operand}`),
+				)
+			}
+		}
+	}
+	return all(parts)
+}

package/src/listen.ts

@@ -0,0 +1,97 @@
+// The connection that hears the feed's notifications (D-154): it gives the
+// feed what a tick brought, and once a lost connection is back, `missed`.
+import { createHash } from 'node:crypto'
+import type { ClientConfig } from 'pg'
+import { Client } from 'pg'
+import type { Changed, Feed, Logger } from 'ultimabase'
+import { changedOf } from './notify.ts'
+
+/** The feed's channel of `schema`, within the 63 bytes of a name. */
+export function channelOf(schema: string): string {
+	const channel = `ultimabase:${schema}`
+	if (Buffer.byteLength(channel) <= 63) return channel
+	const hash = createHash('sha256').update(schema).digest('hex')
+	return `ultimabase:${hash.slice(0, 52)}`
+}
+
+export type Listener = { readonly stop: () => Promise<void> }
+
+/** Milliseconds between two attempts to listen again, doubling. */
+const first = 100
+const most = 5000
+
+/** Listens on `channel` until stopped; a first connection that fails throws. */
+export async function listening(
+	config: ClientConfig,
+	channel: string,
+	feed: Feed,
+	logger: Logger,
+): Promise<Listener> {
+	let client: Client | undefined
+	let stopped = false
+	let timer: NodeJS.Timeout | undefined
+	let heard: Changed[] = []
+	const flush = (): void => {
+		const changes = heard
+		heard = []
+		if (changes.length > 0) feed.changed(changes)
+	}
+	const connect = async (): Promise<Client> => {
+		const own = new Client({ ...config, application_name: 'ultimabase-feed' })
+		own.on('notification', ({ channel: to, payload }) => {
+			const change = to === channel ? changedOf(payload) : undefined
+			if (change === undefined) return
+			if (heard.length === 0) setImmediate(flush)
+			heard.push(change)
+		})
+		own.on('error', () => lost(own))
+		own.on('end', () => lost(own))
+		try {
+			await own.connect()
+			await own.query(`listen "${channel.replaceAll('"', '""')}"`)
+		} catch (error) {
+			own.removeAllListeners('end')
+			await own.end().catch(() => undefined)
+			throw error
+		}
+		return own
+	}
+	const retry = (wait: number): void => {
+		timer = setTimeout(() => void again(wait), wait)
+	}
+	const again = async (wait: number): Promise<void> => {
+		let own: Client
+		try {
+			own = await connect()
+		} catch {
+			retry(Math.min(wait * 2, most))
+			return
+		}
+		if (stopped) {
+			await own.end().catch(() => undefined)
+			return
+		}
+		client = own
+		logger.info('The change feed listens again.')
+		// What was committed while no one listened is unknown.
+		feed.missed()
+	}
+	const lost = (own: Client): void => {
+		if (stopped || client !== own) return
+		client = undefined
+		own.removeAllListeners('end')
+		own.end().catch(() => undefined)
+		logger.warn('The change feed lost its connection: it listens again soon.')
+		retry(first)
+	}
+	client = await connect()
+	return {
+		stop: async () => {
+			stopped = true
+			clearTimeout(timer)
+			const own = client
+			client = undefined
+			await own?.end()
+		},
+	}
+}

package/src/logic.ts

@@ -0,0 +1,28 @@
+// The SQL a filter is made of (D-73): conditions joined with PostgreSQL's
+// three-valued logic, and a `like` pattern that matches its text only.
+import type { RawBuilder } from 'kysely'
+import { sql } from 'kysely'
+
+export type Sql = RawBuilder<unknown>
+
+export function all(parts: readonly Sql[]): Sql {
+	if (parts.length === 0) return sql`true`
+	return parts.length === 1
+		? (parts[0] ?? sql`true`)
+		: sql`(${sql.join(parts, sql` and `)})`
+}
+
+export function any(parts: readonly Sql[]): Sql {
+	if (parts.length === 0) return sql`false`
+	return sql`(${sql.join(parts, sql` or `)})`
+}
+
+/** `%`, `_` and `\` are characters, not patterns (D-94). */
+export function pattern(
+	operand: unknown,
+	before: string,
+	after: string,
+): string {
+	const text = typeof operand === 'string' ? operand : ''
+	return `${before}${text.replaceAll(/[\\%_]/g, '\\$&')}${after}`
+}