ultimabase 0.0.0-stage → 0.1.0

package/src/relation-write.ts

@@ -0,0 +1,176 @@
+// A relation write's operations (D-20, D-128, D-138), their shape checked:
+// `connect`, `connectOrCreate` and `create`, and in an update `delete`,
+// `disconnect`, `update` and, on a `many`, `set`.
+import { InvalidQuery } from './errors.ts'
+import { clean, entries, isObject, unknownKey } from './query-where.ts'
+import type { Draft } from './write-data.ts'
+
+/** `{ id }`, exactly. */
+function ref(value: unknown, path: string): string {
+	const given = entries(value, path)
+	const [first] = given
+	if (
+		given.length !== 1 ||
+		first?.[0] !== 'id' ||
+		typeof first[1] !== 'string' ||
+		!clean(first[1])
+	) {
+		throw new InvalidQuery(path, `${path} must be { id }.`)
+	}
+	return first[1]
+}
+
+/** The operations a relation write takes (D-128, D-138). */
+function allowed(kind: 'one' | 'many', creating: boolean): readonly string[] {
+	if (creating) return ['connect', 'connectOrCreate', 'create']
+	const changing = kind === 'one' ? ['update'] : ['set', 'update']
+	return [
+		'connect',
+		'connectOrCreate',
+		'create',
+		'delete',
+		'disconnect',
+		...changing,
+	].toSorted()
+}
+
+function operations(
+	value: unknown,
+	path: string,
+	model: string,
+	kind: 'one' | 'many',
+	creating: boolean,
+): Map<string, unknown> {
+	if (value === null) {
+		throw new InvalidQuery(path, `${path} cannot be null; use disconnect.`)
+	}
+	const given = new Map(entries(value, path))
+	for (const key of given.keys()) {
+		if (!allowed(kind, creating).includes(key))
+			throw unknownKey(`${path}.${key}`, model)
+	}
+	return given
+}
+
+/** Data a nested `create` or `update` writes (D-128, D-138). */
+function made(value: unknown, path: string): Draft {
+	if (!isObject(value)) {
+		throw new InvalidQuery(path, `${path} must be an object.`)
+	}
+	return value
+}
+
+/** An object of exactly `keys`. */
+function exactly(
+	value: unknown,
+	path: string,
+	keys: readonly [string, string],
+): Map<string, unknown> {
+	const given = new Map(entries(value, path))
+	if (given.size !== 2 || !keys.every((key) => given.has(key))) {
+		throw new InvalidQuery(path, `${path} must be { ${keys.join(', ')} }.`)
+	}
+	return given
+}
+
+/** A `connectOrCreate`: the unique target it looks for, the row it creates. */
+export type OrCreate = { readonly where: unknown; readonly create: Draft }
+
+function orCreate(value: unknown, path: string): OrCreate {
+	const given = exactly(value, path, ['where', 'create'])
+	return {
+		where: given.get('where'),
+		create: made(given.get('create'), `${path}.create`),
+	}
+}
+
+/** A `many` relation's `update`: a unique target, and its data. */
+export type Updating = { readonly where: unknown; readonly data: Draft }
+
+function updating(value: unknown, path: string): Updating {
+	const given = exactly(value, path, ['where', 'data'])
+	return {
+		where: given.get('where'),
+		data: made(given.get('data'), `${path}.data`),
+	}
+}
+
+function list(value: unknown, path: string): readonly unknown[] {
+	if (!Array.isArray(value))
+		throw new InvalidQuery(path, `${path} must be a list.`)
+	return value
+}
+
+/** A `one` relation write. */
+export type OneWrite =
+	| { readonly kind: 'connect'; readonly id: string }
+	| { readonly kind: 'create'; readonly data: Draft }
+	| ({ readonly kind: 'connectOrCreate' } & OrCreate)
+	| { readonly kind: 'update'; readonly data: Draft }
+	| { readonly kind: 'delete' }
+	| { readonly kind: 'disconnect' }
+
+export function oneWrite(
+	value: unknown,
+	path: string,
+	model: string,
+	creating: boolean,
+): OneWrite {
+	const given = operations(value, path, model, 'one', creating)
+	const [entry] = given
+	if (entry === undefined || given.size !== 1) {
+		throw new InvalidQuery(
+			path,
+			`${path} takes one of ${allowed('one', creating).join(', ')}.`,
+		)
+	}
+	const [key, operand] = entry
+	const at = `${path}.${key}`
+	if (key === 'connect') return { kind: key, id: ref(operand, at) }
+	if (key === 'create' || key === 'update') {
+		return { kind: key, data: made(operand, at) }
+	}
+	if (key === 'connectOrCreate') return { kind: key, ...orCreate(operand, at) }
+	if (operand !== true) throw new InvalidQuery(at, `${at} must be true.`)
+	return { kind: key === 'delete' ? 'delete' : 'disconnect' }
+}
+
+/** A `many` relation write, each operation's list. */
+export type ManyWrite = {
+	readonly connect: string[]
+	readonly disconnect: string[]
+	readonly create: Draft[]
+	readonly set: string[] | undefined
+	readonly connectOrCreate: OrCreate[]
+	readonly update: Updating[]
+	readonly delete: unknown[]
+}
+
+export function manyWrite(
+	value: unknown,
+	path: string,
+	model: string,
+	creating: boolean,
+): ManyWrite {
+	const given = operations(value, path, model, 'many', creating)
+	const each = <T>(key: string, read: (item: unknown, at: string) => T): T[] =>
+		list(given.get(key) ?? [], `${path}.${key}`).map((item, index) =>
+			read(item, `${path}.${key}.${index}`),
+		)
+	if (given.has('set') && (given.has('connect') || given.has('disconnect'))) {
+		throw new InvalidQuery(
+			`${path}.set`,
+			`${path}.set cannot be used with connect or disconnect.`,
+		)
+	}
+	return {
+		// A row disconnected and connected again stays linked (D-101).
+		connect: each('connect', ref),
+		disconnect: each('disconnect', ref),
+		create: each('create', made),
+		set: given.has('set') ? each('set', ref) : undefined,
+		connectOrCreate: each('connectOrCreate', orCreate),
+		update: each('update', updating),
+		delete: each('delete', (item) => item),
+	}
+}

