ultimabase 0.0.0-stage → 0.1.0

package/src/adapter.ts

@@ -0,0 +1,363 @@
+// The adapter contract (D-73): what the kernel sends a storage adapter, fully
+// prepared. Names are the models' own; `dbName` says what to store them as.
+import type { JsonCondition } from './adapter-json.ts'
+import type { Migrations } from './adapter-migrations.ts'
+import type { Logger } from './app-options.ts'
+
+export type {
+	Migration,
+	Migrations,
+	Run,
+	Statement,
+	Stored,
+} from './adapter-migrations.ts'
+export {
+	CheckFailed,
+	MigrationFailed,
+	OutOfRange,
+	RelationViolation,
+	UniqueViolation,
+} from './adapter-errors.ts'
+
+export type ScalarType =
+	| 'string'
+	| 'number'
+	| 'decimal'
+	| 'boolean'
+	| 'dateTime'
+	| 'date'
+	| 'json'
+	| 'enum'
+
+export type SchemaField =
+	| {
+			readonly kind: 'scalar'
+			readonly name: string
+			readonly type: ScalarType
+			/** An `enum`'s values. */
+			readonly values?: readonly string[]
+			/**
+			 * A list of `type`, a string, a number or an enum value: never
+			 * `null`, `[]` when empty (D-120, D-127).
+			 */
+			readonly list: boolean
+			/** A `number` of whole numbers from -2^31 to 2^31 - 1 (D-132). */
+			readonly integer?: true
+			/**
+			 * A `decimal`'s digits, `scale` of them after the point; its values
+			 * are strings at that scale (D-145).
+			 */
+			readonly precision?: number
+			readonly scale?: number
+			readonly optional: boolean
+			readonly unique: boolean
+			/** A `string` in its model's document, which `_search` matches (D-148). */
+			readonly search?: true
+			readonly dbName?: string
+			/** Its default when it is a value, not a function (D-105). */
+			readonly default?: unknown
+	  }
+	| {
+			readonly kind: 'one'
+			readonly name: string
+			readonly target: string
+			/** The target's field on the other side (D-37). */
+			readonly inverse: string
+			/** Whether this side stores the key, one per pair (D-37). */
+			readonly stored: boolean
+			/** One-to-one: the stored key is unique. */
+			readonly unique: boolean
+			readonly optional: boolean
+			readonly onDelete: 'cascade' | 'restrict' | 'setNull'
+			readonly dbName?: string
+	  }
+	| {
+			readonly kind: 'many'
+			readonly name: string
+			readonly target: string
+			readonly inverse: string
+			/** Facing a `many`: a join holding the two keys only (D-64). */
+			readonly join: boolean
+			/** Its reads see the rows a filter keeps; it takes no `set` (D-151). */
+			readonly filtered?: true
+			/**
+			 * A view: read-only, on the link of the `many` it names, with that
+			 * relation's `inverse` and `join` (D-151).
+			 */
+			readonly from?: string
+	  }
+
+export type SchemaModel = {
+	readonly name: string
+	readonly dbName?: string
+	/** `id`, `createdAt` and `updatedAt` are implicit (D-22). */
+	readonly fields: readonly SchemaField[]
+	readonly indexes: readonly {
+		readonly fields: readonly string[]
+		readonly unique: boolean
+		/** Serves `contains` and `mode: 'insensitive'` (D-141). */
+		readonly contains: boolean
+	}[]
+}
+
+export type Schema = { readonly models: readonly SchemaModel[] }
+
+/** A normalized condition on one field: no shorthand, no `undefined`. */
+export type Condition = JsonCondition & {
+	readonly equals?: unknown
+	readonly not?: unknown
+	readonly in?: readonly unknown[]
+	readonly notIn?: readonly unknown[]
+	readonly lt?: unknown
+	readonly lte?: unknown
+	readonly gt?: unknown
+	readonly gte?: unknown
+	readonly contains?: string
+	readonly startsWith?: string
+	readonly endsWith?: string
+	/** The string operators ignore case (D-140). */
+	readonly mode?: 'insensitive'
+	/** A list holds this element (D-120, D-127). */
+	readonly has?: unknown
+	/** A list holds one of these elements (D-120, D-127). */
+	readonly hasSome?: readonly unknown[]
+	/** A list holds each of these elements (D-149). */
+	readonly hasEvery?: readonly unknown[]
+	/** A list is empty, or not (D-149). */
+	readonly isEmpty?: boolean
+	readonly is?: Filter | null
+	readonly isNot?: Filter | null
+	readonly some?: Filter
+	readonly every?: Filter
+	readonly none?: Filter
+	/**
+	 * A stored `one` key names a row that the delete at this index of the
+	 * write's changes removed, a change before this one (D-102).
+	 */
+	readonly removedBy?: number
+	/**
+	 * Under the key `_search`: the row's searched fields match this text, in
+	 * PostgreSQL's `websearch_to_tsquery` syntax (D-148).
+	 */
+	readonly search?: string
+}
+
+/** A normalized `where`: `AND`, `OR` and `NOT` are lists (D-73). */
+export interface Filter {
+	readonly AND?: readonly Filter[]
+	readonly OR?: readonly Filter[]
+	readonly NOT?: readonly Filter[]
+	readonly [field: string]: Condition | readonly Filter[] | undefined
+}
+
+/** A `one` relation a sort key goes through, to the rows `where` selects. */
+export type Step = { readonly relation: string; readonly where?: Filter }
+
+export type Order = {
+	/** A field of the row, or of the row `through` reaches. */
+	readonly field: string
+	readonly direction: 'asc' | 'desc'
+	/** Where `null` sorts: by default last ascending, first descending (D-149). */
+	readonly nulls?: 'first' | 'last'
+	/** The `one` relations followed first; an absent row sorts as `null` (D-134). */
+	readonly through?: readonly Step[]
+	/** `field` is a `many` relation: its rows this filter selects are counted (D-134). */
+	readonly count?: Filter
+	/** `field` is `_relevance`: how well the row matches this text (D-148). */
+	readonly relevance?: string
+}
+
+export type Sort = Pick<Order, 'direction' | 'nulls'>
+
+/** A relation to read with its rows; a `one` relation reads `where` only. */
+export type Nested = {
+	readonly where?: Filter
+	/** Always ends with `id`, so the order is total. */
+	readonly orderBy?: readonly Order[]
+	/** A unique target the page starts at, as Prisma's `cursor`. */
+	readonly cursor?: Filter
+	readonly skip?: number
+	/** Negative: the rows before the cursor, or the last ones. */
+	readonly take?: number
+	/**
+	 * The system and scalar fields the rows return, `id` always; absent, every
+	 * field and each `one` key (D-136).
+	 */
+	readonly fields?: readonly string[]
+	readonly include?: { readonly [field: string]: Nested }
+	/** `many` relations to count in the row's `_count`, by filter (D-134). */
+	readonly count?: { readonly [field: string]: Filter }
+}
+
+export type Read = Nested & {
+	readonly model: string
+	/** Locks the root rows, in `id` order, until the transaction ends (D-99, D-133). */
+	readonly lock?: boolean
+	/**
+	 * Keeps, of the rows with the same keys, the first in `orderBy`'s order,
+	 * before `skip` and `take` (D-147).
+	 */
+	readonly distinct?: readonly GroupKey[]
+}
+
+export type CountRead = { readonly model: string; readonly where?: Filter }
+
+/** One aggregate: `count` without a field counts the rows (D-143). */
+export type Aggregate = {
+	readonly operation: 'count' | 'sum' | 'avg' | 'min' | 'max'
+	/** A scalar field, neither a list nor `json`. */
+	readonly field?: string
+}
+
+/** A group's key: a field, or the `id` of the row `through` reaches (D-146). */
+export type GroupKey = {
+	readonly field: string
+	readonly through?: readonly Step[]
+}
+
+/**
+ * Aggregates of the rows `where` selects, one value each, in order: a count
+ * is a number, the others `null` without a value (D-143). With `by`, of each
+ * group of rows with the same keys; an absent row gives `null` (D-146).
+ */
+export type AggregateRead = CountRead & {
+	readonly aggregates: readonly Aggregate[]
+	readonly by?: readonly GroupKey[]
+	/** A position, `orderBy`'s `at` or a `having` key (D-149): keys, then aggregates. */
+	readonly having?: Filter
+	readonly orderBy?: readonly ({ readonly at: number } & Sort)[]
+	readonly skip?: number
+	readonly take?: number
+}
+
+/**
+ * A stored row: system and scalar fields, and each `one` relation as its key
+ * `{ id } | null`, or the included row. An included `many` is a list of rows.
+ */
+export type Row = { readonly id: string; readonly [field: string]: unknown }
+
+/**
+ * A number update computed on each row the write changes, `null` counting
+ * as 0; an integer's division truncates toward zero (D-132).
+ */
+export type Arithmetic = {
+	readonly operation: 'increment' | 'decrement' | 'multiply' | 'divide'
+	readonly by: number
+}
+
+/**
+ * A list update computed on each row the write changes (D-149): `push`
+ * appends, `pushUnique` appends each element the list lacks, once, and
+ * `remove` drops every occurrence.
+ */
+export type ListUpdate = {
+	readonly operation: 'push' | 'pushUnique' | 'remove'
+	readonly elements: readonly unknown[]
+}
+
+/** In a change, a stored `one` key is the target's id or `null`. */
+export type Change =
+	| { readonly kind: 'insert'; readonly model: string; readonly row: Row }
+	| {
+			readonly kind: 'update'
+			readonly model: string
+			readonly where: Filter
+			readonly set: { readonly [field: string]: unknown }
+			readonly compute?: {
+				readonly [field: string]: Arithmetic | ListUpdate
+			}
+	  }
+	| { readonly kind: 'delete'; readonly model: string; readonly where: Filter }
+	| {
+			readonly kind: 'link' | 'unlink'
+			readonly model: string
+			/** A `many` relation facing a `many`. */
+			readonly field: string
+			readonly id: string
+			readonly targets: readonly string[]
+	  }
+
+/** A count of rows a write needs before it changes anything (D-99). */
+export type Check = {
+	readonly model: string
+	readonly where: Filter
+	readonly count: number
+	/** Locks the rows it counts until the transaction ends, as `Read.lock` (D-99). */
+	readonly lock?: boolean
+}
+
+/**
+ * One whole write: its checks first, which write nothing when one fails,
+ * then its changes, then `read`, in the same write. With `before`, the read
+ * selects among the rows of its model that the write's delete removed, as
+ * they were (D-102, D-104); when the write deletes none of them, among the
+ * rows its first update of that model changed, as it left them (D-133).
+ */
+export type Write = {
+	readonly checks?: readonly Check[]
+	readonly changes: readonly Change[]
+	readonly read?: Read
+	readonly before?: boolean
+}
+
+/**
+ * What a committed write changed (D-154): `ids` is absent when they were
+ * more than `feedIds`, `fields` when they were every field or longer than
+ * `feedFields`. A delete's links go with its rows, unlisted. How changes
+ * group into entries and calls is the adapter's.
+ */
+export type Changed =
+	| {
+			readonly kind: 'insert' | 'update' | 'delete'
+			readonly model: string
+			readonly ids?: readonly string[]
+			/** The fields an update set, `updatedAt` included. */
+			readonly fields?: readonly string[]
+	  }
+	| {
+			readonly kind: 'link' | 'unlink'
+			readonly model: string
+			/** A `many` relation facing a `many`. */
+			readonly field: string
+			/** The model's id, then the target's. */
+			readonly pairs?: readonly (readonly [string, string])[]
+	  }
+
+/** The most ids or pairs a change lists (D-154). */
+export const feedIds = 1000
+/** The longest list of fields, as JSON, an update lists (D-154). */
+export const feedFields = 1500
+
+/** Where an adapter sends the changes each commit makes, on any server. */
+export type Feed = {
+	readonly changed: (changes: readonly Changed[]) => void
+	/** Changes may have been lost, as when a listener reconnects. */
+	readonly missed: () => void
+}
+
+export interface Transaction {
+	find(read: Read): Promise<Row[]>
+	count(read: CountRead): Promise<number>
+	/**
+	 * One list per group: its keys' values, then its aggregates'; without
+	 * `by`, one list, even without rows (D-146).
+	 */
+	aggregate(read: AggregateRead): Promise<unknown[][]>
+	write(write: Write): Promise<Row[]>
+	commit(): Promise<void>
+	rollback(): Promise<void>
+}
+
+/** A storage adapter: its own slot, not a plugin (D-02, D-73). */
+export interface Adapter extends Omit<Transaction, 'commit' | 'rollback'> {
+	/**
+	 * Connects; the kernel then syncs or checks the tables (D-105). `logger`
+	 * is the kernel's, for what the adapter reports (D-140). With `feed`, each
+	 * commit's changes reach it, this server's and the others' (D-154).
+	 */
+	start(schema: Schema, logger: Logger, feed?: Feed): Promise<void>
+	stop(): Promise<void>
+	begin(): Promise<Transaction>
+	/** None for a database that starts empty every time, as `memory()`. */
+	readonly migrations?: Migrations
+}

