@znight/graphql 0.3.0 → 0.5.0

package/README.md

@@ -540,6 +540,32 @@ Built-in scalars appear in the schema only when used: `String`, `Float`, `Int`,
   `plugin.execute()` and `plugin.subscribe()` run in the current scope when one is active (a
   controller calling GraphQL), otherwise in a scope of their own.
 
+### Custom parameter decorators
+
+A decorator defined with `createParamDecorator` (`@znight/core`, RFC 0010) works on resolver
+methods when it has a `graphql` resolver, which receives the field's `ResolverContext` (`parent`,
+`args`, `info`, `operation`, `http`, `route.meta`). One definition serves HTTP routes and GraphQL
+fields:
+
+```ts
+import { createParamDecorator } from '@znight/core'
+import type { User } from './user.ts'
+
+export const CurrentUser = createParamDecorator<User>({
+  http: ctx => ctx.state.get('user') as User,
+  graphql: ctx => ctx.operation.state.get('user') as User,
+})
+
+// @Query() me(@CurrentUser() user: User): User { return user }
+```
+
+The resolver runs after the guards (it sees what they stored) and before the method; what it
+throws fails the field like the method would (`errors[]`, or a result mapper). A custom parameter
+is not a GraphQL argument: it never appears in the schema. Resolver classes implementing
+`ParamResolver` are resolved in the operation scope. Custom parameters belong to the field
+resolvers of the schema, so they work the same through the built-in transport, `plugin.execute()`
+and a driver such as `yogaDriver()` (RFC 0009).
+
 ## Authorization
 
 The route decorators of `@znight/http` (`createRouteDecorator`, with RFC 0001's groups) apply to
@@ -1486,7 +1512,17 @@ interface GraphQLResolverBinding {
   guards: Token[] // class @UseGuard guards, then method ones
   meta: Record<string, unknown> // effective route metadata (method over class); {}: none
   loaders?: Token[] // informational: loaders the method injects
-  invoke: (resolver, parent, args: GraphQLArgs, context: GraphQLContext, info: GraphQLResolveInfo) => unknown
+  context?: true // custom parameters (RFC 0010): the pipeline passes the ResolverContext as `f`
+  paramResolvers?: Token[] // class resolvers of custom parameters, passed as `x`
+  invoke(
+    resolver,
+    parent,
+    args: GraphQLArgs,
+    context: GraphQLContext,
+    info: GraphQLResolveInfo,
+    f?: ResolverContext,
+    x?,
+  ): unknown
 }
 ```
 
@@ -1498,7 +1534,9 @@ Type references are strings in graphql-js' canonical form, parsed by
 
 `invoke` maps the graphql-js arguments to the method parameters: `@Args('x')` → `a['x']`,
 `@Args()` → `a`, `@Parent()` → `p`, `@Ctx()` → `c`, `@Info()` → `i`, `@Loader()` →
-`c.loader(token)`. Unused middle parameters are `_`-prefixed and trailing ones omitted, so the code
+`c.loader(token)`, a custom parameter decorator (`createParamDecorator`, RFC 0010) →
+`(D.resolvers.graphql as ParamFunctionOf<typeof D, 'graphql'>)(f, data)` or `x[i].resolve(f, data)`
+(evaluated like a validated argument: synchronous while the resolvers return values). Unused middle parameters are `_`-prefixed and trailing ones omitted, so the code
 type-checks with `noUnusedParameters`. It calls these runtime helpers, kept stable:
 
 - `validateArgs(schema, value, label)`, exported from `@znight/graphql`: validates an argument with

package/dist/compiler.d.mts

@@ -1,6 +1,6 @@
 import { Scope } from "@znight/core";
 import { MetaEntry } from "@znight/http/compiler";
-import { BindingHandle, ClassInfo, ClassRef, CompilerExtension, Location, ValueRef } from "@znight/compiler";
+import { BindingHandle, ClassInfo, ClassRef, CompilerExtension, Location, StaticValue, ValueRef } from "@znight/compiler";
 /** Kind of field a resolver method provides. */
 type FieldOperation = "query" | "mutation" | "subscription" | "field";
 /** A `@Resolver` class. */
@@ -71,6 +71,26 @@ type ParamData = {
   /** Identity of `L` in `Loader<L>`. */
   readonly identity: string;
   readonly location: Location;
+} | {
+  /** A custom parameter decorator (`createParamDecorator`, RFC 0010). */
+  readonly kind: "custom";
+  /** Canonical identity of the decorator `const` (imported by the generated module). */
+  readonly identity: string;
+  readonly name: string;
+  /** The data argument (a value, possibly holding references, or a reference); `undefined` without argument. */
+  readonly data: {
+    readonly value: StaticValue;
+  } | undefined;
+  /** The class resolver (`x[i].resolve(f, data)`); `undefined` for a function resolver. */
+  readonly resolver: ClassRef | undefined;
+  /**
+   * Parameters of the class resolver's `resolve` (own, inherited or an arrow function property);
+   * `undefined` for a function, or when the compiler cannot read it (the call is cast).
+   */
+  readonly arity?: number;
+  /** The value type could not be checked against the parameter. */
+  readonly cast: boolean;
+  readonly location: Location;
 };
 /** Everything the extension stores. */
 type GraphQLData = ResolverData;

package/dist/compiler.mjs

@@ -417,6 +417,22 @@ function parameterDecorators(param) {
 }
 function analyzeParameter(ctx, cls, param, where) {
 	const decorators = parameterDecorators(param);
+	const custom = typeof ctx.paramDecorator === "function" ? ctx.paramDecorator(param, "graphql", cls) : void 0;
+	if (custom !== void 0) {
+		for (const other of decorators) error(ctx, Codes.InvalidDecorator, other.location, `Parameter '${param.name}' of ${where} has several parameter decorators (@${custom.decorator.name} and @${other.name})`, ["Keep a single parameter decorator"]);
+		if (!custom.ok || decorators.length > 0) return void 0;
+		const data = custom.data;
+		return {
+			kind: "custom",
+			identity: custom.identity,
+			name: custom.name,
+			data: data === void 0 ? void 0 : { value: data.ref ?? data.value },
+			resolver: custom.resolver.kind === "class" ? custom.resolver.ref : void 0,
+			...custom.resolver.kind === "class" && custom.resolver.arity !== void 0 ? { arity: custom.resolver.arity } : {},
+			cast: custom.cast,
+			location: custom.location
+		};
+	}
 	const decorator = decorators[0];
 	if (decorator === void 0) {
 		const lookAlike = param.decorators.find((found) => found.identity !== void 0 && HTTP_LOOK_ALIKES.has(found.identity));
@@ -2627,6 +2643,8 @@ function createImports(ctx) {
 	let args;
 	let context;
 	let info;
+	let resolverContext;
+	let paramFunctionOf;
 	let validateArgs;
 	let isThenable;
 	const hosts = /* @__PURE__ */ new Map();
@@ -2643,6 +2661,14 @@ function createImports(ctx) {
 			info ??= ctx.importFrom("graphql", "GraphQLResolveInfo", { type: true });
 			return info;
 		},
+		resolverContextType: () => {
+			resolverContext ??= ctx.importFrom(RUNTIME_MODULE, "ResolverContext", { type: true });
+			return resolverContext;
+		},
+		paramFunctionOf: () => {
+			paramFunctionOf ??= ctx.importFrom("@znight/core", "ParamFunctionOf", { type: true });
+			return paramFunctionOf;
+		},
 		validateArgs: () => {
 			validateArgs ??= ctx.importFrom(RUNTIME_MODULE, "validateArgs");
 			return validateArgs;
@@ -2734,7 +2760,10 @@ function resolverNode(ctx, imports, resolver, field) {
 	];
 	const loaders = field.params.flatMap((param) => param?.kind === "loader" ? [loaderToken(ctx, param)] : []);
 	if (loaders.length > 0) entries.push(["loaders", ctx.lit(loaders)]);
-	entries.push(["invoke", invokeNode(ctx, imports, resolver, field)]);
+	const resolvers = paramResolvers(field);
+	if (field.params.some((param) => param?.kind === "custom")) entries.push(["context", ctx.lit(true)]);
+	if (resolvers.length > 0) entries.push(["paramResolvers", ctx.lit(resolvers.map((ref) => ctx.tokenOf(ref) ?? ref.token))]);
+	entries.push(["invoke", invokeNode(ctx, imports, resolver, field, resolvers)]);
 	return ctx.obj(entries);
 }
 /** The provider token a loader parameter is bound to. */
@@ -2744,13 +2773,28 @@ function loaderToken(ctx, param) {
 	if (ref !== void 0 && "token" in ref) return ref.token;
 	return param.identity;
 }
-/** Which `invoke` parameters a field uses: `(r, p, a, c, i)`. */
+/** The provider classes resolving custom parameters, in order of first use (`x[i]`). */
+function paramResolvers(field) {
+	const found = /* @__PURE__ */ new Map();
+	for (const param of field.params) {
+		const resolver = param?.kind === "custom" ? param.resolver : void 0;
+		if (resolver !== void 0 && !found.has(resolver.token)) found.set(resolver.token, resolver);
+	}
+	return [...found.values()];
+}
+/** Which `invoke` parameters a field uses: `(r, p, a, c, i, f, x)`. */
 function usedParameters(field) {
 	let p = false;
 	let a = false;
 	let c = false;
 	let i = false;
+	let f = false;
+	let x = false;
 	for (const param of field.params) switch (param?.kind) {
+		case "custom":
+			f ||= param.resolver === void 0 || param.arity !== 0;
+			x ||= param.resolver !== void 0;
+			break;
 		case "parent":
 			p = true;
 			break;
@@ -2767,43 +2811,63 @@ function usedParameters(field) {
 		p,
 		a,
 		c,
-		i
+		i,
+		f,
+		x
 	];
 }
 /**
 * `(r: Resolver, p: unknown, a: GraphQLArgs, c: GraphQLContext, i: GraphQLResolveInfo) => r.m(...)`:
 * unused middle parameters are `_`-prefixed, trailing ones omitted (`noUnusedParameters`).
 */
-function invokeNode(ctx, imports, resolver, field) {
+function invokeNode(ctx, imports, resolver, field, resolvers) {
 	const used = usedParameters(field);
 	const last = used.lastIndexOf(true);
 	const types = [
 		() => ctx.code`unknown`,
 		imports.argsType,
 		imports.contextType,
-		imports.infoType
+		imports.infoType,
+		imports.resolverContextType,
+		() => tupleType(ctx, resolvers.map((ref) => ctx.importType(ref)))
 	];
 	const names = [
 		"p",
 		"a",
 		"c",
-		"i"
+		"i",
+		"f",
+		"x"
 	];
 	const params = [["r", imports.hostType(resolver.host.identity)]];
 	for (let index = 0; index <= last; index++) params.push([`${used[index] ? "" : "_"}${names[index]}`, types[index]()]);
-	const validated = field.params.flatMap((param, index) => param?.kind === "args" && param.schema !== void 0 ? [index] : []);
+	const deferred = field.params.flatMap((param, index) => param !== void 0 && isDeferred(param) ? [index] : []);
+	const positions = new Map(resolvers.map((ref, position) => [ref.token, position]));
 	return ctx.arrow(params, (r, ...rest) => {
-		const [p, a, c, i] = rest;
+		const [p, a, c, i, f, x] = rest;
 		const scope = {
 			p,
 			a,
 			c,
-			i
+			i,
+			f,
+			x,
+			resolvers: positions,
+			imports
 		};
-		if (validated.length === 0) return call(ctx, r, field, (index) => argument(ctx, scope, field, index));
-		return validatingBlock(ctx, imports, r, scope, field, validated);
+		if (deferred.length === 0) return call(ctx, r, field, (index) => argument(ctx, scope, field, index));
+		return validatingBlock(ctx, imports, r, scope, field, deferred);
 	});
 }
+/** `readonly [A, B]`. */
+function tupleType(ctx, nodes) {
+	const joined = nodes.slice(1).reduce((all, node) => ctx.code`${all}, ${node}`, nodes[0]);
+	return ctx.code`readonly [${joined}]`;
+}
+/** An argument whose expression may return a thenable: a validated `@Args`, or a custom parameter. */
+function isDeferred(param) {
+	return param.kind === "args" && param.schema !== void 0 || param.kind === "custom";
+}
 /** `r.method(args)`. */
 function call(ctx, r, field, argumentOf) {
 	return ctx.call(ctx.member(r, field.method), field.params.map((_, index) => argumentOf(index)));
@@ -2817,9 +2881,48 @@ function argument(ctx, scope, field, index) {
 		case "info": return scope.i;
 		case "loader": return ctx.code`${ctx.call(ctx.member(scope.c, "loader"), [loaderToken(ctx, param)])} as never`;
 		case "args": return ctx.code`${argsValue(ctx, scope, param.name)} as never`;
+		case "custom": return customArgument(ctx, scope, param);
 		default: return ctx.lit(void 0);
 	}
 }
+/**
+* A custom parameter (RFC 0010): `(D.resolvers.graphql as ParamFunctionOf<typeof D, 'graphql'>)(f, data)`
+* or `x[i].resolve(f, data)`, cast with `as never` when the value type could not be checked.
+*/
+function customArgument(ctx, scope, param) {
+	const f = scope.f;
+	const data = param.data === void 0 ? ctx.lit(void 0) : dataNode(ctx, param.data.value);
+	let node;
+	if (param.resolver === void 0) {
+		const decorator = ctx.importValue(param.identity);
+		const type = ctx.code`${scope.imports.paramFunctionOf()}<typeof ${decorator}, 'graphql'>`;
+		node = ctx.call(ctx.code`${ctx.member(decorator, "resolvers", "graphql")} as ${type}`, [f, data]);
+	} else {
+		const position = scope.resolvers.get(param.resolver.token);
+		if (param.arity === void 0) return ctx.code`(${scope.x}[${position}] as { resolve(ctx: unknown, data: unknown): unknown }).resolve(${f}, ${data}) as never`;
+		const arity = Math.min(param.arity, 2);
+		let args = ctx.code``;
+		if (arity === 1) args = f;
+		else if (arity === 2) args = ctx.code`${f}, ${data}`;
+		node = ctx.code`${scope.x}[${position}].resolve(${args})`;
+	}
+	return param.cast ? ctx.code`${node} as never` : node;
+}
+/** The data argument of a custom parameter: a literal (references imported) or a reference. */
+function dataNode(ctx, value) {
+	return isValueRef(value) ? ctx.ref(value) : ctx.lit(value);
+}
+/** `true` for a {@link ValueRef} (the only non-plain object a static value can hold). */
+function isValueRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype !== Object.prototype && prototype !== null && value.kind === "ref";
+}
+/** The expression of a deferred parameter (validation or custom resolver), before any `await`. */
+function deferredValue(ctx, imports, scope, field, index) {
+	const param = field.params[index];
+	return param.kind === "custom" ? customArgument(ctx, scope, param) : validation(ctx, imports, scope, param);
+}
 /** `a['name']`, or `a` for `@Args()`. */
 function argsValue(ctx, scope, name) {
 	const a = scope.a;
@@ -2853,15 +2956,13 @@ function validatingBlock(ctx, imports, r, scope, field, validated) {
 		const statements = [];
 		for (const index of validated) {
 			const name = local.get(index);
-			const param = field.params[index];
-			statements.push(ctx.code`const ${name} = ${validation(ctx, imports, scope, param)}`);
+			statements.push(ctx.code`const ${name} = ${deferredValue(ctx, imports, scope, field, index)}`);
 			const resume = ctx.arrow([], () => call(ctx, r, field, (position) => {
 				const value = local.get(position);
 				if (value === void 0) return argument(ctx, scope, field, position);
 				if (position < index) return ctx.code`${value} as never`;
 				if (position === index) return ctx.code`await ${value} as never`;
-				const later = field.params[position];
-				return ctx.code`await ${validation(ctx, imports, scope, later)} as never`;
+				return ctx.code`await ${deferredValue(ctx, imports, scope, field, position)} as never`;
 			}), { async: true });
 			statements.push(ctx.code`if (${ctx.call(imports.isThenable(), [name])}) return (${resume})()`);
 		}