ultimabase 0.0.0-stage → 0.1.0

package/src/transaction.ts

@@ -0,0 +1,211 @@
+// Transactions (D-36, D-88): `AsyncLocalStorage` carries the open one, so a
+// hook's queries join it without a `tx` argument.
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { randomUUID } from 'node:crypto'
+import type { Adapter, Transaction } from './adapter.ts'
+import { RelationViolation } from './adapter.ts'
+import type { Logger } from './app-options.ts'
+import { decoded } from './field-codec.ts'
+import { recordCount, recordFind } from './recorder.ts'
+import type { Running } from './running.ts'
+import { current } from './running.ts'
+import { refused } from './write-target.ts'
+
+/** What a query reads and writes through. */
+export type Store = Pick<
+	Transaction,
+	'find' | 'count' | 'aggregate' | 'write'
+> & {
+	/**
+	 * The write's changes when nothing follows them: alone, they need no
+	 * transaction (D-99).
+	 */
+	readonly last: Transaction['write']
+}
+
+/** A `*Commit` hook, run once the transaction commits (D-15). */
+export type Commit = () => Promise<void>
+
+type Open = {
+	readonly app: Running
+	/** Begun by the first query (D-99). */
+	tx: Promise<Transaction> | undefined
+	readonly commits: Commit[]
+	/** The first query that failed in it (D-36). */
+	failure: { readonly error: unknown } | undefined
+}
+
+const opened = new AsyncLocalStorage<Open>()
+
+async function begun(open: Open): Promise<Transaction> {
+	open.tx ??= open.app.adapter.begin()
+	return open.tx
+}
+
+/**
+ * The store's rows with their plugin fields decoded (D-122), each read kept
+ * if a recording runs (D-154).
+ */
+function decoding(app: Running, store: Store): Store {
+	const { models } = app.resolved
+	return {
+		find: async (read) => {
+			const rows = await store.find(read)
+			recordFind(models, read, rows)
+			return decoded(models, read, rows)
+		},
+		count: async (read) => {
+			recordCount(models, read)
+			return store.count(read)
+		},
+		// It reads no plugin field (D-143).
+		aggregate: async (read) => {
+			recordCount(models, read)
+			return store.aggregate(read)
+		},
+		write: async (write) =>
+			decoded(models, write.read, await store.write(write)),
+		last: async (write) => decoded(models, write.read, await store.last(write)),
+	}
+}
+
+/** Queries in the transaction; `owner`'s last write may run alone. */
+function storeOf(open: Open, owner: boolean): Store {
+	return decoding(open.app, {
+		find: async (read) => (await begun(open)).find(read),
+		count: async (read) => (await begun(open)).count(read),
+		aggregate: async (read) => (await begun(open)).aggregate(read),
+		write: async (write) => (await begun(open)).write(write),
+		last: async (write) =>
+			owner && open.tx === undefined
+				? open.app.adapter.write(write)
+				: (await begun(open)).write(write),
+	})
+}
+
+/** Runs in the open transaction; a failure rolls all of it back (D-36). */
+async function joined<R>(open: Open, run: () => Promise<R>): Promise<R> {
+	if (open.failure !== undefined) {
+		throw new Error(
+			'A query failed in this transaction, which rolls back: no other query runs in it.',
+			{ cause: open.failure.error },
+		)
+	}
+	try {
+		return await run()
+	} catch (error) {
+		open.failure ??= { error }
+		throw error
+	}
+}
+
+async function committed(logger: Logger, commits: Commit[]): Promise<void> {
+	for (const commit of commits) {
+		try {
+			await commit()
+		} catch (error) {
+			logger.error(
+				{ correlationId: randomUUID(), err: error },
+				'A commit hook failed; the write is kept.',
+			)
+		}
+	}
+}
+
+/** A transaction that failed to begin has nothing to roll back. */
+async function rollback(open: Open): Promise<void> {
+	const tx = await open.tx?.catch(() => undefined)
+	await tx?.rollback()
+}
+
+async function atomic<R>(
+	app: Running,
+	run: (open: Open) => Promise<R>,
+): Promise<R> {
+	const open: Open = { app, tx: undefined, commits: [], failure: undefined }
+	let result: R
+	try {
+		result = await opened.run(open, run, open)
+	} catch (error) {
+		await rollback(open)
+		throw error
+	}
+	if (open.failure !== undefined) {
+		await rollback(open)
+		throw open.failure.error
+	}
+	try {
+		await (await open.tx)?.commit()
+	} catch (error) {
+		// A deferred foreign key checks at the commit (D-99).
+		throw error instanceof RelationViolation ? refused(error) : error
+	}
+	// Outside the transaction: a commit hook's queries open their own.
+	await committed(app.logger, open.commits)
+	return result
+}
+
+/** A read: in the open transaction, else straight on the adapter. */
+export async function reading<R>(
+	app: Running,
+	run: (store: Store) => Promise<R>,
+): Promise<R> {
+	const open = opened.getStore()
+	if (open === undefined) {
+		const { adapter } = app
+		return run(
+			decoding(app, {
+				find: async (read) => adapter.find(read),
+				count: async (read) => adapter.count(read),
+				aggregate: async (read) => adapter.aggregate(read),
+				write: async (write) => adapter.write(write),
+				last: async (write) => adapter.write(write),
+			}),
+		)
+	}
+	return joined(open, async () => run(storeOf(open, false)))
+}
+
+/** A write: in the open transaction, else in its own (D-36). */
+export async function writing<R>(
+	app: Running,
+	run: (store: Store, commits: Commit[]) => Promise<R>,
+): Promise<R> {
+	const open = opened.getStore()
+	if (open !== undefined) {
+		return joined(open, async () => run(storeOf(open, false), open.commits))
+	}
+	return atomic(app, async (own) => run(storeOf(own, true), own.commits))
+}
+
+/**
+ * Runs `run` in one transaction: if it throws, or if a query in it fails,
+ * every write rolls back and the `*Commit` hooks never run. Inside another
+ * `transaction`, it joins that one (D-36).
+ */
+export async function transaction<R>(run: () => Promise<R>): Promise<R> {
+	const open = opened.getStore()
+	if (open !== undefined) return joined(open, run)
+	const app = current()
+	if (app === undefined) {
+		throw new Error('transaction runs on a started application.')
+	}
+	return app.work.run(async () => atomic(app, run))
+}
+
+/**
+ * Runs an adapter's own statement, `database.sql`, in the running
+ * application's open transaction, else alone (D-137).
+ */
+export async function joining<R>(
+	adapter: Adapter,
+	run: (tx: Transaction | undefined) => Promise<R>,
+): Promise<R> {
+	const open = opened.getStore()
+	if (open?.app.adapter === adapter) {
+		return joined(open, async () => run(await begun(open)))
+	}
+	const app = current()
+	if (app?.adapter !== adapter) return run(undefined)
+	return app.work.run(async () => run(undefined))
+}

