ultimabase 0.0.0-stage → 0.1.0

package/src/plugin.ts

@@ -0,0 +1,400 @@
+// A plugin is an interface of types and one `definePlugin` (D-57). Its types
+// travel with its values; nothing is declared globally (D-24).
+import type { Logger } from './app-options.ts'
+import type { Enum, FieldBuilders, StandardSchema } from './fields.ts'
+import type { Client, FunctionShape } from './function.ts'
+import type { Identify } from './identify.ts'
+import { pluginEntries, pluginValues } from './definition.ts'
+import { pluginCode } from './plugin-code.ts'
+import type { FieldShape, ModelHooks, ModelShape } from './model.ts'
+import type { Changed, Row, SchemaModel } from './adapter.ts'
+import type { Queries, QueryOptions, UniqueWhere } from './query.ts'
+import type {
+	Caller,
+	Identity,
+	Register,
+	UserCallerKeys,
+	UserOf,
+} from './rules.ts'
+import type { pluginTypes } from './symbols.ts'
+
+/** The keys of a user caller a plugin gives (D-121). */
+type CallerKeys = Partial<UserCallerKeys> & object
+
+/**
+ * What a plugin adds to the models that use it (D-57). `this['fields']` is
+ * the fields of the model that lists the plugin in its `use`, and
+ * `this['options']` the options of its entry there.
+ */
+export interface PluginTypes {
+	/** Its name, the key of its `.with` (D-24). */
+	readonly name: string
+	readonly fields: unknown
+	/** The value of the field whose `.with` holds its field rule. */
+	readonly value: unknown
+	/** Its entry's options, `softDelete({ ... })` (D-07). */
+	readonly options?: object
+	/** Its application value's options, `softDeletePlugin({ ... })` (D-24). */
+	readonly appOptions?: object
+	/** The plugins it needs, by their types (D-16). */
+	readonly requires?: PluginTypes
+	/** The plugins it uses when installed (D-16). */
+	readonly optional?: PluginTypes
+	/** What it offers other plugins (D-16). */
+	readonly api?: object
+	/** The fields it adds to the models that use it (D-07, D-15, D-89). */
+	readonly addedFields?: { readonly [field: string]: FieldShape }
+	/** Its commands (D-15). */
+	readonly commands?: object
+	/** Its key of the model's `.with` (D-42); `false` turns it off (D-107). */
+	readonly with?: object | false
+	/** Its key of a field's `.with`, read with `this['value']` (D-12). */
+	readonly fieldWith?: object
+	/** Its key of a function's `.with`; `false` stops exposing it (D-27). */
+	readonly functionWith?: object | false
+	/** Only a query may list it in its `use` (D-154). */
+	readonly queryOnly?: true
+}
+
+/** A plugin's types for one model's fields. */
+export type ForModel<T, F> = T & { readonly fields: F }
+/** What a plugin's own code sees of a model: the fields it adds. Other
+ * fields are the model's, unknown to the plugin (D-57). */
+type Own<T> = T extends { readonly addedFields: infer A }
+	? A
+	: // oxlint-disable-next-line typescript/no-generated-empty-object-type -- no fields, not any value
+		Record<never, never>
+type EntryOptions<T> = T extends { readonly options: infer O extends object }
+	? O
+	: { readonly [option: string]: never }
+type AppOptions<T> = T extends { readonly appOptions: infer O } ? O : never
+type Requires<T> = T extends { readonly requires: infer R extends PluginTypes }
+	? R['name']
+	: never
+type Optional<T> = T extends { readonly optional: infer R extends PluginTypes }
+	? R['name']
+	: never
+type ApiOf<X> = X extends { readonly api: infer A } ? A : undefined
+type Apis<T> = (T extends { readonly requires: infer R extends PluginTypes }
+	? { readonly [X in R as X['name']]: ApiOf<X> }
+	: unknown) &
+	(T extends { readonly optional: infer R extends PluginTypes }
+		? { readonly [X in R as X['name']]: ApiOf<X> | undefined }
+		: unknown)
+
+type Args = { readonly [key: string]: unknown }
+/** A model's queries as a transport calls them, with its client's arguments. */
+export interface ModelQueries {
+	findUnique(args: Args, options: QueryOptions): Promise<Row | null>
+	findMany(args: Args, options: QueryOptions): Promise<readonly Row[]>
+	count(args: Args, options: QueryOptions): Promise<number>
+	create(args: Args, options: QueryOptions): Promise<Row>
+	update(args: Args, options: QueryOptions): Promise<Row>
+	delete(args: Args, options: QueryOptions): Promise<Row>
+}
+
+/** A model as transports and tools read it (D-16, D-107). */
+export interface ExposedModel<W = unknown> {
+	/** As the adapter receives it (D-73). */
+	readonly schema: SchemaModel
+	/** The model's `description` and its fields' (D-150). */
+	readonly description: string | undefined
+	readonly descriptions: { readonly [field: string]: string }
+	/** Each field whose values are a `defineEnum` (D-150). */
+	readonly enums: { readonly [field: string]: Enum }
+	/** `id`, unique fields and unique indexes (D-52). */
+	readonly uniques: readonly (readonly string[])[]
+	/** Each field with a read rule, `private` when only Master reads it (D-44). */
+	readonly readRules: { readonly [field: string]: 'private' | 'rule' }
+	/** The fields `create` needs: neither optional nor with a default (D-53). */
+	readonly required: readonly string[]
+	/** Each `json` field's `validate`, when it is a Standard Schema (D-125). */
+	readonly validators: { readonly [field: string]: StandardSchema }
+	/** Each plugin field type's field, which a client reads as `toJSON` gives (D-122). */
+	readonly fieldTypes: {
+		readonly [field: string]: {
+			readonly plugin: string
+			/** The field type's own options the field took (D-152). */
+			readonly options: { readonly [key: string]: unknown }
+			readonly toJSON: (value: unknown) => unknown
+			/** What `toJSON` gives, if the field type says (D-152). */
+			readonly shape: StandardSchema | undefined
+		}
+	}
+	/** Its virtual fields, in their order (D-151). */
+	readonly virtuals: readonly ExposedVirtual[]
+	/** The plugin's key of the model's `.with`, if it was given. */
+	readonly with: W | undefined
+	/** Whether the model's `use` lists the plugin's entry. */
+	readonly used: boolean
+	readonly queries: ModelQueries
+	/** `upsert`, which also says whether it created the row (D-142). */
+	readonly upsert: (
+		args: Args,
+		options: QueryOptions,
+	) => Promise<{ readonly row: Row; readonly created: boolean }>
+	/** The `defineModel` value, which a plugin's function may return (D-113). */
+	readonly model: ModelShape
+}
+
+/** A virtual field as transports read it (D-151). */
+export interface ExposedVirtual {
+	readonly name: string
+	readonly description: string | undefined
+	/** A Standard Schema of an object: the field's arguments. */
+	readonly input: StandardSchema | undefined
+	readonly output: ExposedOutput
+	/** In the row without `select`: a value without input. */
+	readonly default: boolean
+}
+
+/** How an output holds a model or a type (D-109). */
+export type OutputForm = 'one' | 'nullable' | 'list'
+
+/** A function's or a type's output, as transports read it (D-109). */
+export type ExposedOutput =
+	| { readonly kind: 'schema'; readonly schema: StandardSchema }
+	| { readonly kind: 'model'; readonly name: string; readonly form: OutputForm }
+	| {
+			readonly kind: 'type'
+			readonly type: ExposedType
+			readonly form: OutputForm
+	  }
+
+/** A `defineType`, its fields in their order (D-109). */
+export interface ExposedType {
+	readonly name: string
+	readonly description: string | undefined
+	readonly fields: ReadonlyMap<string, ExposedOutput>
+}
+
+/** A function as transports read it (D-109). */
+export interface ExposedFunction<W = unknown> {
+	readonly name: string
+	readonly description: string | undefined
+	/** The plugin that gives it, `undefined` for the application's (D-113). */
+	readonly plugin: string | undefined
+	/** A query, which a transport may serve over GET; a mutation otherwise. */
+	readonly query: boolean
+	/** Whether the function's `use` lists the plugin (D-154). */
+	readonly used: boolean
+	readonly input: StandardSchema | undefined
+	/** `undefined` when it returns nothing. */
+	readonly output: ExposedOutput | undefined
+	/** The plugin's key of the function's `.with`, if it was given. */
+	readonly with: W | undefined
+	/** Checks access, validates the input, then runs it for `client` (D-75, D-113). */
+	run(input: unknown, options: QueryOptions, client?: Client): Promise<unknown>
+}
+
+type WithOf<T> = T extends { readonly with: infer W } ? W : never
+type FunctionWithOf<T> = T extends { readonly functionWith: infer W }
+	? W
+	: never
+
+/** What the plugin's start and api receive: its application options. */
+export interface PluginContext<T> {
+	readonly options: [AppOptions<T>] extends [never]
+		? { readonly [option: string]: never }
+		: AppOptions<T>
+	readonly plugins: Apis<T>
+	readonly logger: Logger
+	/** Who sends a request: what a transport runs it as (D-106). */
+	readonly identify: Identify
+	/**
+	 * The caller being built stops holding at `at`, as a session that
+	 * expires: a live read builds it again then (D-154). Outside a caller's
+	 * construction, it does nothing.
+	 */
+	readonly expires: (at: Date) => void
+	/** The application's models, in their order (D-107). */
+	readonly models: readonly ExposedModel<WithOf<T>>[]
+	/** The application's functions, in their order (D-109). */
+	readonly functions: readonly ExposedFunction<FunctionWithOf<T>>[]
+}
+
+/** A plugin's entry in a model's `use`, named after the plugin. */
+export interface ModelUse<P extends string, T> {
+	readonly plugin: P
+	readonly [pluginTypes]: T
+}
+
+/** A plugin's value in the application's `plugins`. */
+export interface PluginValue<P extends string, R extends string = never> {
+	readonly name: P
+	readonly requires?: readonly R[]
+}
+
+type HookFacts<F, K extends keyof ModelHooks<F>> = Parameters<
+	NonNullable<ModelHooks<F>[K]>
+>[0]
+/**
+ * The hooks a plugin runs on every model that uses it (D-15). `command` names
+ * the plugin's command the operation was called through, on that model only
+ * (D-71).
+ */
+export type PluginHooks<F, O, A, C> = {
+	readonly [K in keyof ModelHooks<unknown>]?: (
+		facts: HookFacts<F, K> &
+			PluginModel<F, O, A> & { readonly command: C | undefined },
+	) => ReturnType<NonNullable<ModelHooks<F>[K]>>
+}
+/** `redirect` replaces an operation with another (D-15). */
+export type PluginRedirects<F, O, A> = {
+	readonly delete?: (
+		facts: {
+			readonly caller: Caller
+			readonly where: UniqueWhere<F>
+		} & PluginModel<F, O, A>,
+	) => Promise<unknown>
+}
+
+/** What a model gives a plugin's code. */
+export interface PluginModel<F, O, A> {
+	/** The model's name (D-152). */
+	readonly name: string
+	readonly queries: Queries<F>
+	readonly options: O
+	readonly plugins: A
+}
+
+type CodePart<T, K extends 'commands' | 'addedFields', Out> = T extends {
+	readonly [P in K]: object
+}
+	? { readonly [P in K]: Out }
+	: { readonly [P in K]?: never }
+
+// A plugin without an API may still use the step that builds them, before
+// any start, to call another plugin's API (D-107).
+type ApiPart<T> = T extends { readonly api: object }
+	? { readonly api: (context: PluginContext<T>) => T['api'] }
+	: { readonly api?: (context: PluginContext<T>) => void }
+
+/** A plugin's package, usually its imported `package.json` (D-57). */
+export interface Manifest {
+	readonly name: string
+	readonly version: string
+	/** The ranges of `ultimabase` and of the plugins it needs. */
+	readonly peerDependencies?: { readonly [name: string]: string }
+}
+
+type PluginFn<N extends string> = (...args: never[]) => PluginValue<N, string>
+// Each needed plugin's application value under its name (D-16): a missing,
+// an extra or a swapped one is refused.
+type Needs<K extends 'requires' | 'optional', N extends string> = [N] extends [
+	never,
+]
+	? { readonly [P in K]?: never }
+	: { readonly [P in K]: { readonly [X in N]: PluginFn<X> } }
+
+/** What a plugin's author writes (D-57). */
+export type PluginDefinition<T extends PluginTypes> = {
+	readonly name: T['name']
+	readonly manifest: Manifest
+	/** The hooks it runs on each model that uses it. */
+	readonly hooks?: PluginHooks<
+		Own<T>,
+		EntryOptions<T>,
+		Apis<T>,
+		keyof ForModel<T, Own<T>>['commands'] & string
+	>
+	readonly redirect?: PluginRedirects<Own<T>, EntryOptions<T>, Apis<T>>
+	/** Runs once when the application starts (D-15). */
+	readonly start?: (context: PluginContext<T>) => void | Promise<void>
+	/** Runs once when the application stops: close, flush (D-15). */
+	readonly stop?: (context: PluginContext<T>) => void | Promise<void>
+	/**
+	 * Who sends a request, or `undefined` when it is not the plugin's; the
+	 * first plugin to know it wins, after the master key (D-112).
+	 */
+	readonly identify?: (
+		request: Request,
+		context: PluginContext<T>,
+	) => Promise<Identity | undefined>
+	/**
+	 * The plugin's keys of a user caller, given once per caller the kernel
+	 * receives, each plugin's in the order of `plugins` (D-121).
+	 */
+	readonly caller?: (
+		identity: { readonly kind: 'user'; readonly user: UserOf<Register> },
+		context: PluginContext<T>,
+	) => CallerKeys | Promise<CallerKeys>
+	/**
+	 * What each commit changed, on any server: the adapter sends it only when
+	 * a plugin takes it (D-154).
+	 */
+	readonly changed?: (
+		changes: readonly Changed[],
+		context: PluginContext<T>,
+	) => void
+	/** Changes may have been lost: what `changed` follows is unknown. */
+	readonly missed?: (context: PluginContext<T>) => void
+	/** Its own models, which no plugin is given (D-110). */
+	readonly models?: readonly ModelShape[]
+	/** The indexes it adds to each model that uses it (D-52, D-122). */
+	readonly addedIndexes?: readonly {
+		readonly fields: readonly (keyof Own<T> & string)[]
+		readonly unique?: boolean
+		/** A trigram index, for `contains` and `mode: 'insensitive'` (D-141). */
+		readonly contains?: true
+	}[]
+	/**
+	 * Its `defineFunction` values, built once when the application starts and
+	 * exposed as the application's are (D-113).
+	 */
+	readonly functions?: (
+		context: Omit<PluginContext<T>, 'functions'>,
+	) => readonly FunctionShape[]
+} & CodePart<
+	T,
+	'commands',
+	(
+		model: PluginModel<Own<T>, EntryOptions<T>, Apis<T>>,
+	) => ForModel<T, Own<T>>['commands']
+> &
+	ApiPart<T> &
+	CodePart<
+		T,
+		'addedFields',
+		(fields: FieldBuilders<never>, options: EntryOptions<T>) => Own<T>
+	> &
+	Needs<'requires', Requires<T>> &
+	Needs<'optional', Optional<T>>
+
+/** A plugin's two values (D-24). */
+export interface Plugin<T extends PluginTypes> {
+	readonly plugin: (
+		options?: AppOptions<T>,
+	) => PluginValue<T['name'], Requires<T>>
+	readonly use: PluginEntry<T>
+}
+/** Without options, the entry is the plugin's own types; with them, its
+ * types read the options' literal values. */
+export interface PluginEntry<T extends PluginTypes> {
+	(): ModelUse<T['name'], T>
+	<const O extends EntryOptions<T>>(
+		options: O,
+	): ModelUse<T['name'], T & { readonly options: O }>
+}
+/** The type of a plugin's entry function, for its export. */
+export type UseOf<T extends PluginTypes> = Plugin<T>['use']
+/** The type of a plugin's application value function, for its export. */
+export type PluginOf<T extends PluginTypes> = Plugin<T>['plugin']
+
+export function definePlugin<T extends PluginTypes>(
+	definition: PluginDefinition<T>,
+): Plugin<T> {
+	const code = pluginCode(definition)
+	const plugin = (options?: object): PluginValue<string, string> => {
+		const value = Object.freeze({ name: code.name, requires: code.requires })
+		pluginValues.set(value, { code, options: options ?? {} })
+		return value
+	}
+	const use = (options?: object): object => {
+		const entry = Object.freeze({ plugin: code.name, options })
+		pluginEntries.set(entry, { code, options: options ?? {} })
+		return entry
+	}
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the two functions are Plugin<T>'s; their types follow T.
+	return { plugin, use } as unknown as Plugin<T>
+}

