ultimabase 0.0.0-stage → 0.1.0

package/src/definition.ts

@@ -0,0 +1,352 @@
+// What `defineModel`, the field builders and `definePlugin` record at run
+// time: the values behind the types.
+import type { ScalarType } from './adapter.ts'
+import type { Enum, StandardSchema } from './fields.ts'
+import type { Manifest, OutputForm } from './plugin.ts'
+import type { Standard } from './validation.ts'
+import { Refused } from './errors.ts'
+import { isObject } from './query-where.ts'
+import { standardOf } from './validation.ts'
+
+export type FieldOptions = { readonly [option: string]: unknown }
+
+/** What a plugin field type adds to its stored field (D-122). */
+export type Codec = {
+	readonly plugin: string
+	/** The field type's own options this field took (D-152). */
+	readonly options: { readonly [key: string]: unknown }
+	/** The stored value of the rows stored before the field (D-152). */
+	readonly filled?: unknown
+	readonly decode: (stored: unknown) => unknown
+	readonly encode: (value: unknown) => unknown
+	readonly schema: Standard
+	readonly toJSON: (value: unknown) => unknown
+	/** What `toJSON` gives, as a Standard Schema (D-152). */
+	readonly shape?: StandardSchema
+}
+
+/** A field as its builder recorded it. */
+export type FieldDefinition =
+	| {
+			readonly kind: 'scalar'
+			readonly type: ScalarType
+			readonly values?: readonly string[]
+			/** The `defineEnum` its values are, if one (D-150). */
+			readonly enum?: Enum
+			readonly options: FieldOptions
+			readonly rules?: object
+			/** A plugin field type's, whose `type` is the stored one (D-122). */
+			readonly codec?: Codec
+	  }
+	| {
+			readonly kind: 'one' | 'many'
+			readonly target: () => unknown
+			readonly options: FieldOptions
+			readonly rules?: object
+	  }
+	| {
+			/** Computed on read (D-151): its schema, or a thunk of its output. */
+			readonly kind: 'virtual'
+			readonly output: unknown
+			readonly options: FieldOptions
+			readonly rules?: object
+	  }
+
+export type IndexDefinition = {
+	readonly fields: readonly string[]
+	readonly unique?: boolean
+	/** A trigram index, for `contains` and `mode: 'insensitive'` (D-141). */
+	readonly contains?: true
+}
+
+export type ModelDefinition = {
+	readonly name: string
+	readonly description: string | undefined
+	readonly dbName: string | undefined
+	readonly fields: ReadonlyMap<string, FieldDefinition>
+	readonly indexes: readonly IndexDefinition[]
+	/** The plugins of its `use`, in that order (D-89). */
+	readonly uses: readonly PluginUse[]
+	/** Its operations, which a field type's plugin is given (D-152). */
+	readonly queries: object
+	/** What `.with` received, once (D-07). */
+	rules: object | undefined
+}
+
+/** A plugin's code, as `definePlugin` checked it (D-57, D-89). */
+export type PluginCode = {
+	readonly name: string
+	readonly manifest: Manifest
+	readonly requires: readonly string[]
+	readonly optional: readonly string[]
+	readonly hooks: { readonly [hook: string]: Function | undefined }
+	readonly redirect: Function | undefined
+	readonly commands: Function | undefined
+	readonly api: Function | undefined
+	readonly addedFields: Function | undefined
+	/** The indexes it adds to the models that use it (D-122). */
+	readonly addedIndexes: readonly IndexDefinition[]
+	readonly start: Function | undefined
+	readonly stop: Function | undefined
+	/** Who sends a request, if the plugin knows it (D-112). */
+	readonly identify: Function | undefined
+	/** The keys it gives a user caller (D-121). */
+	readonly caller: Function | undefined
+	/** Takes what each commit changed (D-154). */
+	readonly changed: Function | undefined
+	readonly missed: Function | undefined
+	/** Its own models, which no plugin is given (D-110). */
+	readonly models: readonly unknown[]
+	/** Builds its functions when the application starts (D-113). */
+	readonly functions: Function | undefined
+	/** The APIs of the plugins it needs, read when used (D-89). */
+	readonly plugins: object
+}
+
+/** A plugin's entry in `use`, or its value in `plugins`, with its options. */
+export type PluginRecord = {
+	readonly code: PluginCode
+	readonly options: object
+}
+
+/** A plugin in a model's `use`, and what its code gets of the model. */
+export type PluginUse = {
+	readonly code: PluginCode
+	readonly model: {
+		readonly name: string
+		readonly queries: object
+		readonly options: object
+		readonly plugins: object
+	}
+}
+
+/** A model or a type, as an output holds it (D-109). */
+export type NamedOutput =
+	| {
+			readonly kind: 'model'
+			/** The `defineModel` value. */
+			readonly value: object
+			readonly name: string
+	  }
+	| { readonly kind: 'type'; readonly type: TypeDefinition }
+
+/** A function's or a type's output, as the kernel reads it (D-109). */
+export type Output =
+	| { readonly kind: 'schema'; readonly schema: StandardSchema }
+	| (NamedOutput & { readonly form: OutputForm })
+
+export type TypeDefinition = {
+	readonly name: string
+	readonly description: string | undefined
+	readonly fields: ReadonlyMap<string, Output>
+}
+
+export type FunctionDefinition = {
+	readonly name: string
+	readonly description: string | undefined
+	readonly query: boolean
+	readonly input: StandardSchema | undefined
+	readonly output: Output | undefined
+	/** The plugins of its `use` (D-27). */
+	readonly uses: readonly PluginRecord[]
+	readonly run: Function
+	/** What `.with` received, once. */
+	rules: object | undefined
+}
+
+export const fieldDefinitions: WeakMap<object, FieldDefinition> = new WeakMap()
+export const modelDefinitions: WeakMap<object, ModelDefinition> = new WeakMap()
+/** The application values `plugin()` returned. */
+export const pluginValues: WeakMap<object, PluginRecord> = new WeakMap()
+/** The model entries `use()` returned. */
+export const pluginEntries: WeakMap<object, PluginRecord> = new WeakMap()
+export const typeDefinitions: WeakMap<object, TypeDefinition> = new WeakMap()
+export const functionDefinitions: WeakMap<object, FunctionDefinition> =
+	new WeakMap()
+/** What each `X.nullable()` returned stands for (D-109). */
+export const nullables: WeakMap<object, NamedOutput> = new WeakMap()
+
+/** `X.nullable()`, for a model or a type. */
+export function nullable(named: NamedOutput): object {
+	const marker = Object.freeze({})
+	nullables.set(marker, named)
+	return marker
+}
+
+/** The name a `define*` call takes: a non-empty string. */
+export function nameOf(name: unknown, by: string): string {
+	if (typeof name !== 'string' || name === '') {
+		throw new Error(`${by} takes a name.`)
+	}
+	return name
+}
+
+/** A `description` (D-150): a non-empty string, when given. */
+export function describedBy(
+	description: unknown,
+	of: string,
+): string | undefined {
+	if (description === undefined) return undefined
+	if (typeof description !== 'string' || description === '') {
+		throw new Error(`${of}: description is a non-empty string.`)
+	}
+	return description
+}
+
+/**
+ * The `.with` of a model or a function: its rules, in one call, read when
+ * they apply, so it returns the same value.
+ */
+export const withOnce =
+	(name: string, record: { rules: object | undefined }, value: () => object) =>
+	(rules: unknown): object => {
+		if (record.rules !== undefined) {
+			throw new Refused(`${name} takes its rules in one \`.with\`.`)
+		}
+		if (!isObject(rules)) throw new Refused(`${name}.with takes an object.`)
+		record.rules = rules
+		return value()
+	}
+
+/** A field value, keyed by its definition; `.with` takes its rules once. */
+export function build(definition: FieldDefinition): object {
+	describedBy(definition.options['description'], 'A field')
+	const field = {
+		with: (rules: object): object => {
+			if (definition.rules !== undefined) {
+				throw new Error('A field takes its rules in one `.with`.')
+			}
+			return build({ ...definition, rules })
+		},
+	}
+	fieldDefinitions.set(field, definition)
+	return field
+}
+
+/** A field that `list: true` makes a list (D-120, D-127). */
+function listable(
+	type: ScalarType,
+	options: FieldOptions = {},
+	values?: readonly string[],
+	shared?: Enum,
+): object {
+	const list = options['list'] === true
+	if (list) {
+		if (options['optional'] !== undefined) {
+			throw new Error(
+				'A list is never null: left out, it is []. Remove optional.',
+			)
+		}
+		if (options['unique'] !== undefined) {
+			throw new Error('A list cannot be unique.')
+		}
+	}
+	if (options['search'] !== undefined && (list || type !== 'string')) {
+		throw new Error('search takes a string field that is not a list.')
+	}
+	return build({
+		kind: 'scalar',
+		type,
+		...(values === undefined ? {} : { values }),
+		...(shared === undefined ? {} : { enum: shared }),
+		options,
+	})
+}
+
+/** A field no list holds yet (D-127). */
+const scalar =
+	(type: ScalarType) =>
+	(options?: FieldOptions): object => {
+		if (options?.['list'] !== undefined) {
+			throw new Error(
+				`f.${type}() makes no list: a list holds strings, numbers or enum values.`,
+			)
+		}
+		return build({ kind: 'scalar', type, options: options ?? {} })
+	}
+
+const whole = (value: unknown, most: number): value is number =>
+	Number.isInteger(value) && Number(value) >= 0 && Number(value) <= most
+
+/** Exact numbers of `precision` digits, `scale` after the point (D-145). */
+function decimal(options?: FieldOptions): object {
+	const { precision, scale } = options ?? {}
+	if (!whole(precision, 1000) || precision === 0) {
+		throw new Error('f.decimal() takes a precision from 1 to 1000.')
+	}
+	if (!whole(scale, precision)) {
+		throw new Error(
+			`f.decimal() takes a scale from 0 to its precision, ${precision}.`,
+		)
+	}
+	return scalar('decimal')(options)
+}
+
+const relation =
+	(kind: 'one' | 'many') =>
+	(target: () => unknown, options?: FieldOptions): object =>
+		build({ kind, target, options: options ?? {} })
+
+/** The `defineEnum` values, which `enumOf` takes in place of a list. */
+export const sharedEnums: WeakMap<object, Enum> = new WeakMap()
+
+/** An enum's values: strings, each once. */
+export function enumValues(values: unknown, of: string): readonly string[] {
+	const listed: readonly unknown[] = Array.isArray(values) ? values : []
+	const strings = listed.filter((value) => typeof value === 'string')
+	if (strings.length === 0 || strings.length !== listed.length) {
+		throw new Error(`${of} takes a list of strings.`)
+	}
+	if (new Set(strings).size !== strings.length) {
+		throw new Error(`${of} lists a value twice: ${strings.join(', ')}.`)
+	}
+	return strings
+}
+
+function enumOf(values: unknown, options?: FieldOptions): object {
+	const shared = isObject(values) ? sharedEnums.get(values) : undefined
+	if (shared !== undefined) {
+		return listable('enum', options, shared.values, shared)
+	}
+	return listable('enum', options, enumValues(values, 'enumOf'))
+}
+
+/** The builders `defineModel`'s `fields` callback receives (D-09, D-12). */
+export const fieldBuilders: object = Object.freeze({
+	string: (options?: FieldOptions) => listable('string', options),
+	number: (options?: FieldOptions) => listable('number', options),
+	decimal,
+	boolean: scalar('boolean'),
+	dateTime: scalar('dateTime'),
+	date: scalar('date'),
+	json: scalar('json'),
+	enumOf,
+	one: relation('one'),
+	many: relation('many'),
+	virtual: (output: unknown, options?: FieldOptions): object =>
+		build({ kind: 'virtual', output, options: options ?? {} }),
+})
+
+function namedOf(value: unknown): NamedOutput | undefined {
+	if (!isObject(value)) return undefined
+	const model = modelDefinitions.get(value)
+	if (model !== undefined) return { kind: 'model', value, name: model.name }
+	const type = typeDefinitions.get(value)
+	return type === undefined ? undefined : { kind: 'type', type }
+}
+
+/** An output's value, read once at its definition (D-109). */
+export function outputOf(value: unknown, where: string): Output {
+	const standard = standardOf(value)
+	if (standard !== undefined) return { kind: 'schema', schema: standard.schema }
+	const named = namedOf(value)
+	if (named !== undefined) return { ...named, form: 'one' }
+	const marked = isObject(value) ? nullables.get(value) : undefined
+	if (marked !== undefined) return { ...marked, form: 'nullable' }
+	const list: readonly unknown[] = Array.isArray(value) ? value : []
+	const listed = list.length === 1 ? namedOf(list[0]) : undefined
+	if (listed !== undefined) return { ...listed, form: 'list' }
+	throw new Refused(
+		`${where} is a model, a type, a list of one, X.nullable() or a Standard Schema.`,
+	)
+}