package/src/types.ts

@@ -0,0 +1,79 @@
+// A model's and a function's types, named from the model or the function
+// (D-74): what application code passes to queries and gets back.
+import type { ResultOf, RunArgs } from './function.ts'
+import type { Model } from './model.ts'
+import type { AggregateArgs } from './query-aggregate.ts'
+import type {
+	CreateManyAndReturnArgs,
+	CreateManyArgs,
+	UpdateManyAndReturnArgs,
+	UpdateManyArgs,
+} from './query-bulk.ts'
+import type { GroupByArgs } from './query-group.ts'
+import type {
+	CreateArgs,
+	FindFirstArgs,
+	FindManyArgs,
+	FindUniqueArgs,
+	Include,
+	OrderBy,
+	Payload,
+	Select,
+	UpdateArgs,
+	UpsertArgs,
+	Where,
+} from './query.ts'
+import type { CreateData, UpdateData } from './record.ts'
+
+type Parts<M> =
+	M extends Model<infer N, infer F, infer _P, infer _W, infer X>
+		? { readonly name: N; readonly fields: F; readonly unique: X }
+		: never
+type FieldsOf<M> = Parts<M>['fields']
+type UniqueOf<M> = Parts<M>['unique']
+type NameOf<M> = Parts<M>['name']
+
+type Operations<F, X, N> = {
+	readonly findMany: FindManyArgs<F, X, N>
+	readonly findFirst: FindFirstArgs<F, X>
+	readonly findUnique: FindUniqueArgs<F, X>
+	readonly findFirstOrThrow: FindFirstArgs<F, X>
+	readonly findUniqueOrThrow: FindUniqueArgs<F, X>
+	readonly count: { readonly where?: Where<F> }
+	readonly aggregate: AggregateArgs<F>
+	readonly groupBy: GroupByArgs<F, N>
+	readonly create: CreateArgs<F, N>
+	readonly update: UpdateArgs<F, X, N>
+	readonly upsert: UpsertArgs<F, X, N>
+	readonly delete: FindUniqueArgs<F, X>
+	readonly updateMany: UpdateManyArgs<F>
+	readonly createMany: CreateManyArgs<F>
+	readonly updateManyAndReturn: UpdateManyAndReturnArgs<F>
+	readonly createManyAndReturn: CreateManyAndReturnArgs<F>
+	readonly deleteMany: { readonly where?: Where<F> | undefined }
+}
+
+/** One record, as arguments `A` return it; without them, its scalars. */
+export type RecordOf<M, A = {}> = Payload<FieldsOf<M>, A>
+export type WhereOf<M> = Where<FieldsOf<M>>
+export type IncludeOf<M> = Include<FieldsOf<M>>
+export type SelectOf<M> = Select<FieldsOf<M>>
+export type OrderByOf<M> = OrderBy<FieldsOf<M>>
+export type CreateDataOf<M> = CreateData<FieldsOf<M>, NameOf<M>>
+export type UpdateDataOf<M> = UpdateData<FieldsOf<M>, NameOf<M>>
+/** The arguments of one operation of the model. */
+export type ArgsOf<
+	M,
+	O extends keyof Operations<FieldsOf<M>, UniqueOf<M>, NameOf<M>>,
+> = Operations<FieldsOf<M>, UniqueOf<M>, NameOf<M>>[O]
+
+/** What a caller sends to a function, before validation. */
+export type InputOf<Fn> = Fn extends { readonly input: infer I }
+	? RunArgs<I> extends readonly [input: infer V, options?: unknown]
+		? V
+		: undefined
+	: never
+/** What a function returns. */
+export type OutputOf<Fn> = Fn extends { readonly output: infer O }
+	? ResultOf<O>
+	: never

