@ultimabase/graphql 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@ultimabase/graphql",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "GraphQL for UltimaBase: a Relay schema generated from the models, served by the HTTP plugin.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev/docs/graphql",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/graphql"
+  },
+  "engines": {
+    "node": ">=24.7.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "graphql-http": "1.23.1",
+    "graphql-ws": "6.4.1",
+    "ws": "8.22.0"
+  },
+  "peerDependencies": {
+    "@ultimabase/http": "^0.1.0",
+    "@ultimabase/realtime": "^0.1.0",
+    "graphql": "^17.0.2",
+    "ultimabase": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@ultimabase/realtime": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/pg": "8.23.1",
+    "@types/ws": "8.18.2",
+    "@ultimabase/http": "0.1.0",
+    "@ultimabase/postgres": "0.1.0",
+    "@ultimabase/realtime": "0.1.0",
+    "graphql": "17.0.2",
+    "pg": "8.23.1",
+    "ultimabase": "0.1.0",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }

package/src/data-types.ts

@@ -0,0 +1,100 @@
+// The data types functions and json fields give (D-45, D-125), each name
+// given one shape, none named like a model.
+import type {
+	GraphQLInputObjectType,
+	GraphQLNamedType,
+	GraphQLObjectType,
+} from 'graphql'
+import { GraphQLEnumType } from 'graphql'
+import { Refused } from 'ultimabase'
+
+type Shaped<T> = {
+	readonly key: string
+	readonly owner: string
+	readonly type: T
+}
+
+/** The named types of functions and json fields, each given one shape. */
+export class DataTypes {
+	readonly #objects = new Map<string, Shaped<GraphQLObjectType>>()
+	readonly #inputs = new Map<string, Shaped<GraphQLInputObjectType>>()
+	readonly #enums = new Map<string, Shaped<GraphQLEnumType>>()
+	readonly #models: ReadonlySet<string>
+	/** Each named type, and the first function or field to give it. */
+	readonly owners: Map<string, string> = new Map()
+
+	constructor(models: Iterable<string>) {
+		this.#models = new Set(models)
+	}
+
+	object(
+		name: string,
+		key: string,
+		owner: string,
+		build: () => GraphQLObjectType,
+	): GraphQLObjectType {
+		return this.#shaped(this.#objects, name, key, owner, build)
+	}
+
+	input(
+		name: string,
+		key: string,
+		owner: string,
+		build: () => GraphQLInputObjectType,
+	): GraphQLInputObjectType {
+		return this.#shaped(this.#inputs, name, key, owner, build)
+	}
+
+	enum(
+		name: string,
+		values: readonly string[],
+		owner: string,
+		description?: string,
+	): GraphQLEnumType {
+		const build = () =>
+			new GraphQLEnumType({
+				name,
+				description,
+				values: Object.fromEntries(values.map((value) => [value, { value }])),
+			})
+		return this.#shaped(this.#enums, name, values.join(), owner, build)
+	}
+
+	/** The type named `name`, if one was given. */
+	named(name: string): GraphQLNamedType | undefined {
+		return (
+			this.#objects.get(name)?.type ??
+			this.#inputs.get(name)?.type ??
+			this.#enums.get(name)?.type
+		)
+	}
+
+	#shaped<T>(
+		cache: Map<string, Shaped<T>>,
+		name: string,
+		key: string,
+		owner: string,
+		build: () => T,
+	): T {
+		if (this.#models.has(name)) {
+			throw new Refused(`${owner}: the type ${name} is named like a model.`)
+		}
+		const known = cache.get(name)
+		const other = this.owners.get(name)
+		if (known === undefined && other !== undefined) {
+			throw new Refused(
+				`${other} and ${owner} give the type ${name} two shapes; name each once.`,
+			)
+		}
+		if (known === undefined) {
+			const type = build()
+			cache.set(name, { key, owner, type })
+			this.owners.set(name, owner)
+			return type
+		}
+		if (known.key === key) return known.type
+		throw new Refused(
+			`${known.owner} and ${owner} give the type ${name} two shapes; name each once.`,
+		)
+	}
+}

package/src/data.ts

