ultimabase 0.0.0-stage → 0.1.0

package/src/schema-virtuals.ts

@@ -0,0 +1,134 @@
+// Virtual fields at startup (D-151): each one's output, input and needs
+// resolved, with the `run` or `runMany` its model's `.with` gives it.
+import type { ModelDefinition, Output } from './definition.ts'
+import { outputOf } from './definition.ts'
+import { Refused } from './errors.ts'
+import { isObject, systemFields } from './query-where.ts'
+import type { Standard } from './validation.ts'
+import { standardOf } from './validation.ts'
+
+export type VirtualInfo = {
+	readonly name: string
+	readonly model: string
+	readonly output: Output
+	readonly input: Standard | undefined
+	/** The scalar fields its rule reads, `id` first. */
+	readonly needs: readonly string[]
+	/** `runMany` takes the rows at once, `run` one by one. */
+	readonly many: boolean
+	readonly run: (facts: object) => unknown
+	/** A value without input is in the row without `select`. */
+	readonly default: boolean
+	readonly description: string | undefined
+}
+
+/** The keys that shape a model output's rows, which no input property takes. */
+const shaping = ['select', 'include', 'omit']
+
+/** An input's properties, from its JSON Schema export when it has one. */
+function propertiesOf(input: Standard): readonly string[] {
+	const exporter: unknown = Reflect.get(input.self, 'jsonSchema')
+	const exported = isObject(exporter) ? exporter['input'] : undefined
+	if (typeof exported !== 'function') return []
+	const node: unknown = Reflect.apply(exported, exporter, [
+		{ target: 'draft-2020-12' },
+	])
+	const properties = isObject(node) ? node['properties'] : undefined
+	return isObject(properties) ? Object.keys(properties) : []
+}
+
+function outputFor(value: unknown, where: string): Output {
+	const standard = standardOf(value)
+	if (standard !== undefined) return { kind: 'schema', schema: standard.schema }
+	if (typeof value !== 'function') {
+		throw new Refused(
+			`${where} is a Standard Schema, or a model or a type behind an arrow.`,
+		)
+	}
+	const returned: unknown = Reflect.apply(value, undefined, [])
+	return outputOf(returned, where)
+}
+
+function ruleOf(
+	given: { readonly [key: string]: unknown },
+	where: string,
+): { readonly many: boolean; readonly run: (facts: object) => unknown } {
+	const rule = given[where.slice(where.indexOf('.') + 1)]
+	if (!isObject(rule)) {
+		throw new Refused(
+			`${where} is virtual; give its run or runMany in .with({ virtuals }).`,
+		)
+	}
+	const { run, runMany } = rule
+	if ((typeof run === 'function') === (typeof runMany === 'function')) {
+		throw new Refused(`${where}: give run or runMany, one of them.`)
+	}
+	const chosen = typeof run === 'function' ? run : runMany
+	if (typeof chosen !== 'function') throw new TypeError('A rule is a function.')
+	return {
+		many: chosen === runMany,
+		run: (facts) => {
+			const value: unknown = Reflect.apply(chosen, rule, [facts])
+			return value
+		},
+	}
+}
+
+/** The virtual fields of a model, checked against its fields and models. */
+export function virtualsOf(
+	model: string,
+	definition: ModelDefinition,
+	models: ReadonlyMap<object, string>,
+): ReadonlyMap<string, VirtualInfo> {
+	const rules = isObject(definition.rules)
+		? definition.rules['virtuals']
+		: undefined
+	const given = isObject(rules) ? rules : {}
+	const virtuals = new Map<string, VirtualInfo>()
+	for (const name of Object.keys(given)) {
+		if (definition.fields.get(name)?.kind !== 'virtual') {
+			throw new Refused(`${model}.virtuals.${name} names no virtual field.`)
+		}
+	}
+	for (const [name, field] of definition.fields) {
+		if (field.kind !== 'virtual') continue
+		const where = `${model}.${name}`
+		const output = outputFor(field.output, where)
+		if (output.kind === 'model' && !models.has(output.value)) {
+			throw new Refused(`${where}: its output model is not in models.`)
+		}
+		const { input: schema, needs: listed, description } = field.options
+		const input = schema === undefined ? undefined : standardOf(schema)
+		if (schema !== undefined && input === undefined) {
+			throw new Refused(`${where}: input is a Standard Schema of an object.`)
+		}
+		for (const key of input === undefined ? [] : propertiesOf(input)) {
+			if (shaping.includes(key)) {
+				throw new Refused(
+					`${where}: no input property is named ${key}, which shapes a model's rows.`,
+				)
+			}
+		}
+		const needs: readonly unknown[] = Array.isArray(listed) ? listed : []
+		for (const need of needs) {
+			const scalar =
+				typeof need === 'string' &&
+				(systemFields.includes(need) ||
+					definition.fields.get(need)?.kind === 'scalar')
+			if (!scalar) {
+				throw new Refused(`${where} needs ${String(need)}, no scalar field.`)
+			}
+		}
+		virtuals.set(name, {
+			name,
+			model,
+			output,
+			input,
+			needs: [...new Set(['id', ...needs.map(String)])],
+			...ruleOf(given, where),
+			default: output.kind === 'schema' && input === undefined,
+			description: typeof description === 'string' ? description : undefined,
+		})
+	}
+	return virtuals
+}

