ultimabase 0.0.0-stage → 0.1.0

package/src/memory.ts

@@ -0,0 +1,173 @@
+// `memory()`: the in-memory adapter, for tests and examples (D-02). Each write
+// runs on a copy of the store that replaces it once whole, so a failed write
+// changes nothing; a transaction holds the write lock until it ends.
+import type { Adapter, Changed, Feed, Schema, Transaction } from './adapter.ts'
+import { feedFields, feedIds } from './adapter.ts'
+import { Draft } from './memory-draft.ts'
+import type { Fields, Store, StoredRow } from './memory-read.ts'
+import { clone } from './memory-read.ts'
+
+/** The reads of the draft `get` gives, each a tick later, as a database's. */
+function readsOf(
+	get: () => Draft,
+): Pick<Transaction, 'find' | 'count' | 'aggregate'> {
+	const later = async <R>(read: (draft: Draft) => R): Promise<R> => {
+		await Promise.resolve()
+		return read(get())
+	}
+	return {
+		find: async (read) => later((draft) => draft.find(read)),
+		count: async (read) => later((draft) => draft.count(read)),
+		aggregate: async (read) => later((draft) => draft.aggregate(read)),
+	}
+}
+
+/**
+ * `changes` as the feed gives them: one entry for the same rows' changes,
+ * without the lists past its limits (D-154).
+ */
+function fed(changes: readonly Changed[]): Changed[] {
+	type Entry = {
+		readonly change: Changed
+		readonly ids: string[]
+		readonly pairs: (readonly [string, string])[]
+	}
+	const entries = new Map<string, Entry>()
+	for (const change of changes) {
+		const linked = 'field' in change
+		const key = JSON.stringify([
+			change.kind,
+			change.model,
+			linked ? change.field : change.fields,
+		])
+		const entry = entries.get(key) ?? { change, ids: [], pairs: [] }
+		if (linked) entry.pairs.push(...(change.pairs ?? []))
+		else entry.ids.push(...(change.ids ?? []))
+		entries.set(key, entry)
+	}
+	return [...entries.values()].map(({ change, ids, pairs }): Changed => {
+		if ('field' in change) {
+			const { kind, model, field } = change
+			const listed = pairs.length > feedIds ? {} : { pairs }
+			return { kind, model, field, ...listed }
+		}
+		const { kind, model, fields } = change
+		const listed = ids.length > feedIds ? {} : { ids }
+		const some =
+			fields !== undefined && JSON.stringify(fields).length <= feedFields
+		return { kind, model, ...listed, ...(some ? { fields } : {}) }
+	})
+}
+
+/** The in-memory adapter (D-02); its state lives as long as the value. */
+export function memory(): Adapter {
+	let schema: Schema | undefined
+	let fields: Fields = new Map()
+	let store: Store = { tables: new Map(), joins: new Map() }
+	let lock: Promise<void> = Promise.resolve()
+	let feed: Feed | undefined
+
+	// After the commit, as a database's notifications come.
+	const deliver = (changes: readonly Changed[]): void => {
+		const to = feed
+		if (to === undefined || changes.length === 0) return
+		setImmediate(() => to.changed(fed(changes)))
+	}
+
+	const draft = (from: Store): Draft => {
+		if (schema === undefined) throw new Error('memory() is not started.')
+		return new Draft(from, fields, schema)
+	}
+	// Writes queue behind each other and behind an open transaction.
+	const acquire = async (): Promise<() => void> => {
+		const previous = lock
+		const { promise, resolve } = Promise.withResolvers<void>()
+		lock = promise
+		await previous
+		return resolve
+	}
+
+	return {
+		start: async (started, _logger, given) => {
+			schema = started
+			feed = given
+			fields = new Map(
+				started.models.map((model) => [
+					model.name,
+					new Map(model.fields.map((field) => [field.name, field])),
+				]),
+			)
+			store = {
+				tables: new Map(
+					started.models.map((model) => [
+						model.name,
+						new Map<string, StoredRow>(),
+					]),
+				),
+				joins: new Map(),
+			}
+			await Promise.resolve()
+		},
+		stop: async () => {
+			await lock
+		},
+		...readsOf(() => draft(store)),
+		write: async (write) => {
+			const release = await acquire()
+			try {
+				const next = clone(store)
+				const writing = draft(next)
+				const rows = writing.write(write)
+				store = next
+				deliver(writing.changed)
+				return rows
+			} finally {
+				release()
+			}
+		},
+		begin: async (): Promise<Transaction> => {
+			const release = await acquire()
+			const next = clone(store)
+			const changed: Changed[] = []
+			let open = true
+			const active = (): Draft => {
+				if (!open) throw new Error('The transaction has ended.')
+				return draft(next)
+			}
+			const end = (): void => {
+				open = false
+				release()
+			}
+			return {
+				...readsOf(active),
+				write: async (write) => {
+					await Promise.resolve()
+					active()
+					// A failed write leaves the transaction as it was.
+					const attempt = clone(next)
+					const writing = draft(attempt)
+					const rows = writing.write(write)
+					changed.push(...writing.changed)
+					next.tables.clear()
+					next.joins.clear()
+					for (const [name, table] of attempt.tables)
+						next.tables.set(name, table)
+					for (const [name, side] of attempt.joins) next.joins.set(name, side)
+					return rows
+				},
+				commit: async () => {
+					active()
+					store = next
+					end()
+					deliver(changed)
+					await Promise.resolve()
+				},
+				rollback: async () => {
+					active()
+					end()
+					await Promise.resolve()
+				},
+			}
+		},
+	}
+}

