ultimabase 0.0.0-stage → 0.1.1

package/src/errors.ts

@@ -0,0 +1,97 @@
+// The errors a client may see (D-28, D-72). Any other error is masked as
+// `INTERNAL` with a correlation id. `Refused` is for the developer (D-119).
+import type { JsonValue } from './fields.ts'
+
+/** The kernel's codes; a transport gives each its own status (D-72). */
+export type ErrorCode =
+	| 'ACCESS_DENIED'
+	| 'NOT_FOUND'
+	| 'VALIDATION_FAILED'
+	| 'UNIQUE_VIOLATION'
+	| 'RELATION_RESTRICTED'
+	| 'UNAUTHENTICATED'
+	| 'INVALID_CREDENTIALS'
+	| 'TOO_MANY_ATTEMPTS'
+	| 'INTERNAL'
+
+/** One failing value, as Standard Schema reports it (D-23). */
+export type Issue = {
+	readonly path: readonly (string | number)[]
+	readonly message: string
+}
+
+type Details<C> = C extends 'VALIDATION_FAILED'
+	? { readonly issues: readonly Issue[] }
+	: C extends 'TOO_MANY_ATTEMPTS'
+		? { /** In seconds (D-113). */ readonly retryAfter: number }
+		: JsonValue
+
+/** An error whose code, message and details reach the client. */
+export interface PublicError extends Error {
+	readonly code: ErrorCode | Uppercase<string>
+	readonly details?: JsonValue
+}
+
+type PublicErrorConstructor = {
+	new <const C extends string>(
+		code: C extends Uppercase<C> ? C : Uppercase<C>,
+		message: string,
+		options?: { readonly details?: Details<C>; readonly cause?: unknown },
+	): PublicError
+	readonly prototype: PublicError
+}
+
+class PublicErrorClass extends Error {
+	readonly code: string
+	readonly details?: JsonValue
+
+	constructor(
+		code: string,
+		message: string,
+		options?: { readonly details?: JsonValue; readonly cause?: unknown },
+	) {
+		super(
+			message,
+			options && 'cause' in options ? { cause: options.cause } : {},
+		)
+		this.name = 'PublicError'
+		this.code = code
+		if (options?.details !== undefined) this.details = options.details
+	}
+}
+
+/**
+ * The code is a kernel code, which keeps its meaning, or the application's
+ * own, in capitals. Only the constructor is generic: `instanceof` would type
+ * a generic class's members as `any`.
+ */
+export const PublicError: PublicErrorConstructor =
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the class is the constructor; only its generic signature is added.
+	PublicErrorClass as unknown as PublicErrorConstructor
+
+/**
+ * A query argument the kernel does not know (D-20): a bug of the server
+ * code, never public.
+ */
+export class InvalidQuery extends Error {
+	readonly code = 'INVALID_QUERY'
+	readonly path: string
+
+	constructor(path: string, message: string) {
+		super(message)
+		this.name = 'InvalidQuery'
+		this.path = path
+	}
+}
+
+/**
+ * A configuration refused while the application is defined or starts, whose
+ * message says what is wrong and how to fix it: a command prints it without
+ * its stack (D-119).
+ */
+export class Refused extends Error {
+	constructor(message: string, options?: ErrorOptions) {
+		super(message, options)
+		this.name = 'Refused'
+	}
+}

package/src/exact.ts