package/src/schema.ts

@@ -0,0 +1,367 @@
+// The schema `start` resolves from the application's models: each relation
+// gets its inverse and the side that stores its key (D-37, D-54, D-64).
+import type { Schema, SchemaField, SchemaModel } from './adapter.ts'
+import type {
+	Codec,
+	FieldDefinition,
+	FieldOptions,
+	ModelDefinition,
+	PluginCode,
+	PluginUse,
+} from './definition.ts'
+import type { Digits } from './decimal.ts'
+import type { Enum } from './fields.ts'
+import { modelDefinitions } from './definition.ts'
+import { Refused } from './errors.ts'
+import { installedUses } from './plugin-use.ts'
+import { checkRelations, isFiltered, viewField } from './relations.ts'
+import { checkIndexes, checkSearch } from './schema-indexes.ts'
+import type { VirtualInfo } from './schema-virtuals.ts'
+import { virtualsOf } from './schema-virtuals.ts'
+
+/**
+ * A field as the kernel reads it: its schema, its builder's options, a
+ * plugin field type's codec (D-122) and its shared enum (D-150).
+ */
+export type FieldInfo = SchemaField & {
+	readonly options: FieldOptions
+	readonly codec?: Codec
+	readonly enum?: Enum
+}
+
+export type ModelInfo = {
+	readonly name: string
+	readonly definition: ModelDefinition
+	readonly fields: ReadonlyMap<string, FieldInfo>
+	/** The unique targets (D-52): `id`, unique fields, unique indexes. */
+	readonly uniques: readonly (readonly string[])[]
+	/** The plugins of its `use`, in the order of `plugins` (D-29). */
+	readonly plugins: readonly PluginUse[]
+	/** The plugin whose own model it is, if one (D-110). */
+	readonly owner: string | undefined
+	/** Its fields computed on read, which the adapter never sees (D-151). */
+	readonly virtuals: ReadonlyMap<string, VirtualInfo>
+}
+
+export type Resolved = {
+	readonly schema: Schema
+	readonly models: ReadonlyMap<string, ModelInfo>
+	/** The model each `defineModel` value stands for. */
+	readonly byValue: ReadonlyMap<object, ModelInfo>
+}
+
+type Relation = Extract<FieldDefinition, { readonly kind: 'one' | 'many' }>
+type Linked = {
+	readonly model: string
+	readonly name: string
+	readonly field: Relation
+	readonly target: string
+}
+
+function fail(message: string): never {
+	throw new Refused(message)
+}
+
+function inverseOf(link: Linked, links: readonly Linked[]): Linked {
+	const { model, name, target } = link
+	const where = `${model}.${name}`
+	const named = link.field.options['inverse']
+	const back = links.filter(
+		(other) =>
+			other.model === target &&
+			other.target === model &&
+			!(other.model === model && other.name === name),
+	)
+	if (typeof named === 'string') {
+		const found = links.find(
+			(other) => other.model === target && other.name === named,
+		)
+		if (found === undefined || found.target !== model) {
+			fail(
+				`${where}: inverse '${named}' is not a relation of ${target} to ${model}.`,
+			)
+		}
+		if (found.model === model && found.name === name) {
+			fail(`${where} cannot be its own inverse.`)
+		}
+		return found
+	}
+	const candidates = back.filter((other) => {
+		const theirs = other.field.options['inverse']
+		return typeof theirs !== 'string' || theirs === name
+	})
+	const [only, ...others] = candidates
+	if (only === undefined) {
+		fail(`${where}: ${target} has no relation to ${model}; add its side.`)
+	}
+	if (others.length > 0) {
+		fail(
+			`${where}: ${target} has several relations to ${model}; name one with \`inverse\`.`,
+		)
+	}
+	return only
+}
+
+function relationField(link: Linked, inverse: Linked): FieldInfo {
+	const { field } = link
+	const optional = field.options['optional'] === true
+	const where = `${link.model}.${link.name}`
+	if (field.kind === 'many') {
+		return {
+			kind: 'many',
+			name: link.name,
+			target: link.target,
+			inverse: inverse.name,
+			join: inverse.field.kind === 'many',
+			options: field.options,
+		}
+	}
+	let stored = inverse.field.kind === 'many'
+	if (inverse.field.kind === 'one') {
+		const theirs = inverse.field.options['optional'] === true
+		if (optional === theirs) {
+			fail(
+				`${where} and ${inverse.model}.${inverse.name}: make one side of a one-to-one relation optional.`,
+			)
+		}
+		stored = !optional
+	}
+	const asked = field.options['onDelete']
+	if (!stored && asked !== undefined) {
+		fail(
+			`${where}: onDelete belongs on ${inverse.model}.${inverse.name}, which stores the key.`,
+		)
+	}
+	if (asked === 'setNull' && !optional) {
+		throw new Refused(`${where}: setNull needs an optional relation.`)
+	}
+	const onDelete =
+		asked === 'cascade' || asked === 'restrict' || asked === 'setNull'
+			? asked
+			: optional
+				? 'setNull'
+				: 'restrict'
+	const dbName = field.options['dbName']
+	return {
+		kind: 'one',
+		name: link.name,
+		target: link.target,
+		inverse: inverse.name,
+		stored,
+		unique: stored && inverse.field.kind === 'one',
+		optional,
+		onDelete,
+		...(typeof dbName === 'string' ? { dbName } : {}),
+		options: field.options,
+	}
+}
+
+/** A decimal's precision and scale, which its builder checked (D-145). */
+const digitsOf = (options: FieldOptions): Digits => ({
+	precision: Number(options['precision']),
+	scale: Number(options['scale']),
+})
+
+function scalarField(name: string, field: FieldDefinition): FieldInfo {
+	if (field.kind !== 'scalar') throw new Error('Expected a scalar field.')
+	const dbName = field.options['dbName']
+	// A field type's default is a value code sees, never a column's; its
+	// stored field's fills the rows stored before it (D-122, D-152).
+	const fixed: unknown =
+		field.codec === undefined ? field.options['default'] : field.codec.filled
+	return {
+		kind: 'scalar',
+		name,
+		type: field.type,
+		...(field.values === undefined ? {} : { values: field.values }),
+		list: field.options['list'] === true,
+		...(field.type === 'number' && field.options['integer'] === true
+			? { integer: true }
+			: {}),
+		...(field.type === 'decimal' ? digitsOf(field.options) : {}),
+		optional: field.options['optional'] === true,
+		unique: field.options['unique'] === true,
+		...(field.options['search'] === true ? { search: true } : {}),
+		...(typeof dbName === 'string' ? { dbName } : {}),
+		// `null` is no value: a create without one stores none either.
+		...(fixed === undefined || fixed === null || typeof fixed === 'function'
+			? {}
+			: { default: fixed }),
+		options: field.options,
+		...(field.codec === undefined ? {} : { codec: field.codec }),
+		...(field.enum === undefined ? {} : { enum: field.enum }),
+	}
+}
+
+/** A field as the adapter reads it, without the builder's options. */
+function schemaField(model: ModelInfo, field: FieldInfo): SchemaField {
+	const { options: _options, codec: _codec, enum: _enum, ...schema } = field
+	if (schema.kind !== 'many' || !isFiltered(model, field.name)) return schema
+	return { ...schema, filtered: true }
+}
+
+const whose = (owner: string | undefined): string =>
+	owner === undefined ? 'models lists' : `${owner}.models lists`
+
+/** The models, the application's then each plugin's, by name (D-110). */
+function definitionsOf(
+	values: readonly unknown[],
+	plugins: readonly PluginCode[],
+): {
+	readonly definitions: ReadonlyMap<string, ModelDefinition>
+	readonly names: ReadonlyMap<object, string>
+	readonly owners: ReadonlyMap<string, string | undefined>
+} {
+	const definitions = new Map<string, ModelDefinition>()
+	const names = new Map<object, string>()
+	const owners = new Map<string, string | undefined>()
+	const lists: [string | undefined, readonly unknown[]][] = [
+		[undefined, values],
+		...plugins.map((code): [string, readonly unknown[]] => [
+			code.name,
+			code.models,
+		]),
+	]
+	for (const [owner, list] of lists) {
+		for (const value of list) {
+			const definition =
+				typeof value === 'object' && value !== null
+					? modelDefinitions.get(value)
+					: undefined
+			if (
+				definition === undefined ||
+				typeof value !== 'object' ||
+				value === null
+			) {
+				throw new Refused(
+					`${whose(owner)} a value that defineModel did not return.`,
+				)
+			}
+			const { name } = definition
+			if (owners.has(name)) {
+				const other = owners.get(name)
+				throw new Refused(
+					owner === other
+						? `${whose(owner)} two models named ${name}.`
+						: `${whose(owner)} a model named ${name}, as ${whose(other)}; name a plugin's models after it.`,
+				)
+			}
+			definitions.set(name, definition)
+			names.set(value, name)
+			owners.set(name, owner)
+		}
+	}
+	return { definitions, names, owners }
+}
+
+/** Resolves the application's models, or stops startup with a message. */
+export function resolve(
+	values: readonly unknown[],
+	plugins: readonly PluginCode[] = [],
+): Resolved {
+	const { definitions, names, owners } = definitionsOf(values, plugins)
+	const links: Linked[] = []
+	const views: Linked[] = []
+	for (const [model, definition] of definitions) {
+		for (const [name, field] of definition.fields) {
+			if (field.kind === 'scalar' || field.kind === 'virtual') continue
+			const value = field.target()
+			const target =
+				typeof value === 'object' && value !== null
+					? names.get(value)
+					: undefined
+			if (target === undefined) {
+				throw new Refused(`${model}.${name}: its target is not in models.`)
+			}
+			const owner = owners.get(model)
+			if (owner !== owners.get(target)) {
+				throw new Refused(
+					`${model}.${name}: a plugin's model relates only to models of the same plugin; keep the id as a scalar.`,
+				)
+			}
+			// A view reads the link of another relation (D-151).
+			const from = field.kind === 'many' ? field.options['from'] : undefined
+			const link = { model, name, field, target }
+			;(typeof from === 'string' ? views : links).push(link)
+		}
+	}
+	const inverses = new Map(links.map((link) => [link, inverseOf(link, links)]))
+	for (const [link, inverse] of inverses) {
+		if (inverses.get(inverse) !== link) {
+			fail(
+				`${link.model}.${link.name} and ${inverse.model}.${inverse.name} do not name each other.`,
+			)
+		}
+	}
+	const linkOf = (list: readonly Linked[], model: string, name: string) =>
+		list.find((each) => each.model === model && each.name === name)
+	const relationOf = (model: string, name: string): FieldInfo | undefined => {
+		const link = linkOf(links, model, name)
+		const inverse = link && inverses.get(link)
+		return link && inverse ? relationField(link, inverse) : undefined
+	}
+	const fieldOf = (model: string, name: string, field: FieldDefinition) => {
+		const view = linkOf(views, model, name)
+		if (view === undefined) {
+			return relationOf(model, name) ?? scalarField(name, field)
+		}
+		const from = String(field.options['from'])
+		return viewField(
+			{ model, name, target: view.target, options: field.options },
+			from,
+			linkOf(views, model, from) ? 'view' : relationOf(model, from),
+		)
+	}
+	const models = new Map<string, ModelInfo>()
+	const byValue = new Map<object, ModelInfo>()
+	const schemaModels: SchemaModel[] = []
+	for (const [model, definition] of definitions) {
+		const fields = new Map<string, FieldInfo>()
+		for (const [name, field] of definition.fields) {
+			// A virtual is no field of the adapter's (D-151).
+			if (field.kind === 'virtual') continue
+			const plugin = field.kind === 'scalar' ? field.codec?.plugin : undefined
+			if (plugin !== undefined && !plugins.some((p) => p.name === plugin)) {
+				fail(
+					`${model}.${name} is a ${plugin} field, and ${plugin} is not in plugins.`,
+				)
+			}
+			fields.set(name, fieldOf(model, name, field))
+		}
+		checkIndexes(model, fields, definition.indexes)
+		const uniques: (readonly string[])[] = [['id']]
+		for (const field of fields.values()) {
+			if (field.kind === 'scalar' && field.unique) uniques.push([field.name])
+		}
+		for (const index of definition.indexes) {
+			if (index.unique === true) uniques.push(index.fields)
+		}
+		const info: ModelInfo = {
+			name: model,
+			definition,
+			fields,
+			uniques,
+			plugins: installedUses(definition, plugins),
+			owner: owners.get(model),
+			virtuals: virtualsOf(model, definition, names),
+		}
+		checkSearch(info)
+		checkRelations(info)
+		models.set(model, info)
+		schemaModels.push({
+			name: model,
+			...(definition.dbName === undefined ? {} : { dbName: definition.dbName }),
+			fields: [...fields.values()].map((field) => schemaField(info, field)),
+			indexes: definition.indexes.map((index) => ({
+				fields: index.fields,
+				unique: index.unique === true,
+				contains: index.contains === true,
+			})),
+		})
+	}
+	for (const [value, name] of names) {
+		const info = models.get(name)
+		if (info !== undefined) byValue.set(value, info)
+	}
+	return { schema: { models: schemaModels }, models, byValue }
+}