package/src/aggregate.ts

@@ -0,0 +1,136 @@
+// `aggregate` (D-143): counts, sums, averages, minimums and maximums of the
+// rows the caller reads, on scalar fields it may filter on.
+import type { Aggregate } from './adapter.ts'
+import { InvalidQuery } from './errors.ts'
+import type { Context } from './query-context.ts'
+import { filtered, given } from './query-context.ts'
+import { entries, systemFields, unknownKey } from './query-where.ts'
+import type { ModelInfo } from './schema.ts'
+import type { Store } from './transaction.ts'
+
+const operations = {
+	_count: 'count',
+	_sum: 'sum',
+	_avg: 'avg',
+	_min: 'min',
+	_max: 'max',
+} as const
+export type Key = keyof typeof operations
+export const keys: readonly Key[] = ['_count', '_sum', '_avg', '_min', '_max']
+
+/** The types each aggregate takes; `_count` takes every scalar. */
+const takes: { readonly [K in Key]?: readonly string[] } = {
+	_sum: ['number', 'decimal'],
+	_avg: ['number', 'decimal'],
+	_min: ['number', 'decimal', 'string', 'enum', 'dateTime', 'date'],
+	_max: ['number', 'decimal', 'string', 'enum', 'dateTime', 'date'],
+}
+
+/** The field's type, which fails on a field an aggregate cannot take. */
+export function typeOf(
+	model: ModelInfo,
+	field: string,
+	path: string,
+	verb = 'aggregated',
+): string {
+	const refuse = (kind: string): never => {
+		throw new InvalidQuery(path, `${path} is ${kind}, which cannot be ${verb}.`)
+	}
+	const known = model.fields.get(field)
+	if (known === undefined) {
+		if (!systemFields.includes(field)) throw unknownKey(path, model.name)
+		return field === 'id' ? 'string' : 'dateTime'
+	}
+	if (known.kind !== 'scalar') return refuse('a relation')
+	if (known.list) return refuse('a list')
+	if (known.type === 'json') return refuse('json')
+	if (known.codec !== undefined) return refuse('a plugin field')
+	return known.type
+}
+
+export type Asked = { readonly key: Key; readonly field: string | undefined }
+
+/** Aggregate `key` of `field`, checked; `_all` counts the rows. */
+export function checked(
+	{ model, scope }: Context,
+	key: Key,
+	field: string,
+	path: string,
+): Asked {
+	if (key === '_count' && field === '_all') return { key, field: undefined }
+	const type = typeOf(model, field, path)
+	const types = takes[key]
+	if (types !== undefined && !types.includes(type)) {
+		throw new InvalidQuery(
+			path,
+			`${path} is a ${type} field; ${key} takes ${types.join(', ')} fields.`,
+		)
+	}
+	scope.check(model, field, path, 'aggregates')
+	return { key, field }
+}
+
+/** The aggregates `key` asks for, each checked. */
+function asked(context: Context, key: Key, value: unknown): readonly Asked[] {
+	if (key === '_count' && value === true) return [{ key, field: undefined }]
+	return entries(value, key).map(([field, flag]): Asked => {
+		const path = `${key}.${field}`
+		if (flag !== true) {
+			throw new InvalidQuery(path, `${path} must be true.`)
+		}
+		return checked(context, key, field, path)
+	})
+}
+
+/** The aggregates the arguments ask for, in the order of `keys`. */
+export const wanted = (
+	context: Context,
+	found: ReadonlyMap<string, unknown>,
+): readonly Asked[] =>
+	keys.flatMap((key) =>
+		found.has(key) ? asked(context, key, found.get(key)) : [],
+	)
+
+export const toAggregate = ({ key, field }: Asked): Aggregate => ({
+	operation: operations[key],
+	...(field !== undefined && { field }),
+})
+
+/** The aggregates' values under the keys the arguments ask for. */
+export function shaped(
+	found: ReadonlyMap<string, unknown>,
+	list: readonly Asked[],
+	values: readonly unknown[],
+): { [key: string]: unknown } {
+	const result: { [key: string]: unknown } = {}
+	for (const [index, { key, field }] of list.entries()) {
+		const value = values[index]
+		if (key === '_count' && found.get(key) === true) {
+			result[key] = value
+			continue
+		}
+		const fields = result[key] ?? {}
+		result[key] = { ...fields, [field ?? '_all']: value }
+	}
+	for (const key of keys) {
+		if (found.has(key)) result[key] ??= {}
+	}
+	return result
+}
+
+export async function aggregate(
+	context: Context,
+	store: Store,
+	args: unknown,
+): Promise<unknown> {
+	const { model } = context
+	const found = given(args, model.name, ['where', ...keys], [])
+	const list = wanted(context, found)
+	const where = await filtered(context, found, 'read')
+	const [values = []] = await store.aggregate({
+		model: model.name,
+		...(where && { where }),
+		aggregates: list.map(toAggregate),
+	})
+	return shaped(found, list, values)
+}

