ultimabase 0.0.0-stage → 0.1.0

package/src/query-group.ts

@@ -0,0 +1,137 @@
+// `groupBy`'s arguments and result (D-146): `having` (D-149) and `orderBy`
+// name the fields of `by` or an aggregate, and each group has the keys the
+// arguments ask for.
+import type {
+	Aggregated,
+	AggregateArgs,
+	Aggregates,
+	DecimalKeys,
+	IsOrdered,
+	KeysWith,
+	Summed,
+	ValueOf,
+} from './query-aggregate.ts'
+import type { Exact } from './exact.ts'
+import type { ScalarFilter } from './query-filter.ts'
+import type { RecordOf, StoredRecord } from './record.ts'
+
+type Direction = 'asc' | 'desc'
+type Sorted<K extends PropertyKey> = {
+	readonly [P in K]?: Direction | undefined
+}
+/** A value's sort: an optional one puts its `null`s first or last (D-149). */
+export type SortOrder<V> = null extends V
+	? | Direction
+		| {
+				readonly sort: Direction
+				readonly nulls?: 'first' | 'last' | undefined
+		  }
+	: Direction
+/** The `one` relations the row stores (D-37). */
+type StoredOnes<F, N> = Exclude<
+	keyof StoredRecord<F, N & string>,
+	keyof RecordOf<F>
+>
+/** What a group takes: a scalar an aggregate takes, or a stored relation. */
+export type GroupField<F, N> = Aggregated<F> | StoredOnes<F, N>
+
+type GroupOrderBy<F, N, B extends PropertyKey> = {
+	readonly [K in B]?: SortOrder<GroupValue<F, N, K>> | undefined
+} & {
+	readonly _count?:
+		| Direction
+		| ({ readonly _all?: Direction | undefined } & Sorted<Aggregated<F>>)
+		| undefined
+	readonly _sum?: Sorted<Summed<F>> | undefined
+	readonly _avg?: Sorted<Summed<F>> | undefined
+	readonly _min?: Sorted<KeysWith<F, number | string | Date>> | undefined
+	readonly _max?: Sorted<KeysWith<F, number | string | Date>> | undefined
+}
+
+/** A value's filter: an id's has no `mode`, a decimal's or a day's compares. */
+type ValueFilter<F, K> = K extends 'id'
+	? Omit<ScalarFilter<string>, 'mode'>
+	: ScalarFilter<ValueOf<F, K>, K extends keyof F ? IsOrdered<F[K]> : false>
+type Filtered<V, Ordered = false> = V | ScalarFilter<V, Ordered> | undefined
+
+/** Field `K`'s aggregates, each filtered as the value it gives (D-149). */
+type AggregateFilters<F, K> = {
+	readonly _count?: Filtered<number>
+} & (K extends Summed<F>
+	? {
+			readonly _sum?: K extends DecimalKeys<F>
+				? Filtered<string, true>
+				: Filtered<number>
+			readonly _avg?: Filtered<number>
+		}
+	: unknown) &
+	(K extends KeysWith<F, number | string | Date>
+		? {
+				readonly _min?: ValueOf<F, K> | ValueFilter<F, K> | undefined
+				readonly _max?: ValueOf<F, K> | ValueFilter<F, K> | undefined
+			}
+		: unknown)
+
+/** The groups kept: a field of `by` by its value, any field by its aggregates. */
+type Having<F, N, B extends PropertyKey> = {
+	readonly [K in Aggregated<F>]?:
+		| (K extends B
+				? GroupValue<F, N, K> | (ValueFilter<F, K> & AggregateFilters<F, K>)
+				: AggregateFilters<F, K>)
+		| undefined
+} & {
+	readonly AND?: Having<F, N, B> | readonly Having<F, N, B>[] | undefined
+	readonly OR?: readonly Having<F, N, B>[] | undefined
+	readonly NOT?: Having<F, N, B> | readonly Having<F, N, B>[] | undefined
+}
+
+export type GroupByArgs<
+	F,
+	N,
+	B extends GroupField<F, N> = GroupField<F, N>,
+> = AggregateArgs<F> & {
+	readonly by: readonly [B, ...B[]]
+	readonly having?: Having<F, N, B> | undefined
+	readonly orderBy?:
+		GroupOrderBy<F, N, B> | readonly GroupOrderBy<F, N, B>[] | undefined
+	readonly skip?: number | undefined
+	readonly take?: number | undefined
+}
+
+/**
+ * Arguments `A`, checked against the fields of their `by`: no unknown key,
+ * and a `having` that fits them, which `Exact` does not check as it skips
+ * values: a value for a field outside `by` would pass.
+ */
+export type GroupChecked<
+	F,
+	N,
+	A extends { readonly by: readonly unknown[] },
+> = Exact<A, GroupByArgs<F, N, A['by'][number] & GroupField<F, N>>> &
+	(A extends { readonly having: infer H }
+		? [H] extends [Having<F, N, A['by'][number] & PropertyKey> | undefined]
+			? unknown
+			: {
+					readonly having: {
+						readonly error: 'a field outside by takes aggregates only'
+					}
+				}
+		: unknown)
+
+/** A relation's target id, `null` when unset or unreadable (D-86). */
+type GroupValue<F, N, K> =
+	K extends StoredOnes<F, N>
+		? { readonly id: string } | null
+		: K extends keyof StoredRecord<F, N & string>
+			? StoredRecord<F, N & string>[K]
+			: never
+
+/** What `groupBy` returns for the arguments `A`. */
+export type Groups<F, N, A> = A extends {
+	readonly by: readonly (infer B)[]
+}
+	? ({ readonly [K in B & PropertyKey]: GroupValue<F, N, K> } & Aggregates<
+			F,
+			A
+		>)[]
+	: never

