ultimabase 0.0.0-stage → 0.1.0

package/src/define-app.ts

@@ -0,0 +1,108 @@
+// `defineApp` (D-24, D-59): the application's models and plugins, checked
+// together on its line, and its `start` and `stop` (D-91).
+import type { Adapter } from './adapter.ts'
+import { remember } from './app-internals.ts'
+import type { Logger, MasterKey } from './app-options.ts'
+import type { FunctionShape } from './function.ts'
+import { lifecycle } from './lifecycle.ts'
+import type {
+	App,
+	FieldTypePlugins,
+	InverseCheck,
+	ModelShape,
+} from './model.ts'
+import type { PluginValue } from './plugin.ts'
+import type { fieldType, modelFields } from './symbols.ts'
+
+// Checked on the `defineApp` line, where every model is typed (D-24).
+type Used<M> =
+	| (M extends { readonly plugins?: infer P } ? P : never)
+	| (M extends { readonly [modelFields]: infer F }
+			? FieldTypePlugins<F>
+			: never)
+type Missing<P extends readonly PluginValue<string, string>[], X> = Exclude<
+	Used<X>,
+	P[number]['name'] | undefined
+>
+type RequiresOf<V> = V extends PluginValue<string, infer R> ? R : never
+type Unmet<P extends readonly PluginValue<string, string>[]> = Exclude<
+	RequiresOf<P[number]>,
+	P[number]['name']
+>
+type PluginCheck<
+	P extends readonly PluginValue<string, string>[],
+	M extends readonly ModelShape[],
+	Fn extends readonly FunctionShape[],
+> = [Missing<P, M[number]>] extends [never]
+	? [Missing<P, Fn[number]>] extends [never]
+		? [Unmet<P>] extends [never]
+			? unknown
+			: {
+					readonly pluginError: `a plugin requires '${Unmet<P> & string}', which is not in plugins`
+				}
+		: {
+				readonly pluginError: `a function uses '${Missing<P, Fn[number]> & string}', which is not in plugins`
+			}
+	: {
+			readonly pluginError: `a model uses '${Missing<P, M[number]> & string}', which is not in plugins`
+		}
+
+type Targets<X> = X extends { readonly [modelFields]: infer F }
+	? {
+			[K in keyof F]: F[K] extends {
+				readonly [fieldType]: { readonly target: () => infer T }
+			}
+				? T extends { readonly name: infer N }
+					? N
+					: never
+				: never
+		}[keyof F]
+	: never
+type Unlisted<M extends readonly ModelShape[]> = Exclude<
+	Targets<M[number]>,
+	M[number]['name']
+>
+// Over the names alone, tail-recursive, so a long list stays cheap and within
+// TypeScript's depth. A name typed `string`, a model a function builds, is not
+// compared.
+type Names<M> = {
+	[I in keyof M]: M[I] extends { readonly name: infer N } ? N : never
+}
+type Twice<N, Seen = never, Found = never> = N extends readonly [
+	infer H,
+	...infer R,
+]
+	? string extends H
+		? Twice<R, Seen, Found>
+		: Twice<R, Seen | H, H extends Seen ? Found | H : Found>
+	: Found
+type ModelCheck<M extends readonly ModelShape[]> = [Twice<Names<M>>] extends [
+	never,
+]
+	? [Unlisted<M>] extends [never]
+		? unknown
+		: {
+				readonly modelError: `a relation points to '${Unlisted<M> & string}', which is not in models`
+			}
+	: {
+			readonly modelError: `two models are named '${Twice<Names<M>> & string}'`
+		}
+
+export function defineApp<
+	const P extends readonly PluginValue<string, string>[] = [],
+	const M extends readonly ModelShape[] = [],
+	const Fn extends readonly FunctionShape[] = [],
+>(
+	options: {
+		readonly database: Adapter
+		readonly plugins?: P
+		readonly models: M
+		readonly functions?: Fn
+		readonly masterKey?: MasterKey
+		readonly logger?: Logger
+	} & NoInfer<PluginCheck<P, M, Fn>> &
+		NoInfer<ModelCheck<M>> &
+		NoInfer<InverseCheck<M>>,
+): App<M> {
+	return remember({ models: options.models, ...lifecycle(options) }, options)
+}

