@znight/graphql 0.2.0 → 0.2.1

package/dist/{plugin-BdBxr5NQ.mjs → plugin-CR_wVfRU.mjs}

@@ -2,7 +2,7 @@ import { a as SPECIFIED_SCALARS, o as isGraphQLName, r as RESERVED_ENUM_VALUES,
 import { ErrorCode, ZnightError, displayName, resolveOptions } from "@znight/core";
 import DataLoader from "dataloader";
 import { EventChannel, HttpResponse, HttpTokens, ValidationException, isHttpException, isThenable, parseByteSize, parseMediaType } from "@znight/http";
-import { AbortedGraphQLExecutionError, GraphQLBoolean, GraphQLEnumType, GraphQLError, GraphQLFloat, GraphQLID, GraphQLInputObjectType, GraphQLInt, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLScalarType, GraphQLSchema, GraphQLString, GraphQLUnionType, Kind, NoSchemaIntrospectionCustomRule, createSourceEventStream, execute, executeSubscriptionEvent, getNamedType, isObjectType, parse, printSchema, specifiedRules, validate, validateSchema, validateSubscriptionArgs, valueFromASTUntyped } from "graphql";
+import { AbortedGraphQLExecutionError, GraphQLBoolean, GraphQLEnumType, GraphQLError, GraphQLFloat, GraphQLID, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLScalarType, GraphQLSchema, GraphQLString, GraphQLUnionType, Kind, NoSchemaIntrospectionCustomRule, createSourceEventStream, execute, executeSubscriptionEvent, getNamedType, isObjectType, parse, printSchema, specifiedRules, validate, validateSchema, validateSubscriptionArgs, valueFromASTUntyped } from "graphql";
 import { createHash, randomUUID } from "node:crypto";
 // src/errors.ts
 /**
@@ -1264,7 +1264,7 @@ var GraphQLExecutor = class {
 		this.#logger.error(`GraphQLPlugin: ${message}`, { err: error });
 	}
 };
-function noop() {}
+function noop$1() {}
 function badRequest(message) {
 	return new Rejection(400, [requestError(message, GraphQLErrorCode.BadRequest)], void 0);
 }
@@ -1371,7 +1371,7 @@ var SubscriptionStream = class {
 			signal.addEventListener("abort", this.#onAbort, { once: true });
 		}
 		const first = init.run(() => this.#read());
-		first.catch(noop);
+		first.catch(noop$1);
 		this.#first = first;
 		if (signal?.aborted === true) this.return();
 	}
@@ -1430,7 +1430,7 @@ var SubscriptionStream = class {
 		const reading = this.#reading > 0;
 		try {
 			const returned = Promise.resolve(this.#init.source.return?.());
-			if (reading) returned.catch(noop);
+			if (reading) returned.catch(noop$1);
 			else await returned;
 		} catch {}
 		return DONE$1;
@@ -1460,6 +1460,7 @@ const KEYS = /* @__PURE__ */ new Set([
 	"http",
 	"guards",
 	"errorMappers",
+	"resultMappers",
 	"exposeErrors",
 	"introspection",
 	"graphiql",
@@ -1567,6 +1568,7 @@ function resolveGraphQLOptions(options, env = process.env) {
 		http,
 		guards: refs("guards", options["guards"], "canResolve"),
 		errorMappers: refs("errorMappers", options["errorMappers"], "map"),
+		resultMappers: refs("resultMappers", options["resultMappers"], "toResult"),
 		exposeErrors: boolean("exposeErrors", options["exposeErrors"], false),
 		introspection: boolean("introspection", options["introspection"], nodeEnv !== "production"),
 		graphiql: boolean("graphiql", options["graphiql"], nodeEnv === "development"),
@@ -1599,6 +1601,13 @@ function fieldFunctions(options, normalizers, binding, coordinate, field, parent
 	const target = options.resolver(binding, coordinate);
 	const guards = [...globalGuardsApply(binding) ? options.globalGuards : [], ...binding.guards.map((token) => options.guard(token, coordinate))];
 	const normalize = field.args === void 0 ? void 0 : normalizers.args(field.args);
+	const recover = options.results?.(field, coordinate);
+	const route = guards.length === 0 && recover === void 0 ? void 0 : Object.freeze({
+		meta: binding.meta,
+		coordinate
+	});
+	const parentType = parent.name;
+	const fieldName = field.name;
 	let resolve;
 	if (guards.length === 0) {
 		if (target.token === void 0) {
@@ -1615,12 +1624,6 @@ function fieldFunctions(options, normalizers, binding, coordinate, field, parent
 			};
 		}
 	} else {
-		const route = Object.freeze({
-			meta: binding.meta,
-			coordinate
-		});
-		const parentType = parent.name;
-		const fieldName = field.name;
 		const forbidden = () => {
 			throw new GraphQLException(`Not allowed to resolve ${coordinate}`, { code: GraphQLErrorCode.Forbidden });
 		};
@@ -1637,7 +1640,9 @@ function fieldFunctions(options, normalizers, binding, coordinate, field, parent
 			return allowed.then((ok) => ok ? call() : forbidden());
 		};
 	}
-	if (binding.operation === "subscription") return {
+	const subscription = binding.operation === "subscription";
+	if (recover !== void 0) resolve = withResults(resolve, recover, route, parentType, fieldName, subscription);
+	if (subscription) return {
 		subscribe: resolve,
 		resolve: identity$1
 	};
@@ -1646,6 +1651,34 @@ function fieldFunctions(options, normalizers, binding, coordinate, field, parent
 function identity$1(payload) {
 	return payload;
 }
+/**
+* The resolve function of a field that carries results (RFC 0008): errors of the whole pipeline
+* (guards, null handling, `invoke`), thrown or rejected, go through `recover`. Synchronous results
+* stay synchronous; a promise gets one rejection handler. For a subscription, a value is a source
+* stream of that single event.
+*/
+function withResults(resolve, recover, route, parentType, fieldName, subscription) {
+	const fail = (error, p, a, c, i) => {
+		const value = recover(error, new FieldContext(route, c, parentType, fieldName, a, p, i));
+		return subscription ? once(value) : value;
+	};
+	return (p, a, c, i) => {
+		let result;
+		try {
+			result = resolve(p, a, c, i);
+		} catch (error) {
+			return fail(error, p, a, c, i);
+		}
+		return isThenable(result) ? recoverAsync(result, fail, p, a, c, i) : result;
+	};
+}
+function recoverAsync(result, fail, p, a, c, i) {
+	return Promise.resolve(result).then(void 0, (error) => fail(error, p, a, c, i));
+}
+/** A source event stream of one event. */
+async function* once(value) {
+	yield value;
+}
 /** Runs guards in order, synchronously until one returns a promise. */
 function runGuards(container, guards, ctx, start = 0) {
 	for (let index = start; index < guards.length; index++) {
@@ -1830,12 +1863,14 @@ function builtinScalar(name) {
 * `parseValue` → `coerceInputValue`, `parseLiteral` → `coerceInputLiteral` (default: `parseValue`
 * of the literal's JSON value). The definition's methods are called on the definition.
 */
-function definitionScalar(name, definition) {
+function definitionScalar(name, definition, overrides = {}) {
 	const parseLiteral = definition.parseLiteral;
+	const description = "description" in overrides ? overrides.description : definition.description;
+	const specifiedByURL = "specifiedByURL" in overrides ? overrides.specifiedByURL : definition.specifiedByURL;
 	return new GraphQLScalarType({
 		name,
-		...definition.description === void 0 ? {} : { description: definition.description },
-		...definition.specifiedByURL === void 0 ? {} : { specifiedByURL: definition.specifiedByURL },
+		...description === void 0 ? {} : { description },
+		...specifiedByURL === void 0 ? {} : { specifiedByURL },
 		coerceOutputValue: (value) => definition.serialize(value),
 		coerceInputValue: (value) => definition.parseValue(value),
 		coerceInputLiteral: parseLiteral === void 0 ? (node) => definition.parseValue(valueFromASTUntyped(node)) : (node) => parseLiteral.call(definition, node)
@@ -1861,6 +1896,7 @@ const INPUT_KINDS = /* @__PURE__ */ new Set([
 ]);
 const OUTPUT_KINDS = /* @__PURE__ */ new Set([
 	"object",
+	"interface",
 	"enum",
 	"scalar",
 	"union"
@@ -1940,7 +1976,10 @@ function checkGraphQLSection(section) {
 		if (!isRecord(type) || typeof type["name"] !== "string") continue;
 		const name = type["name"];
 		switch (type["kind"]) {
-			case "object": {
+			case "object":
+			case "interface": {
+				const isInterface = type["kind"] === "interface";
+				checkInterfaces(name, type["interfaces"], kinds, problems);
 				const fields = type["fields"];
 				if (!Array.isArray(fields) || fields.length === 0) {
 					problems.push(`${name}: fields must be a non-empty array`);
@@ -1958,7 +1997,13 @@ function checkGraphQLSection(section) {
 					seen.add(field["name"]);
 					checkRef(coordinate, field["type"], OUTPUT_KINDS, "output");
 					if (field["args"] !== void 0) checkInputValues(`${coordinate} arguments`, field["args"], false);
-					if (field["resolver"] !== void 0) checkBinding(coordinate, field["resolver"], problems);
+					if (field["resolver"] === void 0) continue;
+					if (isInterface) problems.push(`${coordinate}: interface fields have no resolver (bind it on the object types)`);
+					else checkBinding(coordinate, field["resolver"], problems);
+				}
+				if (isInterface) {
+					const implementations = types.filter((other) => isRecord(other) && other["kind"] === "object" && Array.isArray(other["interfaces"]) && other["interfaces"].includes(name));
+					checkDiscriminator(name, type["discriminator"], implementations.map((other) => other["name"]), problems);
 				}
 				break;
 			}
@@ -2002,6 +2047,8 @@ function checkGraphQLSection(section) {
 						if (scalar.name !== name) problems.push(`the scalar ${name} is implemented by the graphql-js scalar ${scalar.name} (names must match)`);
 					} else if (!isRecord(scalar) || typeof scalar["serialize"] !== "function" || typeof scalar["parseValue"] !== "function" || scalar["parseLiteral"] !== void 0 && typeof scalar["parseLiteral"] !== "function") problems.push(`the scalar ${name} needs a definition { serialize, parseValue, parseLiteral? } or a GraphQLScalarType (received ${show(scalar)})`);
 				}
+				for (const key of ["description", "specifiedByURL"]) if (type[key] !== void 0 && typeof type[key] !== "string") problems.push(`${name}: ${key} must be a string`);
+				if (type["sdl"] !== void 0 && type["sdl"] !== true) problems.push(`${name}: sdl must be true when present`);
 				break;
 			default: problems.push(`${name}: unknown kind ${show(type["kind"])}`);
 		}
@@ -2010,6 +2057,15 @@ function checkGraphQLSection(section) {
 	checkGroups(section["groups"], problems);
 	return problems;
 }
+/** `interfaces` of an object or interface type: absent, or interface type names. */
+function checkInterfaces(name, interfaces, kinds, problems) {
+	if (interfaces === void 0) return;
+	if (!Array.isArray(interfaces)) {
+		problems.push(`${name}: interfaces must be an array of interface type names (received ${show(interfaces)})`);
+		return;
+	}
+	for (const entry of interfaces) if (typeof entry !== "string" || kinds.get(entry) !== "interface") problems.push(`${name}: ${show(entry)} is not an interface type`);
+}
 function checkBinding(coordinate, binding, problems) {
 	if (!isRecord(binding)) {
 		problems.push(`${coordinate}: resolver must be an object (received ${show(binding)})`);
@@ -2094,7 +2150,7 @@ function checkGroups(groups, problems) {
 function invalidSchema(problems) {
 	throw new ZnightError(ErrorCode.InvalidGraphQLSetup, `GraphQLPlugin: invalid GraphQL schema (metadata.extensions.graphql), ${problems.length} ${problems.length === 1 ? "problem" : "problems"}:\n${problems.map((problem) => `  - ${problem}`).join("\n")}`, { hints: ["Regenerate the metadata with the @znight/graphql version the application runs (znight generate)", "Hand-written metadata must follow GraphQLMetadata (@znight/graphql, RFC 0005 §7.1)"] });
 }
-/** A union's `resolveType`, from its discriminator: data read once, at boot. */
+/** The `resolveType` of a union or an interface, from its discriminator: data read once, at boot. */
 function typeResolver(discriminator) {
 	switch (discriminator.by) {
 		case "property": {
@@ -2153,7 +2209,7 @@ function buildGraphQLSchema(section, functions) {
 			...field.deprecationReason === void 0 ? {} : { deprecationReason: field.deprecationReason },
 			...field.args === void 0 || field.args.length === 0 ? {} : { args: Object.fromEntries(field.args.map((arg) => [arg.name, inputValue(arg)])) }
 		};
-		if (field.resolver === void 0) return config;
+		if (field.resolver === void 0 || type.kind === "interface") return config;
 		const resolved = functions(field.resolver, `${type.name}.${field.name}`, field, type);
 		return {
 			...config,
@@ -2189,8 +2245,16 @@ function createType(type, fieldConfig, inputValue, lookup) {
 		case "object": return new GraphQLObjectType({
 			name: type.name,
 			...description,
+			...interfacesOf(type, lookup),
 			fields: () => Object.fromEntries(type.fields.map((field) => [field.name, fieldConfig(type, field)]))
 		});
+		case "interface": return new GraphQLInterfaceType({
+			name: type.name,
+			...description,
+			...interfacesOf(type, lookup),
+			fields: () => Object.fromEntries(type.fields.map((field) => [field.name, fieldConfig(type, field)])),
+			resolveType: typeResolver(type.discriminator)
+		});
 		case "input": return new GraphQLInputObjectType({
 			name: type.name,
 			...description,
@@ -2213,10 +2277,153 @@ function createType(type, fieldConfig, inputValue, lookup) {
 		});
 		default: {
 			if ("builtin" in type) return builtinScalar(type.name);
+			const sdl = type.sdl === true;
+			const overrides = {
+				...type.description === void 0 && !sdl ? {} : { description: type.description },
+				...type.specifiedByURL === void 0 && !sdl ? {} : { specifiedByURL: type.specifiedByURL }
+			};
 			const scalar = type.scalar;
-			return scalar instanceof GraphQLScalarType ? scalar : definitionScalar(type.name, scalar);
+			if (scalar instanceof GraphQLScalarType) {
+				if (Object.keys(overrides).length === 0) return scalar;
+				const config = scalar.toConfig();
+				return new GraphQLScalarType({
+					...config,
+					description: "description" in overrides ? overrides.description : config.description,
+					specifiedByURL: "specifiedByURL" in overrides ? overrides.specifiedByURL : config.specifiedByURL
+				});
+			}
+			return definitionScalar(type.name, scalar, overrides);
+		}
+	}
+}
+/** The `interfaces` thunk of an object or interface type (none: no key, as before RFC 0007). */
+function interfacesOf(type, lookup) {
+	const names = type.interfaces;
+	if (names === void 0 || names.length === 0) return {};
+	return { interfaces: () => names.map((name) => lookup(name)) };
+}
+// src/results.ts
+/** The object types a result mapper ref declares: `static types` of a class; for an instance, its `types` property or its class's. */
+function declaredTypes(ref) {
+	try {
+		if (typeof ref === "function") return ref.types;
+		const own = ref.types;
+		if (own !== void 0) return own;
+		return ref.constructor?.types;
+	} catch {
+		return;
+	}
+}
+/**
+* Checks the declared types of the result mappers against the schema's types: a non-empty array of
+* names of object types. Every problem in one ZNIGHT066 error.
+*/
+function checkResultTypes(mappers, types) {
+	if (mappers.length === 0) return;
+	const kinds = new Map(types.map((type) => [type?.name, type?.kind]));
+	const problems = [];
+	for (const mapper of mappers) {
+		const declared = mapper.types;
+		if (!Array.isArray(declared) || declared.length === 0) {
+			problems.push(`the result mapper ${mapper.name} declares no types (static readonly types = [...object type names])`);
+			continue;
 		}
+		for (const name of declared) if (typeof name !== "string" || kinds.get(name) !== "object") problems.push(`the result mapper ${mapper.name} declares ${typeof name === "string" ? name : String(name)}, which is not an object type of the schema`);
 	}
+	if (problems.length === 0) return;
+	throw new ZnightError(ErrorCode.InvalidGraphQLSetup, `GraphQLPlugin: ${problems.join("; ")}`, { hints: ["A result mapper declares the object types its values may have: static readonly types = ['NotFoundRejection'] (RFC 0008)"] });
+}
+/** Decides which fields carry results, and builds their {@link Recover} functions. */
+var ResultMappers = class {
+	#container;
+	#logger;
+	#mappers;
+	#types;
+	/** Built on the first field, once the schema construction checked the section's structure. */
+	#index;
+	#fields = 0;
+	constructor(container, logger, mappers, types) {
+		this.#container = container;
+		this.#logger = logger;
+		this.#mappers = mappers;
+		this.#types = types;
+	}
+	/** Fields that carry results so far. */
+	get fields() {
+		return this.#fields;
+	}
+	/** The {@link Recover} function of `field`, `undefined` when it carries no result. */
+	recover(field, coordinate) {
+		if (this.#mappers.length === 0) return void 0;
+		const ref = parseTypeRef(field.type);
+		if (ref?.kind !== "named") return void 0;
+		this.#index ??= index(this.#types);
+		const objects = this.#index.objects;
+		const union = this.#index.unions.get(ref.name);
+		if (union === void 0) return void 0;
+		const applicable = this.#mappers.filter((mapper) => mapper.types.some((type) => union.members.has(type)));
+		if (applicable.length === 0) return void 0;
+		this.#fields++;
+		const container = this.#container;
+		const logger = this.#logger;
+		return (error, ctx) => {
+			for (const mapper of applicable) {
+				let value;
+				let type;
+				try {
+					value = resolveIn(container, mapper.resolvable).toResult(error, ctx);
+					if (value === void 0 || value === null) continue;
+					if (isThenable(value)) {
+						Promise.resolve(value).catch(noop);
+						logger.error(`GraphQLPlugin: the result mapper ${mapper.name} returned a promise: toResult() must be synchronous`, details(ctx, coordinate, error));
+						continue;
+					}
+					type = union.typeOf(value);
+				} catch (failure) {
+					logger.error(`GraphQLPlugin: the result mapper ${mapper.name} failed`, details(ctx, coordinate, failure));
+					continue;
+				}
+				if (type !== void 0 && union.members.has(type)) {
+					logger.debug(`GraphQL: error resolved as ${type} in ${coordinate}`, {
+						coordinate,
+						type
+					});
+					return value;
+				}
+				if (type !== void 0 && objects.has(type)) logger.debug(`GraphQLPlugin: the result mapper ${mapper.name} returned a value of ${type}, not a member of ${union.name} (${coordinate}): skipped`, details(ctx, coordinate, error));
+				else logger.warn(`GraphQLPlugin: the result mapper ${mapper.name} returned a value of no type of the schema (${coordinate}): skipped`, details(ctx, coordinate, error));
+			}
+			throw error;
+		};
+	}
+};
+function index(types) {
+	const objects = /* @__PURE__ */ new Set();
+	const unions = /* @__PURE__ */ new Map();
+	for (const type of types) if (type.kind === "object") objects.add(type.name);
+	else if (type.kind === "union") unions.set(type.name, {
+		name: type.name,
+		members: new Set(type.members),
+		typeOf: typeResolver(type.discriminator)
+	});
+	return {
+		objects,
+		unions
+	};
+}
+function noop() {}
+function details(ctx, coordinate, err) {
+	return {
+		err,
+		requestId: ctx.operation.requestId,
+		coordinate,
+		path: pathOf(ctx.info).join(".")
+	};
+}
+function pathOf(info) {
+	const path = [];
+	for (let step = info.path; step !== void 0; step = step.prev) path.push(step.key);
+	return path.reverse();
 }
 // src/transport/abort.ts
 /** The stand-in passed as graphql-js `abortSignal` by the HTTP transport (one per request). */
@@ -2854,14 +3061,18 @@ var GraphQLPlugin = class GraphQLPlugin {
 		return new GraphQLPlugin(options);
 	}
 	/**
-	* Providers `TestApp` creates at boot: the classes of the `guards` and `errorMappers` options, and
+	* Providers `TestApp` creates at boot: the classes of the `guards`, `errorMappers` and `resultMappers` options, and
 	* the resolvers, guards and loaders of the metadata.
 	*/
 	initRoots(context) {
 		const roots = /* @__PURE__ */ new Set();
 		try {
 			const options = this.#options;
-			if (options !== null && typeof options === "object") for (const key of ["guards", "errorMappers"]) {
+			if (options !== null && typeof options === "object") for (const key of [
+				"guards",
+				"errorMappers",
+				"resultMappers"
+			]) {
 				const refs = options[key];
 				if (Array.isArray(refs)) {
 					for (const ref of refs) if (typeof ref === "function") roots.add(ref);
@@ -3045,6 +3256,10 @@ var GraphQLPlugin = class GraphQLPlugin {
 		const providers = new Providers(container, metadata);
 		const globalGuards = options.guards.map((ref) => providers.ref(ref, "guard", "canResolve"));
 		const mappers = options.errorMappers.map((ref) => providers.ref(ref, "error mapper", "map"));
+		const resultMappers = options.resultMappers.map((ref) => ({
+			...providers.ref(ref, "result mapper", "toResult"),
+			types: declaredTypes(ref)
+		}));
 		const inputs = /* @__PURE__ */ new Map();
 		const fields = [];
 		const types = Array.isArray(section?.types) ? section.types : [];
@@ -3070,12 +3285,19 @@ var GraphQLPlugin = class GraphQLPlugin {
 				});
 			}
 		}
+		if (resultMappers.length > 0 && checkGraphQLSection(section).length === 0) checkResultTypes(resultMappers, types);
+		const results = new ResultMappers(container, ctx.logger, resultMappers.map((mapper) => ({
+			resolvable: mapper.resolvable,
+			name: mapper.name,
+			types: mapper.types
+		})), types);
 		const schema = buildGraphQLSchema(section, pipelineFactory({
 			container,
 			globalGuards: globalGuards.map((guard) => guard.resolvable),
 			guard: (token, coordinate) => providers.token(token, `guard of ${coordinate}`, "canResolve"),
 			resolver: (binding, coordinate) => providers.token(binding.token, `resolver of ${coordinate}`, binding.method),
-			inputs
+			inputs,
+			results: (field, coordinate) => results.recover(field, coordinate)
 		}));
 		checkFieldDecisions(fields, section.groups, options.enforcement, ctx.logger);
 		const formatter = new ErrorFormatter({
@@ -3103,7 +3325,8 @@ var GraphQLPlugin = class GraphQLPlugin {
 		});
 		ctx.logger.debug("GraphQL schema built", {
 			types: types.length,
-			schemaHash: section.schemaHash
+			schemaHash: section.schemaHash,
+			...results.fields === 0 ? {} : { resultFields: results.fields }
 		});
 		return {
 			schema,
@@ -3219,4 +3442,4 @@ var DeferredPubSub = class extends PubSub {
 };
 export { MemoryPubSub as a, GraphQLErrorCode as c, GraphQLTokens as i, GraphQLException as l, endpointOf as n, PubSub as o, executorOf as r, orderByKeys as s, GraphQLPlugin as t };
 
-//# sourceMappingURL=plugin-BdBxr5NQ.mjs.map
+//# sourceMappingURL=plugin-CR_wVfRU.mjs.map