package/src/query-aggregate.ts

@@ -0,0 +1,96 @@
+// `aggregate`'s arguments and result (D-143): the result has the keys the
+// arguments ask for, each field typed.
+import type { SortedKeys, Where } from './query.ts'
+import type { StoredValue, SystemFields } from './record.ts'
+import type { calendarDay, fieldType } from './symbols.ts'
+
+/** A model's scalars that an aggregate takes: no list, json or plugin field. */
+export type Aggregated<F> = SortedKeys<F> | keyof SystemFields
+export type ValueOf<F, K> = K extends keyof SystemFields
+	? SystemFields[K]
+	: K extends keyof F
+		? NonNullable<StoredValue<F[K]>>
+		: never
+/** The fields whose values are `V`. */
+export type KeysWith<F, V> = {
+	[K in Aggregated<F>]: ValueOf<F, K> extends V ? K : never
+}[Aggregated<F>]
+/** Whether `X` is a decimal field (D-145), filtered and summed as a string. */
+export type IsDecimal<X> = X extends {
+	readonly [fieldType]: { readonly options: { readonly precision: number } }
+}
+	? true
+	: false
+/** Whether `X` is a string compared in order: a decimal or a day (D-150). */
+export type IsOrdered<X> =
+	IsDecimal<X> extends true
+		? true
+		: X extends {
+					readonly [fieldType]: {
+						readonly options: { readonly [calendarDay]: true }
+					}
+			  }
+			? true
+			: false
+export type DecimalKeys<F> = {
+	[K in Aggregated<F>]: K extends keyof F
+		? IsDecimal<F[K]> extends true
+			? K
+			: never
+		: never
+}[Aggregated<F>]
+export type Summed<F> = KeysWith<F, number> | DecimalKeys<F>
+type Fields<K extends PropertyKey> = { readonly [P in K]?: true | undefined }
+
+export type AggregateArgs<F> = {
+	readonly where?: Where<F> | undefined
+	readonly _count?:
+		| true
+		| ({ readonly _all?: true | undefined } & Fields<Aggregated<F>>)
+		| undefined
+	readonly _sum?: Fields<Summed<F>> | undefined
+	readonly _avg?: Fields<Summed<F>> | undefined
+	readonly _min?: Fields<KeysWith<F, number | string | Date>> | undefined
+	readonly _max?: Fields<KeysWith<F, number | string | Date>> | undefined
+}
+
+type Asked<S> = {
+	[K in keyof S]: S[K] extends true ? K : never
+}[keyof S]
+/**
+ * One value per field `S` names: `null` when no row has one. An average is
+ * a number, a sum a number or a decimal's string, a minimum or a maximum
+ * the field's value.
+ */
+type Values<F, S, As extends 'sum' | 'avg' | 'value'> = {
+	readonly [K in Asked<S>]:
+		| (As extends 'avg'
+				? number
+				: As extends 'sum'
+					? K extends DecimalKeys<F>
+						? string
+						: number
+					: ValueOf<F, K>)
+		| null
+}
+
+/** What `aggregate` returns for the arguments `A`. */
+export type Aggregates<F, A> = (A extends { readonly _count: infer C }
+	? C extends true
+		? { readonly _count: number }
+		: C extends object
+			? { readonly _count: { readonly [K in Asked<C>]: number } }
+			: unknown
+	: unknown) &
+	(A extends { readonly _sum: infer S extends object }
+		? { readonly _sum: Values<F, S, 'sum'> }
+		: unknown) &
+	(A extends { readonly _avg: infer S extends object }
+		? { readonly _avg: Values<F, S, 'avg'> }
+		: unknown) &
+	(A extends { readonly _min: infer S extends object }
+		? { readonly _min: Values<F, S, 'value'> }
+		: unknown) &
+	(A extends { readonly _max: infer S extends object }
+		? { readonly _max: Values<F, S, 'value'> }
+		: unknown)