package/src/define-enum.ts

@@ -0,0 +1,26 @@
+// Shared enums (D-150): one name and its values, which every field taking
+// it shows as one GraphQL enum and one OpenAPI schema; storage is unchanged.
+import { describedBy, enumValues, sharedEnums } from './definition.ts'
+import type { Enum } from './fields.ts'
+
+/** A shared enum, frozen, which `f.enumOf` takes in place of its values. */
+export function defineEnum<const E extends string>(
+	name: string,
+	values: readonly E[],
+	options: { readonly description?: string } = {},
+): Enum<E> {
+	if (!/^[A-Z_a-z]\w*$/.test(name) || name.startsWith('__')) {
+		throw new Error(
+			`defineEnum takes a GraphQL name: letters, digits and _, not ${JSON.stringify(name)}.`,
+		)
+	}
+	const of = `defineEnum(${name})`
+	enumValues(values, of)
+	const shared: Enum<E> = Object.freeze({
+		name,
+		values: Object.freeze([...values]),
+		description: describedBy(options.description, of),
+	})
+	sharedEnums.set(shared, shared)
+	return shared
+}

package/src/define-function.ts

@@ -0,0 +1,188 @@
+// `defineFunction` and `defineType` (D-27, D-109): a server operation, its
+// access rule checked and its input validated on each `run` (D-75), and the
+// named objects its output may hold.
+import { refused } from './access.ts'
+import type { FunctionDefinition, Output } from './definition.ts'
+import {
+	describedBy,
+	functionDefinitions,
+	nameOf,
+	nullable,
+	outputOf,
+	typeDefinitions,
+	withOnce,
+} from './definition.ts'
+import { entriesOf } from './plugin-use.ts'
+import { callerOf } from './engine.ts'
+import { PublicError, Refused } from './errors.ts'
+import type { StandardSchema } from './fields.ts'
+import type {
+	Client,
+	FunctionPlugin,
+	FunctionWithKeys,
+	InputCheck,
+	ObjectType,
+	OutputSpec,
+	QueryCheck,
+	ResultOf,
+	RunFacts,
+	ServerFunction,
+	TypeFields,
+} from './function.ts'
+import type { ModelUse } from './plugin.ts'
+import { isObject } from './query-where.ts'
+import type { Caller } from './rules.ts'
+import { isMaster } from './rules.ts'
+import type { Running } from './running.ts'
+import { current } from './running.ts'
+import { checked, standardOf } from './validation.ts'
+
+export function defineType<
+	const N extends string,
+	const F extends TypeFields,
+>(definition: {
+	readonly name: N
+	/** What the type means, which the transports show (D-150). */
+	readonly description?: string
+	readonly fields: F
+}): ObjectType<N, F> {
+	const { fields } = definition
+	const name = nameOf(definition.name, 'defineType')
+	const description = describedBy(definition.description, name)
+	if (!isObject(fields) || Object.keys(fields).length === 0) {
+		throw new Refused(`${name}: fields is an object of one output or more.`)
+	}
+	const outputs = new Map<string, Output>()
+	for (const [field, value] of Object.entries(fields)) {
+		outputs.set(field, outputOf(value, `${name}.${field}`))
+	}
+	const recorded = { name, description, fields: outputs }
+	const type: object = Object.freeze({
+		name,
+		nullable: (): object => nullable({ kind: 'type', type: recorded }),
+	})
+	typeDefinitions.set(type, recorded)
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the value holds the name and `nullable`; its fields are a type only.
+	return type as ObjectType<N, F>
+}
+
+/** Closed to all but Master by default (D-04); the rule reads the caller. */
+function allowed(
+	record: FunctionDefinition,
+	caller: Caller,
+	app: Running,
+): void {
+	if (isMaster(caller)) return
+	const rule = isObject(record.rules) ? record.rules['access'] : undefined
+	if (rule !== undefined && typeof rule !== 'function') {
+		throw new TypeError(`${record.name}: access is a function.`)
+	}
+	const result: unknown =
+		rule === undefined ? false : Reflect.apply(rule, undefined, [{ caller }])
+	if (typeof result !== 'boolean') {
+		throw new TypeError(`${record.name}: access returns a boolean.`)
+	}
+	if (result) return
+	const { name } = record
+	throw refused({ function: name }, `${name} refused.`, caller, app.logger)
+}
+
+/** `run`'s call, the input first when the function takes one; a transport
+ * passes its client (D-113). */
+export async function called(
+	value: object,
+	record: FunctionDefinition,
+	args: readonly unknown[],
+	client?: Client,
+): Promise<unknown> {
+	const app = current()
+	if (app?.functions.get(value) !== record) {
+		throw new Error(
+			`${record.name} is not a function of a started application.`,
+		)
+	}
+	const { input: schema, name } = record
+	const [input, options] =
+		schema === undefined ? [undefined, args[0]] : [args[0], args[1]]
+	const identity = callerOf(options, name)
+	return app.work.run(async () => {
+		const caller = await app.complete(identity)
+		allowed(record, caller, app)
+		const facts: { [key: string]: unknown } = { caller, client }
+		const standard = standardOf(schema)
+		if (standard !== undefined) {
+			const result = await checked(standard, input, [], name)
+			if ('issues' in result) {
+				throw new PublicError('VALIDATION_FAILED', 'Invalid input.', {
+					details: { issues: result.issues },
+				})
+			}
+			facts['input'] = result.value
+		}
+		const output: unknown = await Reflect.apply(record.run, undefined, [
+			Object.freeze(facts),
+		])
+		return record.output === undefined ? undefined : output
+	})
+}
+
+export function defineFunction<
+	const N extends string,
+	const O extends OutputSpec | undefined = undefined,
+	const I extends StandardSchema | undefined = undefined,
+	const U extends readonly ModelUse<string, FunctionPlugin>[] = [],
+>(
+	definition: {
+		readonly name: N
+		/** What the function does, which the transports show (D-150). */
+		readonly description?: string
+		/** A query, served over GET too; a mutation by default (D-109). */
+		readonly query?: boolean
+		readonly use?: U
+		readonly input?: I
+		readonly output?: O
+		readonly run: (
+			facts: RunFacts<NoInfer<I>>,
+		) => NoInfer<ResultOf<O>> | Promise<NoInfer<ResultOf<O>>>
+	} & NoInfer<InputCheck<I>> &
+		NoInfer<QueryCheck<U[number]>>,
+): ServerFunction<N, I, O, U[number]['plugin'], FunctionWithKeys<U[number]>> {
+	const { query = false, input, output, run } = definition
+	const name = nameOf(definition.name, 'defineFunction')
+	const description = describedBy(definition.description, name)
+	if (typeof query !== 'boolean')
+		throw new Refused(`${name}: query is a boolean.`)
+	if (input !== undefined && standardOf(input) === undefined) {
+		throw new Refused(`${name}: input is a Standard Schema.`)
+	}
+	if (typeof run !== 'function')
+		throw new Refused(`${name}: run is a function.`)
+	const record: FunctionDefinition = {
+		name,
+		description,
+		query,
+		input,
+		output:
+			output === undefined ? undefined : outputOf(output, `${name}.output`),
+		uses: entriesOf(name, definition.use ?? []),
+		run,
+		rules: undefined,
+	}
+	const fn: object = Object.freeze({
+		name,
+		input,
+		output,
+		with: withOnce(name, record, () => fn),
+		run: async (...args: unknown[]): Promise<unknown> =>
+			called(fn, record, args),
+	})
+	functionDefinitions.set(fn, record)
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the value ServerFunction describes; its types follow the definition.
+	return fn as unknown as ServerFunction<
+		N,
+		I,
+		O,
+		U[number]['plugin'],
+		FunctionWithKeys<U[number]>
+	>
+}

