ultimabase 0.0.0-stage → 0.1.0

package/src/group-by.ts

@@ -0,0 +1,186 @@
+// `groupBy` (D-146): the rows the caller reads in groups of the same `by`
+// values, each with the aggregates of `aggregate` (D-143), kept by its
+// `having` (D-149), sorted by its keys or its aggregates, then paged.
+import type { AggregateRead, GroupKey } from './adapter.ts'
+import type { Asked, Key } from './aggregate.ts'
+import {
+	checked,
+	keys,
+	shaped,
+	toAggregate,
+	typeOf,
+	wanted,
+} from './aggregate.ts'
+import { InvalidQuery } from './errors.ts'
+import type { Position } from './group-having.ts'
+import { having } from './group-having.ts'
+import type { Context } from './query-context.ts'
+import { filtered, given } from './query-context.ts'
+import { integer } from './query-args.ts'
+import { direction, sortOf } from './query-order.ts'
+import { entries, isObject } from './query-where.ts'
+import type { Store } from './transaction.ts'
+
+type Sort = NonNullable<AggregateRead['orderBy']>[number]
+
+/**
+ * The fields of `by`, or of `distinct` (D-147), each checked; a `one`
+ * relation the row stores.
+ */
+function grouping(
+	{ model, scope }: Context,
+	value: unknown,
+	name: 'by' | 'distinct',
+): string[] {
+	const message = `${name} must be a non-empty list of fields.`
+	const list: readonly unknown[] = Array.isArray(value) ? value : []
+	if (list.length === 0) throw new InvalidQuery(name, message)
+	const [verb, done] =
+		name === 'by'
+			? (['aggregates', 'grouped'] as const)
+			: (['compares', 'compared'] as const)
+	const fields: string[] = []
+	for (const [index, field] of list.entries()) {
+		const path = `${name}.${index}`
+		if (typeof field !== 'string') throw new InvalidQuery(path, message)
+		if (fields.includes(field)) {
+			throw new InvalidQuery(path, `${path} repeats ${field}.`)
+		}
+		const known = model.fields.get(field)
+		if (known?.kind !== 'one' || !known.stored) {
+			typeOf(model, field, path, done)
+		}
+		scope.check(model, field, path, verb)
+		fields.push(field)
+	}
+	return fields
+}
+
+/** Groups by a relation's target id, `null` when the caller cannot read it. */
+async function keyOf(context: Context, field: string): Promise<GroupKey> {
+	const known = context.model.fields.get(field)
+	if (known?.kind !== 'one') return { field }
+	const where = await context.scope.filter(known.target, false)
+	if (where === undefined) return { field }
+	return { field: 'id', through: [{ relation: field, where }] }
+}
+
+/**
+ * The keys of a `findMany`'s `distinct`, which a cursor cannot page (D-147):
+ * `undefined` without one.
+ */
+export async function distinctOf(
+	context: Context,
+	args: unknown,
+): Promise<GroupKey[] | undefined> {
+	if (!isObject(args) || args['distinct'] === undefined) return undefined
+	if (args['cursor'] !== undefined) {
+		throw new InvalidQuery('distinct', 'distinct cannot be used with cursor.')
+	}
+	const fields = grouping(context, args['distinct'], 'distinct')
+	return Promise.all(fields.map(async (field) => keyOf(context, field)))
+}
+
+/**
+ * An aggregate's position in a group's values, after its keys; one the
+ * result does not ask for is added to `aggregates`.
+ */
+const positions =
+	(by: readonly string[], aggregates: Asked[]): Position =>
+	(asked) => {
+		const index = aggregates.findIndex(
+			(each) => each.key === asked.key && each.field === asked.field,
+		)
+		if (index !== -1) return by.length + index
+		aggregates.push(asked)
+		return by.length + aggregates.length - 1
+	}
+
+/** The groups' sort: each key of `orderBy`, then the other fields of `by`. */
+function sorts(
+	context: Context,
+	value: unknown,
+	by: readonly string[],
+	at: Position,
+): Sort[] {
+	const parts: readonly unknown[] = Array.isArray(value) ? value : [value]
+	const sorted: Sort[] = []
+	for (const [index, part] of parts.entries()) {
+		const base = Array.isArray(value) ? `orderBy.${index}` : 'orderBy'
+		for (const [name, order] of entries(part, base)) {
+			const path = `${base}.${name}`
+			if (by.includes(name)) {
+				const known = context.model.fields.get(name)
+				const optional = known?.kind !== 'many' && known?.optional === true
+				sorted.push({ at: by.indexOf(name), ...sortOf(order, path, optional) })
+				continue
+			}
+			const key = keys.find((each): each is Key => each === name)
+			if (key === undefined) {
+				throw new InvalidQuery(
+					path,
+					`${path} must be a field of by or an aggregate.`,
+				)
+			}
+			if (key === '_count' && !isObject(order)) {
+				const asked = { key, field: undefined }
+				sorted.push({ at: at(asked), direction: direction(order, path) })
+				continue
+			}
+			for (const [field, each] of entries(order, path)) {
+				const asked = checked(context, key, field, `${path}.${field}`)
+				const sort = direction(each, `${path}.${field}`)
+				sorted.push({ at: at(asked), direction: sort })
+			}
+		}
+	}
+	for (const [index] of by.entries()) {
+		if (!sorted.some((sort) => sort.at === index)) {
+			sorted.push({ at: index, direction: 'asc' })
+		}
+	}
+	return sorted
+}
+
+export async function groupBy(
+	context: Context,
+	store: Store,
+	args: unknown,
+): Promise<unknown> {
+	const { model } = context
+	const allowed = ['by', 'where', 'having', 'orderBy', 'skip', 'take', ...keys]
+	const found = given(args, model.name, allowed, ['by'])
+	const by = grouping(context, found.get('by'), 'by')
+	const asked = wanted(context, found)
+	const aggregates = [...asked]
+	const position = positions(by, aggregates)
+	const orderBy = sorts(context, found.get('orderBy') ?? {}, by, position)
+	const filter = found.has('having')
+		? having(context, found.get('having'), by, position)
+		: undefined
+	const page: { skip?: number; take?: number } = {}
+	if (found.has('skip')) page.skip = integer(found.get('skip'), 'skip', 0)
+	if (found.has('take')) page.take = integer(found.get('take'), 'take', 0)
+	const where = await filtered(context, found, 'read')
+	const groupKeys = await Promise.all(
+		by.map(async (field) => keyOf(context, field)),
+	)
+	const groups = await store.aggregate({
+		model: model.name,
+		...(where && { where }),
+		aggregates: aggregates.map(toAggregate),
+		by: groupKeys,
+		...(filter && { having: filter }),
+		orderBy,
+		...page,
+	})
+	return groups.map((values) => {
+		const row: { [field: string]: unknown } = {}
+		for (const [index, field] of by.entries()) {
+			const value = values[index] ?? null
+			const relation = model.fields.get(field)?.kind === 'one'
+			row[field] = relation && value !== null ? { id: value } : value
+		}
+		return { ...row, ...shaped(found, asked, values.slice(by.length)) }
+	})
+}