@@ -0,0 +1,366 @@
+// A schema's GraphQL types, from its standard JSON Schema export (D-45,
+// D-109): what a function takes and returns as data, and a json field
+// (D-125). A schema given an id is one shared type; any other object or enum
+// is named from its path.
+import type { Node } from '@ultimabase/http/internal'
+import { isNode, jsonSchemaOf } from '@ultimabase/http/internal'
+import type {
+	GraphQLEnumType,
+	GraphQLFieldConfigArgumentMap,
+	GraphQLNullableInputType,
+	GraphQLNullableOutputType,
+	GraphQLNullableType,
+	GraphQLScalarType,
+} from 'graphql'
+import {
+	GraphQLBoolean,
+	GraphQLFloat,
+	GraphQLInputObjectType,
+	GraphQLInt,
+	GraphQLList,
+	GraphQLNonNull,
+	GraphQLObjectType,
+	GraphQLString,
+} from 'graphql'
+import type { Side } from './json-schema.ts'
+import { defsOf, exportOf } from './json-schema.ts'
+import { upper } from './names.ts'
+import type { Context } from './registry.ts'
+import { DateScalar, DateTime, JSONScalar } from './scalars.ts'
+import type { DataTypes } from './data-types.ts'
+import { Refused } from 'ultimabase'
+
+const reserved = new Set(['true', 'false', 'null'])
+const named = (value: string): boolean =>
+	/^[_A-Za-z][_0-9A-Za-z]*$/.test(value) && !value.startsWith('__')
+const isName = (value: unknown): value is string =>
+	typeof value === 'string' && named(value)
+const isValue = (value: unknown): value is string =>
+	isName(value) && !reserved.has(value)
+/** A node's description, as `.describe()` writes it (D-150). */
+const describedBy = (node: Node): string | undefined => {
+	const { description } = node
+	return typeof description === 'string' ? description : undefined
+}
+
+/** Where a node is: who a message names, a type's name, and the path. */
+export type Path = {
+	readonly owner: string
+	readonly name: string
+	/** `Input` under a shared input type: `AddressInput`, `AddressGeoInput`. */
+	readonly suffix: string
+	readonly at: string
+}
+
+/** Stops startup on a name GraphQL refuses. */
+export function checkName(name: string, where: string): string {
+	if (named(name)) return name
+	throw new Refused(`${where}: ${name} is not a GraphQL name.`)
+}
+
+type Leaf = GraphQLScalarType | GraphQLEnumType
+export type Typed<T> = { readonly type: T; readonly nullable: boolean }
+
+/** How one side builds its types, and the JSON Schema's shared ones. */
+interface Scope<T extends GraphQLNullableType> {
+	readonly side: Side
+	/** A json field's: `JSON` where a function's would stop startup (D-125). */
+	readonly lenient: boolean
+	readonly defs: Node
+	readonly types: DataTypes
+	readonly leaf: (type: Leaf) => T
+	readonly list: (of: Typed<T>) => T
+	readonly object: (node: Node, properties: Node, path: Path) => T
+}
+
+const union = (path: Path): Error =>
+	new Refused(
+		`${path.owner}: ${path.at} is a union, which GraphQL cannot type; keep one type, or one and null.`,
+	)
+
+/** `JSON` in a json field's types, or startup stops for a function's. */
+function untyped<T extends GraphQLNullableType>(
+	scope: Scope<T>,
+	nullable: boolean,
+	refused: () => Error,
+): Typed<T> {
+	if (!scope.lenient) throw refused()
+	return { type: scope.leaf(JSONScalar), nullable }
+}
+
+function refType<T extends GraphQLNullableType>(
+	ref: string,
+	path: Path,
+	scope: Scope<T>,
+): Typed<T> {
+	if (ref === '#') {
+		return untyped(
+			scope,
+			false,
+			() =>
+				new Refused(
+					`${path.owner}: ${path.at} refers to its own schema; name it with .meta({ id }).`,
+				),
+		)
+	}
+	const id = ref.startsWith('#/$defs/') ? ref.slice(8) : ''
+	const node = scope.defs[id]
+	if (!isNode(node)) {
+		return untyped(
+			scope,
+			false,
+			() =>
+				new Refused(`${path.owner}: ${path.at} refers to ${ref}, not a $defs.`),
+		)
+	}
+	if (!named(id)) {
+		return untyped(
+			scope,
+			false,
+			() =>
+				new Refused(
+					`${path.owner}: ${path.at} refers to ${id}, which is not a GraphQL name; name it with .meta({ id }).`,
+				),
+		)
+	}
+	const suffix = scope.side === 'input' ? 'Input' : ''
+	return dataType(node, { ...path, name: id, suffix }, scope)
+}
+
+function enumType(
+	node: Node,
+	values: readonly unknown[],
+	path: Path,
+	types: DataTypes,
+) {
+	const names = values.filter((value) => value !== null)
+	if (!names.every(isValue)) return GraphQLString
+	return types.enum(path.name, names, path.owner, describedBy(node))
+}
+
+function typeOf<T extends GraphQLNullableType>(
+	type: unknown,
+	node: Node,
+	path: Path,
+	scope: Scope<T>,
+): T {
+	const { const: only, enum: listed } = node
+	const values: readonly unknown[] =
+		only === undefined ? (Array.isArray(listed) ? listed : []) : [only]
+	if (type === 'boolean') return scope.leaf(GraphQLBoolean)
+	// A literal number is an `Int` when each of its values is whole.
+	if (type === 'integer' || type === 'number') {
+		const whole = values.length > 0 && values.every(Number.isInteger)
+		return scope.leaf(type === 'integer' || whole ? GraphQLInt : GraphQLFloat)
+	}
+	if (only !== undefined) return scope.leaf(GraphQLString)
+	if (values.length > 0)
+		return scope.leaf(enumType(node, values, path, scope.types))
+	if (type === 'string') {
+		const format = node['format']
+		return scope.leaf(
+			format === 'date-time'
+				? DateTime
+				: format === 'date'
+					? DateScalar
+					: GraphQLString,
+		)
+	}
+	if (type === 'array') {
+		const items = isNode(node['items']) ? node['items'] : {}
+		return scope.list(dataType(items, { ...path, at: `${path.at}[]` }, scope))
+	}
+	const { properties } = node
+	if (type === 'object' && isNode(properties)) {
+		const keys = Object.keys(properties)
+		// A json field's key GraphQL cannot name makes its object `JSON`.
+		const typed = !scope.lenient || keys.every(named)
+		if (keys.length > 0 && typed) return scope.object(node, properties, path)
+	}
+	return scope.leaf(JSONScalar)
+}
+
+/** A node's GraphQL type, and whether it accepts `null`. */
+function dataType<T extends GraphQLNullableType>(
+	node: Node,
+	path: Path,
+	scope: Scope<T>,
+): Typed<T> {
+	const ref = node['$ref']
+	if (typeof ref === 'string') return refType(ref, path, scope)
+	const variants: unknown = node['anyOf'] ?? node['oneOf']
+	if (Array.isArray(variants)) {
+		const others: readonly unknown[] = variants.filter(
+			(variant) => !isNode(variant) || variant['type'] !== 'null',
+		)
+		const [only] = others
+		if (others.length !== 1 || variants.length !== 2 || !isNode(only)) {
+			return untyped(scope, others.length < variants.length, () => union(path))
+		}
+		return { type: dataType(only, path, scope).type, nullable: true }
+	}
+	const listed: readonly unknown[] = Array.isArray(node['type'])
+		? node['type']
+		: [node['type']]
+	const types = listed.filter((type) => type !== undefined && type !== 'null')
+	const nullable = types.length < listed.length
+	if (types.length > 1) return untyped(scope, nullable, () => union(path))
+	return { type: typeOf(types[0], node, path, scope), nullable }
+}
+
+/** Each property's type, required when it always holds a value. */
+type Property<T extends GraphQLNullableType> = {
+	readonly type: T | GraphQLNonNull<T>
+	readonly description: string | undefined
+}
+
+function propertiesOf<T extends GraphQLNullableType>(
+	node: Node,
+	properties: Node,
+	path: Path,
+	scope: Scope<T>,
+): (readonly [string, Property<T>])[] {
+	const listed: readonly unknown[] = Array.isArray(node['required'])
+		? node['required']
+		: []
+	return Object.entries(properties).map(([key, value]) => {
+		const at = `${path.at}.${key}`
+		checkName(key, `${path.owner}: ${at}`)
+		const child = { ...path, name: `${path.name}${upper(key)}`, at }
+		const property = isNode(value) ? value : {}
+		const { type, nullable } = dataType(property, child, scope)
+		// A default fills an input the client leaves out.
+		const defaulted =
+			scope.side === 'input' && property['default'] !== undefined
+		const required = listed.includes(key) && !nullable && !defaulted
+		return [
+			key,
+			{
+				type: required ? new GraphQLNonNull(type) : type,
+				description: describedBy(property),
+			},
+		]
+	})
+}
+
+/** An object type's fields, read when the schema is built. */
+const fieldsOf =
+	<T extends GraphQLNullableType>(
+		node: Node,
+		properties: Node,
+		path: Path,
+		scope: Scope<T>,
+	) =>
+	(): { [key: string]: Property<T> } =>
+		Object.fromEntries(propertiesOf(node, properties, path, scope))
+
+const listOf = <T extends GraphQLNullableType>({ type, nullable }: Typed<T>) =>
+	new GraphQLList(nullable ? type : new GraphQLNonNull(type))
+
+/** Each side's scope for `root`'s types. */
+function scopesOf(root: Node, types: DataTypes, lenient: boolean) {
+	const shared = {
+		lenient,
+		defs: defsOf(root),
+		types,
+		leaf: (type: Leaf) => type,
+	}
+	const output: Scope<GraphQLNullableOutputType> = {
+		...shared,
+		side: 'output',
+		list: listOf,
+		object: (node, properties, path) =>
+			types.object(
+				path.name,
+				JSON.stringify(node),
+				path.owner,
+				() =>
+					new GraphQLObjectType<unknown, Context>({
+						name: path.name,
+						description: describedBy(node),
+						fields: fieldsOf(node, properties, path, output),
+					}),
+			),
+	}
+	const input: Scope<GraphQLNullableInputType> = {
+		...shared,
+		side: 'input',
+		list: listOf,
+		object: (node, properties, path) => {
+			const name = `${path.name}${path.suffix}`
+			return types.input(
+				name,
+				JSON.stringify(node),
+				path.owner,
+				() =>
+					new GraphQLInputObjectType({
+						name,
+						description: describedBy(node),
+						fields: fieldsOf(node, properties, path, input),
+					}),
+			)
+		},
+	}
+	return { output, input }
+}
+
+/** An output schema's type, nullable when its JSON Schema accepts `null`. */
+export function outputData(
+	schema: object,
+	path: Path,
+	types: DataTypes,
+): Typed<GraphQLNullableOutputType> {
+	const root = jsonSchemaOf(schema, 'output', `${path.owner}: ${path.at}`)
+	return dataType(root, path, scopesOf(root, types, false).output)
+}
+
+/**
+ * An object input's properties as arguments, `flat`; any other input as one
+ * `input` argument (D-109).
+ */
+export function inputArgs(
+	schema: object,
+	path: Path,
+	types: DataTypes,
+): { readonly args: GraphQLFieldConfigArgumentMap; readonly flat: boolean } {
+	const root = jsonSchemaOf(schema, 'input', `${path.owner}: ${path.at}`)
+	const scope = scopesOf(root, types, false).input
+	const ref = root['$ref']
+	const object = typeof ref === 'string' ? scope.defs[ref.slice(8)] : root
+	const properties = isNode(object) ? object['properties'] : undefined
+	if (isNode(object) && object['type'] === 'object' && isNode(properties)) {
+		const args = propertiesOf(object, properties, path, scope)
+		return { args: Object.fromEntries(args), flat: true }
+	}
+	const { type, nullable } = dataType(root, path, scope)
+	const description = describedBy(root)
+	return {
+		args: {
+			input: { type: nullable ? type : new GraphQLNonNull(type), description },
+		},
+		flat: false,
+	}
+}
+
+/**
+ * A json field's type when read, from its schema's output side (D-125);
+ * `undefined` when the schema has no JSON Schema export.
+ */
+export function fieldOutput(
+	schema: object,
+	path: Path,
+	types: DataTypes,
+): Typed<GraphQLNullableOutputType> | undefined {
+	const root = exportOf(schema, 'output')
+	return root && dataType(root, path, scopesOf(root, types, true).output)
+}
+
+/** A json field's type when written, from its schema's input side. */
+export function fieldInput(
+	schema: object,
+	path: Path,
+	types: DataTypes,
+): Typed<GraphQLNullableInputType> | undefined {
+	const root = exportOf(schema, 'input')
+	return root && dataType(root, path, scopesOf(root, types, true).input)
+}