@@ -0,0 +1,49 @@
+// Query arguments are inferred (`const A`), so TypeScript skips the excess
+// property check: a misspelled key next to a valid one would pass. `Exact`
+// walks the written arguments against their schema and turns every unknown
+// key into a message, reported on that key's line. It is `unknown` where the
+// arguments fit, so a valid query costs one walk and no comparison.
+type Leaf =
+	string | number | boolean | bigint | symbol | Date | null | undefined
+type Shapes<S> = Exclude<
+	Extract<S, object>,
+	Date | readonly unknown[] | ((...args: never[]) => unknown)
+>
+type Keys<S> = S extends unknown ? keyof S : never
+type At<S, K> = S extends unknown ? (K extends keyof S ? S[K] : never) : never
+type Items<S> = Extract<S, readonly unknown[]>[number]
+// Identical, not only assignable both ways: an index signature is not.
+type Same<A, S> =
+	// oxlint-disable-next-line typescript/no-unnecessary-type-parameters -- `T` probes how each type relates, the usual identity test.
+	(<T>() => T extends A ? 1 : 2) extends <T>() => T extends S ? 1 : 2
+		? true
+		: false
+type Fine<O> = [keyof O] extends [never] ? unknown : O
+// Only the misspelled keys, and the keys whose value holds one, are kept.
+type Fields<A, S> = Fine<{
+	readonly [
+		K in keyof A as K extends Keys<S>
+			? unknown extends Exact<A[K], At<S, K>>
+				? never
+				: K
+			: K
+	]: K extends Keys<S>
+		? Exact<A[K], At<S, K>>
+		: { readonly error: `'${K & string}' is not a key here` }
+}>
+// A written key is required; a type whose keys are all optional, such as a
+// variable typed `Where<F>`, was checked where it was written. Walking it
+// would recurse through every relation. So would arguments inferred as their
+// own schema, as on a failed call.
+export type Exact<A, S> = [A] extends [Leaf]
+	? unknown
+	: {} extends A
+		? unknown
+		: Same<A, S> extends true
+			? unknown
+			: A extends readonly unknown[]
+				? Fits<A, { readonly [I in keyof A]: Exact<A[I], Items<S>> }>
+				: Fields<A, Shapes<S>>
+// A list whose every item fits is `unknown`, like an object: a list of rows
+// to create sits inside another one (D-128).
+type Fits<A, E> = { readonly [I in keyof A]: unknown } extends E ? unknown : E

package/src/feed.ts

@@ -0,0 +1,39 @@
+// The change feed (D-154): what each commit changed, to the plugins that
+// take it. The adapter feeds nothing when none does.
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { Feed } from './adapter.ts'
+import type { PluginRecord } from './definition.ts'
+import { inOrder, type Installed } from './plugin-app.ts'
+
+// Outside every async context: an adapter may deliver from within the write,
+// whose transaction and recording a hook's queries must not join.
+const outside = AsyncLocalStorage.snapshot()
+
+/** Calls each plugin's `changed` and `missed`, in declaration order. */
+export function feedOf(
+	records: readonly PluginRecord[],
+	plugins: readonly Installed[],
+): Feed | undefined {
+	const takers = inOrder(records, plugins).filter(
+		({ code }) => code.changed !== undefined,
+	)
+	if (takers.length === 0) return undefined
+	// A plugin failing on a change must not stop the others nor the write.
+	const each = (hook: 'changed' | 'missed', args: readonly unknown[]): void => {
+		for (const { code, context } of takers) {
+			const run = code[hook]
+			if (run === undefined) continue
+			try {
+				outside(() => {
+					Reflect.apply(run, undefined, [...args, context])
+				})
+			} catch (error) {
+				context.logger.error({ err: error }, `The plugin's ${hook} failed.`)
+			}
+		}
+	}
+	return {
+		changed: (changes) => each('changed', [changes]),
+		missed: () => each('missed', []),
+	}
+}

package/src/field-codec.ts

