ultimabase 0.0.0-stage → 0.1.1

package/src/plugin-app.ts

@@ -0,0 +1,308 @@
+// The application's plugins at `start` (D-16, D-89): their values checked,
+// their requirements met, then their APIs built, each after those it needs.
+import type { Row, SchemaModel } from './adapter.ts'
+import { readRules } from './access.ts'
+import type { Logger } from './app-options.ts'
+import type { PluginRecord } from './definition.ts'
+import type { FunctionSource, Functions } from './functions.ts'
+import type { Identify, PluginIdentify } from './identify.ts'
+import type { PluginCaller } from './complete.ts'
+import type { Identity } from './rules.ts'
+import type { ExposedFunction, ExposedModel, ModelQueries } from './plugin.ts'
+import type { ModelShape } from './model.ts'
+import type { ModelInfo, Resolved } from './schema.ts'
+import { pluginValues } from './definition.ts'
+import { query } from './engine.ts'
+import { recordExpiry } from './recorder.ts'
+import { exposedFunctions, resolveFunctions } from './functions.ts'
+import { isObject } from './query-where.ts'
+import { Refused } from './errors.ts'
+import type { Enum, StandardSchema } from './fields.ts'
+import { standardOf } from './validation.ts'
+
+/** Each plugin after the plugins it needs; a cycle stops startup. */
+function needsFirst(plugins: readonly PluginRecord[]): readonly PluginRecord[] {
+	const byName = new Map(plugins.map((plugin) => [plugin.code.name, plugin]))
+	const ordered: PluginRecord[] = []
+	const visit = (plugin: PluginRecord, path: readonly string[]): void => {
+		if (ordered.includes(plugin)) return
+		const { name, requires, optional } = plugin.code
+		if (path.includes(name)) {
+			const cycle = [...path.slice(path.indexOf(name)), name].join(' → ')
+			throw new Refused(`plugins need each other: ${cycle}.`)
+		}
+		for (const needed of [...requires, ...optional]) {
+			const other = byName.get(needed)
+			if (other !== undefined) visit(other, [...path, name])
+		}
+		ordered.push(plugin)
+	}
+	for (const plugin of plugins) visit(plugin, [])
+	return ordered
+}
+
+/**
+ * The application's `plugins`, in their order (D-29), and the order their
+ * APIs are built in, or startup stops with a message.
+ */
+export function installed(values: readonly unknown[]): {
+	readonly plugins: readonly PluginRecord[]
+	readonly apiOrder: readonly PluginRecord[]
+} {
+	const plugins: PluginRecord[] = []
+	for (const value of values) {
+		const plugin = isObject(value) ? pluginValues.get(value) : undefined
+		if (plugin === undefined) {
+			throw new Refused('plugins lists a value that no plugin returned.')
+		}
+		const { name } = plugin.code
+		if (plugins.some((other) => other.code.name === name)) {
+			throw new Refused(`plugins lists two plugins named ${name}.`)
+		}
+		plugins.push(plugin)
+	}
+	for (const { code } of plugins) {
+		for (const needed of code.requires) {
+			if (plugins.some((other) => other.code.name === needed)) continue
+			throw new Refused(
+				`${code.name} requires ${needed}, which is not in plugins.`,
+			)
+		}
+	}
+	return { plugins, apiOrder: needsFirst(plugins) }
+}
+
+/**
+ * A plugin and what its `api`, `start` and `stop` receive (D-58, D-91, D-106,
+ * D-109).
+ */
+export type Installed = {
+	readonly code: PluginRecord['code']
+	readonly context: {
+		readonly options: object
+		readonly plugins: object
+		readonly logger: Logger
+		readonly identify: Identify
+		readonly expires: (at: Date) => void
+		readonly models: readonly ExposedModel[]
+		readonly functions: readonly ExposedFunction[]
+	}
+}
+
+/** The models as the plugin `name` reads them, with its `.with` key. */
+function exposed(name: string, resolved: Resolved): readonly ExposedModel[] {
+	const own = [...resolved.byValue].filter(
+		([, info]) => info.owner === undefined,
+	)
+	return own.map(([value, info]) => {
+		const rules = info.definition.rules
+		// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a model value holds its queries; transports pass client arguments, which the kernel checks (D-20).
+		const queries = value as ModelQueries
+		const key: unknown =
+			rules === undefined ? undefined : Reflect.get(rules, name)
+		return Object.freeze({
+			schema: schemaOf(resolved, info.name),
+			description: info.definition.description,
+			descriptions: descriptions(info),
+			enums: enums(info),
+			uniques: info.uniques,
+			readRules: readRules(info),
+			required: required(info),
+			validators: validators(info),
+			fieldTypes: fieldTypes(info),
+			virtuals: [...info.virtuals.values()].map((virtual) =>
+				Object.freeze({
+					name: virtual.name,
+					description: virtual.description,
+					input: virtual.input?.schema,
+					output: virtual.output,
+					default: virtual.default,
+				}),
+			),
+			with: key,
+			used: info.plugins.some((use) => use.code.name === name),
+			queries,
+			upsert: async (args, options) =>
+				// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the kernel's upsert answers its row and its branch (D-142).
+				(await query(info.name, 'upserted', args, options)) as {
+					readonly row: Row
+					readonly created: boolean
+				},
+			// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- a `defineModel` value, keyed by it.
+			model: value as ModelShape,
+		})
+	})
+}
+
+/** The fields `create` needs, as its type says (D-53): a list is `[]`. */
+function required(info: ModelInfo): readonly string[] {
+	return [...info.fields.values()]
+		.filter(
+			(field) =>
+				field.kind !== 'many' &&
+				!field.optional &&
+				field.options['default'] === undefined &&
+				field.options['list'] !== true,
+		)
+		.map((field) => field.name)
+}
+
+/** Each field's `description` (D-150). */
+function descriptions(info: ModelInfo): ExposedModel['descriptions'] {
+	const found: { [field: string]: string } = {}
+	for (const field of info.fields.values()) {
+		const description = field.options['description']
+		if (typeof description === 'string') found[field.name] = description
+	}
+	return found
+}
+
+/** Each field's `defineEnum` (D-150). */
+function enums(info: ModelInfo): ExposedModel['enums'] {
+	const found: { [field: string]: Enum } = {}
+	for (const field of info.fields.values()) {
+		if (field.kind === 'scalar' && field.enum !== undefined) {
+			found[field.name] = field.enum
+		}
+	}
+	return found
+}
+
+/** Each `json` field's schema (D-125); a function validate has no shape. */
+function validators(info: ModelInfo): {
+	readonly [field: string]: StandardSchema
+} {
+	const found: { [field: string]: StandardSchema } = {}
+	for (const field of info.fields.values()) {
+		const standard =
+			field.kind === 'scalar' && field.type === 'json'
+				? standardOf(field.options['validate'])
+				: undefined
+		if (standard !== undefined) found[field.name] = standard.schema
+	}
+	return found
+}
+
+/** Each plugin field type's field: its plugin, options and `toJSON` (D-122). */
+function fieldTypes(info: ModelInfo): ExposedModel['fieldTypes'] {
+	const found: { [field: string]: ExposedModel['fieldTypes'][string] } = {}
+	for (const field of info.fields.values()) {
+		if (field.kind !== 'scalar' || field.codec === undefined) continue
+		const { plugin, options, toJSON, shape } = field.codec
+		found[field.name] = { plugin, options, toJSON, shape }
+	}
+	return found
+}
+
+function schemaOf(resolved: Resolved, name: string): SchemaModel {
+	const found = resolved.schema.models.find((model) => model.name === name)
+	if (found === undefined) throw new Error(`${name} has no schema.`)
+	return found
+}
+
+/**
+ * Each plugin with its context, its logger naming it (D-91), and the
+ * functions, the application's then each plugin's (D-113).
+ */
+export function withContexts(
+	apiOrder: readonly PluginRecord[],
+	logger: Logger,
+	identify: Identify,
+	resolved: Resolved,
+	appFunctions: readonly unknown[],
+): { readonly plugins: readonly Installed[]; readonly functions: Functions } {
+	const bases = apiOrder.map(({ code, options }) => ({
+		code,
+		base: {
+			options,
+			plugins: code.plugins,
+			logger: logger.child({ name: code.name }),
+			identify,
+			expires: recordExpiry,
+			models: exposed(code.name, resolved),
+		},
+	}))
+	const sources: FunctionSource[] = [
+		{ plugin: undefined, values: appFunctions },
+	]
+	for (const { code, base } of bases) {
+		if (code.functions === undefined) continue
+		const values: unknown = Reflect.apply(code.functions, undefined, [base])
+		if (!Array.isArray(values)) {
+			throw new TypeError(`${code.name}.functions returns an array.`)
+		}
+		sources.push({ plugin: code.name, values })
+	}
+	const functions = resolveFunctions(
+		sources,
+		resolved,
+		apiOrder.map((plugin) => plugin.code),
+	)
+	const plugins = bases.map(({ code, base }) => ({
+		code,
+		context: { ...base, functions: exposedFunctions(code.name, functions) },
+	}))
+	return { plugins, functions }
+}
+
+/** Builds each plugin's API into `apis`, in their order (D-16, D-89). */
+export function buildApis(
+	plugins: readonly Installed[],
+	apis: Map<string, unknown>,
+): void {
+	for (const { code, context } of plugins) {
+		if (code.api === undefined) continue
+		const api: unknown = Reflect.apply(code.api, undefined, [context])
+		apis.set(code.name, api)
+	}
+}
+
+/** `plugins` in the order they were declared. */
+export const inOrder = (
+	records: readonly PluginRecord[],
+	plugins: readonly Installed[],
+): readonly Installed[] =>
+	plugins.toSorted(
+		(a, b) =>
+			records.findIndex((record) => record.code === a.code) -
+			records.findIndex((record) => record.code === b.code),
+	)
+
+/** Each plugin's `identify` with its context, in the order of `plugins`. */
+export function pluginIdentifiers(
+	records: readonly PluginRecord[],
+	plugins: readonly Installed[],
+): readonly PluginIdentify[] {
+	return inOrder(records, plugins).flatMap(({ code, context }) => {
+		const identify = code.identify
+		if (identify === undefined) return []
+		return [
+			async (request: Request) => {
+				const caller: unknown = await Reflect.apply(identify, undefined, [
+					request,
+					context,
+				])
+				// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- its type is PluginDefinition's; each query checks its caller (D-19).
+				return caller as Identity | undefined
+			},
+		]
+	})
+}
+
+/** Each plugin's `caller` with its context, in the order of `plugins`. */
+export function pluginCallers(
+	records: readonly PluginRecord[],
+	plugins: readonly Installed[],
+): readonly PluginCaller[] {
+	return inOrder(records, plugins).flatMap(({ code, context }) => {
+		const caller = code.caller
+		if (caller === undefined) return []
+		return [
+			{
+				plugin: code.name,
+				caller: async (identity: Identity): Promise<unknown> =>
+					Reflect.apply(caller, undefined, [identity, context]),
+			},
+		]
+	})
+}