package/src/query-json.ts

@@ -0,0 +1,90 @@
+// A json field's path filter (D-149), Prisma's PostgreSQL JSON filter in
+// camelCase: `{ meta: { path: ['author', 'name'], equals: 'Ada' } }`.
+import type { Condition } from './adapter.ts'
+import { InvalidQuery } from './errors.ts'
+import {
+	clean,
+	cleanText,
+	entries,
+	isJson,
+	isObject,
+	unknownKey,
+} from './query-values.ts'
+
+const json = (operand: unknown, at: string): unknown => {
+	if (isJson(operand)) return operand
+	throw new InvalidQuery(at, `${at} must be a JSON value.`)
+}
+
+const operands: {
+	readonly [operator: string]: (operand: unknown, at: string) => unknown
+} = {
+	equals: json,
+	not: json,
+	...Object.fromEntries(
+		['lt', 'lte', 'gt', 'gte'].map((operator) => [
+			operator,
+			(operand: unknown, at: string) => {
+				if (typeof operand === 'string' && clean(operand)) return operand
+				if (typeof operand === 'number' && Number.isFinite(operand)) {
+					return operand
+				}
+				throw new InvalidQuery(at, `${at} must be a number or a string.`)
+			},
+		]),
+	),
+	...Object.fromEntries(
+		['stringContains', 'stringStartsWith', 'stringEndsWith'].map((operator) => [
+			operator,
+			cleanText,
+		]),
+	),
+	mode: (operand, at) => {
+		if (operand === 'insensitive') return operand
+		throw new InvalidQuery(at, `${at} must be 'insensitive'.`)
+	},
+	// A value is a list of one, as in Prisma.
+	arrayContains: (operand, at) => {
+		const value = json(operand, at)
+		if (!Array.isArray(value)) return [value]
+		const items: readonly unknown[] = value
+		return items
+	},
+	arrayStartsWith: json,
+	arrayEndsWith: json,
+}
+
+/** Whether a json field's filter is a path filter, which names `path`. */
+export const isPathFilter = (value: unknown): boolean =>
+	isObject(value) && value['path'] !== undefined
+
+/**
+ * A path filter of `model`'s json field, `undefined` when it has no operator,
+ * as `mode` alone (D-140).
+ */
+export function jsonCondition(
+	model: string,
+	value: unknown,
+	path: string,
+): Condition | undefined {
+	const condition: { [operator: string]: unknown } = {}
+	for (const [operator, operand] of entries(value, path)) {
+		const at = `${path}.${operator}`
+		if (operator === 'path') {
+			if (!Array.isArray(operand)) {
+				throw new InvalidQuery(at, `${at} must be a list of keys.`)
+			}
+			condition['path'] = operand.map((key: unknown, index) =>
+				cleanText(key, `${at}.${index}`),
+			)
+			continue
+		}
+		const check = operands[operator]
+		if (check === undefined) throw unknownKey(at, model)
+		condition[operator] = check(operand, at)
+	}
+	const tested = Object.keys(condition).filter(
+		(operator) => operator !== 'path' && operator !== 'mode',
+	)
+	return tested.length === 0 ? undefined : condition
+}