package/src/relations.ts

@@ -0,0 +1,165 @@
+// The filter of a `many` relation, from its model's `.with({ relations })`
+// (D-151): every read of the relation sees only the rows it keeps, Master's
+// too, and a filtered relation takes no `set`.
+import type { Filter } from './adapter.ts'
+import type { FieldOptions } from './definition.ts'
+import { InvalidQuery, Refused } from './errors.ts'
+import type { Models, Scope } from './query-where.ts'
+import { isObject, modelOf, normalizeWhere } from './query-where.ts'
+import type { Caller } from './rules.ts'
+import { filterOf, isReadFilter, readFilter } from './rules.ts'
+import type { FieldInfo, ModelInfo } from './schema.ts'
+
+type Many = Extract<FieldInfo, { readonly kind: 'many' }>
+
+function relationsOf(model: ModelInfo): { readonly [field: string]: unknown } {
+	const { rules } = model.definition
+	const relations = isObject(rules) ? rules['relations'] : undefined
+	return isObject(relations) ? relations : {}
+}
+
+/**
+ * Stops startup on a filter that names no `many` of the model, or on a view
+ * without one (D-151).
+ */
+export function checkRelations(model: ModelInfo): void {
+	for (const [name, rule] of Object.entries(relationsOf(model))) {
+		const where = `${model.name}.with.relations.${name}`
+		if (model.fields.get(name)?.kind !== 'many') {
+			throw new Refused(`${where}: ${name} is not a many relation.`)
+		}
+		if (!isObject(rule) || typeof rule['where'] !== 'function') {
+			throw new Refused(`${where} takes a where function.`)
+		}
+	}
+	for (const field of model.fields.values()) {
+		if (field.kind === 'many' && field.from !== undefined) {
+			if (!isFiltered(model, field.name)) {
+				throw new Refused(
+					`${model.name}.${field.name} is a view; filter it in .with({ relations }).`,
+				)
+			}
+		}
+	}
+}
+
+/**
+ * A view (D-151): `source`, the `many` its `from` names, under its own name
+ * and options. Stops startup unless `from` names a `many` of the model to the
+ * same target that is no view.
+ */
+export function viewField(
+	view: {
+		readonly model: string
+		readonly name: string
+		readonly target: string
+		readonly options: FieldOptions
+	},
+	from: string,
+	source: FieldInfo | 'view' | undefined,
+): FieldInfo {
+	const { model, name, target, options } = view
+	const at = `${model}.${name}`
+	if (options['inverse'] !== undefined) {
+		throw new Refused(`${at} is a view and takes no inverse.`)
+	}
+	if (source === 'view') {
+		throw new Refused(`${at}: from '${from}' is a view; name its relation.`)
+	}
+	if (source?.kind !== 'many') {
+		throw new Refused(`${at}: from '${from}' is not a many relation.`)
+	}
+	if (source.target !== target) {
+		throw new Refused(
+			`${at}: from '${from}' relates to ${source.target}, not ${target}.`,
+		)
+	}
+	return { ...source, name, from, options }
+}
+
+/** Whether `.with({ relations })` filters `field` of `model`. */
+export function isFiltered(model: ModelInfo, field: string): boolean {
+	return Object.hasOwn(relationsOf(model), field)
+}
+
+/** Fails on a `set` of a filtered relation, which would detach hidden rows. */
+export function refuseSet(model: ModelInfo, field: string, path: string): void {
+	if (!isFiltered(model, field)) return
+	throw new InvalidQuery(
+		path,
+		`${model.name}.${field} is filtered; use connect and disconnect, not set.`,
+	)
+}
+
+/** No row passes: a filter that returns `false`. */
+const closed: Filter = { OR: [] }
+const pending = Symbol('pending')
+
+/** The relation filters of one query, run once each for its caller. */
+export class Relations {
+	private readonly filters = new Map<
+		string,
+		Filter | undefined | typeof pending
+	>()
+	private readonly models: Models
+	private readonly caller: Caller
+
+	constructor(models: Models, caller: Caller) {
+		this.models = models
+		this.caller = caller
+	}
+
+	/** The rows of `model.field` its filter keeps; `undefined` for all. */
+	filter(model: ModelInfo, field: Many): Filter | undefined {
+		const key = `${model.name}.${field.name}`
+		const known = this.filters.get(key)
+		if (known === pending) {
+			throw new TypeError(`${key}: its filter reads the relation itself.`)
+		}
+		if (this.filters.has(key)) return known
+		const rule = relationsOf(model)[field.name]
+		this.filters.set(key, pending)
+		const filter = isObject(rule)
+			? this.run(model, field, rule['where'])
+			: undefined
+		this.filters.set(key, filter)
+		return filter
+	}
+
+	private run(
+		model: ModelInfo,
+		field: Many,
+		rule: unknown,
+	): Filter | undefined {
+		const path = `${model.name}.with.relations.${field.name}.where`
+		if (typeof rule !== 'function')
+			throw new TypeError(`${path} is a function.`)
+		const result: unknown = Reflect.apply(rule, undefined, [
+			{ caller: this.caller, where: readFilter },
+		])
+		if (result === true) return undefined
+		if (result === false) return closed
+		if (!isReadFilter(result)) {
+			throw new TypeError(`${path} returns where({ ... }) or a boolean.`)
+		}
+		const target = modelOf(this.models, field.target)
+		// Trusted server code, as a read rule's own filter (D-86).
+		return normalizeWhere(
+			this.models,
+			target,
+			filterOf(result),
+			path,
+			trusted(this),
+		)
+	}
+}
+
+/** The scope of trusted filters: no access rule, relation filters only. */
+export function trusted(relations: Relations): Scope {
+	return {
+		check: () => undefined,
+		ruled: () => false,
+		readable: () => undefined,
+		related: (model, field) => relations.filter(model, field),
+	}
+}

