@ultimabase/graphql 0.0.0-stage → 0.1.0

package/src/pages.ts

@@ -0,0 +1,39 @@
+// A list's kernel read (D-55, D-107): its `where`, its order and its page,
+// read with the arguments REST reads (D-139).
+import type { Page } from '@ultimabase/http/internal'
+import { pageOf } from '@ultimabase/http/internal'
+import { plainWhere } from './json-fields.ts'
+import type { Args, Registry } from './registry.ts'
+import type { Entry } from './registry.ts'
+
+/** The kernel's `where` of a list or count's arguments. */
+export function whereOf(registry: Registry, model: string, args: Args): Args {
+	const { where } = args
+	return typeof where === 'object' && where !== null
+		? { where: plainWhere(registry, model, { ...where }) }
+		: {}
+}
+
+/** A list's kernel read, and its Relay page unless `pagination: 'list'`. */
+export function listRead(
+	registry: Registry,
+	entry: Entry,
+	args: Args,
+	master: boolean,
+): { readonly read: Args; readonly page: Page['relay'] } {
+	const { orderBy } = args
+	const { read, relay } = pageOf(
+		registry.settings.pagination,
+		entry,
+		args,
+		master,
+	)
+	return {
+		read: {
+			...whereOf(registry, entry.model.name, args),
+			...(orderBy === undefined || orderBy === null ? {} : { orderBy }),
+			...read,
+		},
+		page: relay,
+	}
+}

package/src/registry.ts