package/src/update-many.ts

@@ -0,0 +1,268 @@
+// `updateMany` (D-133): what an `update` runs, on each row its `where`
+// selects, all or nothing; one write when nothing needs the rows (D-99).
+// `updateManyAndReturn` returns them in `id` order, each as `update` does
+// (D-149).
+import { recordOf } from './access.ts'
+import type { Change, Filter, Order, Row } from './adapter.ts'
+import { InvalidQuery } from './errors.ts'
+import type { Event } from './hooks.ts'
+import { rereads, runHook, settle } from './hooks.ts'
+import type { Operations } from './number-update.ts'
+import { computeOn, operationsOf, inRange, validates } from './number-update.ts'
+import type { Plan as Shaped } from './query-args.ts'
+import { oneKeys } from './query-args.ts'
+import type { Context } from './query-context.ts'
+import { filtered, given, shapedRows } from './query-context.ts'
+import { byIds, entries } from './query-where.ts'
+import { updatePlan } from './query-write.ts'
+import type { ModelInfo } from './schema.ts'
+import type { Commit, Store } from './transaction.ts'
+import type { Draft } from './write-data.ts'
+import { prepared, readData } from './write-data.ts'
+import type { Plan } from './write-plan.ts'
+import { updated } from './write-plan.ts'
+import { checkedWrite, guarded } from './write-target.ts'
+import { writingOf } from './writing.ts'
+import { returned } from './writes.ts'
+
+// In id order, so two calls on the same rows wait instead of deadlocking.
+const orderBy: readonly Order[] = [{ field: 'id', direction: 'asc' }]
+
+/** The scalar data of the rows, as `update` reads it (D-133 point 2). */
+function scalarData(context: Context, data: unknown): Draft {
+	const { models, model } = context
+	for (const [name] of entries(data, 'data')) {
+		if (model.fields.get(name)?.kind === 'scalar') continue
+		if (!model.fields.has(name)) continue
+		const path = `data.${name}`
+		throw new InvalidQuery(
+			path,
+			`${path} is a relation, which updateMany does not write.`,
+		)
+	}
+	return readData(models, model, data, false)
+}
+
+/** The plan's update, spread to every row `where` selects. */
+function spread(plan: Plan, where: Filter): Change[] {
+	return plan.steps.flatMap((step) =>
+		step.kind === 'update' ? [{ ...step, where }] : [],
+	)
+}
+
+/** A row, its own copy of the data, and the data the rules saw (D-133). */
+type Item = {
+	readonly row: Row
+	readonly draft: Draft
+	readonly sent: Readonly<Draft>
+}
+
+/** Rows whose data came out the same, and the operations the write computes. */
+type Group = {
+	readonly draft: Draft
+	readonly operations: Operations
+	readonly items: [Item, ...Item[]]
+}
+
+const same = (a: Group, b: Omit<Group, 'items'>): boolean => {
+	const keys = Object.keys(a.draft)
+	return (
+		keys.length === Object.keys(b.draft).length &&
+		keys.every(
+			(key) =>
+				Object.hasOwn(b.draft, key) && Object.is(a.draft[key], b.draft[key]),
+		) &&
+		[...a.operations.keys()].join() === [...b.operations.keys()].join()
+	)
+}
+
+/**
+ * A row's data after its hooks: a number or list they left as computed is
+ * computed by the write again, the row being locked, so rows share one
+ * statement.
+ */
+function settled(item: Item, operations: Operations): Omit<Group, 'items'> {
+	const left = new Map(operations)
+	const draft: Draft = { ...item.draft }
+	for (const name of operations.keys()) {
+		if (Object.is(item.draft[name], item.sent[name])) delete draft[name]
+		else left.delete(name)
+	}
+	return { draft, operations: left }
+}
+
+/** The rows by data; one a hook gave a relation write is planned alone. */
+function grouped(
+	model: ModelInfo,
+	items: readonly Item[],
+	operations: Operations,
+) {
+	const groups: Group[] = []
+	for (const item of items) {
+		const each = settled(item, operations)
+		const scalars = Object.keys(each.draft).every(
+			(name) => model.fields.get(name)?.kind === 'scalar',
+		)
+		const found = scalars
+			? groups.find((group) => same(group, each))
+			: undefined
+		if (found === undefined) groups.push({ ...each, items: [item] })
+		else found.items.push(item)
+	}
+	return groups
+}
+
+/**
+ * Each row through the update rule and hooks, then their writes (D-133):
+ * the rows changed, or with `at` as it shapes them.
+ */
+async function lockedRows(
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	data: { readonly draft: Draft; readonly operations: Operations },
+	where: Filter,
+	at: Shaped | undefined,
+): Promise<readonly unknown[]> {
+	const { model, caller, scope } = context
+	const { operations } = data
+	const rows = await store.find({
+		model: model.name,
+		where,
+		orderBy,
+		lock: true,
+	})
+	const items = rows.map((row): Item => {
+		const draft: Draft = { ...data.draft }
+		computeOn(model, row, draft, operations)
+		return { row, draft, sent: { ...draft } }
+	})
+	// One row refused, none written (D-111).
+	for (const { row, sent } of items) {
+		scope.access?.allow(model, 'update', { record: row, data: sent })
+	}
+	if (items.length === 0) return []
+	for (const { row, draft } of items) {
+		await prepared(model, draft, caller, false)
+		const record = recordOf(model, row)
+		await runHook(model, 'beforeUpdate', { caller, record, data: draft })
+	}
+	const events: Event[] = items.map(({ row }) => ({
+		model,
+		operation: 'update',
+		id: row.id,
+		before: row,
+	}))
+	const writing = writingOf(scope, store, events)
+	const changes: Change[] = []
+	for (const group of grouped(model, items, operations)) {
+		const [{ row, sent }] = group.items
+		const plan = await updatePlan(
+			scope,
+			model,
+			row.id,
+			group.draft,
+			sent,
+			store,
+			group.operations,
+		)
+		events.push(...plan.events)
+		await plan.check(writing)
+		const ids = group.items.map((item) => item.row.id)
+		const one = ids.length === 1
+		changes.push(
+			...(one
+				? await plan.changes(writing)
+				: spread(plan, { id: { in: ids } })),
+		)
+	}
+	const ids = items.map((item) => item.row.id)
+	const read = at && {
+		model: model.name,
+		...at.read,
+		where: byIds(ids),
+		orderBy,
+	}
+	// An `after*` hook may change the rows: they are read once it ran (D-88).
+	const again = rereads(events)
+	const written = await inRange(
+		model,
+		checkedWrite(store, writing.checks, changes, again ? undefined : read),
+	)
+	await settle(store, caller, events, commits)
+	if (at === undefined || read === undefined) return ids
+	const result = again ? await store.find(read) : written
+	return shapedRows(context, store, result, at.shape, scope.access)
+}
+
+/**
+ * Updates the rows `where` selects: their ids, or with `at` the rows as it
+ * shapes them, in `id` order. The rows come back even when a read rule
+ * would hide them, as `update`'s does (D-86).
+ */
+async function updating(
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	found: ReadonlyMap<string, unknown>,
+	at?: Shaped,
+): Promise<readonly unknown[]> {
+	const { model, caller, scope } = context
+	const draft = scalarData(context, found.get('data'))
+	const operations = operationsOf(model, draft)
+	const where: Filter = (await filtered(context, found, 'update')) ?? {}
+	// A relation read beside the UPDATE would see its rows as they were.
+	const nests = at?.read.include !== undefined || at?.read.count !== undefined
+	if (
+		scope.access !== undefined ||
+		updated(model) ||
+		validates(model, operations) ||
+		nests
+	) {
+		const data = { draft, operations }
+		return lockedRows(context, store, commits, data, where, at)
+	}
+	// Nothing needs the stored rows: one UPDATE, which computes the numbers
+	// and lists and returns the rows it changed (D-104).
+	await prepared(model, draft, caller, false)
+	const plan = await updatePlan(
+		scope,
+		model,
+		'',
+		draft,
+		draft,
+		store,
+		operations,
+	)
+	const write = {
+		changes: spread(plan, where),
+		read: { model: model.name, ...at?.read, orderBy },
+		before: true,
+	}
+	const rows = await inRange(model, guarded(store.last(write), []))
+	if (at === undefined) return rows.map((row) => row.id)
+	return shapedRows(context, store, rows, at.shape, scope.access)
+}
+
+export async function updateMany(
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	args: unknown,
+): Promise<{ readonly count: number }> {
+	const found = given(args, context.model.name, ['where', 'data'], ['data'])
+	const ids = await updating(context, store, commits, found)
+	return { count: ids.length }
+}
+
+export async function updateManyAndReturn(
+	context: Context,
+	store: Store,
+	commits: Commit[],
+	args: unknown,
+): Promise<readonly unknown[]> {
+	const keys = ['where', 'data', ...oneKeys]
+	const found = given(args, context.model.name, keys, ['data'])
+	const at = await returned(context, found)
+	return updating(context, store, commits, found, at)
+}