package/src/rules.ts

@@ -0,0 +1,188 @@
+// What every access rule receives, and the kernel's ready-made rules (D-10).
+import type { RecordOf } from './record.ts'
+import type { modelFields } from './symbols.ts'
+
+export type Operation = 'read' | 'create' | 'update' | 'delete'
+
+/**
+ * The application declares its user model here, once; without it,
+ * `caller.user` is `{ id }` (D-24, D-62).
+ */
+export interface Register {}
+
+/** The user record a registry gives `caller.user`. */
+export type UserOf<R> = R extends {
+	readonly user: { readonly [modelFields]: infer F }
+}
+	? RecordOf<F>
+	: { readonly id: string }
+
+/**
+ * The keys plugins add to a user caller, each plugin declaring its own
+ * (D-121): `declare module 'ultimabase' { interface UserCallerKeys { ... } }`.
+ */
+export interface UserCallerKeys {}
+
+type Master = {
+	readonly kind: 'master'
+	readonly master: { readonly source: 'code' | 'key' }
+}
+
+/**
+ * Who code says sends an operation, as `as` and a plugin's `identify` give
+ * it: a user caller without the keys plugins add (D-121).
+ */
+export type Identity =
+	| { readonly kind: 'anonymous' }
+	| { readonly kind: 'user'; readonly user: UserOf<Register> }
+	| Master
+
+/** Who sends an operation, as rules, hooks and functions see it (D-19). */
+export type Caller =
+	| { readonly kind: 'anonymous' }
+	| ({
+			readonly kind: 'user'
+			readonly user: UserOf<Register>
+	  } & UserCallerKeys)
+	| Master
+
+const masters = new WeakSet<object>()
+
+/** A Master caller; the kernel's code and transports only (D-19, D-49). */
+export function createMaster(source: 'code' | 'key'): Master {
+	const caller: Master = Object.freeze({
+		kind: 'master',
+		master: Object.freeze({ source }),
+	})
+	masters.add(caller)
+	return caller
+}
+
+/** Whether a caller is a Master the kernel created. */
+export function isMaster(caller: object): caller is Master {
+	return masters.has(caller)
+}
+
+/** Server code acting with every right; only the kernel creates it. */
+export const master: Master = createMaster('code')
+
+/** A rule that reads only the caller and the operation fits any access key. */
+export type AnyRule = (facts: {
+	readonly caller: Caller
+	readonly operation: Operation
+}) => boolean
+
+/** A rule that reads only the caller also fits a function's access (D-27). */
+export type CallerRule = (facts: { readonly caller: Caller }) => boolean
+
+type Allow = {
+	readonly public: CallerRule
+	readonly readOnly: AnyRule
+	readonly private: CallerRule
+}
+
+/** Open to everyone, open to reads, closed to everyone but Master (D-10). */
+export const allow: Allow = Object.freeze({
+	public: () => true,
+	readOnly: ({ operation }) => operation === 'read',
+	private: () => false,
+})
+
+const filters = new WeakMap<object, unknown>()
+
+/** The read filter a read rule's `where` returns (D-10). */
+export function readFilter(where: unknown): object {
+	const token = Object.freeze({})
+	filters.set(token, where)
+	return token
+}
+
+/** Whether a rule's result is a read filter. */
+export function isReadFilter(value: unknown): value is object {
+	return typeof value === 'object' && value !== null && filters.has(value)
+}
+
+/** The `where` a read filter holds. */
+export function filterOf(token: object): unknown {
+	return filters.get(token)
+}
+
+type Results = { readonly decided: boolean; readonly filters: object[] }
+
+// A rule returns a boolean, or a filter in a read rule (D-76, D-81).
+function collect(
+	rules: readonly Rule[],
+	facts: unknown,
+	decisive: boolean,
+): Results {
+	const found: object[] = []
+	for (const rule of rules) {
+		const result: unknown = Reflect.apply(rule, undefined, [facts])
+		if (result === decisive) return { decided: true, filters: [] }
+		if (isReadFilter(result)) found.push(result)
+		else if (typeof result !== 'boolean') {
+			throw new TypeError('A rule returns a boolean or a read filter.')
+		}
+	}
+	return { decided: false, filters: found }
+}
+
+function combine(
+	rules: readonly Rule[],
+	decisive: boolean,
+	operator: 'AND' | 'OR',
+): (facts: unknown) => unknown {
+	return (facts) => {
+		const { decided, filters: found } = collect(rules, facts, decisive)
+		if (decided) return decisive
+		const [first, ...others] = found
+		if (first === undefined) return !decisive
+		if (others.length === 0) return first
+		return readFilter({ [operator]: found.map(filterOf) })
+	}
+}
+type Rule = (facts: never) => unknown
+
+/** A rule already typed, such as a `const` holding `signedIn(...)`. */
+type Named = (facts: never) => unknown
+type Both<U> = (U extends unknown ? (u: U) => void : never) extends (
+	u: infer I,
+) => void
+	? I
+	: never
+/** The rule combining named rules: it needs every rule's facts. */
+type Combined<Rules extends readonly Named[]> = (
+	facts: Both<Parameters<Rules[number]>[0]>,
+) => ReturnType<Rules[number]>
+
+/**
+ * True when one of the rules is (D-10). The facts and the result come from
+ * where it is used, never from the rules, so each rule is typed by its place.
+ * In a read rule, the filters combine with `OR` (D-81): `true` from any rule
+ * lets every row through, `false` adds nothing.
+ */
+export function anyOf<Facts, R = boolean>(
+	...rules: readonly NoInfer<(facts: Facts) => R>[]
+): (facts: Facts) => R
+/** Outside any place, the facts are those every rule needs. */
+export function anyOf<const Rules extends readonly Named[]>(
+	...rules: Rules
+): Combined<Rules>
+export function anyOf(...rules: readonly Rule[]): (facts: never) => unknown {
+	return combine(rules, true, 'OR')
+}
+
+/**
+ * True when every rule is (D-81), typed as `anyOf`. In a read rule, the
+ * filters combine with `AND`: `false` from any rule hides every row, `true`
+ * adds nothing.
+ */
+export function allOf<Facts, R = boolean>(
+	...rules: readonly NoInfer<(facts: Facts) => R>[]
+): (facts: Facts) => R
+export function allOf<const Rules extends readonly Named[]>(
+	...rules: Rules
+): Combined<Rules>
+export function allOf(...rules: readonly Rule[]): (facts: never) => unknown {
+	return combine(rules, false, 'AND')
+}

