@znight/messaging 0.3.0 → 0.5.0

package/README.md

@@ -112,6 +112,21 @@ Handler selection: exact type, then patterns (declaration order), then the defau
 message no handler matches is dead-lettered with reason `no-handler` (or acknowledged by `@OnError`).
 A queue is consumed by a single `@Consumer` class per application.
 
+Handler parameters can also use a custom parameter decorator defined with `createParamDecorator`
+(`@znight/core`, RFC 0010) when it has a `messaging` resolver, which receives the `InboundMessage`:
+
+```ts
+import { createParamDecorator } from '@znight/core'
+
+export const Tenant = createParamDecorator<string>({
+  messaging: message => message.headers['x-tenant'] ?? 'default',
+})
+
+// @OnMessage('order.placed') placed(@Message(Order) order: Order, @Tenant() tenant: string) { ... }
+```
+
+A resolver error fails the delivery like a handler error (retries, `@OnError`, dead letters).
+
 ## Delivery semantics
 
 Delivery is **at-least-once**. A message can be handled more than once: redelivery after a crash, a
@@ -566,7 +581,8 @@ interface MessagingMetadata {
       method: string
       type?: string // @OnMessage(type)
       retry?: { attempts: number; backoff: 'fixed' | 'exponential'; delay: number; maxDelay?: number } // @Retry, defaults filled
-      invoke: (consumer: any, message: InboundMessage) => unknown
+      paramResolvers?: Token[] // class resolvers of custom parameters (RFC 0010), passed to invoke as `x`
+      invoke: (consumer: any, message: InboundMessage, x?: readonly object[]) => unknown
     }[]
     errorHandler?: string // @OnError method name, called as consumer[errorHandler](error, message)
   }[]
@@ -584,9 +600,14 @@ Helpers generated code may call (exported from `@znight/messaging`, stable):
 Parameter extraction in `invoke`: `@Message()` → `m.payload as never` (no schema, ZNIGHT017 when the
 type is not primitive); `@Message(S)` → `await validateMessage(S, m.payload)` (the invoker is then
 `async`); `@Headers()` → `m.headers`; `@Headers('x')` → `messageHeader(m, 'x')`; `@Ctx()` → `m`
-(`m as InboundMessage<never>` when the parameter narrows the payload type); an optional parameter
-without decorator → `undefined` (trailing ones are omitted). The invoker is `async` only when it
-awaits a validation, and its `m` parameter is omitted when no argument uses it (`noUnusedParameters`).
+(`m as InboundMessage<never>` when the parameter narrows the payload type); a custom parameter
+decorator (`createParamDecorator`, RFC 0010) → `await (D.resolvers.messaging as ParamFunctionOf<typeof
+D, 'messaging'>)(m, data)` or `await x[i].resolve(m, data)` for a provider class (`x`: the
+instances of `paramResolvers`, resolved in the delivery scope); an optional parameter without
+decorator → `undefined` (trailing ones are omitted). The invoker is `async` only when it awaits a
+validation or a custom parameter, and its `m` parameter is omitted when the handler has no
+argument, `_m` when no argument reads it (only class resolvers whose `resolve()` takes no
+parameter), so that it type-checks with `noUnusedParameters`.
 Consumers are sorted by token, handlers keep their declaration order (inherited handlers first), and
 `options` / `errorHandler` / `type` / `retry` are omitted when absent. Example:
 

package/dist/compiler.d.mts

@@ -1,5 +1,5 @@
 import { Token } from "@znight/core";