package/src/scope.ts

@@ -0,0 +1,123 @@
+// The filters one query reads through (D-71, D-86, D-88): the caller's read
+// rules and the `beforeFind` of each model the query reaches, run once per
+// operation (D-124).
+import type { Access } from './access.ts'
+import { and } from './access.ts'
+import type { Filter } from './adapter.ts'
+import { beforeFind } from './hooks.ts'
+import type { FindOperation } from './model.ts'
+import type { Caller } from './rules.ts'
+import { Relations } from './relations.ts'
+import type { FieldInfo, ModelInfo } from './schema.ts'
+import type { Models, Scope, Verb } from './query-where.ts'
+import { modelOf } from './query-where.ts'
+
+/**
+ * `readable` is synchronous, as the planning that calls it, but `beforeFind`
+ * may not be: a model read before its hook ran is recorded, and `ready` runs
+ * the hooks so the query can be planned again with their filters.
+ */
+export class QueryScope implements Scope {
+	/** By `operation name`, as `read Post`. */
+	private readonly narrowed = new Map<string, Filter | undefined>()
+	private readonly wanted = new Map<
+		string,
+		{ readonly name: string; readonly operation: FindOperation }
+	>()
+	readonly models: Models
+	readonly caller: Caller
+	/** `undefined` for Master, which skips access rules (D-48). */
+	readonly access: Access | undefined
+	private readonly relations: Relations
+
+	constructor(models: Models, caller: Caller, access: Access | undefined) {
+		this.models = models
+		this.caller = caller
+		this.access = access
+		this.relations = access?.relations ?? new Relations(models, caller)
+	}
+
+	check(model: ModelInfo, field: string, path: string, verb: Verb): void {
+		this.access?.check(model, field, path, verb)
+	}
+
+	ruled(model: ModelInfo, field: string): boolean {
+		return this.access?.ruled(model, field) ?? false
+	}
+
+	/**
+	 * The rows of `name` the query reads, or the write `operation` targets:
+	 * its read rule and `beforeFind`.
+	 */
+	readable(
+		name: string,
+		operation: FindOperation = 'read',
+	): Filter | undefined {
+		return and(this.narrowing(name, operation), this.access?.readable(name))
+	}
+
+	related(
+		model: ModelInfo,
+		field: Extract<FieldInfo, { readonly kind: 'many' }>,
+	): Filter | undefined {
+		return and(this.relations.filter(model, field), this.readable(field.target))
+	}
+
+	/**
+	 * Runs the `beforeFind` hooks of the models read since the last call;
+	 * whether one of them narrows, so the query must be planned again.
+	 */
+	async ready(): Promise<boolean> {
+		let narrowed = false
+		for (const [key, { name, operation }] of this.wanted) {
+			this.wanted.delete(key)
+			const model = modelOf(this.models, name)
+			const filter = await beforeFind(
+				this.models,
+				model,
+				this.caller,
+				operation,
+				this.relations,
+			)
+			this.narrowed.set(key, filter)
+			if (filter !== undefined) narrowed = true
+		}
+		return narrowed
+	}
+
+	/**
+	 * The rows of `name` a write reaches; `trusted` for a value a hook or a
+	 * default wrote, which skips access rules but not `beforeFind` (D-67).
+	 */
+	async filter(
+		name: string,
+		trusted: boolean,
+		operation: FindOperation = 'read',
+	): Promise<Filter | undefined> {
+		this.narrowing(name, operation)
+		await this.ready()
+		return trusted
+			? this.narrowing(name, operation)
+			: this.readable(name, operation)
+	}
+
+	private narrowing(
+		name: string,
+		operation: FindOperation,
+	): Filter | undefined {
+		const key = `${operation} ${name}`
+		if (this.narrowed.has(key)) return this.narrowed.get(key)
+		this.wanted.set(key, { name, operation })
+		return undefined
+	}
+}
+
+/** Plans a query, then again once the `beforeFind` hooks it reached ran. */
+export async function planned<T>(
+	scope: QueryScope,
+	build: () => T,
+): Promise<T> {
+	let built = build()
+	while (await scope.ready()) built = build()
+	return built
+}