package/src/uuid.ts

@@ -0,0 +1,51 @@
+// UUIDv7 ids (D-22, RFC 9562): a millisecond timestamp, then a 12-bit counter
+// in `rand_a` so that ids made in the same millisecond still sort in order.
+
+let lastTime = 0
+let counter = 0
+
+export function uuidv7(): string {
+	let time = Date.now()
+	if (time > lastTime) {
+		lastTime = time
+		counter = 0
+	} else {
+		counter += 1
+		if (counter > 0xfff) {
+			lastTime += 1
+			counter = 0
+		}
+		time = lastTime
+	}
+	const bytes = new Uint8Array(16)
+	crypto.getRandomValues(bytes)
+	for (let index = 5; index >= 0; index -= 1) {
+		bytes[index] = time % 256
+		time = Math.floor(time / 256)
+	}
+	bytes[6] = 0x70 | (counter >> 8)
+	bytes[7] = counter & 0xff
+	bytes[8] = 0x80 | ((bytes[8] ?? 0) & 0x3f)
+	const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, '0'))
+	return [
+		hex.slice(0, 4),
+		hex.slice(4, 6),
+		hex.slice(6, 8),
+		hex.slice(8, 10),
+		hex.slice(10, 16),
+	]
+		.map((part) => part.join(''))
+		.join('-')
+}
+
+const made = new WeakMap<object, string>()
+
+/**
+ * The id of the row a nested `create` makes from `data`: made once, so its
+ * relation's field rule sees it before the row is planned (D-128).
+ */
+export function madeId(data: object): string {
+	const id = made.get(data) ?? uuidv7()
+	made.set(data, id)
+	return id
+}