package/src/group-having.ts

@@ -0,0 +1,143 @@
+// `groupBy`'s `having` (D-149), as Prisma's: a field of `by` filters the
+// groups by its value, any field by its aggregates, which the result need
+// not ask for. The adapter's filter names each value by its position in the
+// group's values, as `orderBy` does.
+import type { Condition, Filter } from './adapter.ts'
+import type { Asked, Key } from './aggregate.ts'
+import { checked, keys, typeOf } from './aggregate.ts'
+import { decimalPattern, normalized } from './decimal.ts'
+import { InvalidQuery } from './errors.ts'
+import type { Context } from './query-context.ts'
+import type { Operand } from './query-where.ts'
+import { entries, fieldCondition, isObject } from './query-where.ts'
+
+/** An aggregate's position in the group's values, added if not asked. */
+export type Position = (asked: Asked) => number
+
+const decimal = new RegExp(decimalPattern)
+
+const whole: Operand = {
+	type: 'number',
+	check: (item, at) => {
+		if (!Number.isSafeInteger(item)) {
+			throw new InvalidQuery(at, `${at} must be a whole number.`)
+		}
+		return item
+	},
+}
+
+const finite: Operand = {
+	type: 'number',
+	check: (item, at) => {
+		if (typeof item !== 'number' || !Number.isFinite(item)) {
+			throw new InvalidQuery(at, `${at} must be a finite number.`)
+		}
+		return item
+	},
+}
+
+/** A decimal's sum, exact at its field's scale, of any precision (D-145). */
+const sum = (scale: number): Operand => ({
+	type: 'decimal',
+	check: (item, at) => {
+		if (typeof item !== 'string' || !decimal.test(item)) {
+			throw new InvalidQuery(
+				at,
+				`${at} must be a decimal string, such as '12.50'.`,
+			)
+		}
+		return normalized(item, scale)
+	},
+})
+
+/**
+ * The operands of aggregate `key` of a field: a count's a whole number, a
+ * sum's and an average's a number, a decimal's sum a decimal string, a
+ * minimum's and a maximum's the field's own.
+ */
+function operandOf(
+	context: Context,
+	key: Key,
+	name: string,
+): Operand | undefined {
+	if (key === '_count') return whole
+	if (key === '_min' || key === '_max') return undefined
+	const field = context.model.fields.get(name)
+	return key === '_sum' && field?.kind === 'scalar' && field.type === 'decimal'
+		? sum(field.scale ?? 0)
+		: finite
+}
+
+type Parts = { [key: string]: Condition | Filter[] }
+
+/** The conditions of field `name`'s value and aggregates, by position. */
+function conditions(
+	context: Context,
+	name: string,
+	part: unknown,
+	at: string,
+	by: readonly string[],
+	position: Position,
+): Parts {
+	const { model, scope } = context
+	typeOf(model, name, at, 'used in having')
+	const found: Parts = {}
+	const own: [string, unknown][] = []
+	const listed = isObject(part) ? entries(part, at) : []
+	for (const [key, operand] of listed) {
+		const aggregate = keys.find((each): each is Key => each === key)
+		if (aggregate === undefined) {
+			own.push([key, operand])
+			continue
+		}
+		const where = `${at}.${key}`
+		const asked = checked(context, aggregate, name, where)
+		const of = operandOf(context, aggregate, name)
+		const condition = fieldCondition(model, name, operand, where, of)
+		if (condition !== undefined) found[String(position(asked))] = condition
+	}
+	if (isObject(part) && own.length === 0) return found
+	if (!by.includes(name)) {
+		throw new InvalidQuery(
+			at,
+			`${at} is not a field of by: only its aggregates filter the groups.`,
+		)
+	}
+	scope.check(model, name, at, 'filters')
+	const value = isObject(part) ? Object.fromEntries(own) : part
+	const condition = fieldCondition(model, name, value, at)
+	if (condition !== undefined) found[String(by.indexOf(name))] = condition
+	return found
+}
+
+/** The `having` of the groups by `by`, normalized; `path` names it in errors. */
+export function having(
+	context: Context,
+	value: unknown,
+	by: readonly string[],
+	position: Position,
+	path = 'having',
+): Filter {
+	const filter: Parts = {}
+	for (const [name, part] of entries(value, path)) {
+		const at = `${path}.${name}`
+		if (name !== 'AND' && name !== 'OR' && name !== 'NOT') {
+			Object.assign(filter, conditions(context, name, part, at, by, position))
+			continue
+		}
+		if (!Array.isArray(part) && name === 'OR') {
+			throw new InvalidQuery(at, `${at} must be a list.`)
+		}
+		const list: readonly unknown[] = Array.isArray(part) ? part : [part]
+		filter[name] = list.map((item, index) =>
+			having(
+				context,
+				item,
+				by,
+				position,
+				Array.isArray(part) ? `${at}.${index}` : at,
+			),
+		)
+	}
+	return filter
+}