package/src/query-order.ts

@@ -0,0 +1,158 @@
+// A read's `orderBy` (D-20): the row's fields, a field reached through
+// `one` relations, or the number of a `many` relation's rows (D-134), or
+// how well the row matches the read's `_search` (D-148).
+import type { Order, Sort, Step } from './adapter.ts'
+import { InvalidQuery } from './errors.ts'
+import type { ModelInfo } from './schema.ts'
+import { searchedFields } from './query-search.ts'
+import type { Models, Scope } from './query-where.ts'
+import {
+	entries,
+	isObject,
+	modelOf,
+	systemFields,
+	unknownKey,
+} from './query-where.ts'
+
+export function direction(value: unknown, path: string): 'asc' | 'desc' {
+	if (value !== 'asc' && value !== 'desc') {
+		throw new InvalidQuery(path, `${path} must be 'asc' or 'desc'.`)
+	}
+	return value
+}
+
+/**
+ * A sort key's value: a direction, or on an optional field `{ sort, nulls }`
+ * (D-149).
+ */
+export function sortOf(value: unknown, path: string, optional: boolean): Sort {
+	if (!isObject(value)) return { direction: direction(value, path) }
+	if (!optional) {
+		throw new InvalidQuery(
+			path,
+			`${path} is required: it sorts by 'asc' or 'desc'.`,
+		)
+	}
+	const { sort, nulls, ...rest } = value
+	const [extra] = Object.keys(rest)
+	if (extra !== undefined) {
+		throw new InvalidQuery(
+			`${path}.${extra}`,
+			`${path} takes sort and nulls only.`,
+		)
+	}
+	const sorted = direction(sort, `${path}.sort`)
+	if (nulls === undefined) return { direction: sorted }
+	if (nulls !== 'first' && nulls !== 'last') {
+		const at = `${path}.nulls`
+		throw new InvalidQuery(at, `${at} must be 'first' or 'last'.`)
+	}
+	return { direction: sorted, nulls }
+}
+
+/** A scalar field that sorts: no json, no list, no plugin field (D-94). */
+function sortable(model: ModelInfo, field: string, path: string): void {
+	const known = model.fields.get(field)
+	if (known === undefined) {
+		if (!systemFields.includes(field)) throw unknownKey(path, model.name)
+		return
+	}
+	if (known.kind !== 'scalar') return
+	if (known.type !== 'json' && !known.list && known.codec === undefined) {
+		return
+	}
+	const kind =
+		known.codec !== undefined
+			? `a ${known.codec.plugin} field`
+			: known.type === 'json'
+				? 'a json field'
+				: 'a list'
+	throw new InvalidQuery(path, `${path} is ${kind}, which cannot be sorted.`)
+}
+
+/** The sort keys of one object of `orderBy`, in its keys' order. */
+function keys(
+	models: Models,
+	model: ModelInfo,
+	part: unknown,
+	at: string,
+	scope: Scope | undefined,
+	through: readonly Step[],
+	search: string | undefined,
+): Order[] {
+	const order: Order[] = []
+	const path = through.length === 0 ? {} : { through }
+	const searched = searchedFields(model.fields.values()).length > 0
+	for (const [field, value] of entries(part, at)) {
+		const where = `${at}.${field}`
+		if (field === '_relevance' && through.length === 0 && searched) {
+			if (search === undefined) {
+				throw new InvalidQuery(
+					where,
+					`${where} sorts by the _search at the top of the read's where, which has none.`,
+				)
+			}
+			order.push({
+				field,
+				direction: direction(value, where),
+				relevance: search,
+			})
+			continue
+		}
+		sortable(model, field, where)
+		scope?.check(model, field, where, 'sorts')
+		const known = model.fields.get(field)
+		if (known === undefined || known.kind === 'scalar') {
+			const optional = known?.optional === true
+			order.push({ field, ...sortOf(value, where, optional), ...path })
+			continue
+		}
+		const target = modelOf(models, known.target)
+		if (known.kind === 'one') {
+			const readable = scope?.readable(target.name)
+			const step = { relation: field, ...(readable && { where: readable }) }
+			const next = [...through, step]
+			order.push(...keys(models, target, value, where, scope, next, search))
+			continue
+		}
+		const [only, ...rest] = isObject(value) ? Object.entries(value) : []
+		if (only?.[0] !== '_count' || rest.length > 0) {
+			throw new InvalidQuery(
+				where,
+				`${where} is a many relation, sorted by { _count: 'asc' | 'desc' }.`,
+			)
+		}
+		const sorted = direction(only[1], `${where}._count`)
+		const count = scope?.related(model, known) ?? {}
+		order.push({ field, direction: sorted, ...path, count })
+	}
+	return order
+}
+
+/**
+ * A read's sort keys, ending with `id` so the order is total; `search` is
+ * the text of its where's `_search`.
+ */
+export function orderBy(
+	models: Models,
+	model: ModelInfo,
+	value: unknown,
+	path: string,
+	scope: Scope | undefined,
+	search?: string,
+): Order[] {
+	const parts = Array.isArray(value) ? value : [value]
+	const order = parts.flatMap((part: unknown, index) => {
+		const at = Array.isArray(value) ? `${path}.${index}` : path
+		return keys(models, model, part, at, scope, [], search)
+	})
+	// The order is total, so a cursor and a page are exact.
+	const total = order.some(
+		(each) =>
+			each.field === 'id' &&
+			each.through === undefined &&
+			each.count === undefined,
+	)
+	if (!total) order.push({ field: 'id', direction: 'asc' })
+	return order
+}