@@ -0,0 +1,189 @@
+// What the schema is built from (D-107): each model with its names and
+// limits, the plugin's settings, and each type built once, when first used.
+import type {
+	GraphQLFieldConfigMap,
+	GraphQLInputObjectType,
+	GraphQLObjectType,
+	GraphQLResolveInfo,
+	GraphQLScalarType,
+} from 'graphql'
+import {
+	GraphQLBoolean,
+	GraphQLEnumType,
+	GraphQLFloat,
+	GraphQLInt,
+	GraphQLList,
+	GraphQLNonNull,
+	GraphQLString,
+} from 'graphql'
+import type {
+	Caller,
+	Client,
+	ExposedModel,
+	SchemaField,
+	SchemaModel,
+} from 'ultimabase'
+import { DataTypes } from './data-types.ts'
+import { upper } from './names.ts'
+import { DateScalar, DateTime, DecimalScalar, JSONScalar } from './scalars.ts'
+
+/** A model's key of `.with` (D-107). */
+export type GraphqlWith =
+	{ readonly plural?: string; readonly maxTake?: number } | false
+
+/** What every resolver receives, the generated ones and those `extend` adds. */
+export type Context = {
+	readonly caller: Caller
+	/** The request's client, which a function's `run` receives (D-113). */
+	readonly client: Client
+	/**
+	 * The kernel's `select` for what the client asks of the rows a field
+	 * returns, relations and their pages included; spread it to add a field.
+	 * Its type names `id` only: the rest depends on the document.
+	 */
+	readonly select: (info: GraphQLResolveInfo) => { readonly id: true }
+}
+/** A kernel query's options: run as the request's caller (D-106). */
+export const as = (context: Context): { readonly as: Caller } => ({
+	as: context.caller,
+})
+export type Args = { readonly [arg: string]: unknown }
+export type Scalar = Extract<SchemaField, { readonly kind: 'scalar' }>
+
+export type Entry = {
+	readonly exposed: ExposedModel<GraphqlWith>
+	readonly model: SchemaModel
+	/** In the root fields; a hidden model is reached by relations only. */
+	readonly visible: boolean
+	readonly single: string
+	readonly list: string
+	/** The rows a list returns without `first`, `last` or `take`. */
+	readonly take: number
+	readonly maxTake: number
+}
+
+export type Settings = {
+	readonly pagination: 'connection' | 'list'
+}
+
+function memo<T>(cache: Map<string, T>, name: string, build: () => T): T {
+	const found = cache.get(name)
+	if (found !== undefined) return found
+	const built = build()
+	cache.set(name, built)
+	return built
+}
+
+export class Registry {
+	readonly #objects = new Map<string, GraphQLObjectType>()
+	readonly #inputs = new Map<string, GraphQLInputObjectType>()
+	readonly #enums = new Map<string, GraphQLEnumType>()
+	readonly entries: ReadonlyMap<string, Entry>
+	readonly settings: Settings
+	/** The types functions and json fields give, shared by both (D-125). */
+	readonly data: DataTypes
+	/** A model's virtual fields, which the functions' outputs build (D-151). */
+	virtualFields: (model: string) => GraphQLFieldConfigMap<unknown, Context> =
+		() => ({})
+
+	constructor(entries: ReadonlyMap<string, Entry>, settings: Settings) {
+		this.entries = entries
+		this.settings = settings
+		this.data = new DataTypes(entries.keys())
+		// Before any function's: a `defineEnum` keeps its own description.
+		for (const [model, { exposed }] of entries) {
+			for (const [field, shared] of Object.entries(exposed.enums)) {
+				const { name, values, description } = shared
+				this.data.enum(name, values, `${model}.${field}`, description)
+			}
+		}
+	}
+
+	entry(model: string): Entry {
+		const entry = this.entries.get(model)
+		if (entry === undefined) throw new Error(`Unknown model ${model}.`)
+		return entry
+	}
+
+	object(name: string, build: () => GraphQLObjectType): GraphQLObjectType {
+		return memo(this.#objects, name, build)
+	}
+
+	input(
+		name: string,
+		build: () => GraphQLInputObjectType,
+	): GraphQLInputObjectType {
+		return memo(this.#inputs, name, build)
+	}
+
+	enum(name: string, build: () => GraphQLEnumType): GraphQLEnumType {
+		return memo(this.#enums, name, build)
+	}
+}
+
+/** Each field's `description` (D-150), on the fields of a type or an input. */
+export function described<
+	C extends { readonly description?: string | null | undefined },
+>(entry: Entry, fields: { [field: string]: C }): { [field: string]: C } {
+	for (const [field, description] of Object.entries(
+		entry.exposed.descriptions,
+	)) {
+		const config = fields[field]
+		if (config !== undefined) fields[field] = { ...config, description }
+	}
+	return fields
+}
+
+export const scalarTypes: {
+	readonly [T in Exclude<Scalar['type'], 'enum'>]: GraphQLScalarType
+} = {
+	string: GraphQLString,
+	number: GraphQLFloat,
+	decimal: DecimalScalar,
+	boolean: GraphQLBoolean,
+	dateTime: DateTime,
+	date: DateScalar,
+	json: JSONScalar,
+}
+
+/**
+ * A scalar field's type; an enum's is `PostStatus`, built once, and a
+ * `defineEnum`'s its own name, one type for every field (D-150).
+ */
+export function scalarType(
+	registry: Registry,
+	model: string,
+	field: Scalar,
+): GraphQLScalarType | GraphQLEnumType {
+	if (field.integer === true) return GraphQLInt
+	if (field.type !== 'enum') return scalarTypes[field.type]
+	const shared = registry.entry(model).exposed.enums[field.name]
+	if (shared !== undefined) {
+		const { name, values } = shared
+		return registry.data.enum(name, values, `${model}.${field.name}`)
+	}
+	const name = `${model}${upper(field.name)}`
+	return registry.enum(
+		name,
+		() =>
+			new GraphQLEnumType({
+				name,
+				values: Object.fromEntries(
+					(field.values ?? []).map((value) => [value, { value }]),
+				),
+			}),
+	)
+}
+
+/** A scalar field's value, read or written: a list's is `[Float!]` (D-127). */
+export const valueType = (
+	registry: Registry,
+	model: string,
+	field: Scalar,
+):
+	| GraphQLScalarType
+	| GraphQLEnumType
+	| GraphQLList<GraphQLNonNull<GraphQLScalarType | GraphQLEnumType>> => {
+	const item = scalarType(registry, model, field)
+	return field.list ? new GraphQLList(new GraphQLNonNull(item)) : item
+}

package/src/reread.ts

@@ -0,0 +1,159 @@
+// A function's output as the client reads it (D-109): its scalars as `run`
+// returned them, its rows' relations re-read by id as the caller, in one
+// query per model and only when a relation is selected.
+import { badInput, rowsOf, run } from '@ultimabase/http/internal'
+import type { FieldNode, GraphQLResolveInfo } from 'graphql'
+import type { ExposedOutput } from 'ultimabase'
+import { isMaster, objectType } from './outputs.ts'
+import type { Args, Context, Registry } from './registry.ts'
+import { as } from './registry.ts'
+import type { Fields } from './select.ts'
+import { grouped, selectOf } from './select.ts'
+
+type Row = { [field: string]: unknown }
+type Named = Exclude<ExposedOutput, { readonly kind: 'schema' }>
+/** The rows of one model to re-read, and the relations they select. */
+type Pending = {
+	readonly select: { [relation: string]: unknown }
+	readonly rows: Map<string, Row[]>
+}
+
+const isRecord = (value: unknown): value is object =>
+	typeof value === 'object' && value !== null
+
+/** `run`'s value, its rows' relations read as the caller. */
+export async function reread(
+	registry: Registry,
+	output: ExposedOutput,
+	value: unknown,
+	context: Context,
+	info: GraphQLResolveInfo,
+	call: { readonly name: string; readonly take: number },
+): Promise<unknown> {
+	const master = isMaster(context)
+	// The rows whose relations are read, which the row budget counts.
+	let counted = 0
+	const pending = new Map<string, Pending>()
+	// A list's items share their nodes: each selection is read once.
+	const relations = new Map<readonly FieldNode[], Args>()
+	const fields = new Map<readonly FieldNode[], ReadonlyMap<string, Fields>>()
+
+	const relationsOf = (model: string, nodes: readonly FieldNode[]): Args => {
+		const known = relations.get(nodes)
+		if (known !== undefined) return known
+		const type = objectType(registry, model)
+		const select = selectOf(registry, info, type, nodes, master)
+		// A virtual is computed when its row is read (D-151).
+		const { virtuals } = registry.entry(model).exposed
+		const found = Object.fromEntries(
+			Object.entries(select).filter(
+				([name, read]) =>
+					read !== true || virtuals.some((virtual) => virtual.name === name),
+			),
+		)
+		relations.set(nodes, found)
+		return found
+	}
+
+	const fieldsOf = (nodes: readonly FieldNode[]) => {
+		const known = fields.get(nodes)
+		if (known !== undefined) return known
+		const found = grouped(info, nodes)
+		fields.set(nodes, found)
+		return found
+	}
+
+	const row = (model: string, item: object, nodes: readonly FieldNode[]) => {
+		const select = relationsOf(model, nodes)
+		if (Object.keys(select).length === 0) return item
+		const copy: Row = { ...item }
+		const { id } = copy
+		if (typeof id !== 'string') {
+			throw new TypeError(`A ${model} was returned without its id.`)
+		}
+		const reading: Pending = pending.get(model) ?? {
+			select: {},
+			rows: new Map(),
+		}
+		pending.set(model, reading)
+		for (const [name, read] of Object.entries(select)) {
+			const known = reading.select[name]
+			if (
+				known !== undefined &&
+				JSON.stringify(known) !== JSON.stringify(read)
+			) {
+				throw badInput(
+					`${model}.${name} is selected in two ways; select it the same way everywhere.`,
+				)
+			}
+			reading.select[name] = read
+		}
+		reading.rows.set(id, [...(reading.rows.get(id) ?? []), copy])
+		counted += 1
+		return copy
+	}
+
+	const one = (named: Named, item: unknown, nodes: readonly FieldNode[]) => {
+		if (!isRecord(item)) return item
+		if (named.kind === 'model') return row(named.name, item, nodes)
+		const copy: Row = { ...item }
+		const selected = fieldsOf(nodes)
+		for (const [name, field] of named.type.fields) {
+			const below = selected.get(name)
+			if (below !== undefined) {
+				copy[name] = walk(field, Reflect.get(item, name), below)
+			}
+		}
+		return copy
+	}
+
+	const walk = (
+		at: ExposedOutput,
+		item: unknown,
+		nodes: readonly FieldNode[],
+	): unknown => {
+		if (at.kind === 'schema') return item
+		if (at.form !== 'list' || !Array.isArray(item)) {
+			return one(at, item, nodes)
+		}
+		const before = counted
+		const items = item.map((each: unknown) => one(at, each, nodes))
+		// The budget counts `take` rows in a list (D-109).
+		if (items.length > call.take && counted > before) {
+			throw new RangeError(
+				`${call.name} returned ${items.length} rows; a list counts take (${call.take}) rows, so it holds no more under a selected relation.`,
+			)
+		}
+		return items
+	}
+
+	const result = walk(output, value, info.fieldNodes)
+	for (const [model, { select, rows }] of pending) {
+		const entry = registry.entry(model)
+		const ids = [...rows.keys()]
+		const read = await run(() =>
+			entry.exposed.queries.findMany(
+				{
+					where: { id: { in: ids } },
+					take: ids.length,
+					select: { id: true, ...select },
+				},
+				as(context),
+			),
+		)
+		const byId = new Map(rowsOf(read).map((found) => [found.id, found]))
+		for (const [id, copies] of rows) {
+			const found = byId.get(id)
+			for (const name of Object.keys(select)) {
+				// A row the caller cannot read has no relations (D-109).
+				const many = entry.model.fields.some(
+					(field) => field.name === name && field.kind === 'many',
+				)
+				const empty = many ? [] : null
+				const relation = found === undefined ? empty : Reflect.get(found, name)
+				for (const copy of copies) copy[name] = relation
+			}
+		}
+	}
+	return result
+}

package/src/rows.ts

@@ -0,0 +1,151 @@
+// The row budget (D-107): a document that may return more than `maxRows`
+// rows, or reads and writes more than `maxRoots` times at its root, is
+// refused before it runs. Each list counts the rows it asks for, times the
+// rows of the lists above it. Each relation a list's `orderBy` goes through
+// counts one level of `maxDepth` under the list (D-134).
+import type {
+	FieldNode,
+	GraphQLObjectType,
+	ValidatedExecutionArgs,
+} from 'graphql'
+import {
+	getArgumentValues,
+	getNamedType,
+	GraphQLError,
+	isObjectType,
+} from 'graphql'
+import type { Info, Selecting } from './select.ts'
+import { grouped } from './select.ts'
+import type { Entry, Registry } from './registry.ts'
+
+/**
+ * What a field reads: one row, a list of a model's rows, or a function's
+ * list, which counts `take` rows (D-109).
+ */
+export type Read =
+	| { readonly kind: 'one' }
+	| { readonly kind: 'many'; readonly entry: Entry }
+	| { readonly kind: 'list'; readonly size: number }
+
+const one: Read = { kind: 'one' }
+/** Each a query or a write of its own, a count one more. */
+const maxRoots = 20
+const responseKey = (node: FieldNode) => node.alias?.value ?? node.name.value
+
+// `take` for none or a negative number; above `maxTake`, the list refuses.
+const sizeOf = (entry: Entry, asked: unknown): number =>
+	typeof asked === 'number' && asked >= 0
+		? Math.min(asked, entry.maxTake)
+		: entry.take
+
+/** The reads of the root query, by field name. */
+function rootReads(registry: Registry): ReadonlyMap<string, Read> {
+	const reads = new Map<string, Read>()
+	for (const entry of registry.entries.values()) {
+		if (!entry.visible) continue
+		reads.set(entry.single, one)
+		reads.set(entry.list, { kind: 'many', entry })
+	}
+	return reads
+}
+
+/** The relations an `orderBy` goes through, the deepest path's. */
+function sortDepth(orderBy: unknown): number {
+	if (Array.isArray(orderBy)) return Math.max(0, ...orderBy.map(sortDepth))
+	if (typeof orderBy !== 'object' || orderBy === null) return 0
+	return Math.max(
+		0,
+		...Object.values(orderBy).map((value: unknown) =>
+			typeof value === 'object' && value !== null ? 1 + sortDepth(value) : 0,
+		),
+	)
+}
+
+export type Limits = { readonly maxRows: number; readonly maxDepth: number }
+
+/** The refusal of a document that may return more than `maxRows` rows. */
+export function rowBudget(
+	registry: Registry,
+	{ maxRows, maxDepth }: Limits,
+	functions: ReadonlyMap<string, ReadonlyMap<string, Read>>,
+): (args: ValidatedExecutionArgs) => GraphQLError | undefined {
+	const roots = rootReads(registry)
+	const list = registry.settings.pagination === 'list'
+	const readOf = (
+		type: GraphQLObjectType,
+		root: string,
+		name: string,
+	): Read | undefined => {
+		const called = functions.get(type.name)
+		if (called?.has(name) === true) return called.get(name)
+		if (root === 'mutation') return one
+		if (root === 'query') return roots.get(name)
+		const entry = registry.entries.get(type.name)
+		const field = entry?.model.fields.find((f) => f.name === name)
+		if (field === undefined || field.kind === 'scalar') return undefined
+		if (field.kind === 'one') return one
+		return { kind: 'many', entry: registry.entry(field.target) }
+	}
+	return (args) => {
+		const info: Info = {
+			fragments: args.fragmentDefinitions,
+			variableValues: args.variableValues,
+		}
+		let rows = 0
+		let rootFields = 0
+		let deepest = 0
+		const walk = (
+			type: GraphQLObjectType,
+			nodes: readonly Selecting[],
+			times: number,
+			root: string,
+			level: number,
+		): void => {
+			for (const fields of grouped(info, nodes, responseKey).values()) {
+				if (rows > maxRows) return
+				const [node] = fields
+				const field = type.getFields()[node.name.value]
+				if (field === undefined) continue
+				const read = readOf(type, root, node.name.value)
+				let each = times
+				if (read?.kind === 'many') {
+					const asked = getArgumentValues(field, node, args.variableValues)
+					const size = sizeOf(
+						read.entry,
+						list ? asked['take'] : (asked['last'] ?? asked['first']),
+					)
+					// A count reads the rows it counts, however few the page returns.
+					deepest = Math.max(deepest, level + sortDepth(asked['orderBy']))
+					const counted = grouped(info, fields).has('totalCount')
+					each *= counted ? Math.max(size, read.entry.take) : size
+					if (counted && root !== '') rootFields += 1
+				} else if (read?.kind === 'list') each *= read.size
+				if (read !== undefined) rows += each
+				if (root !== '') rootFields += 1
+				const named = getNamedType(field.type)
+				if (isObjectType(named) && each > 0) {
+					walk(named, fields, each, '', level + 1)
+				}
+			}
+		}
+		const { operation } = args
+		const type = args.schema.getRootType(operation.operation)
+		// `validateExecutionArgs` refused an operation the schema has no root for.
+		if (type) walk(type, [operation], 1, operation.operation, 1)
+		if (deepest > maxDepth) {
+			return new GraphQLError(
+				`The document is nested ${deepest} levels deep, its orderBy included; the most is ${maxDepth}.`,
+			)
+		}
+		if (rootFields > maxRoots) {
+			return new GraphQLError(
+				`The document asks for more than ${maxRoots} root fields, a totalCount counted as one more. Send several documents.`,
+			)
+		}
+		if (rows <= maxRows) return undefined
+		const fewer = list ? 'take' : 'first or last'
+		return new GraphQLError(
+			`The document asks for more than ${maxRows.toLocaleString('en-US')} rows. Ask for fewer with ${fewer}.`,
+		)
+	}
+}

package/src/scalars.ts

@@ -0,0 +1,110 @@
+// `DateTime` and `JSON` (D-107): a date as an ISO 8601 string, and any JSON
+// value as the kernel stores it; `Decimal` (D-145), an exact number, and
+// `Date` (D-150), a day, as strings, which the kernel checks.
+import type { ConstValueNode } from 'graphql'
+import { GraphQLError, GraphQLScalarType, Kind } from 'graphql'
+
+const iso =
+	/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/
+
+/** A date a client sent, which keeps its text for a function (D-109). */
+export class SentDate extends Date {
+	readonly sent: string
+
+	constructor(sent: string) {
+		super(sent)
+		this.sent = sent
+	}
+}
+
+function date(value: unknown): Date {
+	if (typeof value === 'string' && iso.test(value)) {
+		const parsed = new SentDate(value)
+		if (!Number.isNaN(parsed.getTime())) return parsed
+	}
+	throw new GraphQLError(
+		'A DateTime is an ISO 8601 string, such as 2026-01-31T12:00:00.000Z.',
+	)
+}
+
+export const DateTime: GraphQLScalarType<Date, string> = new GraphQLScalarType<
+	Date,
+	string
+>({
+	name: 'DateTime',
+	description: 'A date and time, as an ISO 8601 string.',
+	coerceOutputValue: (value) => {
+		if (value instanceof Date) return value.toISOString()
+		// A function's schema output holds its dates as strings (D-109).
+		if (typeof value === 'string') return date(value).toISOString()
+		throw new GraphQLError('A DateTime field returned no date.')
+	},
+	coerceInputValue: date,
+	coerceInputLiteral: (node) =>
+		date(node.kind === Kind.STRING ? node.value : undefined),
+})
+
+function decimal(value: unknown): string {
+	if (typeof value === 'string') return value
+	throw new GraphQLError("A Decimal is a string, such as '12.50'.")
+}
+
+export const DecimalScalar: GraphQLScalarType<string, string> =
+	new GraphQLScalarType<string, string>({
+		name: 'Decimal',
+		description: "An exact number, as a string such as '12.50'.",
+		coerceOutputValue: decimal,
+		coerceInputValue: decimal,
+		coerceInputLiteral: (node) =>
+			decimal(node.kind === Kind.STRING ? node.value : undefined),
+	})
+
+function day(value: unknown): string {
+	if (typeof value === 'string') return value
+	throw new GraphQLError("A Date is a day as a string, such as '2026-07-31'.")
+}
+
+export const DateScalar: GraphQLScalarType<string, string> =
+	new GraphQLScalarType<string, string>({
+		name: 'Date',
+		description: "A day, as an ISO 8601 string such as '2026-07-31'.",
+		coerceOutputValue: day,
+		coerceInputValue: day,
+		coerceInputLiteral: (node) =>
+			day(node.kind === Kind.STRING ? node.value : undefined),
+	})
+
+/** Dates back to their text: a validator reads what the client sent. */
+export function plain(value: unknown): unknown {
+	if (value instanceof SentDate) return value.sent
+	if (Array.isArray(value)) return value.map(plain)
+	if (typeof value !== 'object' || value === null) return value
+	return Object.fromEntries(
+		Object.entries(value).map(([key, item]) => [key, plain(item)]),
+	)
+}
+
+/** A literal as the plain value the kernel's JSON check accepts. */
+function literal(node: ConstValueNode): unknown {
+	if (node.kind === Kind.OBJECT) {
+		return Object.fromEntries(
+			node.fields.map((field) => [field.name.value, literal(field.value)]),
+		)
+	}
+	if (node.kind === Kind.LIST) return node.values.map(literal)
+	if (node.kind === Kind.INT || node.kind === Kind.FLOAT) {
+		return Number(node.value)
+	}
+	if (node.kind === Kind.NULL) return null
+	// A string, a boolean or an enum's name.
+	return node.value
+}
+
+export const JSONScalar: GraphQLScalarType<unknown, unknown> =
+	new GraphQLScalarType<unknown, unknown>({
+		name: 'JSON',
+		description: 'Any JSON value.',
+		coerceOutputValue: (value) => value,
+		coerceInputValue: (value) => value,
+		coerceInputLiteral: literal,
+	})