@ultimabase/graphql 0.0.0-stage → 0.1.1

package/src/inputs.ts

@@ -0,0 +1,348 @@
+// The read inputs (D-107), as the query API spells them (D-20): filters,
+// `where`, `orderBy` and the `@oneOf` unique target.
+import { readable } from '@ultimabase/http/internal'
+import type {
+	GraphQLInputFieldConfigMap,
+	GraphQLInputType,
+	GraphQLNamedInputType,
+	GraphQLScalarType,
+} from 'graphql'
+import {
+	GraphQLBoolean,
+	GraphQLEnumType,
+	GraphQLID,
+	GraphQLInputObjectType,
+	GraphQLList,
+	GraphQLNonNull,
+	GraphQLString,
+} from 'graphql'
+import type { SchemaField } from 'ultimabase'
+import { upper } from './names.ts'
+import type { Args, Registry, Scalar } from './registry.ts'
+import { scalarType } from './registry.ts'
+import { DateTime } from './scalars.ts'
+
+/** An input object's value, as the kernel's arguments. */
+export const objectOf = (value: unknown): Args =>
+	typeof value === 'object' && value !== null ? { ...value } : {}
+
+/** Whether a model has fields its `_search` matches (D-148). */
+const searched = (fields: readonly SchemaField[]): boolean =>
+	fields.some((field) => field.kind === 'scalar' && field.search === true)
+
+const list = <T extends GraphQLNamedInputType>(
+	type: T,
+): GraphQLList<GraphQLNonNull<T>> => new GraphQLList(new GraphQLNonNull(type))
+
+const base = ['equals', 'not', 'in', 'notIn']
+const ordered = [...base, 'lt', 'lte', 'gt', 'gte']
+const text = [...base, 'contains', 'startsWith', 'endsWith']
+
+/** `QueryMode`: a string filter's operators ignore case (D-140). */
+const queryMode = (registry: Registry): GraphQLEnumType =>
+	registry.enum(
+		'QueryMode',
+		() =>
+			new GraphQLEnumType({
+				name: 'QueryMode',
+				values: { insensitive: { value: 'insensitive' } },
+			}),
+	)
+
+/** The input type of a filter's operator. */
+function operand(
+	registry: Registry,
+	type: GraphQLNamedInputType,
+	operator: string,
+): GraphQLInputType {
+	if (operator === 'mode') return queryMode(registry)
+	if (operator === 'path') return list(GraphQLString)
+	if (operator.startsWith('string')) return GraphQLString
+	return operator === 'in' || operator === 'notIn' ? list(type) : type
+}
+
+/** `StringFilter`, `FloatFilter`, `PostStatusFilter`: the kernel's operators. */
+function filter(
+	registry: Registry,
+	type: GraphQLNamedInputType,
+	operators: readonly string[],
+): GraphQLInputObjectType {
+	const name = `${type.name}Filter`
+	return registry.input(
+		name,
+		() =>
+			new GraphQLInputObjectType({
+				name,
+				fields: Object.fromEntries(
+					operators.map((operator) => [
+						operator,
+						{ type: operand(registry, type, operator) },
+					]),
+				),
+			}),
+	)
+}
+
+/** Each scalar type's operators: no order on strings, as the kernel. */
+const operators: { readonly [T in Scalar['type']]: readonly string[] } = {
+	string: [...text, 'mode'],
+	number: ordered,
+	decimal: ordered,
+	dateTime: ordered,
+	date: ordered,
+	boolean: base,
+	// Any JSON, a path into it or not, typed field or not (D-149).
+	json: [
+		'path',
+		...ordered,
+		'stringContains',
+		'stringStartsWith',
+		'stringEndsWith',
+		'mode',
+		'arrayContains',
+		'arrayStartsWith',
+		'arrayEndsWith',
+	],
+	enum: base,
+}
+
+/**
+ * `StringListFilter`, `FloatListFilter`, `ProductSizesListFilter`: no
+ * shorthand, `NOT` gives the opposite (D-120, D-127, D-149).
+ */
+const listFilter = (
+	registry: Registry,
+	item: GraphQLScalarType | GraphQLEnumType,
+): GraphQLInputObjectType => {
+	const name = `${item.name}ListFilter`
+	return registry.input(
+		name,
+		() =>
+			new GraphQLInputObjectType({
+				name,
+				fields: {
+					has: { type: item },
+					hasSome: { type: list(item) },
+					hasEvery: { type: list(item) },
+					isEmpty: { type: GraphQLBoolean },
+				},
+			}),
+	)
+}
+
+const scalarFilter = (
+	registry: Registry,
+	model: string,
+	field: Scalar,
+): GraphQLInputObjectType => {
+	const item = scalarType(registry, model, field)
+	if (field.list) return listFilter(registry, item)
+	return filter(registry, item, operators[field.type])
+}
+
+const relationFilter = (
+	registry: Registry,
+	field: Exclude<SchemaField, Scalar>,
+): GraphQLInputObjectType => {
+	const one = field.kind === 'one'
+	const name = `${field.target}${one ? 'Relation' : 'ListRelation'}Filter`
+	return registry.input(
+		name,
+		() =>
+			new GraphQLInputObjectType({
+				name,
+				fields: () => {
+					const type = whereInput(registry, field.target)
+					return Object.fromEntries(
+						(one ? ['is', 'isNot'] : ['some', 'every', 'none']).map((key) => [
+							key,
+							{ type },
+						]),
+					)
+				},
+			}),
+	)
+}
+
+/** `PostWhereInput`. */
+export function whereInput(
+	registry: Registry,
+	model: string,
+): GraphQLInputObjectType {
+	const name = `${model}WhereInput`
+	return registry.input(
+		name,
+		() =>
+			new GraphQLInputObjectType({
+				name,
+				fields: () => {
+					const self = whereInput(registry, model)
+					const fields: GraphQLInputFieldConfigMap = {
+						AND: { type: list(self) },
+						OR: { type: list(self) },
+						NOT: { type: list(self) },
+						id: { type: filter(registry, GraphQLID, base) },
+						createdAt: { type: filter(registry, DateTime, ordered) },
+						updatedAt: { type: filter(registry, DateTime, ordered) },
+					}
+					const entry = registry.entry(model)
+					if (searched(readable(entry))) {
+						fields['_search'] = { type: GraphQLString }
+					}
+					for (const field of readable(entry)) {
+						// Only a beforeFind filters a plugin field (D-122).
+						if (entry.exposed.fieldTypes[field.name] !== undefined) continue
+						fields[field.name] = {
+							type:
+								field.kind === 'scalar'
+									? scalarFilter(registry, model, field)
+									: relationFilter(registry, field),
+						}
+					}
+					return fields
+				},
+			}),
+	)
+}
+
+const sortOrder = (registry: Registry): GraphQLEnumType =>
+	registry.enum(
+		'SortOrder',
+		() =>
+			new GraphQLEnumType({
+				name: 'SortOrder',
+				values: { asc: { value: 'asc' }, desc: { value: 'desc' } },
+			}),
+	)
+
+/** `CountOrderByInput`: a `many` relation sorted by its rows (D-134). */
+const countOrderBy = (registry: Registry): GraphQLInputObjectType =>
+	registry.input(
+		'CountOrderByInput',
+		() =>
+			new GraphQLInputObjectType({
+				name: 'CountOrderByInput',
+				fields: { _count: { type: sortOrder(registry) } },
+			}),
+	)
+
+/**
+ * `PostOrderByInput`: scalar fields but json, lists and plugin fields, as
+ * the kernel sorts (D-94, D-120, D-122); a `one` relation as its target's,
+ * a `many` one by its count (D-134).
+ */
+export function orderByInput(
+	registry: Registry,
+	model: string,
+): GraphQLInputObjectType {
+	const name = `${model}OrderByInput`
+	return registry.input(
+		name,
+		() =>
+			new GraphQLInputObjectType({
+				name,
+				fields: () => {
+					const type = sortOrder(registry)
+					const fields: GraphQLInputFieldConfigMap = {
+						id: { type },
+						createdAt: { type },
+						updatedAt: { type },
+					}
+					const entry = registry.entry(model)
+					// The kernel refuses it in a relation's: a read ranks by its own search.
+					if (searched(readable(entry))) fields['_relevance'] = { type }
+					for (const field of readable(entry)) {
+						if (field.kind === 'one') {
+							fields[field.name] = {
+								type: orderByInput(registry, field.target),
+							}
+						} else if (field.kind === 'many') {
+							fields[field.name] = { type: countOrderBy(registry) }
+						} else if (
+							field.type !== 'json' &&
+							!field.list &&
+							entry.exposed.fieldTypes[field.name] === undefined
+						) {
+							fields[field.name] = { type }
+						}
+					}
+					return fields
+				},
+			}),
+	)
+}
+
+/** A unique field's type: a `one` relation's is its target's `ID`. */
+function uniqueType(
+	registry: Registry,
+	model: string,
+	name: string,
+): GraphQLNamedInputType {
+	const field = registry.entry(model).model.fields.find((f) => f.name === name)
+	return field?.kind === 'scalar'
+		? scalarType(registry, model, field)
+		: GraphQLID
+}
+
+const compositeName = (fields: readonly string[]): string => fields.join('_')
+
+/**
+ * `PostWhereUniqueInput @oneOf`: `id`, each unique field, and each unique
+ * index as `author_slug: { author, slug }`.
+ */
+export function uniqueInput(
+	registry: Registry,
+	model: string,
+): GraphQLInputObjectType {
+	const name = `${model}WhereUniqueInput`
+	return registry.input(name, () => {
+		const fields: GraphQLInputFieldConfigMap = {}
+		const { exposed } = registry.entry(model)
+		// A field only Master reads is absent, as from the filters (D-44).
+		const uniques = exposed.uniques.filter((unique) =>
+			unique.every((field) => exposed.readRules[field] !== 'private'),
+		)
+		for (const unique of uniques) {
+			const [only] = unique
+			if (unique.length === 1 && only !== undefined) {
+				fields[only] = { type: uniqueType(registry, model, only) }
+				continue
+			}
+			const key = compositeName(unique)
+			const composite = `${model}${unique.map(upper).join('')}UniqueInput`
+			fields[key] = {
+				type: new GraphQLInputObjectType({
+					name: composite,
+					fields: Object.fromEntries(
+						unique.map((field) => [
+							field,
+							{ type: new GraphQLNonNull(uniqueType(registry, model, field)) },
+						]),
+					),
+				}),
+			}
+		}
+		return new GraphQLInputObjectType({ name, fields, isOneOf: true })
+	})
+}
+
+/** A `@oneOf` unique target as the kernel's flat `where`. */
+export function uniqueWhere(
+	registry: Registry,
+	model: string,
+	where: Args,
+): Args {
+	const composites = new Set(
+		registry
+			.entry(model)
+			.exposed.uniques.filter((unique) => unique.length > 1)
+			.map(compositeName),
+	)
+	const flat: { [field: string]: unknown } = {}
+	for (const [key, value] of Object.entries(where)) {
+		if (composites.has(key) && typeof value === 'object') {
+			Object.assign(flat, value)
+		} else flat[key] = value
+	}
+	return flat
+}