package/src/hooks.ts

@@ -0,0 +1,215 @@
+// The fixed hooks of D-15 at run time (D-71, D-88): the plugins', then the
+// model's `.with` (D-89), run with their facts; `after*` hooks in the
+// transaction, the `*Commit` hooks once it commits.
+import { and, recordOf } from './access.ts'
+import type { Filter, Row } from './adapter.ts'
+import type { hookNames } from './plugin-code.ts'
+import { commandOf, outsideCommands } from './plugin-code.ts'
+import type { FindOperation } from './model.ts'
+import type { Caller } from './rules.ts'
+import type { Relations } from './relations.ts'
+import { trusted } from './relations.ts'
+import { filterOf, isReadFilter, readFilter } from './rules.ts'
+import type { ModelInfo } from './schema.ts'
+import type { Models } from './query-where.ts'
+import { isObject, normalizeWhere } from './query-where.ts'
+import type { Commit, Store } from './transaction.ts'
+
+type HookName = (typeof hookNames)[number]
+
+type Hook = {
+	/** Where it is written, for its errors. */
+	readonly path: string
+	readonly run: (facts: object) => Promise<unknown>
+}
+
+/** Runs a hook's body; the queries it makes run outside any command. */
+async function called(hook: Function, facts: object): Promise<unknown> {
+	return outsideCommands(async () => {
+		const result: unknown = await Reflect.apply(hook, undefined, [facts])
+		return result
+	})
+}
+
+/** The application's hook `name` of the model, from its `.with` (D-71). */
+function ownHook(model: ModelInfo, name: HookName): Hook | undefined {
+	const rules = model.definition.rules
+	const hooks =
+		rules !== undefined && isObject(rules) ? rules['hooks'] : undefined
+	if (hooks === undefined) return undefined
+	if (!isObject(hooks)) {
+		throw new TypeError(`${model.name}: hooks is an object.`)
+	}
+	const hook = hooks[name]
+	if (hook === undefined) return undefined
+	if (typeof hook !== 'function') {
+		throw new TypeError(`${model.name}.hooks.${name} is a function.`)
+	}
+	const path = `${model.name}.hooks.${name}`
+	return { path, run: async (facts) => called(hook, facts) }
+}
+
+/**
+ * The hooks `name` of the model: its plugins' first, in the order of
+ * `plugins`, then the application's (D-29). A plugin's facts add what its
+ * code gets of the model and the command running (D-89).
+ */
+function hooksOf(model: ModelInfo, name: HookName): readonly Hook[] {
+	const hooks: Hook[] = []
+	for (const use of model.plugins) {
+		const hook = use.code.hooks[name]
+		if (hook === undefined) continue
+		const plugin = use.code.name
+		hooks.push({
+			path: `${plugin}.hooks.${name} on ${model.name}`,
+			run: async (facts) =>
+				called(hook, {
+					...facts,
+					...use.model,
+					command: commandOf(model.name, plugin),
+				}),
+		})
+	}
+	const own = ownHook(model, name)
+	return own === undefined ? hooks : [...hooks, own]
+}
+
+export function hasHook(model: ModelInfo, name: HookName): boolean {
+	return hooksOf(model, name).length > 0
+}
+
+export async function runHook(
+	model: ModelInfo,
+	name: 'beforeCreate' | 'beforeUpdate' | 'beforeDelete',
+	facts: object,
+): Promise<void> {
+	for (const hook of hooksOf(model, name)) await hook.run(facts)
+}
+
+/** The filters every `beforeFind` ANDs into each read of the model (D-71). */
+export async function beforeFind(
+	models: Models,
+	model: ModelInfo,
+	caller: Caller,
+	operation: FindOperation,
+	relations: Relations,
+): Promise<Filter | undefined> {
+	let filter: Filter | undefined
+	for (const hook of hooksOf(model, 'beforeFind')) {
+		const result = await hook.run({ caller, operation, where: readFilter })
+		if (result === undefined) continue
+		if (!isReadFilter(result)) {
+			throw new TypeError(`${hook.path} returns where({ ... }) or nothing.`)
+		}
+		// Trusted server code, as a read rule's filter (D-86, D-88); the one
+		// filter of a plugin field (D-122).
+		const where = normalizeWhere(
+			models,
+			model,
+			filterOf(result),
+			hook.path,
+			trusted(relations),
+			true,
+		)
+		filter = and(where, filter)
+	}
+	return filter
+}
+
+/**
+ * The plugin's `redirect.delete`, which replaces the write of a `delete`,
+ * given `where: { id }` of the row found (D-15, D-89).
+ */
+export function redirectOf(
+	model: ModelInfo,
+): ((caller: Caller, id: string) => Promise<unknown>) | undefined {
+	const use = model.plugins.find((each) => each.code.redirect !== undefined)
+	const redirect = use?.code.redirect
+	if (use === undefined || redirect === undefined) return undefined
+	return async (caller, id) => {
+		const facts = { caller, where: { id }, ...use.model }
+		const result: unknown = await Reflect.apply(redirect, undefined, [facts])
+		return result
+	}
+}
+
+/** A row a write changed, whose `after*` hooks run once it is written. */
+export type Event =
+	| {
+			readonly model: ModelInfo
+			readonly operation: 'create'
+			readonly id: string
+	  }
+	| {
+			readonly model: ModelInfo
+			readonly operation: 'update' | 'delete'
+			readonly id: string
+			/** The stored row before the write. */
+			readonly before: Row
+	  }
+
+const names = {
+	create: ['afterCreate', 'afterCreateCommit'],
+	update: ['afterUpdate', 'afterUpdateCommit'],
+	delete: ['afterDelete', 'afterDeleteCommit'],
+} as const
+
+/** Whether an `after*` hook may change the rows, so the result is read again. */
+export function rereads(events: readonly Event[]): boolean {
+	return events.some((event) => hasHook(event.model, names[event.operation][0]))
+}
+
+/** Whether a hook follows the write, which then runs in a transaction. */
+export function settles(events: readonly Event[]): boolean {
+	return events.some((event) =>
+		names[event.operation].some((name) => hasHook(event.model, name)),
+	)
+}
+
+async function factsOf(
+	store: Store,
+	caller: Caller,
+	event: Event,
+): Promise<object> {
+	const { model, id } = event
+	if (event.operation === 'delete') {
+		return { caller, record: recordOf(model, event.before) }
+	}
+	// As written, whatever `beforeFind` hides (D-88).
+	const [row] = await store.find({
+		model: model.name,
+		where: { id: { equals: id } },
+		take: 1,
+	})
+	if (row === undefined) {
+		throw new Error(`${model.name} ${id} was deleted before its after hooks.`)
+	}
+	const record = recordOf(model, row)
+	if (event.operation === 'create') return { caller, record }
+	return { caller, record, previous: recordOf(model, event.before) }
+}
+
+/**
+ * Runs each event's `after*` hook in the transaction, and queues its
+ * `*Commit` hook, with the same facts, for after the commit (D-15, D-71).
+ */
+export async function settle(
+	store: Store,
+	caller: Caller,
+	events: readonly Event[],
+	commits: Commit[],
+): Promise<void> {
+	for (const event of events) {
+		const [now, later] = names[event.operation]
+		const afters = hooksOf(event.model, now)
+		const laters = hooksOf(event.model, later)
+		if (afters.length === 0 && laters.length === 0) continue
+		const facts = await factsOf(store, caller, event)
+		for (const hook of afters) await hook.run(facts)
+		for (const hook of laters) {
+			commits.push(async () => {
+				await hook.run(facts)
+			})
+		}
+	}
+}