package/src/depth.ts

@@ -0,0 +1,98 @@
+// The depth limits (D-107): a document nested deeper than `maxDepth` is
+// refused before it runs. `__schema` and `__type` do not count, since the
+// standard introspection query is about 12 levels deep; they have their own
+// limit, graphql-js's, measured here once per fragment.
+import type {
+	ASTVisitor,
+	FieldNode,
+	SelectionNode,
+	SelectionSetNode,
+	ValidationContext,
+	ValidationRule,
+} from 'graphql'
+import { GraphQLError, Kind } from 'graphql'
+
+const introspection = new Set(['__schema', '__type'])
+
+/** A field's depth, given the depth of what it selects. */
+type Weigh = (field: FieldNode, below: () => number) => number
+
+/** The deepest path under a selection set, each fragment measured once. */
+function measurer(
+	context: ValidationContext,
+	weigh: Weigh,
+): (set: SelectionSetNode | undefined) => number {
+	// One being measured counts 0, which only a cycle meets, and
+	// `NoFragmentCyclesRule` refuses a cycle.
+	const fragments = new Map<string, number>()
+	const depth = (set: SelectionSetNode | undefined): number => {
+		let deepest = 0
+		for (const selection of set?.selections ?? []) {
+			deepest = Math.max(deepest, depthOf(selection))
+		}
+		return deepest
+	}
+	const depthOf = (selection: SelectionNode): number => {
+		if (selection.kind === Kind.FIELD) {
+			return weigh(selection, () => depth(selection.selectionSet))
+		}
+		if (selection.kind === Kind.INLINE_FRAGMENT) {
+			return depth(selection.selectionSet)
+		}
+		const name = selection.name.value
+		const known = fragments.get(name)
+		if (known !== undefined) return known
+		fragments.set(name, 0)
+		const measured = depth(context.getFragment(name)?.selectionSet)
+		fragments.set(name, measured)
+		return measured
+	}
+	return depth
+}
+
+/** The validation rule that refuses a document deeper than `maxDepth`. */
+export function depthRule(maxDepth: number): ValidationRule {
+	return (context: ValidationContext): ASTVisitor => {
+		const depth = measurer(context, (field, below) =>
+			introspection.has(field.name.value) ? 0 : 1 + below(),
+		)
+		return {
+			OperationDefinition: (node) => {
+				const measured = depth(node.selectionSet)
+				if (measured <= maxDepth) return
+				context.reportError(
+					new GraphQLError(
+						`The document is nested ${measured} levels deep; the most is ${maxDepth}.`,
+						{ nodes: node },
+					),
+				)
+			},
+		}
+	}
+}
+
+// The lists graphql-js's `MaxIntrospectionDepthRule` counts, and how many
+// nested ones it refuses. Its own walk visits a fragment once per path, so a
+// fragment spreading the previous one twice costs 2^n visits.
+const lists = new Set(['fields', 'interfaces', 'possibleTypes', 'inputFields'])
+const maxLists = 3
+
+/** `MaxIntrospectionDepthRule`, measuring each fragment once. */
+export const introspectionDepthRule: ValidationRule = (context) => {
+	const depth = measurer(
+		context,
+		(field, below) => (lists.has(field.name.value) ? 1 : 0) + below(),
+	)
+	return {
+		Field: (node) => {
+			if (!introspection.has(node.name.value)) return undefined
+			if (depth(node.selectionSet) < maxLists) return undefined
+			context.reportError(
+				new GraphQLError('Maximum introspection depth exceeded', {
+					nodes: [node],
+				}),
+			)
+			return false
+		},
+	}
+}