package/src/app-internals.ts

@@ -0,0 +1,26 @@
+// What the `ultimabase` commands read from an application (D-105): its
+// options and its lifecycle, kept off its public surface.
+import type { Lifecycle, LifecycleOptions } from './lifecycle.ts'
+
+export type Internals = {
+	readonly options: LifecycleOptions
+	readonly app: Lifecycle
+}
+
+const internals = new WeakMap<object, Internals>()
+
+/** Remembers the options `defineApp` built `app` from. */
+export function remember<T extends Lifecycle>(
+	app: T,
+	options: LifecycleOptions,
+): T {
+	internals.set(app, { options, app })
+	return app
+}
+
+/** What `defineApp` kept of a value it returned, or `undefined`. */
+export function internalsOf(value: unknown): Internals | undefined {
+	return typeof value === 'object' && value !== null
+		? internals.get(value)
+		: undefined
+}

package/src/app-options.ts

@@ -0,0 +1,24 @@
+// What `defineApp` takes beside its database, plugins and models (D-49,
+// D-58).
+
+type LogFunction = {
+	(message: string): void
+	(bindings: object, message?: string): void
+}
+/** Pino's interface (D-58); without one, the kernel writes JSON lines. */
+export interface Logger {
+	readonly info: LogFunction
+	readonly warn: LogFunction
+	readonly error: LogFunction
+	child(bindings: object): Logger
+}
+
+/**
+ * Refused in production unless written `{ key, production: true }`, with 32
+ * characters at least (D-49).
+ * `undefined` leaves it off, so an unset environment variable passes as is.
+ */
+export type MasterKey =
+	| string
+	| undefined
+	| { readonly key: string | undefined; readonly production: true }