package/src/json-fields.ts

@@ -0,0 +1,95 @@
+// A json field's types (D-125): exact from its schema's JSON Schema export,
+// `JSON` without one. Read as `UserPrefs`, written as `UserPrefsInput`,
+// filtered by `JSONFilter` as an untyped field (D-149). A plugin field reads
+// as its shape says (D-152).
+import type {
+	GraphQLNullableInputType,
+	GraphQLNullableOutputType,
+} from 'graphql'
+import type { Path, Typed } from './data.ts'
+import { fieldInput, fieldOutput } from './data.ts'
+import { upper } from './names.ts'
+import type { Args, Registry, Scalar } from './registry.ts'
+import { JSONScalar, plain } from './scalars.ts'
+
+const pathOf = (model: string, field: Scalar, suffix: string): Path => ({
+	owner: `${model}.${field.name}`,
+	name: `${model}${upper(field.name)}`,
+	suffix,
+	at: field.name,
+})
+
+const untyped = { type: JSONScalar, nullable: false }
+
+/** `UserPrefs` or `PostCover`, and whether the schema reads `null`. */
+export function jsonOutput(
+	registry: Registry,
+	model: string,
+	field: Scalar,
+): Typed<GraphQLNullableOutputType> {
+	const { validators, fieldTypes } = registry.entry(model).exposed
+	const schema = validators[field.name] ?? fieldTypes[field.name]?.shape
+	const path = pathOf(model, field, '')
+	return (schema && fieldOutput(schema, path, registry.data)) ?? untyped
+}
+
+/** `UserPrefsInput`, and whether the schema takes `null`. */
+export function jsonInput(
+	registry: Registry,
+	model: string,
+	field: Scalar,
+): Typed<GraphQLNullableInputType> {
+	const schema = registry.entry(model).exposed.validators[field.name]
+	const path = pathOf(model, field, 'Input')
+	return (schema && fieldInput(schema, path, registry.data)) ?? untyped
+}
+
+/** A written row's json and plugin values, their dates back to text. */
+export function plainData(registry: Registry, model: string, data: Args): Args {
+	const plained: { [field: string]: unknown } = { ...data }
+	const { exposed, model: schema } = registry.entry(model)
+	for (const field of schema.fields) {
+		const value = plained[field.name]
+		if (value === undefined || field.kind !== 'scalar') continue
+		if (field.type === 'json' || exposed.fieldTypes[field.name] !== undefined) {
+			plained[field.name] = plain(value)
+		}
+	}
+	return plained
+}
+
+const each = (value: unknown, map: (where: Args) => Args): unknown =>
+	Array.isArray(value)
+		? value.map((item) => each(item, map))
+		: typeof value === 'object' && value !== null
+			? map({ ...value })
+			: value
+
+/** A filter's json operands, their dates back to text, through relations. */
+export function plainWhere(
+	registry: Registry,
+	model: string,
+	where: Args,
+): Args {
+	const fields = registry.entry(model).model.fields
+	const plained: { [key: string]: unknown } = {}
+	for (const [key, value] of Object.entries(where)) {
+		const field = fields.find((candidate) => candidate.name === key)
+		if (key === 'AND' || key === 'OR' || key === 'NOT') {
+			plained[key] = each(value, (inner) => plainWhere(registry, model, inner))
+		} else if (field?.kind === 'scalar') {
+			plained[key] = field.type === 'json' ? plain(value) : value
+		} else if (field !== undefined) {
+			// `is`, `some` and the others each take the target's filter.
+			plained[key] = each(value, (operators) =>
+				Object.fromEntries(
+					Object.entries(operators).map(([operator, inner]) => [
+						operator,
+						each(inner, (target) => plainWhere(registry, field.target, target)),
+					]),
+				),
+			)
+		} else plained[key] = value
+	}
+	return plained
+}

