ultimabase 0.0.0-stage → 0.1.1

package/src/cascade.ts

@@ -0,0 +1,297 @@
+// What a `delete` does to the rows that reference the row it deletes
+// (D-54, D-90): `cascade` deletes them, `setNull` empties their key,
+// `restrict` refuses the delete.
+import type { Change, Filter, Row } from './adapter.ts'
+import { PublicError } from './errors.ts'
+import { hasHook, redirectOf } from './hooks.ts'
+import type { Models } from './query-where.ts'
+import type { ModelInfo } from './schema.ts'
+import type { Checked, Reads } from './write-plan.ts'
+import { updated } from './write-plan.ts'
+
+/** A row the delete removes, or redirects (D-89). */
+export type Doomed = {
+	readonly model: ModelInfo
+	readonly row: Row
+	readonly redirected: boolean
+}
+
+/** Rows of `model` whose key `field` the delete empties. */
+export type Nulled = {
+	readonly model: ModelInfo
+	readonly field: string
+	readonly rows: readonly Row[]
+}
+
+export type Cascade = {
+	/** The deepest first, the rows the caller deletes last. */
+	readonly deleted: readonly Doomed[]
+	readonly nulled: readonly Nulled[]
+}
+
+type Reference = { readonly model: ModelInfo; readonly field: string }
+
+/** A row's key the cascade leaves: the write empties it itself (D-138). */
+export type Except = {
+	readonly model: string
+	readonly field: string
+	readonly id: string
+}
+
+/** The stored `one` relations to `target`, each with its `onDelete`. */
+function referencesTo(
+	models: Models,
+	target: string,
+): readonly (Reference & { readonly onDelete: string })[] {
+	const references: (Reference & { readonly onDelete: string })[] = []
+	for (const model of models.values()) {
+		for (const field of model.fields.values()) {
+			if (field.kind !== 'one' || !field.stored || field.target !== target) {
+				continue
+			}
+			references.push({ model, field: field.name, onDelete: field.onDelete })
+		}
+	}
+	return references
+}
+
+const keyOf = (model: ModelInfo, id: string): string => `${model.name}:${id}`
+
+/**
+ * Loads every row deleting `deleting` reaches, level by level, as stored: no
+ * `beforeFind`, no access rules (D-54, D-90). Fails with
+ * `RELATION_RESTRICTED` when a row the delete leaves references a deleted one.
+ * A redirected row stays: it cascades nothing (D-89, D-90).
+ */
+export async function cascadeOf(
+	models: Models,
+	model: ModelInfo,
+	deleting: readonly Row[],
+	store: Reads,
+	except?: Except,
+): Promise<Cascade> {
+	const redirected = redirectOf(model) !== undefined
+	const roots = deleting.map((row) => ({ model, row, redirected }))
+	if (redirected) return { deleted: roots, nulled: [] }
+	const deleted = new Map<string, Doomed>()
+	for (const root of roots) deleted.set(keyOf(model, root.row.id), root)
+	const restricted: (Reference & {
+		readonly id: string
+		readonly to: string
+	})[] = []
+	const nulled = new Map<string, Reference & { readonly rows: Row[] }>()
+	let level: readonly Doomed[] = roots
+	while (level.length > 0) {
+		const next: Doomed[] = []
+		const ids = new Map<ModelInfo, string[]>()
+		for (const doomed of level) {
+			ids.set(doomed.model, [...(ids.get(doomed.model) ?? []), doomed.row.id])
+		}
+		for (const [target, targets] of ids) {
+			for (const reference of referencesTo(models, target.name)) {
+				const { model: from, field, onDelete } = reference
+				const rows = await store.find({
+					model: from.name,
+					where: { [field]: { is: { id: { in: targets } } } },
+					lock: true,
+				})
+				for (const found of rows) {
+					const left =
+						except?.model === from.name &&
+						except.field === field &&
+						except.id === found.id
+					if (left) continue
+					if (onDelete === 'restrict') {
+						restricted.push({
+							model: from,
+							field,
+							id: found.id,
+							to: target.name,
+						})
+					} else if (onDelete === 'setNull') {
+						const key = `${from.name}.${field}`
+						const group = nulled.get(key) ?? { model: from, field, rows: [] }
+						// A key holds one target, deleted once: no row comes twice.
+						group.rows.push(found)
+						nulled.set(key, group)
+					} else if (!deleted.has(keyOf(from, found.id))) {
+						// Not redirected: a row that stayed would keep a key to a
+						// deleted one (D-90).
+						const doomed = { model: from, row: found, redirected: false }
+						deleted.set(keyOf(from, found.id), doomed)
+						next.push(doomed)
+					}
+				}
+			}
+		}
+		level = next
+	}
+	// A row the cascade removes no longer references anything.
+	const stays = (from: ModelInfo, id: string): boolean =>
+		!deleted.has(keyOf(from, id))
+	for (const { model: from, field, id, to } of restricted) {
+		if (!stays(from, id)) continue
+		throw new PublicError(
+			'RELATION_RESTRICTED',
+			`${from.name}.${field} references a ${to} the delete removes.`,
+			{ details: { model: from.name, field } },
+		)
+	}
+	return {
+		// The roots last, in the order they were read.
+		deleted: [...deleted.values()]
+			.slice(roots.length)
+			.toReversed()
+			.concat(roots),
+		nulled: [...nulled.values()].map((group) => ({
+			...group,
+			rows: group.rows.filter((found) => stays(group.model, found.id)),
+		})),
+	}
+}
+
+/** Whether deleting a row of `model` runs code of its own. */
+const deleteRuns = (model: ModelInfo): boolean =>
+	redirectOf(model) !== undefined ||
+	hasHook(model, 'beforeDelete') ||
+	hasHook(model, 'afterDelete') ||
+	hasHook(model, 'afterDeleteCommit')
+
+const anyOf = (filters: readonly Filter[]): Filter =>
+	filters.length === 1 && filters[0] !== undefined
+		? filters[0]
+		: { OR: filters }
+
+/**
+ * The changes and checks of a delete whose reach runs no code, so no row is
+ * loaded (D-102): the root goes by `where`, each level by the rows the level
+ * above removed, and `setNull` empties the keys naming them. `undefined` when
+ * a reached model has delete hooks or a redirect, a `setNull` one update
+ * hooks, a cascade comes back to a model it left, or a model is both deleted
+ * and emptied, or emptied twice.
+ */
+export function cascadeWhere(
+	models: Models,
+	model: ModelInfo,
+	where: Filter,
+): { readonly changes: Change[]; readonly checks: Checked[] } | undefined {
+	/**
+	 * Each deleted model's filters from the root, its longest path from the
+	 * root, and the relations to the deleted models that reach it.
+	 */
+	type Level = {
+		readonly filters: Filter[]
+		depth: number
+		readonly parents: Map<string, Reference>
+	}
+	const deleted = new Map<string, Level>()
+	/** The rows each `setNull` or `restrict` relation reaches, by relation. */
+	const reached = new Map<
+		string,
+		Reference & {
+			readonly to: string
+			readonly restricts: boolean
+			readonly filters: Filter[]
+		}
+	>()
+	const reach = (
+		reference: Reference & { readonly to: string; readonly restricts: boolean },
+		filter: Filter,
+	): void => {
+		const key = `${reference.model.name}.${reference.field}`
+		const group = reached.get(key) ?? { ...reference, filters: [] }
+		group.filters.push(filter)
+		reached.set(key, group)
+	}
+	const visit = (
+		at: ModelInfo,
+		filter: Filter,
+		path: string[],
+		parent?: Reference,
+	): boolean => {
+		if (deleteRuns(at)) return false
+		const entry: Level = deleted.get(at.name) ?? {
+			filters: [],
+			depth: 0,
+			parents: new Map(),
+		}
+		entry.filters.push(filter)
+		entry.depth = Math.max(entry.depth, path.length)
+		if (parent !== undefined) {
+			entry.parents.set(`${parent.model.name}.${parent.field}`, parent)
+		}
+		deleted.set(at.name, entry)
+		const below = [...path, at.name]
+		for (const { model: from, field, onDelete } of referencesTo(
+			models,
+			at.name,
+		)) {
+			const child = { [field]: { is: filter } }
+			if (onDelete === 'cascade') {
+				const edge = { model: at, field }
+				if (below.includes(from.name) || !visit(from, child, below, edge)) {
+					return false
+				}
+			} else if (onDelete === 'setNull' && updated(from)) {
+				return false
+			} else {
+				const restricts = onDelete === 'restrict'
+				reach({ model: from, field, to: at.name, restricts }, child)
+			}
+		}
+		return true
+	}
+	if (!visit(model, where, [])) return undefined
+	const groups = [...reached.values()]
+	const nulls = groups.filter((group) => !group.restricts)
+	const emptied = new Set(nulls.map((group) => group.model.name))
+	// PostgreSQL gives two changes of the same rows in one statement no order.
+	const twice =
+		emptied.size < nulls.length ||
+		[...emptied].some((name) => deleted.has(name))
+	if (twice) return undefined
+	// A row the cascade removes is not refusing.
+	const left = (from: ModelInfo, filters: readonly Filter[]): Filter => {
+		const gone = deleted.get(from.name)
+		return gone === undefined
+			? anyOf(filters)
+			: { AND: [anyOf(filters), { NOT: [anyOf(gone.filters)] }] }
+	}
+	const checks = groups
+		.filter((group) => group.restricts)
+		.map((group) => ({
+			check: {
+				model: group.model.name,
+				where: left(group.model, group.filters),
+				count: 0,
+			},
+			message: `${group.model.name}.${group.field} references a ${group.to} the delete removes.`,
+			restricted: { model: group.model.name, field: group.field },
+		}))
+	// A level after the levels above it: its parents have a lower depth.
+	const levels = [...deleted].toSorted(([, a], [, b]) => a.depth - b.depth)
+	const removedBy = (field: string, name: string): Filter => ({
+		[field]: { removedBy: levels.findIndex(([each]) => each === name) },
+	})
+	const changes: Change[] = [
+		...levels.map(([name, { parents }]) => ({
+			kind: 'delete' as const,
+			model: name,
+			where:
+				parents.size === 0
+					? where
+					: anyOf(
+							[...parents.values()].map((edge) =>
+								removedBy(edge.field, edge.model.name),
+							),
+						),
+		})),
+		...nulls.map((group) => ({
+			kind: 'update' as const,
+			model: group.model.name,
+			where: removedBy(group.field, group.to),
+			set: { [group.field]: null, updatedAt: new Date(Date.now()) },
+		})),
+	]
+	return { changes, checks }
+}