package/src/running.ts

@@ -0,0 +1,62 @@
+// The running application (D-18): its resolved models and functions, its
+// adapter, its logger, its plugins' APIs (D-89) and the operations `stop`
+// waits for (D-91), one per realm.
+import type { Adapter } from './adapter.ts'
+import type { Logger } from './app-options.ts'
+import type { Complete } from './complete.ts'
+import type { FunctionDefinition } from './definition.ts'
+import type { Resolved } from './schema.ts'
+
+export type Running = {
+	readonly resolved: Resolved
+	/** Its functions, by their `defineFunction` value (D-75). */
+	readonly functions: ReadonlyMap<object, FunctionDefinition>
+	readonly adapter: Adapter
+	readonly logger: Logger
+	/** Each plugin's API, by its name (D-16). */
+	readonly apis: ReadonlyMap<string, unknown>
+	readonly work: Work
+	/** Completes a user caller with its plugins' keys (D-121). */
+	readonly complete: Complete
+}
+
+/** The operations running, `*Commit` hooks included, that `stop` waits for. */
+export class Work {
+	private count = 0
+	private readonly idle: (() => void)[] = []
+
+	async run<R>(run: () => Promise<R>): Promise<R> {
+		this.count += 1
+		try {
+			return await run()
+		} finally {
+			this.count -= 1
+			if (this.count === 0) for (const done of this.idle.splice(0)) done()
+		}
+	}
+
+	async settled(): Promise<void> {
+		if (this.count === 0) return
+		await new Promise<void>((done) => {
+			this.idle.push(done)
+		})
+	}
+}
+
+let running: Running | undefined
+
+export function register(app: Running): void {
+	if (running !== undefined) {
+		throw new Error('An application is already running; stop it first.')
+	}
+	running = app
+}
+
+export function unregister(app: Running): void {
+	if (running === app) running = undefined
+}
+
+/** The running application, `undefined` before `start`. */
+export function current(): Running | undefined {
+	return running
+}