-import { CompilerExtension, Location, StaticValue, ValueRef } from "@znight/compiler";
+import { ClassRef, CompilerExtension, Location, StaticValue, ValueRef } from "@znight/compiler";
 /** A normalized `@Retry` policy (`MessageHandlerDefinition.retry`). */
 interface RetryPolicyData {
   readonly attempts: number;
@@ -23,6 +23,24 @@ type HandlerParamData = {
   readonly narrow: boolean;
 } | {
   readonly kind: "undefined";
+} | {
+  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; `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;
 };
 /** One `@OnMessage` decorator of a method. */
 interface HandlerData {

package/dist/compiler.mjs

@@ -526,7 +526,7 @@ function analyzeMethod(cls, method, ctx) {
 	let handlers = [];
 	if (onMessage.length > 0) {
 		const policy = retry[0] === void 0 ? void 0 : normalizeRetryDecorator(retry[0], where, ctx);
-		const params = analyzeHandlerParams(method, where, ctx);
+		const params = analyzeHandlerParams(cls, method, where, ctx);
 		handlers = onMessage.flatMap((decorator) => {
 			const type = messageType(decorator, where, ctx);
 			if (type === false) return [];
@@ -631,11 +631,32 @@ function checkErrorHandler(method, decorator, where, ctx) {
 		hints: ["Declare the return type `'ack' | undefined` (or `void`)"]
 	});
 }
-function analyzeHandlerParams(method, where, ctx) {
-	return Object.freeze(method.params.map((param) => analyzeHandlerParam(param, where, ctx)));
+function analyzeHandlerParams(cls, method, where, ctx) {
+	return Object.freeze(method.params.map((param) => analyzeHandlerParam(cls, param, where, ctx)));
 }
-function analyzeHandlerParam(param, where, ctx) {
+function analyzeHandlerParam(cls, param, where, ctx) {
 	const decorators = parameterDecorators(param);
+	const custom = typeof ctx.paramDecorator === "function" ? ctx.paramDecorator(param, "messaging", cls) : void 0;
+	if (custom !== void 0) {
+		for (const other of decorators) ctx.report({
+			code: INVALID_DECORATOR,
+			severity: "error",
+			message: `Parameter '${param.name}' of ${where} has several parameter decorators (@${custom.decorator.name} and @${other.name})`,
+			location: other.location,
+			hints: ["Keep a single parameter decorator"]
+		});
+		if (!custom.ok || decorators.length > 0) return { kind: "undefined" };
+		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
+		};
+	}
 	const decorator = decorators[0];
 	if (decorator === void 0) {
 		const foreign = foreignParameterDecorator(param);
@@ -896,21 +917,45 @@ function handlerNode(ctx, handler, consumerType, helpers) {
 	const entries = [["method", handler.method]];
 	if (handler.type !== void 0) entries.push(["type", handler.type]);
 	if (handler.retry !== void 0) entries.push(["retry", ctx.lit({ ...handler.retry })]);
-	entries.push(["invoke", invokeNode(ctx, handler, consumerType, helpers)]);
+	const resolvers = paramResolvers(handler);
+	if (resolvers.length > 0) entries.push(["paramResolvers", ctx.lit(resolvers.map((ref) => ctx.tokenOf(ref) ?? ref.token))]);
+	entries.push(["invoke", invokeNode(ctx, handler, consumerType, helpers, resolvers)]);
 	return ctx.obj(entries);
 }
+/** The provider classes resolving custom parameters, in order of first use (`x[i]`). */
+function paramResolvers(handler) {
+	const found = /* @__PURE__ */ new Map();
+	for (const param of handler.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()];
+}
 /**
 * `(c: Consumer, m: InboundMessage) => c.method(...args)`, `async` only when it awaits a schema
-* validation. `m` is omitted when no argument uses it (`noUnusedParameters`).
+* validation or a custom parameter. `m` is omitted when no argument uses it (`noUnusedParameters`);
+* `x` (the class resolver instances) is declared only when the handler has class resolvers.
 */
-function invokeNode(ctx, handler, consumerType, helpers) {
+function invokeNode(ctx, handler, consumerType, helpers, resolvers) {
 	const params = [...handler.params];
 	while (params.length > 0 && params[params.length - 1]?.kind === "undefined") params.pop();
 	if (params.length === 0) return ctx.arrow([["c", consumerType()]], (c) => ctx.call(ctx.member(c, handler.method)));
-	return ctx.arrow([["c", consumerType()], ["m", helpers.inboundMessage()]], (c, m) => ctx.call(ctx.member(c, handler.method), params.map((param) => argumentNode(ctx, param, m, helpers))), { async: params.some((param) => param.kind === "validated") });
+	const readsMessage = params.some((param) => param.kind !== "undefined" && (param.kind !== "custom" || param.resolver === void 0 || param.arity !== 0));
+	const arrowParams = [["c", consumerType()], [readsMessage ? "m" : "_m", helpers.inboundMessage()]];
+	if (resolvers.length > 0) {
+		const types = resolvers.map((ref) => ctx.importType(ref));
+		const joined = types.slice(1).reduce((all, node) => ctx.code`${all}, ${node}`, types[0]);
+		arrowParams.push(["x", ctx.code`readonly [${joined}]`]);
+	}
+	const index = new Map(resolvers.map((ref, position) => [ref.token, position]));
+	return ctx.arrow(arrowParams, (c, m, x) => ctx.call(ctx.member(c, handler.method), params.map((param) => argumentNode(ctx, param, m, helpers, {
+		x,
+		index
+	}))), { async: params.some((param) => param.kind === "validated" || param.kind === "custom") });
 }
-function argumentNode(ctx, param, m, helpers) {
+function argumentNode(ctx, param, m, helpers, resolvers) {
 	switch (param.kind) {
+		case "custom": return customArgument(ctx, param, m, helpers, resolvers);
 		case "payload": return ctx.code`${ctx.member(m, "payload")} as never`;
 		case "validated": return ctx.code`await ${ctx.call(helpers.validateMessage(), [ctx.importValue(param.schema), ctx.member(m, "payload")])}`;
 		case "headers": return ctx.member(m, "headers");
@@ -919,6 +964,42 @@ function argumentNode(ctx, param, m, helpers) {
 		case "undefined": return ctx.lit(void 0);
 	}
 }
+/**
+* A custom parameter (RFC 0010), awaited (the invoke is `async`):
+* `await (D.resolvers.messaging as ParamFunctionOf<typeof D, 'messaging'>)(m, data)` or
+* `await x[i].resolve(m, data)`, cast with `as never` when the value type could not be checked.
+*/
+function customArgument(ctx, param, m, helpers, resolvers) {
+	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`${helpers.paramFunctionOf()}<typeof ${decorator}, 'messaging'>`;
+		node = ctx.call(ctx.code`${ctx.member(decorator, "resolvers", "messaging")} as ${type}`, [m, data]);
+	} else {
+		const position = resolvers.index.get(param.resolver.token);
+		if (param.arity === void 0) {
+			const instance = ctx.code`${resolvers.x}[${position}] as { resolve(message: unknown, data: unknown): unknown }`;
+			return ctx.code`(await (${instance}).resolve(${m}, ${data})) as never`;
+		}
+		const arity = Math.min(param.arity, 2);
+		let args = ctx.code``;
+		if (arity === 1) args = m;
+		else if (arity === 2) args = ctx.code`${m}, ${data}`;
+		node = ctx.code`${resolvers.x}[${position}].resolve(${args})`;
+	}
+	return param.cast ? ctx.code`(await ${node}) as never` : ctx.code`await ${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";
+}
 function lazyHelpers(ctx) {
 	const cache = /* @__PURE__ */ new Map();
 	const get = (name, type) => {
@@ -932,7 +1013,15 @@ function lazyHelpers(ctx) {
 	return {
 		inboundMessage: () => get("InboundMessage", true),
 		validateMessage: () => get("validateMessage", false),
-		messageHeader: () => get("messageHeader", false)
+		messageHeader: () => get("messageHeader", false),
+		paramFunctionOf: () => {
+			let node = cache.get("@znight/core#ParamFunctionOf");
+			if (node === void 0) {
+				node = ctx.importFrom("@znight/core", "ParamFunctionOf", { type: true });
+				cache.set("@znight/core#ParamFunctionOf", node);
+			}
+			return node;
+		}
 	};
 }
 // src/compiler/validate.ts