package/src/scratch.ts

@@ -0,0 +1,28 @@
+// A test file's own tables on a database that keeps them (D-137): the
+// adapter says how it gives them, and `testApplication` asks for them.
+import type { Adapter } from './adapter.ts'
+
+/**
+ * The tables of one test file: until `drop`, each start of the adapter
+ * finds them empty, and no other table is read or written.
+ */
+export type Scratch = {
+	/** Drops them; the adapter's next start is on its own tables again. */
+	readonly drop: () => Promise<void>
+}
+
+const scratches = new WeakMap<Adapter, () => Scratch>()
+
+/** Remembers how `adapter` gives a test file its own tables. */
+export function scratchable<T extends Adapter>(
+	adapter: T,
+	scratch: () => Scratch,
+): T {
+	scratches.set(adapter, scratch)
+	return adapter
+}
+
+/** How `adapter` gives a test file its own tables, if it can. */
+export function scratchOf(adapter: Adapter): (() => Scratch) | undefined {
+	return scratches.get(adapter)
+}

package/src/serve.ts

@@ -0,0 +1,5 @@
+// What `ultimabase dev` runs under `node --watch` (D-105): the application
+// of the config file it is given.
+import { serve } from './cli-main.ts'
+
+process.exitCode = await serve(process.argv[2])

package/src/symbols.ts

@@ -0,0 +1,11 @@
+// Keys that carry types only. They never exist at runtime and stay out of
+// autocompletion on models and fields.
+export declare const modelFields: unique symbol
+export declare const fieldType: unique symbol
+export declare const declaredRecord: unique symbol
+export declare const pluginTypes: unique symbol
+export declare const readFilter: unique symbol
+export declare const typeFields: unique symbol
+export declare const nullableOf: unique symbol
+/** Marks a calendar day's options, a string compared in order (D-150). */
+export declare const calendarDay: unique symbol