ultimabase 0.0.0-stage → 0.1.0

package/src/query-args.ts

@@ -0,0 +1,375 @@
+// A read's arguments: `select`, `include`, `orderBy`, `take`, `skip` and
+// `cursor` checked (D-20), as the adapter's read and the shape of the result.
+import type { Filter, Nested } from './adapter.ts'
+import { and } from './access.ts'
+import { InvalidQuery } from './errors.ts'
+import type { FieldInfo, ModelInfo } from './schema.ts'
+import type { VirtualInfo } from './schema-virtuals.ts'
+import { orderBy } from './query-order.ts'
+import type { Models, Scope } from './query-where.ts'
+import {
+	entries,
+	isObject,
+	modelOf,
+	normalizeWhere,
+	systemFields,
+	unknownKey,
+} from './query-where.ts'
+
+/** What a query returns of each row, and of each relation it reads. */
+export type Shape = {
+	readonly model: ModelInfo
+	readonly fields: readonly string[]
+	readonly relations: ReadonlyMap<string, Shape>
+	/** The `many` relations `_count` returns (D-134). */
+	readonly counts: readonly string[]
+	readonly virtuals: ReadonlyMap<string, VirtualRead>
+}
+
+/** A virtual a read computes (D-151): its input, and a model's rows. */
+export type VirtualRead = {
+	readonly info: VirtualInfo
+	readonly input: { readonly [key: string]: unknown }
+	readonly path: string
+	readonly plan: Plan | undefined
+}
+
+type Many = Extract<FieldInfo, { readonly kind: 'many' }>
+
+export type Plan = { readonly read: Nested; readonly shape: Shape }
+
+/** Without `select`, scalar fields return and relations do not (D-20). */
+function scalars(model: ModelInfo): string[] {
+	return [
+		...systemFields,
+		...[...model.fields.values()]
+			.filter((field) => field.kind === 'scalar')
+			.map((field) => field.name),
+	]
+}
+
+export function integer(value: unknown, path: string, least?: number): number {
+	if (
+		typeof value !== 'number' ||
+		!Number.isSafeInteger(value) ||
+		(least !== undefined && value < least)
+	) {
+		const range = least === undefined ? '' : ` of at least ${least}`
+		throw new InvalidQuery(path, `${path} must be an integer${range}.`)
+	}
+	return value
+}
+
+/** `_count`: the `many` relations it names, each with its filter (D-134). */
+function counted(
+	models: Models,
+	model: ModelInfo,
+	value: unknown,
+	path: string,
+	scope: Scope | undefined,
+): Map<string, Filter> {
+	const filter = (field: Many, where?: Filter): Filter =>
+		and(where, scope?.related(model, field)) ?? {}
+	const counts = new Map<string, Filter>()
+	if (value === true) {
+		for (const field of model.fields.values()) {
+			if (field.kind === 'many') counts.set(field.name, filter(field))
+		}
+		return counts
+	}
+	const given = new Map(entries(value, path))
+	for (const key of given.keys()) {
+		if (key !== 'select') throw unknownKey(`${path}.${key}`, model.name)
+	}
+	const select = `${path}.select`
+	for (const [name, chosen] of entries(given.get('select'), select)) {
+		const at = `${select}.${name}`
+		const field = model.fields.get(name)
+		if (field?.kind !== 'many') throw unknownKey(at, model.name)
+		if (chosen === false) continue
+		if (chosen === true) {
+			counts.set(name, filter(field))
+			continue
+		}
+		const args = new Map(entries(chosen, at))
+		for (const key of args.keys()) {
+			if (key !== 'where') throw unknownKey(`${at}.${key}`, model.name)
+		}
+		const counting = modelOf(models, field.target)
+		const where = args.has('where')
+			? normalizeWhere(
+					models,
+					counting,
+					args.get('where'),
+					`${at}.where`,
+					scope,
+				)
+			: undefined
+		counts.set(name, filter(field, where))
+	}
+	return counts
+}
+
+/** A unique target (D-52): exactly `id`, a unique field or a unique index. */
+export function uniqueWhere(
+	models: Models,
+	model: ModelInfo,
+	where: unknown,
+	path: string,
+	scope?: Scope,
+): Filter {
+	const given = entries(where, path)
+	const keys = given.map(([key]) => key).toSorted()
+	const matched = model.uniques.some(
+		(fields) =>
+			fields.length === keys.length &&
+			fields.toSorted().every((field, index) => field === keys[index]),
+	)
+	if (!matched) {
+		throw new InvalidQuery(
+			path,
+			`${path} must name exactly id, a unique field or a unique index of ${model.name}.`,
+		)
+	}
+	const filter: { [field: string]: unknown } = {}
+	for (const [key, value] of given) {
+		const at = `${path}.${key}`
+		if (value === null || isObject(value)) {
+			throw new InvalidQuery(at, `${at} must be a value.`)
+		}
+		const field = model.fields.get(key)
+		filter[key] = field?.kind === 'one' ? { is: { id: value } } : value
+	}
+	return normalizeWhere(models, model, filter, path, scope)
+}
+
+/** A read narrowed to the rows of a read filter, its cursor too (D-86). */
+export function restrict(read: Nested, readable: Filter | undefined): Nested {
+	if (readable === undefined) return read
+	return {
+		...read,
+		where: and(read.where, readable),
+		...(read.cursor === undefined
+			? {}
+			: { cursor: and(read.cursor, readable) }),
+	}
+}
+
+type Kind = 'many' | 'one'
+
+/** A virtual's `true` or its input, with a model's `select`, `include`, `omit`. */
+function virtualRead(
+	models: Models,
+	info: VirtualInfo,
+	value: unknown,
+	path: string,
+	scope: Scope | undefined,
+): VirtualRead {
+	const { output } = info
+	const target = output.kind === 'model' ? output.name : undefined
+	const shaping: { [key: string]: unknown } = {}
+	const input: { [key: string]: unknown } = {}
+	for (const [key, given] of value === true ? [] : entries(value, path)) {
+		if (target !== undefined && oneKeys.has(key)) shaping[key] = given
+		else if (info.input === undefined) {
+			throw unknownKey(`${path}.${key}`, info.model)
+		} else input[key] = given
+	}
+	const nested =
+		target === undefined
+			? undefined
+			: plan(
+					models,
+					modelOf(models, target),
+					shaping,
+					path,
+					'one',
+					oneKeys,
+					scope,
+				)
+	return { info, input, path, plan: nested }
+}
+
+/**
+ * The arguments of a relation read, or of a top-level read when `path` is
+ * empty. A `scope` checks them and narrows each included relation (D-86).
+ */
+export function plan(
+	models: Models,
+	model: ModelInfo,
+	args: unknown,
+	path: string,
+	kind: Kind,
+	keys: ReadonlySet<string>,
+	scope?: Scope,
+): Plan {
+	const given = new Map(args === undefined ? [] : entries(args, path || 'args'))
+	const at = (key: string): string => (path === '' ? key : `${path}.${key}`)
+	for (const key of given.keys()) {
+		if (!keys.has(key)) throw unknownKey(at(key), model.name)
+	}
+	const select = given.get('select')
+	const include = given.get('include')
+	if (select !== undefined && include !== undefined) {
+		throw new InvalidQuery(
+			path,
+			`${at('select')} and include cannot be used together.`,
+		)
+	}
+	if (select !== undefined && given.has('omit')) {
+		throw new InvalidQuery(
+			path,
+			`${at('select')} and omit cannot be used together.`,
+		)
+	}
+	const read: {
+		-readonly [K in keyof Nested]: Nested[K]
+	} = {}
+	const fields: string[] = select === undefined ? scalars(model) : []
+	const relations = new Map<string, Shape>()
+	const virtuals = new Map<string, VirtualRead>()
+	for (const info of select === undefined ? model.virtuals.values() : []) {
+		if (info.default)
+			virtuals.set(info.name, virtualRead(models, info, true, '', scope))
+	}
+	const nested: { [field: string]: Nested } = {}
+	let count = new Map<string, Filter>()
+	const chosen = select ?? include
+	if (chosen !== undefined) {
+		const base = select === undefined ? 'include' : 'select'
+		for (const [name, value] of entries(chosen, at(base))) {
+			const where = `${at(base)}.${name}`
+			if (name === '_count') {
+				if (value === false) continue
+				count = counted(models, model, value, where, scope)
+				continue
+			}
+			const virtual = model.virtuals.get(name)
+			if (virtual !== undefined) {
+				if (value === false) virtuals.delete(name)
+				else
+					virtuals.set(name, virtualRead(models, virtual, value, where, scope))
+				continue
+			}
+			const field = model.fields.get(name)
+			const scalar =
+				field === undefined
+					? systemFields.includes(name)
+					: field.kind === 'scalar'
+			if ((field === undefined && !scalar) || (base === 'include' && scalar)) {
+				throw unknownKey(where, model.name)
+			}
+			if (value === false) continue
+			if (scalar) {
+				if (value !== true) {
+					throw new InvalidQuery(where, `${where} must be a boolean.`)
+				}
+				fields.push(name)
+				continue
+			}
+			if (field === undefined || field.kind === 'scalar') continue
+			const relation = plan(
+				models,
+				modelOf(models, field.target),
+				value === true ? undefined : value,
+				where,
+				field.kind,
+				field.kind === 'many' ? manyKeys : oneKeys,
+				scope,
+			)
+			const readable =
+				field.kind === 'one'
+					? scope?.readable(field.target)
+					: scope?.related(model, field)
+			nested[name] = restrict(relation.read, readable)
+			relations.set(name, relation.shape)
+		}
+	}
+	if (Object.keys(nested).length > 0) read.include = nested
+	if (count.size > 0) read.count = Object.fromEntries(count)
+	if (given.has('where')) {
+		read.where = normalizeWhere(
+			models,
+			model,
+			given.get('where'),
+			at('where'),
+			scope,
+		)
+	}
+	if (kind === 'many') {
+		// `_relevance` ranks by the `_search` at the top of `where` (D-148).
+		const search: unknown = read.where?.['_search']
+		read.orderBy = orderBy(
+			models,
+			model,
+			given.get('orderBy') ?? [],
+			at('orderBy'),
+			scope,
+			isObject(search) && typeof search['search'] === 'string'
+				? search['search']
+				: undefined,
+		)
+		if (given.has('take')) read.take = integer(given.get('take'), at('take'))
+		if (given.has('skip')) read.skip = integer(given.get('skip'), at('skip'), 0)
+		if (given.has('cursor')) {
+			read.cursor = uniqueWhere(
+				models,
+				model,
+				given.get('cursor'),
+				at('cursor'),
+				scope,
+			)
+		}
+	}
+	const hidden = omitted(model, given.get('omit'), at('omit'))
+	const shown = fields.filter((name) => !hidden.has(name))
+	for (const name of hidden) virtuals.delete(name)
+	const needs = [...virtuals.values()].flatMap(({ info }) => info.needs)
+	// A field read rule may read any field of the row (D-136).
+	const names = [
+		...shown,
+		...relations.keys(),
+		...count.keys(),
+		...virtuals.keys(),
+	]
+	if (!names.some((name) => scope?.ruled(model, name) === true)) {
+		read.fields = [...new Set(['id', ...shown, ...needs])]
+	}
+	const counts = [...count.keys()]
+	return { read, shape: { model, fields: shown, relations, counts, virtuals } }
+}
+
+/** The scalar and system fields `omit` leaves out of the rows (D-135). */
+function omitted(model: ModelInfo, omit: unknown, path: string): Set<string> {
+	const names = new Set<string>()
+	if (omit === undefined) return names
+	for (const [name, value] of entries(omit, path)) {
+		const where = `${path}.${name}`
+		const field = model.fields.get(name)
+		const scalar =
+			field === undefined
+				? systemFields.includes(name) || model.virtuals.get(name)?.default
+				: field.kind === 'scalar'
+		if (scalar !== true) throw unknownKey(where, model.name)
+		if (typeof value !== 'boolean') {
+			throw new InvalidQuery(where, `${where} must be a boolean.`)
+		}
+		if (value) names.add(name)
+	}
+	return names
+}
+
+/** The keys that shape a read's rows. */
+export const oneKeys: ReadonlySet<string> = new Set([
+	'select',
+	'include',
+	'omit',
+])
+const manyKeys = new Set([
+	...oneKeys,
+	'where',
+	'orderBy',
+	'take',
+	'skip',
+	'cursor',
+])