@@ -0,0 +1,72 @@
+// Plugin field values decoded as rows leave the adapter (D-122): code, rules
+// and hooks read the value, the adapter its stored form.
+import type { Nested, Row } from './adapter.ts'
+import type { Codec } from './definition.ts'
+import { isObject } from './query-where.ts'
+import type { ModelInfo } from './schema.ts'
+
+type Models = ReadonlyMap<string, ModelInfo>
+type Codecs = readonly (readonly [string, Codec])[]
+
+const known = new WeakMap<ModelInfo, Codecs>()
+
+function codecsOf(model: ModelInfo): Codecs {
+	const found = known.get(model)
+	if (found !== undefined) return found
+	const codecs = [...model.fields.values()].flatMap((field) =>
+		field.kind === 'scalar' && field.codec !== undefined
+			? [[field.name, field.codec] as const]
+			: [],
+	)
+	known.set(model, codecs)
+	return codecs
+}
+
+/** The row with its plugin fields decoded, its included rows' too. */
+function decodedRow(
+	models: Models,
+	model: ModelInfo,
+	read: Nested,
+	row: Row,
+): Row {
+	const changed: { [field: string]: unknown } = {}
+	// `null` is stored as is, never decoded.
+	for (const [name, codec] of codecsOf(model)) {
+		const value = row[name]
+		if (value !== undefined && value !== null) {
+			changed[name] = codec.decode(value)
+		}
+	}
+	for (const [name, nested] of Object.entries(read.include ?? {})) {
+		const field = model.fields.get(name)
+		const target =
+			field === undefined || field.kind === 'scalar'
+				? undefined
+				: models.get(field.target)
+		const value = row[name]
+		if (target === undefined) continue
+		if (Array.isArray(value)) {
+			changed[name] = value.map((item: unknown) =>
+				isRow(item) ? decodedRow(models, target, nested, item) : item,
+			)
+		} else if (isRow(value)) {
+			changed[name] = decodedRow(models, target, nested, value)
+		}
+	}
+	return Object.keys(changed).length === 0 ? row : { ...row, ...changed }
+}
+
+/** A value the kernel reads as a row: an object with a string `id`. */
+export const isRow = (value: unknown): value is Row =>
+	isObject(value) && typeof value['id'] === 'string'
+
+/** The rows `read` returned, decoded. */
+export function decoded(
+	models: Models,
+	read: (Nested & { readonly model: string }) | undefined,
+	rows: Row[],
+): Row[] {
+	const model = read === undefined ? undefined : models.get(read.model)
+	if (read === undefined || model === undefined) return rows
+	return rows.map((row) => decodedRow(models, model, read, row))
+}

package/src/field-rules.ts

@@ -0,0 +1,77 @@
+// The rules a field's `.with` takes (D-44), and the plugins' own (D-57).
+import type { RecordFor } from './record.ts'
+import type { Caller } from './rules.ts'
+import type { declaredRecord } from './symbols.ts'
+
+// `R` is the record type the developer declares for the rules (D-44). It
+// never derives from the model, which is still being typed here: that would
+// be a cycle (TS7022).
+type ReadFacts<R extends object> = {
+	readonly caller: Caller
+	readonly operation: 'read'
+	readonly record: RecordFor<R>
+}
+type CreateFacts<V> = {
+	readonly caller: Caller
+	readonly operation: 'create'
+	readonly value: V
+}
+type UpdateFacts<R extends object, V> = {
+	readonly caller: Caller
+	readonly operation: 'update'
+	readonly record: RecordFor<R>
+	readonly value: V
+}
+type Rule<F> = (facts: F) => boolean
+// Named, so a type error shows the rule the developer wrote.
+type FieldReadRule<R extends object> = Rule<ReadFacts<R>>
+type FieldCreateRule<V> = Rule<CreateFacts<V>>
+type FieldUpdateRule<R extends object, V> = Rule<UpdateFacts<R, V>>
+type FieldWriteRule<R extends object, V> = Rule<
+	CreateFacts<V> | UpdateFacts<R, V>
+>
+type FieldRule<R extends object, V> = Rule<
+	ReadFacts<R> | CreateFacts<V> | UpdateFacts<R, V>
+>
+
+/** A field keeps its declared record type, which `defineModel` checks. */
+// Each declared field is kept as `(value: T) => T`, which only the same `T`
+// fits: a wider or a narrower type fails, and the error shows the model's.
+export type Declared<R> = [R] extends [never]
+	? unknown
+	: {
+			readonly [declaredRecord]: {
+				readonly [P in keyof R]: (value: R[P]) => R[P]
+			}
+		}
+
+/** One rule, or one rule per operation (D-44). */
+export type FieldAccess<R extends object, V> =
+	| FieldRule<R, V>
+	| {
+			readonly read?: FieldReadRule<R>
+			readonly create?: FieldCreateRule<V>
+			readonly update?: FieldUpdateRule<R, V>
+			readonly write?: FieldWriteRule<R, V>
+	  }
+
+/**
+ * The rules of the model's plugins for one field, each under the plugin's
+ * name and typed by the field's value (D-12, D-57).
+ */
+type PluginFieldRules<T, V> = {
+	readonly [
+		X in T as X extends {
+			readonly name: infer N extends string
+			readonly fieldWith: object
+		}
+			? N
+			: never
+	]?: X extends { readonly fieldWith: object }
+		? (X & { readonly value: V })['fieldWith']
+		: never
+}
+
+export type FieldWith<R extends object, V, T = never> = {
+	readonly access?: FieldAccess<R, V>
+} & PluginFieldRules<T, V>