package/src/plugin-code.ts

@@ -0,0 +1,158 @@
+// A plugin's code at run time (D-57, D-89): what `definePlugin` checks, the
+// APIs it reads once the application starts, and the command it runs in.
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { IndexDefinition, PluginCode } from './definition.ts'
+import { nameOf } from './definition.ts'
+import { manifestOf } from './manifest.ts'
+import { isObject } from './query-where.ts'
+import { current } from './running.ts'
+
+type Holder = { readonly [key: string]: unknown }
+
+function functionAt(
+	holder: Holder,
+	key: string,
+	path: string,
+): Function | undefined {
+	const value = holder[key]
+	if (value === undefined || typeof value === 'function') return value
+	throw new TypeError(`${path} is a function.`)
+}
+
+function objectAt(holder: Holder, key: string, path: string): Holder {
+	const value = holder[key]
+	if (value === undefined) return {}
+	if (!isObject(value)) throw new TypeError(`${path} is an object.`)
+	return value
+}
+
+/** The fixed hooks of D-15. */
+export const hookNames = [
+	'beforeFind',
+	'beforeCreate',
+	'beforeUpdate',
+	'beforeDelete',
+	'afterCreate',
+	'afterUpdate',
+	'afterDelete',
+	'afterCreateCommit',
+	'afterUpdateCommit',
+	'afterDeleteCommit',
+] as const
+
+/** The APIs of `names`, each read from the running application. */
+function apisOf(plugin: string, names: readonly string[]): object {
+	const plugins = {}
+	for (const name of names) {
+		Object.defineProperty(plugins, name, {
+			enumerable: true,
+			get: () => {
+				const app = current()
+				if (app === undefined) {
+					throw new Error(
+						`${plugin}: plugins.${name} is read once the application starts.`,
+					)
+				}
+				return app.apis.get(name)
+			},
+		})
+	}
+	return Object.freeze(plugins)
+}
+
+const isList = (value: unknown): value is readonly unknown[] =>
+	Array.isArray(value)
+
+/** `addedIndexes`, each `{ fields, unique?, contains? }`; startup checks the fields. */
+function indexesOf(value: unknown, path: string): readonly IndexDefinition[] {
+	const indexes = value ?? []
+	const valid = (index: unknown): index is IndexDefinition =>
+		isObject(index) &&
+		isList(index['fields']) &&
+		index['fields'].every((field) => typeof field === 'string') &&
+		(index['unique'] === undefined || typeof index['unique'] === 'boolean') &&
+		(index['contains'] === undefined || index['contains'] === true)
+	if (!isList(indexes) || !indexes.every(valid)) {
+		throw new TypeError(
+			`${path} is a list of { fields, unique?, contains?: true }.`,
+		)
+	}
+	return Object.freeze(
+		indexes.map(({ fields, unique, contains }) => ({
+			fields: [...fields],
+			...(unique === undefined ? {} : { unique }),
+			...(contains === undefined ? {} : { contains }),
+		})),
+	)
+}
+
+/** Checks what a plugin's author wrote; the types refuse the rest. */
+export function pluginCode(definition: unknown): PluginCode {
+	if (!isObject(definition))
+		throw new TypeError('definePlugin takes an object.')
+	const name = nameOf(definition['name'], 'definePlugin')
+	const requires = Object.keys(
+		objectAt(definition, 'requires', `${name}.requires`),
+	)
+	const optional = Object.keys(
+		objectAt(definition, 'optional', `${name}.optional`),
+	)
+	const given = objectAt(definition, 'hooks', `${name}.hooks`)
+	const hooks: { [hook: string]: Function | undefined } = {}
+	for (const hook of hookNames) {
+		hooks[hook] = functionAt(given, hook, `${name}.hooks.${hook}`)
+	}
+	const redirect = objectAt(definition, 'redirect', `${name}.redirect`)
+	const part = (key: string) => functionAt(definition, key, `${name}.${key}`)
+	const models: unknown = definition['models'] ?? []
+	if (!isList(models)) {
+		throw new TypeError(`${name}.models is an array.`)
+	}
+	return Object.freeze({
+		name,
+		manifest: manifestOf(definition['manifest'], name),
+		requires,
+		optional,
+		hooks: Object.freeze(hooks),
+		redirect: functionAt(redirect, 'delete', `${name}.redirect.delete`),
+		commands: part('commands'),
+		api: part('api'),
+		addedFields: part('addedFields'),
+		addedIndexes: indexesOf(definition['addedIndexes'], `${name}.addedIndexes`),
+		start: part('start'),
+		stop: part('stop'),
+		identify: part('identify'),
+		caller: part('caller'),
+		changed: part('changed'),
+		missed: part('missed'),
+		functions: part('functions'),
+		models: Object.freeze([...models]),
+		plugins: apisOf(name, [...requires, ...optional]),
+	})
+}
+
+export type Command = {
+	readonly model: string
+	readonly plugin: string
+	readonly command: string
+}
+
+const commands = new AsyncLocalStorage<Command>()
+
+/** The command of `plugin` running on `model`, if any (D-89). */
+export function commandOf(model: string, plugin: string): string | undefined {
+	const running = commands.getStore()
+	return running?.model === model && running.plugin === plugin
+		? running.command
+		: undefined
+}
+
+/** Runs `run` as `plugin`'s command `command` on `model`. */
+export function inCommand<R>(command: Command, run: () => R): R {
+	return commands.run(command, run)
+}
+
+/** Runs a hook's body: the queries it makes run outside any command. */
+export function outsideCommands<R>(run: () => R): R {
+	return commands.exit(run)
+}