package/src/hosts.ts

@@ -0,0 +1,11 @@
+// Which hosts are this machine's own, for the checks that trust them.
+
+/** A host only this machine reaches (D-66, D-105, D-115). */
+export function isLocalHost(hostname: string): boolean {
+	return (
+		hostname === 'localhost' ||
+		hostname.endsWith('.localhost') ||
+		hostname === '127.0.0.1' ||
+		hostname === '[::1]'
+	)
+}

package/src/identify.ts

@@ -0,0 +1,95 @@
+// How a transport finds who sends a request (D-49, D-106, D-112): Master with
+// the master key, then the first plugin that knows it, anonymous otherwise.
+import { createHash, timingSafeEqual } from 'node:crypto'
+import type { Logger, MasterKey } from './app-options.ts'
+import { PublicError, Refused } from './errors.ts'
+import type { Complete } from './complete.ts'
+import type { Caller, Identity } from './rules.ts'
+import { createMaster } from './rules.ts'
+
+/** The header a transport reads the master key from. */
+export const masterKeyHeader = 'x-ultimabase-master-key'
+
+export type Identify = (request: Request) => Promise<Caller>
+/** A plugin's `identify`, bound to its context. */
+export type PluginIdentify = (request: Request) => Promise<Identity | undefined>
+
+const anonymous: Caller = Object.freeze({ kind: 'anonymous' })
+const keyMaster = createMaster('key')
+
+// Digests have one length, so the comparison takes the same time for any key.
+const digest = (text: string): Buffer =>
+	createHash('sha256').update(text).digest()
+
+/** Why a request sending a key is refused before it is compared, if so. */
+function refusalOf(masterKey: MasterKey): string | undefined {
+	const key = typeof masterKey === 'object' ? masterKey.key : masterKey
+	// An empty variable is unset: an empty header must not open Master.
+	if (key === undefined || key === '') return 'No master key is configured.'
+	if (
+		process.env['NODE_ENV'] === 'production' &&
+		typeof masterKey !== 'object'
+	) {
+		return 'The master key is refused in production.'
+	}
+	return undefined
+}
+
+/**
+ * Reads the master key and `NODE_ENV` once, when the application starts.
+ * `plugins` is read on each request: it is filled once their contexts exist.
+ * The caller a plugin knows is completed (D-121).
+ */
+export function identifier(
+	masterKey: MasterKey,
+	logger: Logger,
+	plugins: readonly PluginIdentify[],
+	complete: Complete,
+): Identify {
+	const refusal = refusalOf(masterKey)
+	const key = typeof masterKey === 'object' ? masterKey.key : masterKey
+	// A header drops the spaces around a value and mangles what is not ASCII:
+	// such a key could never match.
+	if (key !== undefined && key !== '' && !/^[\x21-\x7e]+$/.test(key)) {
+		throw new Refused(
+			'The master key holds a space or a character outside ASCII, which a header cannot carry: use letters, digits and symbols only.',
+		)
+	}
+	const expected = digest(key ?? '')
+	// Outside production, the HTTP plugin's development log already shows
+	// each request (D-108); a use of the key is an audit line in production.
+	const audited = process.env['NODE_ENV'] === 'production'
+	// Nothing limits the keys a client tries: one that opens Master in
+	// production must not be guessed.
+	if (
+		audited &&
+		refusal === undefined &&
+		key !== undefined &&
+		key.length < 32
+	) {
+		throw new Refused(
+			`The master key is ${key.length} characters long; production needs 32 at least: \`openssl rand -base64 32\` gives one.`,
+		)
+	}
+	return async (request) => {
+		const sent = request.headers.get(masterKeyHeader)
+		if (sent === null) {
+			for (const identify of plugins) {
+				const caller = await identify(request)
+				if (caller !== undefined) return complete(caller)
+			}
+			return anonymous
+		}
+		const refused =
+			refusal ??
+			(timingSafeEqual(digest(sent), expected)
+				? undefined
+				: 'The master key is wrong.')
+		if (refused !== undefined) {
+			logger.warn(`A request sent the master key, refused: ${refused}`)
+			throw new PublicError('ACCESS_DENIED', refused)
+		}
+		if (audited) logger.info('A request acts as Master with the master key.')
+		return keyMaster
+	}
+}