@ultimabase/graphql 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @ultimabase/graphql
+
+## 0.1.1
+
+### Patch Changes
+
+- The published starter starts: `ultimabase dev` runs `dist/serve.js`, and `@ultimabase/realtime`, which `@ultimabase/graphql` and `@ultimabase/rest` import, is a required peer the starter lists.
+- Updated dependencies
+  - ultimabase@0.1.1
+  - @ultimabase/http@0.1.1
+  - @ultimabase/realtime@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- 0e885c4: The first release: the kernel, its adapters, transports and plugins, the testing helpers and the starter.
+
+### Patch Changes
+
+- Updated dependencies [0e885c4]
+  - @ultimabase/http@0.1.0
+  - @ultimabase/realtime@0.1.0
+  - ultimabase@0.1.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/graphql
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A GraphQL API generated from the models and the functions, served by `@ultimabase/http`. Each request runs as its caller, under the models' access rules, within limits on depth and rows.
+
+Documentation: [GraphQL](https://ultimabase.dev/docs/graphql).

package/dist/data-types.d.ts

@@ -0,0 +1,15 @@
+import type { GraphQLInputObjectType, GraphQLNamedType, GraphQLObjectType } from 'graphql';
+import { GraphQLEnumType } from 'graphql';
+/** The named types of functions and json fields, each given one shape. */
+export declare class DataTypes {
+    #private;
+    /** Each named type, and the first function or field to give it. */
+    readonly owners: Map<string, string>;
+    constructor(models: Iterable<string>);
+    object(name: string, key: string, owner: string, build: () => GraphQLObjectType): GraphQLObjectType;
+    input(name: string, key: string, owner: string, build: () => GraphQLInputObjectType): GraphQLInputObjectType;
+    enum(name: string, values: readonly string[], owner: string, description?: string): GraphQLEnumType;
+    /** The type named `name`, if one was given. */
+    named(name: string): GraphQLNamedType | undefined;
+}
+//# sourceMappingURL=data-types.d.ts.map

package/dist/data-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-types.d.ts","sourceRoot":"","sources":["../src/data-types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AASzC,0EAA0E;AAC1E,qBAAa,SAAS;;IAKrB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAY;IAEhD,YAAY,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EAEnC;IAED,MAAM,CACL,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,iBAAiB,GAC5B,iBAAiB,CAEnB;IAED,KAAK,CACJ,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,sBAAsB,GACjC,sBAAsB,CAExB;IAED,IAAI,CACH,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,KAAK,EAAE,MAAM,EACb,WAAW,CAAC,EAAE,MAAM,GAClB,eAAe,CAQjB;IAED,+CAA+C;IAC/C,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAMhD;CA8BD"}

package/dist/data-types.js

@@ -0,0 +1,53 @@
+import { GraphQLEnumType } from 'graphql';
+import { Refused } from 'ultimabase';
+/** The named types of functions and json fields, each given one shape. */
+export class DataTypes {
+    #objects = new Map();
+    #inputs = new Map();
+    #enums = new Map();
+    #models;
+    /** Each named type, and the first function or field to give it. */
+    owners = new Map();
+    constructor(models) {
+        this.#models = new Set(models);
+    }
+    object(name, key, owner, build) {
+        return this.#shaped(this.#objects, name, key, owner, build);
+    }
+    input(name, key, owner, build) {
+        return this.#shaped(this.#inputs, name, key, owner, build);
+    }
+    enum(name, values, owner, description) {
+        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) {
+        return (this.#objects.get(name)?.type ??
+            this.#inputs.get(name)?.type ??
+            this.#enums.get(name)?.type);
+    }
+    #shaped(cache, name, key, owner, build) {
+        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/dist/data.d.ts

@@ -0,0 +1,34 @@
+import type { GraphQLFieldConfigArgumentMap, GraphQLNullableInputType, GraphQLNullableOutputType } from 'graphql';
+import type { DataTypes } from './data-types.ts';
+/** 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 declare function checkName(name: string, where: string): string;
+export type Typed<T> = {
+    readonly type: T;
+    readonly nullable: boolean;
+};
+/** An output schema's type, nullable when its JSON Schema accepts `null`. */
+export declare function outputData(schema: object, path: Path, types: DataTypes): Typed<GraphQLNullableOutputType>;
+/**
+ * An object input's properties as arguments, `flat`; any other input as one
+ * `input` argument (D-109).
+ */
+export declare function inputArgs(schema: object, path: Path, types: DataTypes): {
+    readonly args: GraphQLFieldConfigArgumentMap;
+    readonly flat: boolean;
+};
+/**
+ * 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 declare function fieldOutput(schema: object, path: Path, types: DataTypes): Typed<GraphQLNullableOutputType> | undefined;
+/** A json field's type when written, from its schema's input side. */
+export declare function fieldInput(schema: object, path: Path, types: DataTypes): Typed<GraphQLNullableInputType> | undefined;
+//# sourceMappingURL=data.d.ts.map

package/dist/data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../src/data.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAEX,6BAA6B,EAC7B,wBAAwB,EACxB,yBAAyB,EAGzB,MAAM,SAAS,CAAA;AAgBhB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAgBhD,yEAAyE;AACzE,MAAM,MAAM,IAAI,GAAG;IAClB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACnB,CAAA;AAED,+CAA+C;AAC/C,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAG7D;AAGD,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAA;AAqPvE,6EAA6E;AAC7E,wBAAgB,UAAU,CACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,GACd,KAAK,CAAC,yBAAyB,CAAC,CAGlC;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,GACd;IAAE,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAkB1E;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,GACd,KAAK,CAAC,yBAAyB,CAAC,GAAG,SAAS,CAG9C;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,SAAS,GACd,KAAK,CAAC,wBAAwB,CAAC,GAAG,SAAS,CAG7C"}

package/dist/data.js

@@ -0,0 +1,207 @@
+import { isNode, jsonSchemaOf } from '@ultimabase/http/internal';
+import { GraphQLBoolean, GraphQLFloat, GraphQLInputObjectType, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLString, } from 'graphql';
+import { defsOf, exportOf } from './json-schema.js';
+import { upper } from './names.js';
+import { DateScalar, DateTime, JSONScalar } from './scalars.js';
+import { Refused } from 'ultimabase';
+const reserved = new Set(['true', 'false', 'null']);
+const named = (value) => /^[_A-Za-z][_0-9A-Za-z]*$/.test(value) && !value.startsWith('__');
+const isName = (value) => typeof value === 'string' && named(value);
+const isValue = (value) => isName(value) && !reserved.has(value);
+/** A node's description, as `.describe()` writes it (D-150). */
+const describedBy = (node) => {
+    const { description } = node;
+    return typeof description === 'string' ? description : undefined;
+};
+/** Stops startup on a name GraphQL refuses. */
+export function checkName(name, where) {
+    if (named(name))
+        return name;
+    throw new Refused(`${where}: ${name} is not a GraphQL name.`);
+}
+const union = (path) => 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(scope, nullable, refused) {
+    if (!scope.lenient)
+        throw refused();
+    return { type: scope.leaf(JSONScalar), nullable };
+}
+function refType(ref, path, scope) {
+    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, values, path, types) {
+    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(type, node, path, scope) {
+    const { const: only, enum: listed } = node;
+    const values = 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(node, path, scope) {
+    const ref = node['$ref'];
+    if (typeof ref === 'string')
+        return refType(ref, path, scope);
+    const variants = node['anyOf'] ?? node['oneOf'];
+    if (Array.isArray(variants)) {
+        const others = 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 = 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 };
+}
+function propertiesOf(node, properties, path, scope) {
+    const listed = 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 = (node, properties, path, scope) => () => Object.fromEntries(propertiesOf(node, properties, path, scope));
+const listOf = ({ type, nullable }) => new GraphQLList(nullable ? type : new GraphQLNonNull(type));
+/** Each side's scope for `root`'s types. */
+function scopesOf(root, types, lenient) {
+    const shared = {
+        lenient,
+        defs: defsOf(root),
+        types,
+        leaf: (type) => type,
+    };
+    const output = {
+        ...shared,
+        side: 'output',
+        list: listOf,
+        object: (node, properties, path) => types.object(path.name, JSON.stringify(node), path.owner, () => new GraphQLObjectType({
+            name: path.name,
+            description: describedBy(node),
+            fields: fieldsOf(node, properties, path, output),
+        })),
+    };
+    const input = {
+        ...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, path, types) {
+    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, path, types) {
+    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, path, types) {
+    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, path, types) {
+    const root = exportOf(schema, 'input');
+    return root && dataType(root, path, scopesOf(root, types, true).input);
+}

package/dist/depth.d.ts

@@ -0,0 +1,6 @@
+import type { ValidationRule } from 'graphql';
+/** The validation rule that refuses a document deeper than `maxDepth`. */
+export declare function depthRule(maxDepth: number): ValidationRule;
+/** `MaxIntrospectionDepthRule`, measuring each fragment once. */
+export declare const introspectionDepthRule: ValidationRule;
+//# sourceMappingURL=depth.d.ts.map

package/dist/depth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"depth.d.ts","sourceRoot":"","sources":["../src/depth.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAMX,cAAc,EACd,MAAM,SAAS,CAAA;AAyChB,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAkB1D;AAQD,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,EAAE,cAiBpC,CAAA"}

package/dist/depth.js

@@ -0,0 +1,67 @@
+import { GraphQLError, Kind } from 'graphql';
+const introspection = new Set(['__schema', '__type']);
+/** The deepest path under a selection set, each fragment measured once. */
+function measurer(context, weigh) {
+    // One being measured counts 0, which only a cycle meets, and
+    // `NoFragmentCyclesRule` refuses a cycle.
+    const fragments = new Map();
+    const depth = (set) => {
+        let deepest = 0;
+        for (const selection of set?.selections ?? []) {
+            deepest = Math.max(deepest, depthOf(selection));
+        }
+        return deepest;
+    };
+    const depthOf = (selection) => {
+        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) {
+    return (context) => {
+        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 = (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/dist/errors.d.ts

@@ -0,0 +1,7 @@
+import { GraphQLError } from 'graphql';
+import type { Logger } from 'ultimabase';
+type Format = (error: Readonly<GraphQLError | Error>) => GraphQLError | Error;
+/** `graphql-http`'s `formatError`: what a client sees of each error. */
+export declare function formatter(logger: Logger): Format;
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAGxC,KAAK,MAAM,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,YAAY,GAAG,KAAK,CAAC,KAAK,YAAY,GAAG,KAAK,CAAA;AAc7E,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAwBhD"}

package/dist/errors.js

@@ -0,0 +1,42 @@
+// 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 { PublicError } from 'ultimabase';
+/** graphql-js's message without the value it refused, a password perhaps. */
+function unvalued(error) {
+    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) {
+    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 },
+        });
+    };
+}

package/dist/functions.d.ts

@@ -0,0 +1,28 @@
+import type { GraphQLFieldConfig, GraphQLNamedType } from 'graphql';
+import type { ExposedFunction } from 'ultimabase';
+import type { Args, Context, Registry } from './registry.ts';
+import type { Read } from './rows.ts';
+/** A function's key of `.with` (D-109): its field's name, or hidden. */
+export type GraphqlFunctionWith = {
+    readonly name?: string;
+} | false;
+export type Field = GraphQLFieldConfig<unknown, Context, Args>;
+/** A function's root field, and the function that gives it. */
+export type RootField = {
+    readonly query: boolean;
+    readonly name: string;
+    readonly owner: string;
+    readonly field: Field;
+};
+/** The functions' root fields, and what each reads (D-109). */
+export declare function functionFields(registry: Registry, functions: readonly ExposedFunction<GraphqlFunctionWith>[], take: number, live: (owner: string) => boolean): {
+    readonly fields: readonly RootField[];
+    /** The live functions' subscriptions, named as their fields (D-154). */
+    readonly subscriptions: {
+        readonly [name: string]: Field;
+    };
+    readonly reads: ReadonlyMap<string, ReadonlyMap<string, Read>>;
+    readonly owners: ReadonlyMap<string, string>;
+    readonly named: (name: string) => GraphQLNamedType | undefined;
+};
+//# sourceMappingURL=functions.d.ts.map

package/dist/functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../src/functions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACX,kBAAkB,EAClB,gBAAgB,EAGhB,MAAM,SAAS,CAAA;AAQhB,OAAO,KAAK,EACX,eAAe,EAIf,MAAM,YAAY,CAAA;AASnB,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAI5D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAErC,wEAAwE;AACxE,MAAM,MAAM,mBAAmB,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAAA;AAEpE,MAAM,MAAM,KAAK,GAAG,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAA;AAE9D,+DAA+D;AAC/D,MAAM,MAAM,SAAS,GAAG;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CACrB,CAAA;AAwMD,+DAA+D;AAC/D,wBAAgB,cAAc,CAC7B,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,eAAe,CAAC,mBAAmB,CAAC,EAAE,EAC1D,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAC9B;IACF,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IACrC,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE;QAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,CAAA;KAAE,CAAA;IAC1D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;IAC9D,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5C,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,gBAAgB,GAAG,SAAS,CAAA;CAC9D,CA8BA"}