package/src/cli-config.ts

@@ -0,0 +1,45 @@
+// `ultimabase.config.ts` (D-105): where the commands find the application.
+import { existsSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import type { Internals } from './app-internals.ts'
+import { internalsOf } from './app-internals.ts'
+import { Refused } from './errors.ts'
+
+const names = [
+	'ultimabase.config.ts',
+	'ultimabase.config.mts',
+	'ultimabase.config.js',
+	'ultimabase.config.mjs',
+]
+
+/** The config file `--config` names, or the first one in `cwd`. */
+export function configPath(cwd: string, given: string | undefined): string {
+	if (given !== undefined) {
+		const path = resolve(cwd, given)
+		if (!existsSync(path)) throw new Refused(`There is no ${path}.`)
+		return path
+	}
+	const found = names.map((name) => join(cwd, name)).find(existsSync)
+	if (found === undefined) {
+		throw new Refused(
+			`There is no ultimabase.config.ts in ${cwd}: write one that default-exports defineApp(...), or pass --config <path>.`,
+		)
+	}
+	return found
+}
+
+/** The application the config file default-exports. */
+export async function load(path: string): Promise<Internals> {
+	const module: unknown = await import(pathToFileURL(path).href)
+	const app =
+		typeof module === 'object' && module !== null
+			? internalsOf(Reflect.get(module, 'default'))
+			: undefined
+	if (app === undefined) {
+		throw new Refused(
+			`${basename(path)} does not default-export defineApp(...).`,
+		)
+	}
+	return app
+}

package/src/cli-deploy.ts

@@ -0,0 +1,235 @@
+// `migrate deploy`, `migrate status` and `reset` (D-105): the migration
+// files against those the database applied.
+import type { Migration, Migrations, Stored } from './adapter.ts'
+import { MigrationFailed } from './adapter.ts'
+import type { Internals } from './app-internals.ts'
+import { create, read } from './cli-migrate.ts'
+import { kernelLogger, schemaOf } from './lifecycle.ts'
+import { Refused } from './errors.ts'
+import { ahead, hashOf, held, migrationsOf } from './migrate.ts'
+
+const upToDate = 'The database is up to date.'
+
+const production = (): boolean => process.env['NODE_ENV'] === 'production'
+
+/** How a development database gets back to what the files build. */
+const rebuild = (): readonly string[] =>
+	production()
+		? []
+		: [
+				'Restore the dump you test on, or rebuild this database from the migrations with `npx ultimabase reset`.',
+			]
+
+const refused = (...lines: readonly string[]): Refused =>
+	new Refused([...lines, ...rebuild()].join('\n'))
+
+/**
+ * The files the database has not applied, and the files it applied after
+ * the last one, which newer code wrote; refuses a file edited or removed.
+ */
+function planOf(
+	stored: Stored | undefined,
+	files: readonly Migration[],
+): { readonly pending: readonly Migration[]; readonly later: string[] } {
+	const applied = stored?.applied ?? []
+	const last = files.at(-1)?.name ?? ''
+	const later: string[] = []
+	for (const { name, checksum } of applied) {
+		const file = files.find((given) => given.name === name)
+		if (file === undefined && name > last) {
+			later.push(name)
+		} else if (file === undefined) {
+			throw refused(
+				`${name} was applied to the database, and migrations/ no longer holds it: restore it from version control.`,
+			)
+		} else if (file.checksum !== checksum) {
+			throw refused(
+				`${name} was edited after it was applied to the database: restore it, and write the change with ${create}.`,
+			)
+		}
+	}
+	const pending = files.filter(
+		(file) => !applied.some((given) => given.name === file.name),
+	)
+	const [first] = pending
+	if (first !== undefined && later.length > 0) {
+		throw refused(
+			`${first.name} is pending, and the database applied ${later.join(', ')} after it, which migrations/ does not hold: deploy the code that holds them.`,
+		)
+	}
+	return { pending, later }
+}
+
+/** Why the files do not lead to the models whose hash is `hash`, if so. */
+function behind(files: readonly Migration[], hash: string): string | undefined {
+	const last = files.at(-1)
+	if (last === undefined) {
+		return `migrations/ holds no migration: run ${create} first.`
+	}
+	if (last.schema === hash) return undefined
+	return `The models changed after ${last.name} was written: run ${create}, then deploy again.`
+}
+
+const syncedSince = (): Refused =>
+	refused(
+		'Development sync changed this database since its last deploy: deploy applies migrations only to a database they built.',
+	)
+
+/** Applies `files`; a refused one names those applied before it. */
+async function deployed(
+	migrations: Migrations,
+	files: readonly Migration[],
+	to: unknown,
+	again: string,
+): Promise<readonly string[]> {
+	const lines = files.map((file) => `Applied ${file.name}.`)
+	try {
+		await migrations.apply({ kind: 'deploy', files, to })
+	} catch (error) {
+		if (!(error instanceof MigrationFailed)) throw error
+		const done = files.findIndex((file) => file.name === error.at)
+		throw new Refused(
+			[
+				...lines.slice(0, done),
+				`${error.at} was not applied: ${error.reason}`,
+				files[done]?.transaction === false
+					? `It ran without a transaction, so nothing was rolled back: undo what it left, such as an invalid index, then ${again}.`
+					: `The database rolled it back: fix it, then ${again}.`,
+			].join('\n'),
+		)
+	}
+	return lines
+}
+
+/** Applies the pending migrations, then stores the models' snapshot. */
+export async function migrateDeploy(
+	{ options }: Internals,
+	dir: string,
+): Promise<readonly string[]> {
+	const { database } = options
+	const migrations = migrationsOf(database)
+	const schema = schemaOf(options)
+	const to = migrations.snapshot(schema)
+	const hash = hashOf(to)
+	const { files } = await read(dir)
+	const late = behind(files, hash)
+	if (late !== undefined) throw new Refused(late)
+	await database.start(schema, kernelLogger(options))
+	try {
+		const stored = await migrations.stored()
+		if (stored?.by === 'sync') throw syncedSince()
+		const { pending, later } = planOf(stored, files)
+		// The code was rolled back: its migrations are applied, and more.
+		if (later.length > 0) return [ahead(later)]
+		const current =
+			stored?.snapshot !== undefined && hashOf(stored.snapshot) === hash
+		if (pending.length === 0 && current) return [upToDate]
+		const lines = await deployed(migrations, pending, to, 'deploy again')
+		return lines.length === 0 ? [upToDate] : lines
+	} finally {
+		await database.stop()
+	}
+}
+
+/** What a deploy would do or refuse; `ok` when it has nothing to do. */
+export async function migrateStatus(
+	{ options }: Internals,
+	dir: string,
+): Promise<{ readonly lines: readonly string[]; readonly ok: boolean }> {
+	const { database } = options
+	const migrations = migrationsOf(database)
+	const schema = schemaOf(options)
+	const hash = hashOf(migrations.snapshot(schema))
+	const { files } = await read(dir)
+	await database.start(schema, kernelLogger(options))
+	try {
+		const stored = await migrations.stored()
+		const late = behind(files, hash)
+		const { pending, later } = planOf(stored, files)
+		const lines = [
+			...(late === undefined ? [] : [late]),
+			...(stored?.by === 'sync' ? [syncedSince().message] : []),
+			...pending.map((file) => `${file.name} is pending.`),
+		]
+		if (lines.length > 0) return { lines, ok: false }
+		if (later.length > 0) return { lines: [ahead(later)], ok: true }
+		if (stored?.snapshot !== undefined && hashOf(stored.snapshot) === hash) {
+			return { lines: [upToDate], ok: true }
+		}
+		return {
+			lines: [
+				"The database's snapshot is not the models': run `npx ultimabase migrate deploy`.",
+			],
+			ok: false,
+		}
+	} finally {
+		await database.stop()
+	}
+}
+
+/** Drops every table; one another session holds stops the reset. */
+async function dropAll(migrations: Migrations): Promise<readonly string[]> {
+	try {
+		return await migrations.reset()
+	} catch (error) {
+		if (!(error instanceof MigrationFailed && error.locked)) throw error
+		throw new Refused(
+			[
+				'UltimaBase did not reset the database: another session held a table.',
+				`  ${error.at};`,
+				`  -- ${error.reason}`,
+				held,
+			].join('\n'),
+		)
+	}
+}
+
+/**
+ * Drops a development database's tables, then applies every migration; one
+ * on another machine only with `force`.
+ */
+export async function reset(
+	{ options }: Internals,
+	dir: string,
+	force: boolean,
+): Promise<readonly string[]> {
+	if (production()) {
+		throw new Refused(
+			'reset rebuilds only a development database: it is refused in production.',
+		)
+	}
+	const { database } = options
+	const migrations = migrationsOf(database)
+	if (migrations.remote !== undefined && !force) {
+		throw new Refused(
+			`reset drops every table, and ${migrations.remote} is not this machine: pass --force if it holds a development database.`,
+		)
+	}
+	const schema = schemaOf(options)
+	const { files, snapshot } = await read(dir)
+	await database.start(schema, kernelLogger(options))
+	try {
+		const dropped = await dropAll(migrations)
+		const lines = [
+			dropped.length === 0
+				? 'The database held no table.'
+				: `Dropped ${dropped.join(', ')}.`,
+		]
+		const last = files.at(-1)
+		if (last === undefined) {
+			return [
+				...lines,
+				'migrations/ holds no migration: the next start builds the tables.',
+			]
+		}
+		lines.push(...(await deployed(migrations, files, snapshot, 'reset again')))
+		if (behind(files, hashOf(migrations.snapshot(schema))) !== undefined) {
+			lines.push(
+				`The models changed after ${last.name} was written: the next start syncs them.`,
+			)
+		}
+		return lines
+	} finally {
+		await database.stop()
+	}
+}