package/src/delete-many.ts

@@ -0,0 +1,76 @@
+// `deleteMany` (D-111): what a `delete` runs, on each row its `where`
+// selects, all or nothing; one write when nothing runs (D-102).
+import type { Filter, Row } from './adapter.ts'
+import { cascadeOf, cascadeWhere } from './cascade.ts'
+import type { Event } from './hooks.ts'
+import { settle } from './hooks.ts'
+import type { Context } from './query-context.ts'
+import { filtered, given } from './query-context.ts'
+import { byIds } from './query-where.ts'
+import type { Commit, Store } from './transaction.ts'
+import { checkedWrite, guarded } from './write-target.ts'
+import { cascaded, writingOf } from './writing.ts'
+
+export async function removeMany(
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	args: unknown,
+): Promise<{ readonly count: number }> {
+	const { models, model, scope } = context
+	const found = given(args, model.name, ['where'], [])
+	const where: Filter = (await filtered(context, found, 'delete')) ?? {}
+	const reach = cascadeWhere(models, model, where)
+	if (reach !== undefined && scope.access === undefined) {
+		// The write reads its rows as they were, to count them (D-102).
+		const read = { model: model.name, where }
+		const { checks } = reach
+		const rows = await guarded(
+			store.last({
+				checks: checks.map(({ check }) => check),
+				changes: reach.changes,
+				read,
+				before: true,
+			}),
+			checks,
+		)
+		return { count: rows.length }
+	}
+	// In id order, so two calls on the same rows wait instead of deadlocking.
+	const orderBy = [{ field: 'id', direction: 'asc' }] as const
+	const rows = await store.find({
+		model: model.name,
+		where,
+		orderBy,
+		lock: true,
+	})
+	// One row refused, none deleted (D-111).
+	for (const row of rows) scope.access?.allow(model, 'delete', { record: row })
+	if (rows.length > 0) await deleted(context, store, commits, rows)
+	return { count: rows.length }
+}
+
+/**
+ * Deletes `rows`, which the caller may delete, as `delete` does: in one write
+ * when nothing runs (D-102), else with their cascade or redirect, then the
+ * hooks.
+ */
+export async function deleted(
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	rows: readonly Row[],
+): Promise<void> {
+	const { models, model, caller, scope } = context
+	const locked = cascadeWhere(models, model, byIds(rows.map(({ id }) => id)))
+	if (locked !== undefined) {
+		await checkedWrite(store, locked.checks, locked.changes)
+		return
+	}
+	const events: Event[] = []
+	const writing = writingOf(scope, store, events)
+	const cascade = await cascadeOf(models, model, rows, store)
+	const changes = await cascaded(writing, cascade)
+	if (changes.length > 0) await checkedWrite(store, writing.checks, changes)
+	await settle(store, caller, events, commits)
+}