package/src/query-project.ts

@@ -0,0 +1,73 @@
+// A row as a query returns it (D-149): the fields of its shape, its
+// relations below, its virtuals as the read computed them (D-151), without
+// the fields the caller's read rules hide (D-44).
+import type { Shape } from './query-args.ts'
+import type { ModelInfo } from './schema.ts'
+import { isObject } from './query-where.ts'
+
+/** The fields of a row its field read rules hide (D-44). */
+export type Hidden = (
+	model: ModelInfo,
+	row: { readonly [field: string]: unknown },
+	fields: Iterable<string>,
+) => ReadonlySet<string>
+
+/** The values of each row's virtuals, as a read computed them (D-151). */
+export type Computed = WeakMap<object, Map<string, unknown>>
+
+/** The virtuals of `shape` a field read rule hides, its own or a need's. */
+export function unseenVirtuals(
+	shape: Shape,
+	row: { readonly [field: string]: unknown },
+	hidden: Hidden | undefined,
+): ReadonlySet<string> {
+	const reads = [...shape.virtuals.values()].map(({ info }) => info)
+	const names = reads.flatMap((info) => [info.name, ...info.needs])
+	const unseen = hidden?.(shape.model, row, names)
+	return new Set(
+		reads
+			.filter((info) => [info.name, ...info.needs].some((n) => unseen?.has(n)))
+			.map((info) => info.name),
+	)
+}
+
+/** A row as the query returns it, through the shape, without hidden fields. */
+export function project(
+	row: unknown,
+	shape: Shape,
+	hidden?: Hidden,
+	computed?: Computed,
+): unknown {
+	if (Array.isArray(row)) {
+		return row.map((item: unknown) => project(item, shape, hidden, computed))
+	}
+	if (!isObject(row)) return null
+	const names = [...shape.fields, ...shape.relations.keys(), ...shape.counts]
+	const unseen = hidden?.(shape.model, row, names)
+	const result: { [field: string]: unknown } = {}
+	for (const field of shape.fields) {
+		if (!unseen?.has(field)) result[field] = row[field] ?? null
+	}
+	for (const [name, nested] of shape.relations) {
+		if (!unseen?.has(name)) {
+			result[name] = project(row[name], nested, hidden, computed)
+		}
+	}
+	const values = computed?.get(row)
+	const unseenVirtual =
+		shape.virtuals.size > 0 ? unseenVirtuals(shape, row, hidden) : new Set()
+	for (const name of shape.virtuals.keys()) {
+		if (!unseenVirtual.has(name)) result[name] = values?.get(name) ?? null
+	}
+	if (shape.counts.length > 0) {
+		const counts: { readonly [name: string]: unknown } = isObject(row['_count'])
+			? row['_count']
+			: {}
+		result['_count'] = Object.fromEntries(
+			shape.counts
+				.filter((name) => !unseen?.has(name))
+				.map((name) => [name, counts[name] ?? 0]),
+		)
+	}
+	return result
+}