package/src/plugin-use.ts

@@ -0,0 +1,217 @@
+// A model's plugins at `defineModel` (D-89): the entries of its `use`, the
+// fields they add and the commands they build, which run in their command.
+import type {
+	FieldDefinition,
+	IndexDefinition,
+	ModelDefinition,
+	PluginCode,
+	PluginRecord,
+	PluginUse,
+} from './definition.ts'
+import { fieldBuilders, fieldDefinitions, pluginEntries } from './definition.ts'
+import type { Command } from './plugin-code.ts'
+import { inCommand } from './plugin-code.ts'
+import { isObject, systemFields } from './query-where.ts'
+import { Refused } from './errors.ts'
+
+/** The kernel's names, which a model's field cannot take (D-22, D-20, D-134, D-148). */
+const reserved = new Set([
+	...systemFields,
+	'AND',
+	'OR',
+	'NOT',
+	'_count',
+	'_search',
+	'_relevance',
+])
+
+/**
+ * Adds the fields a `fields` callback, or a plugin's `addedFields`, built.
+ * `owners` names the plugin that added each field.
+ */
+export function addFields(
+	model: string,
+	built: unknown,
+	fields: Map<string, FieldDefinition>,
+	owners: Map<string, string>,
+	plugin?: string,
+): void {
+	if (!isObject(built)) {
+		const part = plugin === undefined ? 'fields' : `${plugin}.addedFields`
+		throw new Refused(`${model}: ${part} must return an object of fields.`)
+	}
+	for (const [field, value] of Object.entries(built)) {
+		const recorded =
+			typeof value === 'object' && value !== null
+				? fieldDefinitions.get(value)
+				: undefined
+		if (recorded === undefined) {
+			throw new Refused(`${model}.${field} is not a field a builder returned.`)
+		}
+		if (reserved.has(field)) {
+			throw new Refused(`${model}.${field}: the kernel owns this name.`)
+		}
+		if (plugin !== undefined && fields.has(field)) {
+			const owner = owners.get(field) ?? model
+			throw new Refused(
+				`${model}.${field}: ${plugin} adds a field ${owner} already has.`,
+			)
+		}
+		fields.set(field, recorded)
+		if (plugin !== undefined) owners.set(field, plugin)
+	}
+}
+
+/** Runs a command's function, or each function of its object, as it. */
+function wrapped(value: unknown, command: Command, path: string): unknown {
+	const run =
+		(fn: Function) =>
+		(...args: unknown[]): unknown =>
+			inCommand(command, () => {
+				const result: unknown = Reflect.apply(fn, undefined, args)
+				return result
+			})
+	if (typeof value === 'function') return run(value)
+	const refused = new TypeError(
+		`${path} is a function or an object of functions.`,
+	)
+	if (!isObject(value)) throw refused
+	const functions: { [key: string]: unknown } = {}
+	for (const [key, fn] of Object.entries(value)) {
+		if (typeof fn !== 'function') throw refused
+		functions[key] = run(fn)
+	}
+	return Object.freeze(functions)
+}
+
+function commandsOf(
+	model: string,
+	uses: readonly PluginUse[],
+	methods: ReadonlySet<string>,
+): ReadonlyMap<string, unknown> {
+	const commands = new Map<string, unknown>()
+	const owners = new Map<string, string>()
+	for (const { code, model: given } of uses) {
+		if (code.commands === undefined) continue
+		const built: unknown = Reflect.apply(code.commands, undefined, [given])
+		if (!isObject(built)) {
+			throw new TypeError(`${code.name}.commands returns an object.`)
+		}
+		for (const [command, value] of Object.entries(built)) {
+			const path = `${model}.${command}`
+			if (methods.has(command)) {
+				throw new Refused(
+					`${path}: ${code.name} adds a command named after a model method.`,
+				)
+			}
+			const other = owners.get(command)
+			if (other !== undefined) {
+				throw new Refused(
+					`${path}: ${other} and ${code.name} both add this command.`,
+				)
+			}
+			owners.set(command, code.name)
+			const running = { model, plugin: code.name, command }
+			commands.set(command, wrapped(value, running, path))
+		}
+	}
+	return commands
+}
+
+/**
+ * Reads a model's `use`: each entry once, the fields its plugins add into
+ * `fields`, and their commands, built with `queries`.
+ */
+/** The plugin entries `use` lists, each once (D-27). */
+export function entriesOf(name: string, use: unknown): readonly PluginRecord[] {
+	if (!Array.isArray(use)) throw new Refused(`${name}.use is a list.`)
+	const entries: PluginRecord[] = []
+	for (const value of use) {
+		const entry = isObject(value) ? pluginEntries.get(value) : undefined
+		if (entry === undefined) {
+			throw new Refused(`${name}.use lists a value no plugin's entry returned.`)
+		}
+		if (entries.some((other) => other.code.name === entry.code.name)) {
+			throw new Refused(`${name}.use lists ${entry.code.name} twice.`)
+		}
+		entries.push(entry)
+	}
+	return entries
+}
+
+export function usedBy(
+	model: string,
+	use: readonly unknown[],
+	fields: Map<string, FieldDefinition>,
+	queries: object,
+): {
+	readonly uses: readonly PluginUse[]
+	readonly commands: ReadonlyMap<string, unknown>
+	readonly indexes: readonly IndexDefinition[]
+} {
+	const uses: PluginUse[] = []
+	const owners = new Map<string, string>()
+	for (const { code, options } of entriesOf(model, use)) {
+		if (code.addedFields !== undefined) {
+			const built: unknown = Reflect.apply(code.addedFields, undefined, [
+				fieldBuilders,
+				options,
+			])
+			addFields(model, built, fields, owners, code.name)
+		}
+		const given = { name: model, queries, options, plugins: code.plugins }
+		uses.push({ code, model: Object.freeze(given) })
+	}
+	const redirecting = uses.filter((each) => each.code.redirect !== undefined)
+	if (redirecting.length > 1) {
+		const names = redirecting.map((each) => each.code.name).join(' and ')
+		throw new Refused(`${model}: ${names} both redirect delete.`)
+	}
+	const methods = new Set(['name', 'with', 'nullable', ...Object.keys(queries)])
+	return {
+		uses,
+		commands: commandsOf(model, uses, methods),
+		indexes: uses.flatMap(({ code }) => code.addedIndexes),
+	}
+}
+
+/** Stops startup when `owner` uses a plugin that `plugins` does not hold. */
+export function checkInstalled(
+	owner: string,
+	code: PluginCode,
+	plugins: readonly PluginCode[],
+): void {
+	if (plugins.includes(code)) return
+	const { name } = code
+	const other = plugins.some((each) => each.name === name)
+	throw new Refused(
+		other
+			? `${owner} uses a ${name} from another definePlugin than the one in plugins.`
+			: `${owner} uses ${name}, which is not in plugins.`,
+	)
+}
+
+/** A model's plugins in the order of `plugins`, each one installed. */
+export function installedUses(
+	definition: ModelDefinition,
+	plugins: readonly PluginCode[],
+): readonly PluginUse[] {
+	const at = (use: PluginUse) => plugins.indexOf(use.code)
+	for (const use of definition.uses) {
+		checkInstalled(definition.name, use.code, plugins)
+	}
+	// A field type's plugin runs its hooks on the model, as if used (D-152).
+	const { name, queries } = definition
+	const implicit = plugins
+		.filter((code) => !definition.uses.some((use) => use.code === code))
+		.filter((code) =>
+			[...definition.fields.values()].some(
+				(field) => field.kind === 'scalar' && field.codec?.plugin === code.name,
+			),
+		)
+		.map((code) => {
+			const model = { name, queries, options: {}, plugins: code.plugins }
+			return { code, model: Object.freeze(model) }
+		})
+	return [...definition.uses, ...implicit].toSorted((a, b) => at(a) - at(b))
+}