package/src/migrate.ts

@@ -0,0 +1,152 @@
+// Development sync and the production check (D-105): the models' snapshot
+// against the database's, through the adapter's `migrations`.
+import { createHash } from 'node:crypto'
+import type { Adapter, Migrations, Schema, Statement } from './adapter.ts'
+import { MigrationFailed } from './adapter.ts'
+import type { Logger } from './app-options.ts'
+import { Refused } from './errors.ts'
+
+/** The value with its keys sorted, so equal snapshots serialize alike. */
+function canonical(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(canonical)
+	if (typeof value !== 'object' || value === null) return value
+	const keys = Object.keys(value).toSorted()
+	return Object.fromEntries(
+		keys.map((key) => [key, canonical(Reflect.get(value, key))]),
+	)
+}
+
+/** The SHA-256 of a snapshot's canonical JSON. */
+export function hashOf(snapshot: unknown): string {
+	return createHash('sha256')
+		.update(JSON.stringify(canonical(snapshot)))
+		.digest('hex')
+}
+
+/** The database's `migrations`, or a refusal naming what has none. */
+export function migrationsOf(database: Adapter): Migrations {
+	if (database.migrations === undefined) {
+		throw new Refused(
+			'This database starts empty every time: it has no tables to migrate.',
+		)
+	}
+	return database.migrations
+}
+
+function refusal(losing: readonly Statement[]): string {
+	const models = [...new Set(losing.map((statement) => statement.model))]
+	const why = losing.map((statement) => statement.loses).join('; ')
+	return [
+		`UltimaBase did not sync ${models.join(', ')}: ${why}.`,
+		...losing.flatMap(({ sql, rename }) => [
+			...(rename === undefined
+				? []
+				: [
+						`  -- a rename? keep its data: give ${rename.to} dbName: '${rename.dbName}'.`,
+					]),
+			`  ${sql};`,
+		]),
+		'Run `npx ultimabase sync --force` to apply it to this development database,',
+		'or `npx ultimabase migrate create <name>` to write it as a migration.',
+	].join('\n')
+}
+
+/** What to do about a table another session held too long. */
+export const held =
+	"End that session's open transaction, in a database tool perhaps, then try again."
+
+/** Why a tried statement failed, and how to fix the rows. */
+function failure(
+	statements: readonly Statement[],
+	{ at, reason, locked }: MigrationFailed,
+): string {
+	const statement = statements.find((given) => given.sql === at)
+	const model = statement?.model ?? 'the models'
+	const why = locked
+		? 'another session held its table'
+		: (statement?.tries ?? 'the database refused it')
+	return [
+		`UltimaBase did not sync ${model}: ${why}.`,
+		`  ${at};`,
+		`  -- ${reason}`,
+		...(locked
+			? [held]
+			: [
+					'Fix those rows in this development database, or rebuild it from the migrations with `npx ultimabase reset`.',
+					'In production, a migration fixes them: write it with `npx ultimabase migrate create <name>`.',
+				]),
+	].join('\n')
+}
+
+/**
+ * Brings a development database to the models, refusing what loses data
+ * unless `force`, and logs what changed. Returns the statements it ran, or
+ * none when the database already matched.
+ */
+export async function synced(
+	database: Adapter,
+	schema: Schema,
+	logger: Logger,
+	force: boolean,
+): Promise<readonly Statement[] | undefined> {
+	const migrations = database.migrations
+	if (migrations === undefined) return undefined
+	const stored = await migrations.stored()
+	const from = stored?.snapshot
+	const to = migrations.snapshot(schema)
+	if (from !== undefined && hashOf(from) === hashOf(to)) return undefined
+	const statements = migrations.plan(from, schema)
+	const losing = statements.filter((statement) => statement.loses !== undefined)
+	if (losing.length > 0 && !force) throw new Refused(refusal(losing))
+	try {
+		await migrations.apply({ kind: 'sync', from, statements, to })
+	} catch (error) {
+		if (error instanceof MigrationFailed) {
+			throw new Refused(failure(statements, error))
+		}
+		throw error
+	}
+	if (from === undefined) {
+		logger.info("Created the database's tables.")
+		return statements
+	}
+	if (statements.length === 0) {
+		logger.info("Synced the models' names: no table changed.")
+	}
+	const changes = Map.groupBy(statements, (statement) => statement.model)
+	for (const [model, made] of changes) {
+		const does = made.map((statement) => statement.does).join(', ')
+		logger.info(`Synced ${model}: ${does}.`)
+	}
+	return statements
+}
+
+/**
+ * Refuses a production database whose snapshot is not the models', unless
+ * a deploy applied migrations after them: the code was rolled back.
+ */
+export async function checked(
+	database: Adapter,
+	schema: Schema,
+	logger: Logger,
+): Promise<void> {
+	const migrations = database.migrations
+	if (migrations === undefined) return
+	const stored = await migrations.stored()
+	const deploy = 'run `npx ultimabase migrate deploy`, then start again.'
+	if (stored?.snapshot === undefined) {
+		throw new Refused(`The database has no UltimaBase schema: ${deploy}`)
+	}
+	const hash = hashOf(migrations.snapshot(schema))
+	if (hashOf(stored.snapshot) === hash) return
+	const at = stored.applied.findIndex((file) => file.schema === hash)
+	const later = stored.applied.slice(at + 1).map((file) => file.name)
+	if (at === -1 || later.length === 0) {
+		throw new Refused(`The database's tables are not the models': ${deploy}`)
+	}
+	logger.warn(ahead(later))
+}
+
+/** What a database whose migrations follow the models' says. */
+export const ahead = (later: readonly string[]): string =>
+	`The database is ahead of the models: ${later.join(', ')} ${later.length === 1 ? 'was' : 'were'} applied after them.`