package/src/query-search.ts

@@ -0,0 +1,31 @@
+// Full-text search (D-148): `_search` keeps the rows whose searched fields
+// match a text, `_relevance` sorts them by how well.
+import type { SchemaField } from './adapter.ts'
+import type { fieldType } from './symbols.ts'
+
+/** The fields of `F` built with `search: true`. */
+type Searched<F> = {
+	[K in keyof F]: F[K] extends {
+		readonly [fieldType]: { readonly options: { readonly search: true } }
+	}
+		? K
+		: never
+}[keyof F]
+
+/** A model with a searched field takes `_search` in its `where`. */
+export type SearchWhere<F> = [Searched<F>] extends [never]
+	? unknown
+	: { readonly _search?: string | undefined }
+
+/** And `_relevance` at the top of its `orderBy`. */
+export type Relevance<F> = [Searched<F>] extends [never]
+	? unknown
+	: { readonly _relevance?: 'asc' | 'desc' | undefined }
+
+/** The names of a model's searched fields, in declaration order. */
+export const searchedFields = (
+	fields: Iterable<SchemaField>,
+): readonly string[] =>
+	[...fields].flatMap((field) =>
+		field.kind === 'scalar' && field.search === true ? [field.name] : [],
+	)

package/src/query-values.ts

@@ -0,0 +1,131 @@
+// The values a query or a write may hold, checked against a field (D-94,
+// D-139): what PostgreSQL stores as written, in each scalar type.
+import type { ScalarType } from './adapter.ts'
+import { decimalIssue } from './decimal.ts'
+import { InvalidQuery } from './errors.ts'
+import type { FieldInfo } from './schema.ts'
+
+export type Scalar = Extract<FieldInfo, { readonly kind: 'scalar' }>
+
+/** What a scalar value is checked against (D-139). */
+export type ScalarCheck = Pick<
+	Scalar,
+	'type' | 'list' | 'integer' | 'values' | 'precision' | 'scale'
+>
+
+/** An integer field's values (D-132). */
+export const isInteger = (value: unknown): boolean =>
+	Number.isInteger(value) &&
+	Number(value) >= -2_147_483_648 &&
+	Number(value) <= 2_147_483_647
+
+export function isObject(
+	value: unknown,
+): value is { readonly [key: string]: unknown } {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		!Array.isArray(value) &&
+		!(value instanceof Date)
+	)
+}
+
+/** The entries of an argument object, without `undefined` (D-84). */
+export function entries(value: unknown, path: string): [string, unknown][] {
+	if (!isObject(value))
+		throw new InvalidQuery(path, `${path} must be an object.`)
+	return Object.entries(value).filter(([, item]) => item !== undefined)
+}
+
+/** A string PostgreSQL stores as written: no NUL, no lone surrogate (D-94). */
+export const clean = (value: string): boolean =>
+	value.isWellFormed() && !value.includes('\0')
+
+export const cleanText = (value: unknown, at: string): string => {
+	if (typeof value === 'string' && clean(value)) return value
+	throw new InvalidQuery(at, `${at} must be a clean string.`)
+}
+
+/** A date of years 1 to 9999 in UTC, which PostgreSQL reads back (D-94). */
+export const storedDate = (value: unknown): value is Date => {
+	const year = value instanceof Date ? value.getUTCFullYear() : Number.NaN
+	return year >= 1 && year <= 9999
+}
+
+/** A real day of years 1 to 9999, written `'2026-07-31'` (D-150). */
+export function isDay(value: unknown): boolean {
+	const match =
+		typeof value === 'string' && /^(\d{4})-(\d{2})-(\d{2})$/.exec(value)
+	if (!match) return false
+	const [year = 0, month = 0, day = 0] = match.slice(1).map(Number)
+	const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0)
+	const days =
+		month === 2 ? (leap ? 29 : 28) : [4, 6, 9, 11].includes(month) ? 30 : 31
+	return year >= 1 && month >= 1 && month <= 12 && day >= 1 && day <= days
+}
+
+/** JSON data whose strings and keys are clean (D-94). */
+export function isJson(value: unknown): boolean {
+	if (value === null || typeof value === 'boolean') return true
+	if (typeof value === 'string') return clean(value)
+	if (typeof value === 'number') return Number.isFinite(value)
+	if (Array.isArray(value)) return value.every(isJson)
+	if (!isObject(value) || Object.getPrototypeOf(value) !== Object.prototype) {
+		return false
+	}
+	return Object.entries(value).every(
+		([key, item]) => clean(key) && isJson(item),
+	)
+}
+
+export function unknownKey(path: string, model: string): InvalidQuery {
+	return new InvalidQuery(path, `Unknown key '${path}' on ${model}.`)
+}
+
+export const integerRange = 'from -2,147,483,648 to 2,147,483,647'
+
+/** Each scalar type's check, and its message when a value does not fit. */
+const misfits: {
+	readonly [T in ScalarType]: (
+		value: unknown,
+		field: ScalarCheck,
+	) => string | undefined
+} = {
+	string: (value) => {
+		if (typeof value !== 'string') return 'Expected a string.'
+		return clean(value)
+			? undefined
+			: 'Expected a string without a NUL or a lone surrogate.'
+	},
+	number: (value, field) => {
+		if (field.integer !== true) {
+			return typeof value === 'number' && Number.isFinite(value)
+				? undefined
+				: 'Expected a finite number.'
+		}
+		return isInteger(value)
+			? undefined
+			: `Expected a whole number ${integerRange}.`
+	},
+	decimal: decimalIssue,
+	boolean: (value) =>
+		typeof value === 'boolean' ? undefined : 'Expected a boolean.',
+	dateTime: (value) =>
+		storedDate(value) ? undefined : 'Expected a Date of years 1 to 9999.',
+	date: (value) =>
+		isDay(value) ? undefined : "Expected a day written '2026-07-31'.",
+	json: (value) =>
+		isJson(value)
+			? undefined
+			: 'Expected JSON data, its strings without a NUL or a lone surrogate.',
+	enum: (value, field) =>
+		typeof value === 'string' && (field.values ?? []).includes(value)
+			? undefined
+			: `Expected one of ${(field.values ?? []).join(', ')}.`,
+}
+
+/** The message of a value that does not fit `field`, if it does not. */
+export const misfit = (
+	value: unknown,
+	field: ScalarCheck,
+): string | undefined => misfits[field.type](value, field)