ultimabase 0.0.0-stage → 0.1.0

package/src/query.ts

@@ -0,0 +1,400 @@
+// Query arguments and results, in Prisma Client's form (D-20).
+import type {
+	CreateData,
+	RecordOf,
+	RelationKeys,
+	ScalarKeys,
+	StoredValue,
+	SystemFields,
+	TargetFields,
+	UniqueKeys,
+	UpdateData,
+} from './record.ts'
+import type { Exact } from './exact.ts'
+import type { JsonValue } from './fields.ts'
+import type { AggregateArgs, Aggregates, IsOrdered } from './query-aggregate.ts'
+import type { BulkQueries } from './query-bulk.ts'
+import type {
+	JsonPathFilter,
+	ListFilter,
+	ScalarFilter,
+} from './query-filter.ts'
+import type { Relevance, SearchWhere } from './query-search.ts'
+import type {
+	GroupByArgs,
+	GroupChecked,
+	GroupField,
+	Groups,
+	SortOrder,
+} from './query-group.ts'
+import type { Identity } from './rules.ts'
+import type { fieldType } from './symbols.ts'
+import type {
+	DefaultRow,
+	DefaultVirtualKeys,
+	VirtualArgs,
+	VirtualIncludes,
+	VirtualKeys,
+	VirtualOutput,
+} from './virtual.ts'
+
+type KindOf<X> = X extends { readonly [fieldType]: { readonly kind: infer K } }
+	? K
+	: never
+type TargetOf<X> = X extends {
+	readonly [fieldType]: { readonly target: infer T }
+}
+	? T
+	: never
+type OptionalOne<X> = X extends {
+	readonly [fieldType]: { readonly options: { readonly optional: true } }
+}
+	? null
+	: never
+
+type IsList<X> = X extends {
+	readonly [fieldType]: { readonly options: { readonly list: true } }
+}
+	? true
+	: false
+
+/** A json field's value, any JSON without a schema, or a path filter (D-149). */
+type JsonFilter<V> = V | ScalarFilter<NonNullable<V>> | JsonPathFilter
+
+type FilterOf<X> =
+	IsList<X> extends true
+		? StoredValue<X> extends readonly (infer E)[]
+			? ListFilter<E>
+			: never
+		: KindOf<X> extends 'scalar'
+			? X extends { readonly [fieldType]: { readonly json: true } }
+				? JsonFilter<
+						unknown extends StoredValue<X> ? JsonValue : StoredValue<X>
+					>
+				: | StoredValue<X>
+					| ScalarFilter<NonNullable<StoredValue<X>>, IsOrdered<X>>
+			: KindOf<X> extends 'one'
+				? {
+						readonly is?: Where<TargetFields<TargetOf<X>>> | null | undefined
+						readonly isNot?: Where<TargetFields<TargetOf<X>>> | null | undefined
+					}
+				: {
+						readonly some?: Where<TargetFields<TargetOf<X>>> | undefined
+						readonly every?: Where<TargetFields<TargetOf<X>>> | undefined
+						readonly none?: Where<TargetFields<TargetOf<X>>> | undefined
+					}
+
+/** A plugin field type's stored field (D-122), `never` for a kernel one. */
+type StoredOf<X> = X extends {
+	readonly [fieldType]: { readonly stored: infer S }
+}
+	? S
+	: never
+/** The fields of a plugin field type, which only a `beforeFind` filters. */
+type PluginKeys<F> = {
+	[K in keyof F]: [StoredOf<F[K]>] extends [never] ? never : K
+}[keyof F]
+
+/** The system fields' filters and the combinators of a `where` `W`. */
+interface Filters<W> {
+	readonly id?: string | Omit<ScalarFilter<string>, 'mode'> | undefined
+	readonly createdAt?: Date | ScalarFilter<Date> | undefined
+	readonly updatedAt?: Date | ScalarFilter<Date> | undefined
+	readonly AND?: W | readonly W[] | undefined
+	readonly OR?: readonly W[] | undefined
+	readonly NOT?: W | readonly W[] | undefined
+}
+
+/** No `where` filters a virtual (D-151). */
+export type Where<F> = {
+	readonly [K in Exclude<keyof F, PluginKeys<F> | VirtualKeys<F>>]?:
+		FilterOf<F[K]> | undefined
+} & Filters<Where<F>> &
+	SearchWhere<F>
+
+/** A `beforeFind`'s filter: a plugin field's in its stored form (D-122). */
+export type FindWhere<F> = {
+	readonly [K in Exclude<keyof F, VirtualKeys<F>>]?:
+		| (K extends PluginKeys<F> ? FilterOf<StoredOf<F[K]>> : FilterOf<F[K]>)
+		| undefined
+} & Filters<FindWhere<F>> &
+	SearchWhere<F>
+
+/** A unique index's value: a scalar's, or a `one` relation's target id. */
+type IndexValue<X> =
+	KindOf<X> extends 'one' ? string : NonNullable<StoredValue<X>>
+/** A unique index, targeted flat with exactly its fields (D-52). */
+type IndexTarget<F, X> = X extends readonly (infer K extends keyof F)[]
+	? { readonly [P in K]: IndexValue<F[P]> }
+	: never
+
+/**
+ * `findUnique` and single-row writes target `id`, a unique field or a unique
+ * index, whose fields `X` lists (D-52).
+ */
+export type UniqueWhere<F, X = never> =
+	| { readonly id: string }
+	| {
+			[K in UniqueKeys<F>]: { readonly [P in K]: StoredValue<F[K]> }
+	  }[UniqueKeys<F>]
+	| IndexTarget<F, X>
+
+type Direction = 'asc' | 'desc'
+/**
+ * A json field is not sorted: each database orders json its own way (D-94);
+ * nor is a list (D-120), nor a plugin field (D-122).
+ */
+export type SortedKeys<F> = {
+	[K in Exclude<ScalarKeys<F>, PluginKeys<F>>]: F[K] extends {
+		readonly [fieldType]: { readonly json: true }
+	}
+		? never
+		: IsList<F[K]> extends true
+			? never
+			: K
+}[Exclude<ScalarKeys<F>, PluginKeys<F>>]
+type KeysOf<F, Kind> = {
+	[K in keyof F]: KindOf<F[K]> extends Kind ? K : never
+}[keyof F]
+
+/**
+ * An optional field sorts with its `null`s first or last (D-149), a `one`
+ * relation by its target's fields, a `many` by its count (D-134).
+ */
+type Sorts<F> = {
+	readonly [K in SortedKeys<F> | keyof SystemFields]?:
+		SortOrder<K extends keyof RecordOf<F> ? RecordOf<F>[K] : never> | undefined
+} & {
+	readonly [K in KeysOf<F, 'one'>]?:
+		Sorts<TargetFields<TargetOf<F[K]>>> | undefined
+} & {
+	readonly [K in KeysOf<F, 'many'>]?: { readonly _count: Direction } | undefined
+}
+/** A read's sort, by its `_search`'s relevance too (D-148). */
+export type OrderBy<F> = Sorts<F> & Relevance<F>
+
+/** `_count`: every `many` relation, or the ones `select` names (D-134). */
+type Count<F> =
+	| true
+	| {
+			readonly select: {
+				readonly [K in KeysOf<F, 'many'>]?:
+					| boolean
+					| { readonly where?: Where<TargetFields<TargetOf<F[K]>>> | undefined }
+			}
+	  }
+
+/** A model with a `many` relation takes `_count`. */
+type Counts<F> = [KeysOf<F, 'many'>] extends [never]
+	? unknown
+	: { readonly _count?: Count<F> | false }
+
+type Counted<F, C> = C extends { readonly select: infer S }
+	? {
+			readonly [
+				K in keyof S as S[K] extends false | undefined ? never : K
+			]: number
+		}
+	: C extends true
+		? { readonly [K in KeysOf<F, 'many'>]: number }
+		: unknown
+
+/** The `_count` of a `select` or an `include` `A`. */
+type CountOf<F, A> = A extends { readonly _count: infer C }
+	? C extends false | undefined
+		? unknown
+		: { readonly _count: Counted<F, C> }
+	: unknown
+
+type RelationArgs<X> = Shaping<TargetFields<TargetOf<X>>> &
+	(KindOf<X> extends 'many'
+		? {
+				readonly where?: Where<TargetFields<TargetOf<X>>> | undefined
+				readonly orderBy?: OrderBy<TargetFields<TargetOf<X>>> | undefined
+				readonly take?: number | undefined
+				readonly skip?: number | undefined
+				readonly cursor?: UniqueWhere<TargetFields<TargetOf<X>>> | undefined
+			}
+		: unknown)
+
+export type Select<F> = {
+	readonly [K in keyof SystemFields]?: boolean
+} & {
+	readonly [K in keyof F]?: KindOf<F[K]> extends 'scalar'
+		? boolean
+		: KindOf<F[K]> extends 'virtual'
+			? VirtualArgs<F[K]>
+			: boolean | RelationArgs<F[K]>
+} & Counts<F>
+
+/** A model without relations or virtuals takes no `include`. */
+export type Include<F> = [RelationKeys<F> | VirtualKeys<F>] extends [never]
+	? never
+	: {
+			readonly [K in RelationKeys<F>]?: boolean | RelationArgs<F[K]>
+		} & VirtualIncludes<F> &
+			Counts<F>
+
+type Output<X, A> =
+	KindOf<X> extends 'scalar'
+		? StoredValue<X>
+		: KindOf<X> extends 'virtual'
+			? VirtualOutput<X, A>
+			: KindOf<X> extends 'one'
+				? Payload<TargetFields<TargetOf<X>>, A> | OptionalOne<X>
+				: Payload<TargetFields<TargetOf<X>>, A>[]
+
+type Selected<F, S> = {
+	readonly [
+		K in Exclude<keyof S, '_count'> as S[K] extends false | undefined
+			? never
+			: K
+	]: K extends keyof F
+		? Output<F[K], S[K]>
+		: K extends keyof SystemFields
+			? SystemFields[K]
+			: never
+}
+
+type Included<F, I> = {
+	readonly [
+		K in Exclude<keyof I, '_count'> as I[K] extends false | undefined
+			? never
+			: K
+	]: K extends keyof F ? Output<F[K], I[K]> : never
+}
+
+/** `omit`: scalars, system fields, default virtuals left out (D-135). */
+export type OmitArgs<F> = {
+	readonly [K in keyof RecordOf<F> | DefaultVirtualKeys<F>]?: boolean
+}
+
+/** `select` and `omit` exclude each other (D-135). */
+export type Shaping<F> = { readonly include?: Include<F> } & (
+	| { readonly select?: Select<F>; readonly omit?: undefined }
+	| { readonly select?: undefined; readonly omit?: OmitArgs<F> }
+)
+
+/** The scalar and system fields, less those `omit` sets to `true`. */
+type Kept<F, A> = A extends { readonly omit: infer O }
+	? Omit<
+			DefaultRow<F>,
+			{ [K in keyof O]: O[K] extends true ? K : never }[keyof O]
+		>
+	: DefaultRow<F>
+
+/** Without `select`, scalar fields return and relations do not (D-20). */
+export type Payload<F, A> = A extends { readonly select: infer S }
+	? Selected<F, S> & CountOf<F, S>
+	: A extends { readonly include: infer I }
+		? Kept<F, A> & Included<F, I> & CountOf<F, I>
+		: Kept<F, A>
+
+export type QueryOptions = { readonly as?: Identity }
+
+/** `findFirst`; `cursor` starts at a unique target. */
+export type FindFirstArgs<F, X = never> = Shaping<F> & {
+	readonly where?: Where<F> | undefined
+	readonly orderBy?: OrderBy<F> | readonly OrderBy<F>[] | undefined
+	readonly take?: number | undefined
+	readonly skip?: number | undefined
+	readonly cursor?: UniqueWhere<F, X> | undefined
+}
+
+/** `findMany`: `distinct` keeps one row per key, without `cursor` (D-147). */
+export type FindManyArgs<F, X = never, N = never> = FindFirstArgs<F, X> & {
+	readonly distinct?:
+		readonly [GroupField<F, N>, ...GroupField<F, N>[]] | undefined
+}
+
+export type FindUniqueArgs<F, X = never> = Shaping<F> & {
+	readonly where: UniqueWhere<F, X>
+}
+
+export type CreateArgs<F, N = never> = Shaping<F> & {
+	readonly data: CreateData<F, N>
+}
+
+export type UpdateArgs<F, X = never, N = never> = Shaping<F> & {
+	readonly where: UniqueWhere<F, X>
+	readonly data: UpdateData<F, N>
+}
+
+/** `update` the row `where` targets, or `create` it when absent (D-142). */
+export type UpsertArgs<F, X = never, N = never> = Shaping<F> & {
+	readonly where: UniqueWhere<F, X>
+	readonly create: CreateData<F, N>
+	readonly update: UpdateData<F, N>
+}
+
+/** Model methods (D-18), the subset the prototype measures. */
+// Each query is a closure on its model: it can be passed around unbound.
+/** `N` is the model's name, which nested creation needs (D-128). */
+export interface Queries<F, X = never, N = never> extends BulkQueries<F> {
+	findMany<const A extends FindManyArgs<F, X, N>>(
+		this: void,
+		args?: A & NoInfer<Exact<A, FindManyArgs<F, X, N>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A>[]>
+	findFirst<const A extends FindFirstArgs<F, X>>(
+		this: void,
+		args?: A & NoInfer<Exact<A, FindFirstArgs<F, X>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A> | null>
+	findUnique<const A extends FindUniqueArgs<F, X>>(
+		this: void,
+		args: A & NoInfer<Exact<A, FindUniqueArgs<F, X>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A> | null>
+	/** `findFirst`, which fails with `NOT_FOUND` rather than `null` (D-135). */
+	findFirstOrThrow<const A extends FindFirstArgs<F, X>>(
+		this: void,
+		args?: A & NoInfer<Exact<A, FindFirstArgs<F, X>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A>>
+	/** `findUnique`, which fails with `NOT_FOUND` rather than `null` (D-135). */
+	findUniqueOrThrow<const A extends FindUniqueArgs<F, X>>(
+		this: void,
+		args: A & NoInfer<Exact<A, FindUniqueArgs<F, X>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A>>
+	count(
+		this: void,
+		args?: { readonly where?: Where<F> },
+		options?: QueryOptions,
+	): Promise<number>
+	/** Of the rows the caller reads; server code only (D-143). */
+	aggregate<const A extends AggregateArgs<F>>(
+		this: void,
+		args: A & NoInfer<Exact<A, AggregateArgs<F>>>,
+		options?: QueryOptions,
+	): Promise<Aggregates<F, A>>
+	/** Of the rows the caller reads, by `by`; server code only (D-146). */
+	groupBy<const A extends GroupByArgs<F, N>>(
+		this: void,
+		args: A & NoInfer<GroupChecked<F, N, A>>,
+		options?: QueryOptions,
+	): Promise<Groups<F, N, A>>
+	create<const A extends CreateArgs<F, N>>(
+		this: void,
+		args: A & NoInfer<Exact<A, CreateArgs<F, N>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A>>
+	update<const A extends UpdateArgs<F, X, N>>(
+		this: void,
+		args: A & NoInfer<Exact<A, UpdateArgs<F, X, N>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A>>
+	/** The branch that runs applies its own rules and hooks (D-142). */
+	upsert<const A extends UpsertArgs<F, X, N>>(
+		this: void,
+		args: A & NoInfer<Exact<A, UpsertArgs<F, X, N>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A>>
+	/** Its relations and counts are read as they were before it (D-135). */
+	delete<const A extends FindUniqueArgs<F, X>>(
+		this: void,
+		args: A & NoInfer<Exact<A, FindUniqueArgs<F, X>>>,
+		options?: QueryOptions,
+	): Promise<Payload<F, A>>
+}