package/src/model.ts

@@ -0,0 +1,312 @@
+// The model `defineModel(...).with(...)` returns (D-07, D-24) and the
+// application `defineApp` assembles.
+import type { Nullable } from './function.ts'
+import type { FindWhere, Queries, Where } from './query.ts'
+import type {
+	CreateData,
+	RecordOf,
+	StoredRecord,
+	TargetFields,
+	UpdateData,
+} from './record.ts'
+import type { Caller } from './rules.ts'
+import type { VirtualRules } from './virtual.ts'
+import type {
+	declaredRecord,
+	fieldType,
+	modelFields,
+	readFilter,
+} from './symbols.ts'
+
+type ReadFacts = { readonly caller: Caller; readonly operation: 'read' }
+type CreateFacts<F, N extends string> = {
+	readonly caller: Caller
+	readonly operation: 'create'
+	readonly value: CreateData<F, N>
+}
+type UpdateFacts<F, N extends string> = {
+	readonly caller: Caller
+	readonly operation: 'update'
+	readonly record: StoredRecord<F, N>
+	readonly value: UpdateData<F, N, false>
+}
+type DeleteFacts<F, N extends string> = {
+	readonly caller: Caller
+	readonly operation: 'delete'
+	readonly record: StoredRecord<F, N>
+}
+
+/** A read filter; only the `where` a read rule receives builds one (D-10). */
+type ReadFilter = { readonly [readFilter]: true }
+/**
+ * A model read rule cannot see the record: it may return a filter (D-10).
+ * TypeScript never checks a returned object for unknown keys, but it checks
+ * an argument: `where({ ... })` refuses a misspelled key on its line.
+ */
+type ReadRule<F> = (
+	facts: ReadFacts & { readonly where: (filter: Where<F>) => ReadFilter },
+) => boolean | ReadFilter
+
+/** One rule, or one rule per operation; `write` covers the three writes. */
+export type ModelAccess<F, N extends string> =
+	| ((
+			facts:
+				ReadFacts | CreateFacts<F, N> | UpdateFacts<F, N> | DeleteFacts<F, N>,
+	  ) => boolean)
+	| {
+			readonly read?: ReadRule<F>
+			readonly create?: (facts: CreateFacts<F, N>) => boolean
+			readonly update?: (facts: UpdateFacts<F, N>) => boolean
+			readonly delete?: (facts: DeleteFacts<F, N>) => boolean
+			readonly write?: (
+				facts: CreateFacts<F, N> | UpdateFacts<F, N> | DeleteFacts<F, N>,
+			) => boolean
+	  }
+
+type Hook<Facts> = (
+	facts: Facts & { readonly caller: Caller },
+) => void | Promise<void>
+type RecordHook<F, N extends string> = Hook<{
+	readonly record: StoredRecord<F, N>
+}>
+type UpdatedHook<F, N extends string> = Hook<{
+	readonly record: StoredRecord<F, N>
+	readonly previous: StoredRecord<F, N>
+}>
+/** The data a `before*` hook changes in place (D-71). */
+type Draft<D> = { -readonly [K in keyof D]: D[K] }
+
+/**
+ * What the rows a `beforeFind` narrows are for: an update or a delete of the
+ * rows a write targets, a read everywhere else (D-124).
+ */
+export type FindOperation = 'read' | 'update' | 'delete'
+
+/** The fixed hooks of D-15, written by the application (D-43, D-71). */
+export type ModelHooks<F, N extends string = string> = {
+	/**
+	 * Narrows every read of the model, at every level, Master included;
+	 * `operation` says whether the rows are read or written (D-124).
+	 */
+	readonly beforeFind?: (facts: {
+		readonly caller: Caller
+		readonly operation: FindOperation
+		readonly where: (filter: FindWhere<F>) => ReadFilter
+	}) => ReadFilter | void | Promise<ReadFilter | void>
+	readonly beforeCreate?: Hook<{ readonly data: Draft<CreateData<F, N>> }>
+	readonly beforeUpdate?: Hook<{
+		readonly record: StoredRecord<F, N>
+		readonly data: Draft<UpdateData<F, N, false>>
+	}>
+	readonly beforeDelete?: RecordHook<F, N>
+	readonly afterCreate?: RecordHook<F, N>
+	readonly afterUpdate?: UpdatedHook<F, N>
+	readonly afterDelete?: RecordHook<F, N>
+	readonly afterCreateCommit?: RecordHook<F, N>
+	readonly afterUpdateCommit?: UpdatedHook<F, N>
+	readonly afterDeleteCommit?: RecordHook<F, N>
+}
+
+/**
+ * What a `many` relation's reads see, Master's too (D-151): a function
+ * shaped like a read rule, typed from the target.
+ */
+type RelationFilter<T> = {
+	readonly where: (facts: {
+		readonly caller: Caller
+		readonly where: (filter: Where<T>) => ReadFilter
+	}) => boolean | ReadFilter
+}
+
+/** A filter for each `many` relation that has one (D-151). */
+export type RelationFilters<F> = {
+	readonly [
+		K in keyof F as F[K] extends {
+			readonly [fieldType]: { readonly kind: 'many' }
+		}
+			? K
+			: never
+	]?: F[K] extends { readonly [fieldType]: { readonly target: infer T } }
+		? RelationFilter<TargetFields<T>>
+		: never
+}
+
+/** The kernel's keys; `W` holds one key per plugin (D-42, D-151). */
+export type ModelWith<F, W, N extends string> = {
+	readonly access?: ModelAccess<F, N>
+	readonly hooks?: ModelHooks<F, N>
+	readonly relations?: RelationFilters<F>
+	readonly virtuals?: VirtualRules<F>
+} & W
+
+/** `X` lists the fields of each unique index (D-52). */
+export interface Model<N extends string, F, P, W, X = never> extends Queries<
+	F,
+	X,
+	N
+> {
+	readonly name: N
+	readonly [modelFields]: F
+	/** The plugins it uses, checked against the application's (D-24). */
+	readonly plugins?: P
+	with(rules: ModelWith<F, W, N>): this
+	/** The model, or `null`, as a function's output (D-109). */
+	nullable(): Nullable<this>
+}
+
+export type FieldShape = {
+	readonly [fieldType]: {
+		readonly kind: 'scalar' | 'one' | 'many' | 'virtual'
+		readonly options: object
+	}
+}
+
+// Exact type equality, which `any` and optional keys do not pass.
+type Same<A, B> =
+	// oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- the test needs a free `T`
+	(<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+		? true
+		: false
+
+type Exact<V> = (value: V) => V
+
+// The record type a field's rules declare (D-44) lists some of the model's
+// fields, each with the model's exact type, required. Checked here, where the
+// fields are known; a mismatch fails against the model's type, so the error
+// shows it. `any` fits both ways and gets a message instead.
+type Expected<D, F> = {
+	readonly [P in keyof D]-?: P extends keyof RecordOf<F>
+		? Same<D[P], Exact<RecordOf<F>[P]>> extends true
+			? D[P]
+			: D[P] extends Exact<RecordOf<F>[P]>
+				? `'${P & string}' does not have the model's exact type`
+				: Exact<RecordOf<F>[P]>
+		: `'${P & string}' is not a scalar field of the model`
+}
+
+// A field typed before the model cannot check its record against it.
+export type RecordCheck<F> = {
+	readonly [K in keyof F]: F[K] extends { readonly [declaredRecord]: infer D }
+		? { readonly [declaredRecord]: Expected<D, F> }
+		: unknown
+}
+
+/**
+ * The plugins that provide the model's field types (D-32). Without
+ * `exactOptionalPropertyTypes`, a field no plugin provides reads `undefined`.
+ */
+export type FieldTypePlugins<F> = {
+	[K in keyof F]: F[K] extends {
+		readonly [fieldType]: { readonly plugin?: infer P }
+	}
+		? P extends string
+			? P
+			: never
+		: never
+}[keyof F]
+
+/** An index of `defineModel`, over one or several fields (D-52). */
+export type IndexShape = {
+	readonly fields: readonly string[]
+	readonly unique?: boolean
+	/** A trigram index, for `contains` and `mode: 'insensitive'` (D-141). */
+	readonly contains?: true
+}
+
+/** The fields of each unique index. */
+export type UniqueIndexFields<X> = X extends readonly (infer I)[]
+	? I extends { readonly unique: true; readonly fields: infer K }
+		? K
+		: never
+	: never
+
+// An index covers scalar fields and `one` relations, the model's columns.
+type IndexableKeys<F> = {
+	[K in keyof F]: F[K] extends {
+		readonly [fieldType]: { readonly kind: 'scalar' | 'one' }
+	}
+		? K
+		: never
+}[keyof F]
+// A `contains` index covers one string field that is not a list (D-141).
+type TextKeys<F> = {
+	[K in keyof F]: F[K] extends {
+		readonly [fieldType]: { readonly kind: 'scalar'; readonly value: infer V }
+	}
+		? [V] extends [string]
+			? string extends V
+				? K
+				: never
+			: never
+		: never
+}[keyof F]
+type ContainsCheck<I, F> = I extends { readonly contains: true }
+	? I extends {
+			readonly fields: readonly [TextKeys<F>]
+			readonly unique?: false | undefined
+		}
+		? unknown
+		: {
+				readonly contains: 'a contains index covers one string field that is not a list, and is not unique'
+			}
+	: unknown
+type NotIndexable<I, F> = I extends { readonly fields: readonly (infer K)[] }
+	? Exclude<K, IndexableKeys<F>>
+	: never
+
+/**
+ * Each index names fields of the model. TypeScript first checks the call
+ * before reading `fields`, while `F` is still any field name: the check
+ * waits for the real fields.
+ */
+export type IndexCheck<X, F> = string extends keyof F
+	? unknown
+	: {
+			readonly [I in keyof X]: ([NotIndexable<X[I], F>] extends [never]
+				? unknown
+				: {
+						readonly fields: `'${NotIndexable<X[I], F> & string}' is not a scalar field or a one relation of the model`
+					}) &
+				ContainsCheck<X[I], F>
+		}
+
+export type ModelShape = {
+	readonly name: string
+	readonly [modelFields]: object
+}
+
+// An `inverse` names a field of the target (D-37). It is checked here, where
+// every model is typed, since reading the target while declaring is a cycle.
+type InverseErrors<N extends string, F> = {
+	[K in keyof F]: F[K] extends {
+		readonly [fieldType]: {
+			readonly target: infer T
+			readonly options: { readonly inverse: infer I extends string }
+		}
+	}
+		? I extends keyof TargetFields<T>
+			? never
+			: `${N}.${K & string}: inverse '${I}' is not a field of the target`
+		: never
+}[keyof F]
+
+type AppInverseErrors<M> = {
+	[I in keyof M]: M[I] extends {
+		readonly name: infer N extends string
+		readonly [modelFields]: infer F
+	}
+		? InverseErrors<N, F>
+		: never
+}[number & keyof M]
+
+/** Checked on the whole options object, as `ModelCheck` is. */
+export type InverseCheck<M> = [AppInverseErrors<M>] extends [never]
+	? unknown
+	: { readonly inverseError: AppInverseErrors<M> }
+
+/** The application `defineApp` returns (D-24, D-59). */
+export interface App<M> {
+	readonly models: M
+	start(): Promise<void>
+	stop(): Promise<void>
+}