ultimabase 0.0.0-stage → 0.1.0

package/src/query-where.ts

@@ -0,0 +1,318 @@
+// A caller's `where`, checked and normalized for the adapter (D-20, D-73):
+// shorthands become `{ equals }`, `undefined` goes (D-84), and an unknown
+// key fails with its path.
+import type { Condition, Filter, ScalarType } from './adapter.ts'
+import { storedValue } from './decimal.ts'
+import { InvalidQuery } from './errors.ts'
+import type { FieldInfo, ModelInfo } from './schema.ts'
+import { listCondition } from './query-conditions.ts'
+import { isPathFilter, jsonCondition } from './query-json.ts'
+import { searchedFields } from './query-search.ts'
+import {
+	clean,
+	cleanText,
+	entries,
+	isObject,
+	misfit,
+	storedDate,
+	unknownKey,
+} from './query-values.ts'
+
+export type { Scalar, ScalarCheck } from './query-values.ts'
+export {
+	clean,
+	entries,
+	integerRange,
+	isInteger,
+	isJson,
+	isObject,
+	misfit,
+	storedDate,
+	unknownKey,
+} from './query-values.ts'
+
+export type Models = ReadonlyMap<string, ModelInfo>
+
+/** The model, or the table, of `name`; another name is a kernel bug. */
+export function modelOf<T>(models: ReadonlyMap<string, T>, name: string): T {
+	const model = models.get(name)
+	if (model === undefined) throw new Error(`Unknown model ${name}.`)
+	return model
+}
+
+export const byId = (id: string): Filter => ({ id: { equals: id } })
+export const byIds = (ids: readonly string[]): Filter => ({ id: { in: ids } })
+
+/** What a query does with a field: a read rule refuses each (D-44, D-143, D-147). */
+export type Verb = 'filters' | 'sorts' | 'aggregates' | 'compares'
+
+/** What a caller other than Master may filter on and see (D-86). */
+export type Scope = {
+	/** Fails on a field with a read rule (D-44). */
+	readonly check: (
+		model: ModelInfo,
+		field: string,
+		path: string,
+		verb: Verb,
+	) => void
+	/** Whether the caller runs a field read rule on it (D-44). */
+	readonly ruled: (model: ModelInfo, field: string) => boolean
+	/** A model's read filter; `undefined` when every row passes. */
+	readonly readable: (model: string) => Filter | undefined
+	/**
+	 * The rows a `many` relation reads: its filter (D-151) and its target's
+	 * read filter; `undefined` when every row passes.
+	 */
+	readonly related: (
+		model: ModelInfo,
+		field: Extract<FieldInfo, { readonly kind: 'many' }>,
+	) => Filter | undefined
+}
+
+/** `id`, `createdAt` and `updatedAt`, which every model has (D-22). */
+const system: ReadonlyMap<string, ScalarType | 'id'> = new Map([
+	['id', 'id'],
+	['createdAt', 'dateTime'],
+	['updatedAt', 'dateTime'],
+])
+export const systemFields: readonly string[] = [...system.keys()]
+
+type Single = ScalarType | 'id'
+
+function typeOf(model: ModelInfo, name: string): ScalarType | 'id' | undefined {
+	const field = model.fields.get(name)
+	return field?.kind === 'scalar' ? field.type : system.get(name)
+}
+
+/** Whether `value` fits a field, or a system field, which has no info (D-22). */
+const fits = (type: Single, value: unknown, field: FieldInfo | undefined) =>
+	field?.kind === 'scalar'
+		? misfit(value, field) === undefined
+		: type === 'dateTime'
+			? storedDate(value)
+			: typeof value === 'string' && clean(value)
+
+const base = new Set(['equals', 'not', 'in', 'notIn'])
+const ordered = new Set(['lt', 'lte', 'gt', 'gte'])
+const text = new Set(['contains', 'startsWith', 'endsWith'])
+
+function operators(type: Single): ReadonlySet<string> {
+	if (
+		type === 'number' ||
+		type === 'decimal' ||
+		type === 'dateTime' ||
+		type === 'date'
+	)
+		return new Set([...base, ...ordered])
+	if (type === 'string') return new Set([...base, ...text, 'mode'])
+	if (type === 'id' || type === 'enum') return new Set([...base, ...text])
+	return base
+}
+
+/**
+ * The operands of a value other than the field's, as an aggregate's in a
+ * `having` (D-149): their type, and their check, which stores each.
+ */
+export type Operand = {
+	readonly type: ScalarType
+	readonly check: (item: unknown, at: string) => unknown
+}
+
+function scalarCondition(
+	model: ModelInfo,
+	name: string,
+	type: Single,
+	value: unknown,
+	path: string,
+	other?: Operand['check'],
+): Condition | undefined {
+	const field = model.fields.get(name)
+	const fit = (item: unknown, at: string): unknown => {
+		if (!fits(type, item, field)) {
+			throw new InvalidQuery(at, `${at} does not fit ${model.name}.${name}.`)
+		}
+		return field?.kind === 'scalar' ? storedValue(item, field) : item
+	}
+	const check = (item: unknown, at: string, nullable: boolean): unknown =>
+		item === null && nullable ? null : (other ?? fit)(item, at)
+	// A primitive, a `Date` or a list is `equals`; an object is a filter, on
+	// `json` too, which compares whole values with `equals` as in Prisma.
+	if (value === null || !isObject(value)) {
+		return { equals: check(value, path, true) }
+	}
+	const allowed = operators(type)
+	const condition: { [operator: string]: unknown } = {}
+	let insensitive = false
+	for (const [operator, operand] of entries(value, path)) {
+		const at = `${path}.${operator}`
+		if (!allowed.has(operator)) throw unknownKey(at, model.name)
+		if (operator === 'in' || operator === 'notIn') {
+			if (!Array.isArray(operand)) {
+				throw new InvalidQuery(at, `${at} must be a list.`)
+			}
+			condition[operator] = operand.map((item: unknown, index) =>
+				check(item, `${at}.${index}`, false),
+			)
+		} else if (operator === 'mode') {
+			if (operand !== 'insensitive') {
+				throw new InvalidQuery(at, `${at} must be 'insensitive'.`)
+			}
+			insensitive = true
+		} else if (text.has(operator)) {
+			condition[operator] = cleanText(operand, at)
+		} else {
+			condition[operator] = check(operand, at, base.has(operator))
+		}
+	}
+	// `mode` alone filters nothing, as in Prisma (D-140).
+	if (Object.keys(condition).length === 0) return undefined
+	return insensitive ? { ...condition, mode: 'insensitive' } : condition
+}
+
+/** A scalar field's condition, or with `operand` another value's of it. */
+export function fieldCondition(
+	model: ModelInfo,
+	name: string,
+	value: unknown,
+	path: string,
+	operand?: Operand,
+): Condition | undefined {
+	const type = operand?.type ?? typeOf(model, name)
+	if (type === undefined) throw unknownKey(path, model.name)
+	return scalarCondition(model, name, type, value, path, operand?.check)
+}
+
+/**
+ * A relation operator that sees readable targets only (D-86): an unreadable
+ * row is absent, so `is: null` holds when the target is unreadable.
+ */
+function restricted(
+	operator: string,
+	inner: Filter | null,
+	readable: Filter,
+): Condition {
+	if (inner === null) {
+		return operator === 'is' ? { isNot: readable } : { is: readable }
+	}
+	if (operator === 'every') {
+		return { every: { OR: [{ NOT: [readable] }, inner] } }
+	}
+	return { [operator]: { AND: [readable, inner] } }
+}
+
+function relationFilters(
+	models: Models,
+	model: ModelInfo,
+	field: Extract<FieldInfo, { readonly kind: 'one' | 'many' }>,
+	value: unknown,
+	path: string,
+	scope: Scope | undefined,
+): Filter[] {
+	const target = modelOf(models, field.target)
+	const readable =
+		field.kind === 'one'
+			? scope?.readable(field.target)
+			: scope?.related(model, field)
+	const allowed =
+		field.kind === 'one' ? ['is', 'isNot'] : ['some', 'every', 'none']
+	const filters: Filter[] = []
+	for (const [operator, operand] of entries(value, path)) {
+		const at = `${path}.${operator}`
+		if (!allowed.includes(operator)) throw unknownKey(at, model.name)
+		const inner =
+			operand === null && field.kind === 'one'
+				? null
+				: normalizeWhere(models, target, operand, at, scope)
+		filters.push({
+			[field.name]:
+				readable === undefined
+					? { [operator]: inner }
+					: restricted(operator, inner, readable),
+		})
+	}
+	return filters
+}
+
+function list(
+	models: Models,
+	model: ModelInfo,
+	value: unknown,
+	path: string,
+	single: boolean,
+	scope: Scope | undefined,
+	stored: boolean,
+): Filter[] {
+	if (Array.isArray(value)) {
+		return value.map((item: unknown, index) =>
+			normalizeWhere(models, model, item, `${path}.${index}`, scope, stored),
+		)
+	}
+	if (single) return [normalizeWhere(models, model, value, path, scope, stored)]
+	throw new InvalidQuery(path, `${path} must be a list.`)
+}
+
+/**
+ * A `where` of `model`, normalized; `path` names it in errors. With a
+ * `scope`, relation filters see readable rows only (D-86). Only a
+ * `beforeFind`'s, `stored`, filters a plugin field, in its stored form
+ * (D-122).
+ */
+export function normalizeWhere(
+	models: Models,
+	model: ModelInfo,
+	where: unknown,
+	path: string,
+	scope?: Scope,
+	stored = false,
+): Filter {
+	const filter: { [key: string]: Condition | Filter[] } = {}
+	const relations: Filter[] = []
+	for (const [key, value] of entries(where, path)) {
+		const at = `${path}.${key}`
+		if (key === 'AND' || key === 'NOT' || key === 'OR') {
+			filter[key] = list(models, model, value, at, key !== 'OR', scope, stored)
+			continue
+		}
+		if (key === '_search' && searchedFields(model.fields.values()).length > 0) {
+			if (value !== undefined) filter[key] = { search: cleanText(value, at) }
+			continue
+		}
+		const field = model.fields.get(key)
+		const type = typeOf(model, key)
+		if (field === undefined && type === undefined) {
+			throw unknownKey(at, model.name)
+		}
+		const codec = field?.kind === 'scalar' ? field.codec : undefined
+		if (codec !== undefined && !stored) {
+			throw new InvalidQuery(
+				at,
+				`${at}: ${model.name}.${key} is a ${codec.plugin} field, which only a beforeFind filters.`,
+			)
+		}
+		scope?.check(model, key, at, 'filters')
+		if (field !== undefined && field.kind !== 'scalar') {
+			relations.push(...relationFilters(models, model, field, value, at, scope))
+			continue
+		}
+		const condition =
+			type === undefined
+				? undefined
+				: field?.kind === 'scalar' && field.list
+					? listCondition(model, field, value, at)
+					: type === 'json' && isPathFilter(value)
+						? jsonCondition(model.name, value, at)
+						: scalarCondition(model, key, type, value, at)
+		if (condition !== undefined) filter[key] = condition
+	}
+	const [only, ...others] = relations
+	if (only === undefined) return filter
+	// One relation filter stays in place; more join `AND`.
+	if (others.length === 0 && filter['AND'] === undefined) {
+		return { ...filter, ...only }
+	}
+	const and = filter['AND']
+	return {
+		...filter,
+		AND: [...(Array.isArray(and) ? and : []), ...relations],
+	}
+}