package/src/errors.ts

@@ -0,0 +1,48 @@
+// Errors as D-106 sends them, over GraphQL (D-107): a `PublicError` with its
+// code and details, any other error masked and logged with its id, and
+// graphql-js's own without the values they refused.
+import { randomUUID } from 'node:crypto'
+import { GraphQLError } from 'graphql'
+import type { Logger } from 'ultimabase'
+import { PublicError } from 'ultimabase'
+
+type Format = (error: Readonly<GraphQLError | Error>) => GraphQLError | Error
+
+/** graphql-js's message without the value it refused, a password perhaps. */
+function unvalued(error: Readonly<GraphQLError>): GraphQLError {
+	const { message, nodes, path, extensions } = error
+	const reason = message.replace(
+		/[,;]? [Ff]ound: [\s\S]*$|(?<= cannot represent [^:]*): [\s\S]*$/,
+		'',
+	)
+	if (reason === message) return error
+	const ended = /[.?]$/.test(reason) ? reason : `${reason}.`
+	return new GraphQLError(ended, { nodes, path, extensions })
+}
+
+/** `graphql-http`'s `formatError`: what a client sees of each error. */
+export function formatter(logger: Logger): Format {
+	return (error) => {
+		// A request `graphql-http` could not read, or a document GraphQL
+		// refused: their messages are written for the client.
+		if (!(error instanceof GraphQLError)) return error
+		const original = error.originalError
+		if (original === undefined || original instanceof GraphQLError) {
+			return unvalued(error)
+		}
+		const at = { nodes: error.nodes, path: error.path }
+		if (original instanceof PublicError) {
+			const { code, details } = original
+			return new GraphQLError(original.message, {
+				...at,
+				extensions: details === undefined ? { code } : { code, details },
+			})
+		}
+		const correlationId = randomUUID()
+		logger.error({ correlationId, err: original }, 'A GraphQL field failed.')
+		return new GraphQLError('Internal error.', {
+			...at,
+			extensions: { code: 'INTERNAL', correlationId },
+		})
+	}
+}