package/src/field-type.ts

@@ -0,0 +1,219 @@
+// `defineFieldType` (D-32, D-122): a plugin's field type, stored through a
+// kernel field and seen by code as the value its `decode` gives.
+import type { Codec, FieldDefinition, FieldOptions } from './definition.ts'
+import { build, fieldBuilders, fieldDefinitions } from './definition.ts'
+import type {
+	DefaultFunction,
+	Described,
+	Field,
+	FieldBuilders,
+	JsonValue,
+	SchemaTypes,
+	StandardSchema,
+} from './fields.ts'
+import type { fieldType } from './symbols.ts'
+import { standardOf } from './validation.ts'
+
+/** A kernel scalar field, as `stored` returns it. */
+type Stored = {
+	readonly [fieldType]: {
+		readonly kind: 'scalar'
+		readonly value: unknown
+		readonly options: unknown
+	}
+}
+type StoredValue<S> = S extends {
+	readonly [fieldType]: { readonly value: infer V }
+}
+	? V
+	: never
+type StoredOptions<S> = S extends {
+	readonly [fieldType]: { readonly options: infer O }
+}
+	? O
+	: never
+
+/** What `defineFieldType` takes (D-122), each function given the options. */
+export type FieldTypeDefinition<P extends string, S, V, X, O extends object> = {
+	/** The plugin that provides the field type, which `plugins` lists (D-32). */
+	readonly plugin: P
+	/** The names of the field type's own options, beside `default` (D-152). */
+	readonly options?: readonly NoInfer<keyof O & string>[]
+	/** The kernel field that stores, filters and indexes the value. */
+	readonly stored: (f: FieldBuilders<never>, options: O) => S
+	readonly decode: (stored: StoredValue<S>, options: O) => V
+	readonly encode: (value: V, options: O) => StoredValue<S>
+	/** Takes the value or its JSON, and gives the value. */
+	readonly schema: X | ((options: O) => X)
+	/** What a client reads. */
+	readonly toJSON: (value: V, options: O) => JsonValue
+	/** What `toJSON` gives, which types it for clients (D-152). */
+	readonly shape?: StandardSchema | ((options: O) => StandardSchema)
+}
+
+/** A field type's options: the stored field says whether it may be `null`. */
+export type FieldTypeOptions<I> = Described & {
+	readonly default?: I | DefaultFunction<I>
+}
+
+/** The builder `defineFieldType` returns (D-122). */
+export type FieldType<
+	P extends string,
+	S,
+	V,
+	I,
+	// Weak, as `Described` is, so a name it lacks fails to compile.
+	O extends object = Described,
+> = <const G extends FieldTypeOptions<I> & Partial<O> = {}>(
+	options?: G,
+) => Field<V, StoredOptions<S> & G, P, never, I, true, S>
+
+const storedOptions = new Set(['list', 'optional', 'precision', 'scale'])
+const kernelOptions = new Set(['default', 'description'])
+type Options = { readonly [key: string]: unknown }
+
+/**
+ * The stored field `stored` returns, a scalar with no rules; a value as its
+ * default fills the rows stored before the field (D-152).
+ */
+function storedOf(
+	plugin: string,
+	stored: unknown,
+	options: Options,
+): FieldDefinition & { readonly kind: 'scalar' } {
+	if (typeof stored !== 'function') {
+		throw new TypeError(`defineFieldType(${plugin}): stored is a function.`)
+	}
+	const field: unknown = Reflect.apply(stored, undefined, [
+		fieldBuilders,
+		options,
+	])
+	const definition =
+		typeof field === 'object' && field !== null
+			? fieldDefinitions.get(field)
+			: undefined
+	if (definition?.kind !== 'scalar' || definition.rules !== undefined) {
+		throw new TypeError(
+			`defineFieldType(${plugin}): stored returns a kernel scalar field, without .with.`,
+		)
+	}
+	for (const [option, value] of Object.entries(definition.options)) {
+		const filled = option === 'default' && typeof value !== 'function'
+		if (!storedOptions.has(option) && !filled) {
+			throw new Error(
+				`defineFieldType(${plugin}): the stored field takes list, optional, precision, scale or a value as its default only, not ${option}.`,
+			)
+		}
+	}
+	return definition
+}
+
+function functionOf(
+	plugin: string,
+	definition: Options,
+	key: string,
+	options: Options,
+): (value: unknown) => unknown {
+	const value = definition[key]
+	if (typeof value !== 'function') {
+		throw new TypeError(`defineFieldType(${plugin}): ${key} is a function.`)
+	}
+	return (given) => {
+		const result: unknown = Reflect.apply(value, undefined, [given, options])
+		return result
+	}
+}
+
+/** One field's codec, its functions given that field's options. */
+function codecOf(plugin: string, definition: Options, options: Options): Codec {
+	const schemaOf = (key: string) => {
+		const given = definition[key]
+		const standard = standardOf(
+			typeof given === 'function'
+				? Reflect.apply(given, undefined, [options])
+				: given,
+		)
+		if (standard === undefined) {
+			throw new TypeError(
+				`defineFieldType(${plugin}): ${key} is a Standard Schema.`,
+			)
+		}
+		return standard
+	}
+	const shape =
+		definition['shape'] === undefined ? undefined : schemaOf('shape').schema
+	return Object.freeze({
+		plugin,
+		options,
+		decode: functionOf(plugin, definition, 'decode', options),
+		encode: functionOf(plugin, definition, 'encode', options),
+		schema: schemaOf('schema'),
+		toJSON: functionOf(plugin, definition, 'toJSON', options),
+		...(shape === undefined ? {} : { shape }),
+	})
+}
+
+/** The names a builder takes, `default`, `description` and the type's own. */
+function namesOf(plugin: string, definition: Options): ReadonlySet<string> {
+	const names = definition['options'] ?? []
+	if (
+		!Array.isArray(names) ||
+		!names.every((name) => typeof name === 'string')
+	) {
+		throw new TypeError(
+			`defineFieldType(${plugin}): options is a list of option names.`,
+		)
+	}
+	return new Set([...kernelOptions, ...names])
+}
+
+/**
+ * A plugin's field type (D-122): its builder takes `default`, `description`
+ * (D-150) and the type's own options (D-152), and its value is stored through
+ * `stored`, encoded after the hooks and decoded on each read.
+ */
+export function defineFieldType<
+	const P extends string,
+	S extends Stored,
+	V,
+	X extends StandardSchema<unknown, V>,
+	O extends object = Described,
+>(
+	definition: FieldTypeDefinition<P, S, V, X, O>,
+): FieldType<P, S, V, SchemaTypes<X>['input'], O>
+export function defineFieldType(
+	definition: Options,
+): (options?: FieldOptions) => object {
+	const plugin = definition['plugin']
+	if (typeof plugin !== 'string' || plugin === '') {
+		throw new TypeError('defineFieldType takes the name of its plugin.')
+	}
+	const names = namesOf(plugin, definition)
+	// A definition fails at once, not at its first field.
+	codecOf(plugin, definition, {})
+	storedOf(plugin, definition['stored'], {})
+	return (given = {}) => {
+		const own: Record<string, unknown> = {}
+		const kernel: Record<string, unknown> = {}
+		for (const [option, value] of Object.entries(given)) {
+			if (!names.has(option)) {
+				throw new Error(
+					names.size === kernelOptions.size
+						? `A ${plugin} field takes default and description only, not ${option}: its stored field says the rest.`
+						: `A ${plugin} field takes ${[...names].join(', ')} only, not ${option}.`,
+				)
+			}
+			if (kernelOptions.has(option)) kernel[option] = value
+			else own[option] = value
+		}
+		const options = Object.freeze(own)
+		const stored = storedOf(plugin, definition['stored'], options)
+		const { default: filled, ...rest } = stored.options
+		const codec = codecOf(plugin, definition, options)
+		return build({
+			...stored,
+			options: { ...rest, ...kernel },
+			codec: filled === undefined ? codec : Object.freeze({ ...codec, filled }),
+		})
+	}
+}