package/src/engine.ts

@@ -0,0 +1,281 @@
+// The queries a model sends to the running application (D-18): each one
+// checked, run on the adapter, in the open transaction if any (D-36), and
+// returned in the shape it asked for.
+import { accessFor, and } from './access.ts'
+import { InvalidQuery, PublicError } from './errors.ts'
+import type { Identity } from './rules.ts'
+import { isMaster } from './rules.ts'
+import type { Read, Row } from './adapter.ts'
+import type { Running } from './running.ts'
+import { current } from './running.ts'
+import type { ModelInfo } from './schema.ts'
+import type { Context } from './query-context.ts'
+import { filtered, first, given, picked, shapedRows } from './query-context.ts'
+import { oneKeys, plan, restrict, uniqueWhere } from './query-args.ts'
+import { counted } from './virtual-read.ts'
+import { entries, isObject, unknownKey } from './query-where.ts'
+import { QueryScope, planned } from './scope.ts'
+import type { Commit, Store } from './transaction.ts'
+import { reading, writing } from './transaction.ts'
+import { aggregate } from './aggregate.ts'
+import { distinctOf, groupBy } from './group-by.ts'
+import { removeMany } from './delete-many.ts'
+import { updateMany, updateManyAndReturn } from './update-many.ts'
+import { createMany, createManyAndReturn } from './create-many.ts'
+import { create, remove, update, upsert } from './writes.ts'
+
+export type Operation =
+	| 'findMany'
+	| 'findFirst'
+	| 'findUnique'
+	| 'findFirstOrThrow'
+	| 'findUniqueOrThrow'
+	| 'count'
+	| 'aggregate'
+	| 'groupBy'
+	| 'create'
+	| 'update'
+	| 'upsert'
+	| 'delete'
+	| 'updateMany'
+	| 'createMany'
+	| 'updateManyAndReturn'
+	| 'createManyAndReturn'
+	| 'deleteMany'
+	// The transports' upsert, which also says whether it created (D-142).
+	| 'upserted'
+
+const anonymous: Identity = Object.freeze({ kind: 'anonymous' })
+
+/**
+ * `{ as }` only; without it, the caller is anonymous (D-19). The kernel
+ * completes a user one (D-121).
+ */
+export function callerOf(options: unknown, model: string): Identity {
+	if (options === undefined) return anonymous
+	const keys = new Map(entries(options, 'options'))
+	for (const key of keys.keys()) {
+		if (key !== 'as') throw unknownKey(`options.${key}`, model)
+	}
+	const caller = keys.get('as')
+	if (caller === undefined) return anonymous
+	if (!isObject(caller)) {
+		throw new InvalidQuery('options.as', 'options.as must be a caller.')
+	}
+	switch (caller['kind']) {
+		case 'anonymous':
+			return anonymous
+		case 'user':
+			if (
+				!isObject(caller['user']) ||
+				typeof caller['user']['id'] !== 'string'
+			) {
+				throw new InvalidQuery('options.as', 'options.as.user must be { id }.')
+			}
+			// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the kernel reads only the id; the record's other fields are the server code's.
+			return caller as Identity
+		case 'master':
+			// Only the kernel creates Master (D-19): a copy is a forgery.
+			if (!isMaster(caller)) {
+				throw new Error('options.as is a Master the kernel did not create.')
+			}
+			return caller
+		default:
+			throw new InvalidQuery('options.as', 'options.as must be a caller.')
+	}
+}
+
+const manyKeys = new Set([
+	'where',
+	...oneKeys,
+	'orderBy',
+	'take',
+	'skip',
+	'cursor',
+])
+const distinctKeys = new Set([...manyKeys, 'distinct'])
+
+/** Finds a read's root rows, decoded; a live read may serve them (D-154). */
+export type RootFind = (store: Store, read: Read) => Promise<Row[]>
+
+const onStore: RootFind = async (store, read) => store.find(read)
+
+async function find(
+	context: Context,
+	store: Store,
+	args: unknown,
+	single: boolean,
+	root = onStore,
+): Promise<unknown> {
+	const { models, model, scope } = context
+	const keys = single ? manyKeys : distinctKeys
+	const { read, shape, readable } = await planned(scope, () => ({
+		...plan(models, model, args, '', 'many', keys, scope),
+		readable: scope.readable(model.name),
+	}))
+	const take = read.take ?? 1
+	const limited = single ? { ...read, take: Math.sign(take) } : read
+	const distinct = single ? undefined : await distinctOf(context, args)
+	const rows = await root(store, {
+		model: model.name,
+		...restrict(limited, readable),
+		...(distinct && { distinct }),
+	})
+	if (single) return first(context, store, rows, shape, scope.access)
+	return shapedRows(context, store, rows, shape, scope.access)
+}
+
+async function findUnique(
+	context: Context,
+	store: Store,
+	args: unknown,
+): Promise<unknown> {
+	const { models, model, scope } = context
+	const found = given(args, model.name, ['where', ...oneKeys], ['where'])
+	const { read, shape, where } = await planned(scope, () => ({
+		...plan(models, model, picked(found), '', 'one', oneKeys, scope),
+		where: and(
+			uniqueWhere(models, model, found.get('where'), 'where', scope),
+			scope.readable(model.name),
+		),
+	}))
+	const rows = await store.find({ model: model.name, ...read, where })
+	return first(context, store, rows, shape, scope.access)
+}
+
+async function count(
+	context: Context,
+	store: Store,
+	args: unknown,
+): Promise<number> {
+	const { model } = context
+	const where = await filtered(
+		context,
+		given(args, model.name, ['where'], []),
+		'read',
+	)
+	return store.count({ model: model.name, ...(where && { where }) })
+}
+
+type Run = (context: Context, store: Store, args: unknown) => Promise<unknown>
+type Write = (
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	args: unknown,
+) => Promise<unknown>
+
+type ReadOperation =
+	| 'findMany'
+	| 'findFirst'
+	| 'findUnique'
+	| 'findFirstOrThrow'
+	| 'findUniqueOrThrow'
+	| 'count'
+	| 'aggregate'
+	| 'groupBy'
+
+/** The read, which fails with `NOT_FOUND` rather than return `null` (D-135). */
+const orThrow =
+	(read: Run): Run =>
+	async (context, store, args) => {
+		const row = await read(context, store, args)
+		if (row !== null) return row
+		throw new PublicError('NOT_FOUND', `No ${context.model.name} matches.`)
+	}
+
+const reads: { readonly [O in ReadOperation]: Run } = {
+	findMany: async (context, store, args) => find(context, store, args, false),
+	findFirst: async (context, store, args) => find(context, store, args, true),
+	findUnique,
+	findFirstOrThrow: orThrow(async (context, store, args) =>
+		find(context, store, args, true),
+	),
+	findUniqueOrThrow: orThrow(findUnique),
+	count,
+	aggregate,
+	groupBy,
+}
+
+const writes: { readonly [O in Exclude<Operation, ReadOperation>]: Write } = {
+	create,
+	update,
+	upsert: async (context, store, commits, args) =>
+		(await upsert(context, store, commits, args)).row,
+	upserted: upsert,
+	delete: remove,
+	updateMany,
+	createMany,
+	updateManyAndReturn,
+	createManyAndReturn,
+	deleteMany: removeMany,
+}
+
+function isRead(operation: Operation): operation is ReadOperation {
+	return Object.hasOwn(reads, operation)
+}
+
+/** The running application and its model `name`. */
+function runningModel(name: string): {
+	readonly app: Running
+	readonly model: ModelInfo
+} {
+	const app = current()
+	const model = app?.resolved.models.get(name)
+	if (app === undefined || model === undefined) {
+		throw new Error(`${name} is not a model of a started application.`)
+	}
+	return { app, model }
+}
+
+async function contextOf(
+	app: Running,
+	model: ModelInfo,
+	identity: Identity,
+): Promise<Context> {
+	const caller = await app.complete(identity)
+	const { models } = app.resolved
+	const access = accessFor(models, caller, app.logger)
+	const scope = new QueryScope(models, caller, access)
+	return { app, models, model, caller, scope }
+}
+
+/** Runs one query of a model of the running application. */
+export async function query(
+	name: string,
+	operation: Operation,
+	args: unknown,
+	options: unknown,
+): Promise<unknown> {
+	const { app, model } = runningModel(name)
+	const identity = callerOf(options, name)
+	counted()
+	return app.work.run(async () => {
+		const context = await contextOf(app, model, identity)
+		if (isRead(operation)) {
+			const read = reads[operation]
+			return reading(app, async (store) => read(context, store, args))
+		}
+		const write = writes[operation]
+		return writing(app, async (store, commits) =>
+			write(context, store, commits, args),
+		)
+	})
+}
+
+/** `findMany(args)` as `options` says, its root rows found by `root` (D-154). */
+export async function rootFind(
+	name: string,
+	args: unknown,
+	options: unknown,
+	root: RootFind,
+): Promise<unknown> {
+	const { app, model } = runningModel(name)
+	const identity = callerOf(options, name)
+	return app.work.run(async () => {
+		const context = await contextOf(app, model, identity)
+		return reading(app, async (store) =>
+			find(context, store, args, false, root),
+		)
+	})
+}