package/src/query-bulk.ts

@@ -0,0 +1,53 @@
+// The writes of many rows, all or nothing: `createMany` (D-135),
+// `updateMany` (D-133), `deleteMany` (D-111), and the forms that return the
+// rows they write (D-149).
+import type { Exact } from './exact.ts'
+import type { Payload, QueryOptions, Shaping, Where } from './query.ts'
+import type { CreateManyData, UpdateManyData } from './record.ts'
+
+/** `createMany`: a row or a list, no nested writes, no rows back (D-135). */
+export type CreateManyArgs<F> = {
+	readonly data: CreateManyData<F> | readonly CreateManyData<F>[]
+}
+
+/** `updateMany`: no relation writes, no returned rows (D-133). */
+export type UpdateManyArgs<F> = {
+	readonly where?: Where<F> | undefined
+	readonly data: UpdateManyData<F>
+}
+
+export type CreateManyAndReturnArgs<F> = CreateManyArgs<F> & Shaping<F>
+export type UpdateManyAndReturnArgs<F> = UpdateManyArgs<F> & Shaping<F>
+
+export interface BulkQueries<F> {
+	/** A create of each row of `data`, all or nothing (D-135). */
+	createMany(
+		this: void,
+		args: CreateManyArgs<F>,
+		options?: QueryOptions,
+	): Promise<{ readonly count: number }>
+	/** An update of each row `where` selects, all or nothing (D-133). */
+	updateMany(
+		this: void,
+		args: UpdateManyArgs<F>,
+		options?: QueryOptions,
+	): Promise<{ readonly count: number }>
+	/** A delete of each row `where` selects, all or nothing (D-111). */
+	deleteMany(
+		this: void,
+		args?: { readonly where?: Where<F> | undefined },
+		options?: QueryOptions,
+	): Promise<{ readonly count: number }>
+	/** `createMany`'s rows, in `data`'s order, each as `create` returns it. */
+	createManyAndReturn<const A extends CreateManyAndReturnArgs<F>>(
+		this: void,
+		args: A & NoInfer<Exact<A, CreateManyAndReturnArgs<F>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A>[]>
+	/** `updateMany`'s rows, in `id` order, each as `update` returns it. */
+	updateManyAndReturn<const A extends UpdateManyAndReturnArgs<F>>(
+		this: void,
+		args: A & NoInfer<Exact<A, UpdateManyAndReturnArgs<F>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A>[]>
+}

package/src/query-conditions.ts

@@ -0,0 +1,53 @@
+// The conditions of a list field (D-120, D-127, D-149).
+import type { Condition } from './adapter.ts'
+import { InvalidQuery } from './errors.ts'
+import type { ModelInfo } from './schema.ts'
+import type { Scalar } from './query-values.ts'
+import { entries, integerRange, misfit, unknownKey } from './query-values.ts'
+
+/** What an element of `field` must be, for a message. */
+function kindOf(field: Scalar): string {
+	if (field.type === 'enum') return `one of ${(field.values ?? []).join(', ')}`
+	if (field.type !== 'number') return 'a non-empty clean string'
+	return field.integer === true
+		? `a whole number ${integerRange}`
+		: 'a finite number'
+}
+
+/**
+ * A list's `has`, `hasSome` and `hasEvery`, which name its elements, and
+ * `isEmpty` (D-120, D-127, D-149).
+ */
+export function listCondition(
+	model: ModelInfo,
+	field: Scalar,
+	value: unknown,
+	path: string,
+): Condition | undefined {
+	const element = (item: unknown, at: string): unknown => {
+		if (item === '' || misfit(item, field) !== undefined) {
+			throw new InvalidQuery(at, `${at} must be ${kindOf(field)}.`)
+		}
+		return item
+	}
+	const condition: { [operator: string]: unknown } = {}
+	for (const [operator, operand] of entries(value, path)) {
+		const at = `${path}.${operator}`
+		if (operator === 'has') condition[operator] = element(operand, at)
+		else if (operator === 'isEmpty') {
+			if (typeof operand !== 'boolean') {
+				throw new InvalidQuery(at, `${at} must be a boolean.`)
+			}
+			condition[operator] = operand
+		} else if (operator !== 'hasSome' && operator !== 'hasEvery') {
+			throw unknownKey(at, model.name)
+		} else if (!Array.isArray(operand)) {
+			throw new InvalidQuery(at, `${at} must be a list.`)
+		} else {
+			condition[operator] = operand.map((each: unknown, index) =>
+				element(each, `${at}.${index}`),
+			)
+		}
+	}
+	return Object.keys(condition).length === 0 ? undefined : condition
+}

package/src/query-context.ts

@@ -0,0 +1,104 @@
+// What every query of a model shares (D-18): the running application, the
+// caller and the scope it reads through, and the shape it returns.
+import type { Access } from './access.ts'
+import { and } from './access.ts'
+import type { Filter, Row } from './adapter.ts'
+import { InvalidQuery } from './errors.ts'
+import type { FindOperation } from './model.ts'
+import type { Caller } from './rules.ts'
+import type { Running } from './running.ts'
+import type { ModelInfo } from './schema.ts'
+import type { QueryScope } from './scope.ts'
+import { planned } from './scope.ts'
+import type { Shape } from './query-args.ts'
+import { oneKeys, plan } from './query-args.ts'
+import type { Hidden } from './query-project.ts'
+import { project } from './query-project.ts'
+import type { Store } from './transaction.ts'
+import { computeVirtuals } from './virtual-read.ts'
+import type { Models } from './query-where.ts'
+import { entries, unknownKey } from './query-where.ts'
+
+export type Context = {
+	readonly app: Running
+	readonly models: Models
+	readonly model: ModelInfo
+	readonly caller: Caller
+	readonly scope: QueryScope
+}
+
+export function given(
+	args: unknown,
+	model: string,
+	keys: readonly string[],
+	required: readonly string[],
+): Map<string, unknown> {
+	const found = new Map(args === undefined ? [] : entries(args, 'args'))
+	for (const key of found.keys()) {
+		if (!keys.includes(key)) throw unknownKey(key, model)
+	}
+	for (const key of required) {
+		if (!found.has(key)) throw new InvalidQuery(key, `${key} is required.`)
+	}
+	return found
+}
+
+/** `select` and `include` of a single-row operation. */
+export function picked(found: ReadonlyMap<string, unknown>): object {
+	const args: { [key: string]: unknown } = {}
+	for (const key of oneKeys) {
+		if (found.has(key)) args[key] = found.get(key)
+	}
+	return args
+}
+
+/**
+ * The rows a many-row operation's `where` selects that the caller reads, or
+ * deletes (D-124).
+ */
+export async function filtered(
+	context: Context,
+	found: ReadonlyMap<string, unknown>,
+	operation: FindOperation,
+): Promise<Filter | undefined> {
+	const { models, model, scope } = context
+	const keys = new Set(['where'])
+	const args = { where: found.get('where') }
+	return planned(scope, () =>
+		and(
+			plan(models, model, args, '', 'one', keys, scope).read.where,
+			scope.readable(model.name, operation),
+		),
+	)
+}
+
+/** The fields the caller's field read rules hide (D-44). */
+export function hiddenBy(access: Access | undefined): Hidden | undefined {
+	return access && ((model, row, fields) => access.hidden(model, row, fields))
+}
+
+/** Each row, as `shape` shapes it (D-149), its virtuals computed (D-151). */
+export async function shapedRows(
+	context: Context,
+	store: Store,
+	rows: readonly Row[],
+	shape: Shape,
+	access: Access | undefined,
+): Promise<unknown[]> {
+	const hidden = hiddenBy(access)
+	const computed = await computeVirtuals(context, store, rows, shape, hidden)
+	return rows.map((row) => project(row, shape, hidden, computed))
+}
+
+export async function first(
+	context: Context,
+	store: Store,
+	rows: readonly Row[],
+	shape: Shape,
+	access: Access | undefined,
+): Promise<unknown> {
+	const [row] = rows
+	if (row === undefined) return null
+	const [shaped] = await shapedRows(context, store, [row], shape, access)
+	return shaped
+}

package/src/query-filter.ts

@@ -0,0 +1,54 @@
+// A scalar's and a list's filter operators (D-20, D-140, D-149): a decimal
+// (D-145) or a day (D-150) is a string compared in order, without `contains`.
+import type { JsonValue } from './fields.ts'
+
+export type ScalarFilter<V, Ordered = false> = {
+	readonly equals?: V | null | undefined
+	readonly not?: V | null | undefined
+	readonly in?: readonly V[] | undefined
+	readonly notIn?: readonly V[] | undefined
+} & ([V, Ordered] extends [number | Date, unknown] | [unknown, true]
+	? {
+			readonly lt?: V | undefined
+			readonly lte?: V | undefined
+			readonly gt?: V | undefined
+			readonly gte?: V | undefined
+		}
+	: [V] extends [string]
+		? {
+				readonly contains?: string | undefined
+				readonly startsWith?: string | undefined
+				readonly endsWith?: string | undefined
+			} & (string extends V
+				? { readonly mode?: 'insensitive' | undefined }
+				: unknown)
+		: unknown)
+
+/** A list has no shorthand; `NOT` gives the opposite (D-120, D-127, D-149). */
+export type ListFilter<E> = {
+	readonly has?: E | undefined
+	readonly hasSome?: readonly E[] | undefined
+	readonly hasEvery?: readonly E[] | undefined
+	readonly isEmpty?: boolean | undefined
+}
+
+/**
+ * A json field's filter at a path into its value (D-149): the operands are
+ * any JSON, whatever the field's schema, and the path is not checked.
+ */
+export type JsonPathFilter = {
+	readonly path: readonly string[]
+	readonly equals?: JsonValue | undefined
+	readonly not?: JsonValue | undefined
+	readonly lt?: number | string | undefined
+	readonly lte?: number | string | undefined
+	readonly gt?: number | string | undefined
+	readonly gte?: number | string | undefined
+	readonly stringContains?: string | undefined
+	readonly stringStartsWith?: string | undefined
+	readonly stringEndsWith?: string | undefined
+	readonly mode?: 'insensitive' | undefined
+	readonly arrayContains?: JsonValue | undefined
+	readonly arrayStartsWith?: JsonValue | undefined
+	readonly arrayEndsWith?: JsonValue | undefined
+}