package/src/define-model.ts

@@ -0,0 +1,220 @@
+// `defineModel` (D-07, D-12): the fields its callback and its plugins build,
+// recorded for `start`, and the model value whose methods run the queries
+// (D-18) and its plugins' commands (D-89).
+import {
+	describedBy,
+	fieldBuilders,
+	modelDefinitions,
+	nameOf,
+	nullable,
+	withOnce,
+} from './definition.ts'
+import type { FieldDefinition, ModelDefinition } from './definition.ts'
+import { query } from './engine.ts'
+import type { Operation } from './engine.ts'
+import { addFields, usedBy } from './plugin-use.ts'
+import type { FieldBuilders } from './fields.ts'
+import type {
+	FieldShape,
+	IndexCheck,
+	IndexShape,
+	Model,
+	RecordCheck,
+	UniqueIndexFields,
+} from './model.ts'
+import type { ForModel, ModelUse, PluginTypes } from './plugin.ts'
+import { Refused } from './errors.ts'
+
+// The intersection of the used plugins' commands; `unknown` without any.
+type CommandFn<U, F> =
+	U extends ModelUse<string, infer T>
+		? T extends { readonly commands: object }
+			? (value: ForModel<T, F>['commands']) => void
+			: never
+		: never
+type Commands<U, F> = [CommandFn<U, F>] extends [never]
+	? unknown
+	: CommandFn<U, F> extends (value: infer I) => void
+		? I
+		: unknown
+
+/** Each used plugin's key of `.with`, typed by the model's fields. */
+type WithKeys<U, F> = {
+	readonly [
+		V in U as V extends ModelUse<infer P, infer T>
+			? T extends { readonly with: object | false }
+				? P
+				: never
+			: never
+	]?: V extends ModelUse<
+		string,
+		infer T extends { readonly with: object | false }
+	>
+		? ForModel<T, F>['with']
+		: never
+}
+
+/** The types of the plugins in a model's `use`. */
+type UsedTypes<U> = U extends ModelUse<string, infer T> ? T : never
+
+// The fields the used plugins add, merged with the model's own.
+type AddFn<U> =
+	U extends ModelUse<string, infer T>
+		? T extends { readonly addedFields: infer A }
+			? (value: A) => void
+			: never
+		: never
+type Added<U> = [AddFn<U>] extends [never]
+	? unknown
+	: AddFn<U> extends (value: infer I) => void
+		? I
+		: unknown
+type AllFields<F, U> = [Added<U>] extends [unknown]
+	? unknown extends Added<U>
+		? F
+		: F & Added<U>
+	: F & Added<U>
+
+/** A model's fields, as `fields` returns them. */
+export type FieldShapes = { readonly [field: string]: FieldShape }
+
+/** The `fields` callback: its builders know the plugins of `use` (D-12, D-57). */
+export type ModelFields<
+	F,
+	U extends readonly ModelUse<string, PluginTypes>[],
+> = (fields: FieldBuilders<UsedTypes<U[number]>>) => F & NoInfer<RecordCheck<F>>
+
+/**
+ * The model a declaration with these fields and plugins builds; a plugin's
+ * `define<Kind>` returns it with its own entry in `U` (D-13).
+ */
+export type ModelOf<
+	N extends string,
+	F,
+	U extends readonly ModelUse<string, PluginTypes>[],
+	X extends readonly IndexShape[] = [],
+> = Model<
+	N,
+	AllFields<F, U[number]>,
+	U[number]['plugin'],
+	WithKeys<U[number], AllFields<F, U[number]>>,
+	UniqueIndexFields<X>
+> &
+	Commands<U[number], AllFields<F, U[number]>>
+
+/** `indexes`, whose fields are checked against the model's (D-52). */
+export type ModelIndexes<
+	X,
+	F,
+	U extends readonly ModelUse<string, PluginTypes>[],
+> = X & NoInfer<IndexCheck<X, AllFields<F, U[number]>>>
+
+export function defineModel<
+	const N extends string,
+	const F extends FieldShapes,
+	const U extends readonly ModelUse<string, PluginTypes>[] = [],
+	const X extends readonly IndexShape[] = [],
+>(definition: {
+	readonly name: N
+	/** What the model means, which the transports show (D-150). */
+	readonly description?: string
+	/** The stored table's or collection's name (D-63). */
+	readonly dbName?: string
+	readonly use?: U
+	/** The only form (D-12). */
+	readonly fields: ModelFields<F, U>
+	readonly indexes?: ModelIndexes<X, F, U>
+}): ModelOf<N, F, U, X> {
+	const model = createModel({
+		name: definition.name,
+		description: definition.description,
+		dbName: definition.dbName,
+		use: definition.use ?? [],
+		fields: definition.fields,
+		indexes: definition.indexes ?? [],
+	})
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- createModel builds the value ModelOf describes; the types follow the definition.
+	return model as unknown as ModelOf<N, F, U, X>
+}
+
+const operations: readonly Operation[] = [
+	'findMany',
+	'findFirst',
+	'findUnique',
+	'findFirstOrThrow',
+	'findUniqueOrThrow',
+	'count',
+	'aggregate',
+	'groupBy',
+	'create',
+	'update',
+	'upsert',
+	'delete',
+	'updateMany',
+	'createMany',
+	'updateManyAndReturn',
+	'createManyAndReturn',
+	'deleteMany',
+]
+
+function createModel(definition: {
+	readonly name: unknown
+	readonly description: unknown
+	readonly dbName: unknown
+	readonly use: readonly unknown[]
+	readonly fields: Function
+	readonly indexes: readonly IndexShape[]
+}): object {
+	const { dbName } = definition
+	const name = nameOf(definition.name, 'defineModel')
+	if (dbName !== undefined && typeof dbName !== 'string') {
+		throw new Refused(`${name}: dbName must be a string.`)
+	}
+	const description = describedBy(definition.description, name)
+	const built: unknown = Reflect.apply(definition.fields, undefined, [
+		fieldBuilders,
+	])
+	const fields = new Map<string, FieldDefinition>()
+	addFields(name, built, fields, new Map())
+	const queries: { [operation: string]: unknown } = {}
+	for (const operation of operations) {
+		queries[operation] = async (args?: unknown, options?: unknown) =>
+			query(name, operation, args, options)
+	}
+	Object.freeze(queries)
+	const { uses, commands, indexes } = usedBy(
+		name,
+		definition.use,
+		fields,
+		queries,
+	)
+	const record: ModelDefinition = {
+		name,
+		description,
+		dbName,
+		fields,
+		indexes: [
+			...definition.indexes.map((index) => ({
+				fields: [...index.fields],
+				...(index.unique === undefined ? {} : { unique: index.unique }),
+				...(index.contains === undefined ? {} : { contains: index.contains }),
+			})),
+			// A plugin's, checked with the model's at startup (D-122).
+			...indexes,
+		],
+		uses,
+		queries,
+		rules: undefined,
+	}
+	const model: { [key: string]: unknown } = {
+		name,
+		...queries,
+		...Object.fromEntries(commands),
+	}
+	model['with'] = withOnce(name, record, () => frozen)
+	model['nullable'] = (): object =>
+		nullable({ kind: 'model', value: frozen, name })
+	const frozen = Object.freeze(model)
+	modelDefinitions.set(frozen, record)
+	return frozen
+}