package/src/json-schema.ts

@@ -0,0 +1,21 @@
+// A schema's standard JSON Schema export, which `data.ts` types (D-45).
+
+import type { Node } from '@ultimabase/http/internal'
+import { isNode, jsonSchemaOf } from '@ultimabase/http/internal'
+import { Refused } from 'ultimabase'
+
+export type Side = 'input' | 'output'
+
+/** A json field's JSON Schema, `undefined` without one (D-125). */
+export function exportOf(schema: object, side: Side): Node | undefined {
+	try {
+		return jsonSchemaOf(schema, side, '')
+	} catch (error) {
+		if (error instanceof Refused) return undefined
+		throw error
+	}
+}
+
+/** The JSON Schema's shared nodes, by id. */
+export const defsOf = (root: Node): Node =>
+	isNode(root['$defs']) ? root['$defs'] : {}

package/src/live-stream.ts

@@ -0,0 +1,192 @@
+// A live read as graphql-ws streams it (D-154): the engine's messages in
+// order, each run against the subscription's selection, and those the client
+// cannot take while its socket is full dropped until the window is sent again.
+// A completed live list is kept 10 s for a resume, its later events waiting.
+import type { ExecutionResult } from 'graphql'
+import type { LiveHandle, LiveMessage, Viewer } from '@ultimabase/realtime'
+
+/** A message to run against the selection, and how its result is sent. */
+export class LiveEvent {
+	readonly root: unknown
+	readonly finish: (result: ExecutionResult) => ExecutionResult
+
+	constructor(
+		root: unknown,
+		finish: (result: ExecutionResult) => ExecutionResult,
+	) {
+		this.root = root
+		this.finish = finish
+	}
+}
+
+/** The socket a connection's subscriptions write to. */
+export type Channel = {
+	readonly viewer: Viewer
+	/** Whether the client's buffer holds more than it may. */
+	readonly full: () => boolean
+	/** Runs `then` once everything sent is written. */
+	readonly drained: (then: () => void) => void
+	/** Closes the socket: its caller is no longer the same user. */
+	readonly forbid: () => void
+	/** The completed live lists a resume may take back, by token. */
+	readonly kept: Map<string, Kept>
+}
+
+/**
+ * A subscription's channel, whether it gets the whole window each time, and
+ * the token of the completed list it resumes.
+ */
+export type Live = {
+	readonly channel: Channel
+	readonly page: boolean
+	readonly resume?: string
+}
+
+/** A live list's token, what read it is, and the rows it shows. */
+export type Keep = {
+	readonly token: string
+	readonly signature: string
+	first: number
+}
+
+/** A completed live list, until a resume takes it or its time is up. */
+export type Kept = {
+	readonly keep: Keep
+	readonly stream: AsyncIterableIterator<LiveEvent>
+	readonly handle: LiveHandle
+	readonly timer: NodeJS.Timeout
+	readonly end: () => void
+}
+
+/** How long a completed live list waits for a resume. */
+const keptFor = 10_000
+
+/** Each WebSocket operation's, by its context. */
+export const lives: WeakMap<object, Live> = new WeakMap()
+
+const finished = (): IteratorResult<LiveEvent> => ({
+	done: true,
+	value: undefined,
+})
+
+/**
+ * The list `token` keeps, taken back when it is the same read and grown to
+ * `first` rows; a resume that grows past a limit ends it.
+ */
+export async function resumed(
+	channel: Channel,
+	token: string,
+	signature: string,
+	first: number,
+): Promise<AsyncIterableIterator<LiveEvent> | undefined> {
+	const kept = channel.kept.get(token)
+	if (kept?.keep.signature !== signature || first < kept.keep.first) {
+		return undefined
+	}
+	channel.kept.delete(token)
+	clearTimeout(kept.timer)
+	try {
+		if (first > kept.keep.first) await kept.handle.grow(first - kept.keep.first)
+	} catch (error) {
+		kept.end()
+		throw error
+	}
+	kept.keep.first = first
+	return kept.stream
+}
+
+/**
+ * Follows the read `open` starts; `event` turns each message the client
+ * gets into what it runs, and `closed`, given a live function's error, into
+ * the last one, unless the viewer ended, which closes the socket. A list given `keep` is kept once completed.
+ */
+export async function liveStream(
+	channel: Channel,
+	open: (send: (message: LiveMessage) => void) => Promise<LiveHandle>,
+	event: (message: Exclude<LiveMessage, { kind: 'closed' }>) => LiveEvent,
+	closed: (error?: unknown) => LiveEvent,
+	keep?: Keep,
+): Promise<AsyncIterableIterator<LiveEvent>> {
+	const queue: LiveEvent[] = []
+	let waiting: ((next: IteratorResult<LiveEvent>) => void) | undefined
+	let ending = false
+	let done = false
+	// Changes are dropped from a full buffer until the window comes whole.
+	let dropping = false
+	let owed = false
+	let handle: LiveHandle | undefined
+	const push = (value: LiveEvent) => {
+		const taker = waiting
+		waiting = undefined
+		if (taker === undefined) queue.push(value)
+		else taker({ done: false, value })
+	}
+	const end = () => {
+		done = true
+		queue.length = 0
+		handle?.close()
+		const taker = waiting
+		waiting = undefined
+		taker?.(finished())
+	}
+	const send = (message: LiveMessage) => {
+		if (done || ending) return
+		if (message.kind === 'closed') {
+			if (channel.viewer.closed) {
+				end()
+				return channel.forbid()
+			}
+			ending = true
+			return push(closed(message.error))
+		}
+		if (dropping && message.kind === 'changes') return
+		if (!dropping && channel.full()) {
+			queue.length = 0
+			dropping = true
+			channel.drained(() => {
+				if (handle === undefined) owed = true
+				else void handle.resend()
+			})
+			return
+		}
+		dropping = false
+		push(event(message))
+	}
+	const opened = await open(send)
+	handle = opened
+	if (owed) void opened.resend()
+	const stream: AsyncIterableIterator<LiveEvent> = {
+		next: async () => {
+			const value = queue.shift()
+			if (value !== undefined) return { done: false, value }
+			if (done || ending) {
+				end()
+				return finished()
+			}
+			return new Promise((taker) => {
+				waiting = taker
+			})
+		},
+		return: async () => {
+			if (channel.kept.get(keep?.token ?? '')?.stream === stream) {
+				return finished()
+			}
+			if (keep === undefined || done || ending || channel.viewer.closed) {
+				end()
+				return finished()
+			}
+			const taker = waiting
+			waiting = undefined
+			taker?.(finished())
+			const timer = setTimeout(() => {
+				channel.kept.delete(keep.token)
+				end()
+			}, keptFor)
+			timer.unref()
+			channel.kept.set(keep.token, { keep, stream, handle: opened, timer, end })
+			return finished()
+		},
+		[Symbol.asyncIterator]: () => stream,
+	}
+	return stream
+}