package/src/schema-indexes.ts

@@ -0,0 +1,88 @@
+// The indexes of a model, checked against its fields (D-52, D-120, D-141),
+// and its searched fields (D-148).
+import type { SchemaField } from './adapter.ts'
+import type { IndexDefinition } from './definition.ts'
+import type { ModelInfo } from './schema.ts'
+import { readRules } from './access.ts'
+import { Refused } from './errors.ts'
+
+/** An index on a list is a GIN index of that list alone (D-120). */
+function listIndex(model: string, name: string, index: IndexDefinition): void {
+	if (index.fields.length > 1) {
+		throw new Refused(
+			`${model}: the list '${name}' is indexed alone, in an index of its own.`,
+		)
+	}
+	if (index.unique === true) {
+		throw new Refused(`${model}: the list '${name}' cannot be unique.`)
+	}
+}
+
+/** A `contains` index covers one string field, not a list (D-141). */
+function containsIndex(
+	model: string,
+	fields: ReadonlyMap<string, SchemaField>,
+	index: IndexDefinition,
+): void {
+	const [name] = index.fields
+	const field = name === undefined ? undefined : fields.get(name)
+	if (
+		index.fields.length !== 1 ||
+		index.unique === true ||
+		field?.kind !== 'scalar' ||
+		field.type !== 'string' ||
+		field.list
+	) {
+		throw new Refused(
+			`${model}: a contains index covers one string field that is not a list, and is not unique.`,
+		)
+	}
+}
+
+/** Refuses an index over a field that is not one of the model's columns. */
+export function checkIndexes(
+	model: string,
+	fields: ReadonlyMap<string, SchemaField>,
+	indexes: readonly IndexDefinition[],
+): void {
+	for (const index of indexes) {
+		for (const name of index.fields) {
+			const field = fields.get(name)
+			if (
+				field === undefined ||
+				field.kind === 'many' ||
+				(field.kind === 'one' && !field.stored)
+			) {
+				throw new Refused(
+					`${model}: index field '${name}' is not a scalar or a stored one relation.`,
+				)
+			}
+			if (field.kind === 'scalar' && field.list) {
+				listIndex(model, name, index)
+			}
+		}
+		if (index.contains === true) containsIndex(model, fields, index)
+	}
+}
+
+/**
+ * A searched field is the kernel's string, which every caller may read: a
+ * match would reveal a value its read rule hides (D-148).
+ */
+export function checkSearch(model: ModelInfo): void {
+	const rules = readRules(model)
+	for (const field of model.fields.values()) {
+		if (field.kind !== 'scalar' || field.search !== true) continue
+		const name = `${model.name}.${field.name}`
+		if (field.codec !== undefined) {
+			throw new Refused(
+				`${name}: a ${field.codec.plugin} field is not searched.`,
+			)
+		}
+		if (rules[field.name] !== undefined) {
+			throw new Refused(
+				`${name} has a read rule, and a search would reveal its value: remove search or the rule.`,
+			)
+		}
+	}
+}