package/src/query-write.ts

@@ -0,0 +1,360 @@
+// A write's data after its `before*` hooks, turned into the adapter's
+// changes: values and relation writes by id, from either side (D-20, D-78),
+// and the rows its relation writes create, update and delete (D-128, D-138).
+// The caller's data was checked before the hooks (write-data.ts): what fails
+// here is a hook's or a default's value (D-88).
+import { recordOf } from './access.ts'
+import type { Row } from './adapter.ts'
+import { InvalidQuery } from './errors.ts'
+import { runHook } from './hooks.ts'
+import { resolveData, resolveMany, resolveOne } from './nested-write.ts'
+import type { Operations } from './number-update.ts'
+import type { FieldInfo, ModelInfo } from './schema.ts'
+import type { QueryScope } from './scope.ts'
+import { madeId, uuidv7 } from './uuid.ts'
+import { byId, entries, modelOf, unknownKey } from './query-where.ts'
+import type { Context, Relation } from './write-context.ts'
+import {
+	fail,
+	holds,
+	linking,
+	pathOf,
+	resolving,
+	scalar,
+	trusted,
+	viaOf,
+} from './write-context.ts'
+import type { Draft } from './write-data.ts'
+import { prepared, readData } from './write-data.ts'
+import type { Reads, Step } from './write-plan.ts'
+import { Plan } from './write-plan.ts'
+
+/**
+ * A row a relation write creates, as `Target.create` creates it (D-128):
+ * its access rules unless a hook or a default wrote it, its defaults, its
+ * validation and `beforeCreate`, then its own relation writes.
+ */
+async function created(
+	context: Context,
+	field: Relation,
+	data: Draft,
+	at: readonly (string | number)[],
+	skips: boolean,
+): Promise<{ readonly id: string; readonly steps: Step[] }> {
+	const { scope, plan } = context
+	const model = modelOf(context.scope.models, field.target)
+	const made = madeId(data)
+	// A hook's data may come back in another write: it gets a fresh id.
+	const id = skips || plan.made.has(made) ? uuidv7() : made
+	const path = ['data', ...at].join('.')
+	const draft = readData(scope.models, model, data, true, path, field.inverse)
+	const inverse = model.fields.get(field.inverse)
+	if (inverse?.kind === 'one' && inverse.stored) {
+		draft[field.inverse] = { connect: { id: context.id } }
+	}
+	const child = { ...context, model, id, set: {}, at }
+	await resolveData(resolving(child, skips, true), draft)
+	const sent: Readonly<Draft> = skips ? {} : { ...draft }
+	if (!skips) scope.access?.allow(model, 'create', { data: sent })
+	await prepared(model, draft, scope.caller, true, at)
+	await runHook(model, 'beforeCreate', { caller: scope.caller, data: draft })
+	plan.events.push({ model, operation: 'create', id })
+	const steps = await inserted({ ...child, sent, before: [], after: [] }, draft)
+	return { id, steps }
+}
+
+/**
+ * A linked row a relation write updates, as `Target.update` updates it
+ * (D-138): its rules unless a hook or a default wrote it, its validation,
+ * `beforeUpdate`, then its own relation writes.
+ */
+async function changed(
+	context: Context,
+	field: Relation,
+	update: { readonly data: Draft; readonly row: Row },
+	at: readonly (string | number)[],
+	skips: boolean,
+): Promise<Step[]> {
+	const { scope, plan } = context
+	const { data, row } = update
+	const model = modelOf(context.scope.models, field.target)
+	const child = { ...context, model, id: row.id, set: {}, at }
+	await resolveData(resolving(child, skips, false), data)
+	const sent: Readonly<Draft> = skips ? {} : { ...data }
+	const via = viaOf(context, field)
+	if (!skips)
+		scope.access?.allow(model, 'update', { record: row, data: sent, via })
+	await prepared(model, data, scope.caller, false, at)
+	const record = recordOf(model, row)
+	await runHook(model, 'beforeUpdate', { caller: scope.caller, record, data })
+	plan.events.push({ model, operation: 'update', id: row.id, before: row })
+	return updateSteps({ ...child, sent, before: [], after: [] }, data)
+}
+
+/** A linked row a relation write deletes, as `Target.delete` (D-138). */
+function dropped(
+	context: Context,
+	field: Relation,
+	row: Row,
+	path: string,
+	skips: boolean,
+): Step {
+	const model = modelOf(context.scope.models, field.target)
+	const via = viaOf(context, field)
+	if (!skips) context.scope.access?.allow(model, 'delete', { record: row, via })
+	// The parent empties its own key to the row: the cascade leaves it.
+	const except =
+		field.kind === 'one' && field.stored
+			? { model: context.model.name, field: field.name, id: context.id }
+			: undefined
+	return {
+		kind: 'drop',
+		model: model.name,
+		rows: [row],
+		path,
+		...(except === undefined ? {} : { except }),
+		written: context.plan.written,
+	}
+}
+
+async function one(
+	context: Context,
+	field: Extract<FieldInfo, { readonly kind: 'one' }>,
+	value: unknown,
+	creating: boolean,
+): Promise<void> {
+	const skips = trusted(context, field, value)
+	const write = await resolveOne(
+		resolving(context, skips, creating),
+		field,
+		value,
+	)
+	const at = [...context.at, field.name, write.kind]
+	if (write.kind === 'update') {
+		context.after.push(...(await changed(context, field, write, at, skips)))
+		return
+	}
+	if (write.kind === 'delete') {
+		context.after.push(
+			dropped(
+				context,
+				field,
+				write.row,
+				`${pathOf(context, field.name)}.delete`,
+				skips,
+			),
+		)
+	}
+	// A key the other side holds changes its row: it is updated (D-124).
+	const operation = field.stored ? 'read' : 'update'
+	let target = write.kind === 'connect' ? write.id : undefined
+	if (target !== undefined) {
+		context.plan.connect(field.target, [target], skips, operation)
+	}
+	if (write.kind === 'create') {
+		const made = await created(context, field, write.data, write.at, skips)
+		target = made.id
+		// The row that stores the key is written after the row it points to.
+		;(field.stored ? context.before : context.after).push(...made.steps)
+	}
+	if (field.stored) {
+		if (target === undefined && !field.optional) {
+			fail(context, [field.name], 'Required.')
+			return
+		}
+		context.set[field.name] = target ?? null
+		return
+	}
+	// A deleted row holds no key; another one may not be left empty (D-37).
+	if (write.kind === 'delete') return
+	if (!creating && (await holds(context, field, target))) {
+		fail(
+			context,
+			[field.name],
+			`The ${field.target} it points to cannot be left without one.`,
+		)
+		return
+	}
+	if (write.kind === 'connect') {
+		context.after.push({
+			kind: 'move',
+			model: field.target,
+			field: field.inverse,
+			via: viaOf(context, field),
+			where: byId(write.id),
+			to: context.id,
+			trusted: skips,
+		})
+	}
+}
+
+/** Deletes, then creates, disconnects and connects, then updates (D-138). */
+async function many(
+	context: Context,
+	field: Extract<FieldInfo, { readonly kind: 'many' }>,
+	value: unknown,
+	creating: boolean,
+): Promise<void> {
+	const skips = trusted(context, field, value)
+	const write = await resolveMany(
+		resolving(context, skips, creating),
+		field,
+		value,
+	)
+	const operation = field.join ? 'read' : 'update'
+	context.plan.connect(field.target, write.connect, skips, operation)
+	for (const { row, path } of write.delete) {
+		context.after.push(dropped(context, field, row, path, skips))
+	}
+	const made: string[] = []
+	for (const { data, at } of write.create) {
+		const child = await created(context, field, data, at, skips)
+		made.push(child.id)
+		context.after.push(...child.steps)
+	}
+	linking(context, field, write, made, skips)
+	for (const [index, update] of write.update.entries()) {
+		const at = [...context.at, field.name, 'update', index, 'data']
+		context.after.push(...(await changed(context, field, update, at, skips)))
+	}
+}
+
+/** A hook's value the plan refuses is the hook's error, not the caller's. */
+function hookError(context: Context, error: unknown): unknown {
+	if (!(error instanceof InvalidQuery)) return error
+	return new TypeError(
+		`${context.model.name}: a before hook wrote invalid data. ${error.message}`,
+		{ cause: error },
+	)
+}
+
+async function fields(
+	context: Context,
+	data: Draft,
+	creating: boolean,
+): Promise<Set<string>> {
+	const given = new Set<string>()
+	const at = ['data', ...context.at].join('.')
+	for (const [name, value] of entries(data, at)) {
+		const field = context.model.fields.get(name)
+		// The caller's data was read before the hooks: a hook wrote the key.
+		if (field === undefined) {
+			throw hookError(
+				context,
+				unknownKey(pathOf(context, name), context.model.name),
+			)
+		}
+		given.add(name)
+		try {
+			if (field.kind === 'scalar') scalar(context, field, value)
+			else if (field.kind === 'one') await one(context, field, value, creating)
+			else await many(context, field, value, creating)
+		} catch (error) {
+			// The caller's relation value reaches rows only now (D-138).
+			throw trusted(context, field, value) ? hookError(context, error) : error
+		}
+	}
+	return given
+}
+
+function contextOf(
+	scope: QueryScope,
+	model: ModelInfo,
+	id: string,
+	sent: Readonly<Draft>,
+	reads: Reads,
+): Context {
+	const plan = new Plan()
+	const set = {}
+	return {
+		scope,
+		model,
+		id,
+		plan,
+		reads,
+		sent,
+		set,
+		before: [],
+		after: [],
+		at: [],
+	}
+}
+
+/** A created row's steps: the rows it points to, its insert, then the rest. */
+async function inserted(context: Context, draft: Draft): Promise<Step[]> {
+	const { model, id, plan } = context
+	plan.made.add(id)
+	const given = await fields(context, draft, true)
+	for (const field of model.fields.values()) {
+		if (given.has(field.name) || field.kind === 'many') continue
+		if (field.kind === 'one' && !field.stored) continue
+		// A required field may be left to a hook: checked after it (D-88).
+		// A list left unwritten is empty (D-120).
+		if (field.kind === 'scalar' && field.list) {
+			context.set[field.name] = []
+		} else if (field.optional) context.set[field.name] = null
+		else fail(context, [field.name], 'Required.')
+	}
+	const now = Date.now()
+	const row: Row = {
+		...context.set,
+		id,
+		createdAt: new Date(now),
+		updatedAt: new Date(now),
+	}
+	const insert = { kind: 'insert', model: model.name, row } as const
+	return [...context.before, insert, ...context.after]
+}
+
+/** An updated row's steps; `updatedAt` always moves. */
+async function updateSteps(
+	context: Context,
+	draft: Draft,
+	operations: Operations = new Map(),
+): Promise<Step[]> {
+	const { model, id, plan } = context
+	plan.written.add(`${model.name}:${id}`)
+	await fields(context, draft, false)
+	return [
+		...context.before,
+		{
+			kind: 'update',
+			model: model.name,
+			where: byId(id),
+			set: { ...context.set, updatedAt: new Date(Date.now()) },
+			...(operations.size === 0
+				? {}
+				: { compute: Object.fromEntries(operations) }),
+		},
+		...context.after,
+	]
+}
+
+/** `create`'s changes: the row with its id and timestamps (D-22). */
+export async function createPlan(
+	scope: QueryScope,
+	model: ModelInfo,
+	draft: Draft,
+	sent: Readonly<Draft>,
+	reads: Reads,
+	id: string = uuidv7(),
+): Promise<{ readonly id: string; readonly plan: Plan }> {
+	const context = contextOf(scope, model, id, sent, reads)
+	context.plan.steps.push(...(await inserted(context, draft)))
+	return { id: context.id, plan: context.plan }
+}
+
+/** `update`'s changes on the stored row. */
+export async function updatePlan(
+	scope: QueryScope,
+	model: ModelInfo,
+	id: string,
+	draft: Draft,
+	sent: Readonly<Draft>,
+	reads: Reads,
+	operations: Operations = new Map(),
+): Promise<Plan> {
+	const context = contextOf(scope, model, id, sent, reads)
+	context.plan.steps.push(...(await updateSteps(context, draft, operations)))
+	return context.plan
+}