@znight/messaging 0.3.0 → 0.4.0

package/src/compiler/generate.ts

@@ -18,7 +18,7 @@
  * }
  * ```
  */
-import type { GenerateContext, GenInput, GenNode } from '@znight/compiler'
+import type { ClassRef, GenerateContext, GenInput, GenNode, StaticValue, ValueRef } from '@znight/compiler'
 import type { ConsumerData, HandlerData, HandlerParamData, MessagingData } from './data.ts'
 
 import { compareStrings, RUNTIME_MODULE } from './constants.ts'
@@ -33,6 +33,13 @@ interface Helpers {
   inboundMessage(): GenNode
   validateMessage(): GenNode
   messageHeader(): GenNode
+  paramFunctionOf(): GenNode
+}
+
+/** The class resolver instances of the handler being generated (`x`), with the position of each token. */
+interface Resolvers {
+  readonly x: GenNode | undefined
+  readonly index: ReadonlyMap<string, number>
 }
 
 /** Builds the messaging section; `undefined` (no section) when the application has no consumer. */
@@ -68,36 +75,77 @@ function handlerNode(ctx: Context, handler: HandlerData, consumerType: () => Gen
   const entries: [string, GenInput][] = [['method', handler.method]]
   if (handler.type !== undefined) entries.push(['type', handler.type])
   if (handler.retry !== undefined) 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: HandlerData): ClassRef[] {
+  const found = new Map<string, ClassRef>()
+  for (const param of handler.params) {
+    const resolver = param.kind === 'custom' ? param.resolver : undefined
+    if (resolver !== undefined && !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: Context, handler: HandlerData, consumerType: () => GenNode, helpers: Helpers): GenNode {
+function invokeNode(
+  ctx: Context,
+  handler: HandlerData,
+  consumerType: () => GenNode,
+  helpers: Helpers,
+  resolvers: readonly ClassRef[],
+): GenNode {
   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)))
   }
+  // `_m` when only class resolvers whose `resolve()` takes no parameter need arguments (`noUnusedParameters`)
+  const readsMessage = params.some(
+    param =>
+      param.kind !== 'undefined' && (param.kind !== 'custom' || param.resolver === undefined || param.arity !== 0),
+  )
+  const arrowParams: [string, GenNode][] = [
+    ['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] as GenNode)
+    arrowParams.push(['x', ctx.code`readonly [${joined}]`])
+  }
+  const index = new Map(resolvers.map((ref, position) => [ref.token, position]))
   return ctx.arrow(
-    [
-      ['c', consumerType()],
-      ['m', helpers.inboundMessage()],
-    ],
-    (c, m) =>
+    arrowParams,
+    (c, m, x) =>
       ctx.call(
         ctx.member(c, handler.method),
-        params.map(param => argumentNode(ctx, param, m as GenNode, helpers)),
+        params.map(param => argumentNode(ctx, param, m as GenNode, helpers, { x, index })),
       ),
-    { async: params.some(param => param.kind === 'validated') },
+    { async: params.some(param => param.kind === 'validated' || param.kind === 'custom') },
   )
 }
 
-function argumentNode(ctx: Context, param: HandlerParamData, m: GenNode, helpers: Helpers): GenNode {
+function argumentNode(
+  ctx: Context,
+  param: HandlerParamData,
+  m: GenNode,
+  helpers: Helpers,
+  resolvers: Resolvers,
+): GenNode {
   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':
@@ -113,6 +161,54 @@ function argumentNode(ctx: Context, param: HandlerParamData, m: GenNode, helpers
   }
 }
 
+/**
+ * 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: Context,
+  param: Extract<HandlerParamData, { kind: 'custom' }>,
+  m: GenNode,
+  helpers: Helpers,
+  resolvers: Resolvers,
+): GenNode {
+  const data = param.data === undefined ? ctx.lit(undefined) : dataNode(ctx, param.data.value)
+  let node: GenNode
+  if (param.resolver === undefined) {
+    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) as number
+    if (param.arity === undefined) {
+      // a `resolve` the compiler cannot read (inherited from a mixin...): the instance is cast to a
+      // method taking both arguments (method parameters are bivariant), the value with `as never`
+      const instance = ctx.code`${resolvers.x as GenNode}[${position}] as { resolve(message: unknown, data: unknown): unknown }`
+      return ctx.code`(await (${instance}).resolve(${m}, ${data})) as never`
+    }
+    // a `resolve(message)` that ignores the data gets no data argument (TypeScript checks the arity)
+    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 as GenNode}[${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: Context, value: StaticValue): GenNode {
+  return isValueRef(value) ? ctx.ref(value as ValueRef) : ctx.lit(value as never)
+}
+
+/** `true` for a {@link ValueRef} (the only non-plain object a static value can hold). */
+function isValueRef(value: unknown): boolean {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const prototype = Object.getPrototypeOf(value)
+  return prototype !== Object.prototype && prototype !== null && (value as { kind?: unknown }).kind === 'ref'
+}
+
 function lazyHelpers(ctx: Context): Helpers {
   const cache = new Map<string, GenNode>()
   const get = (name: string, type: boolean): GenNode => {
@@ -127,5 +223,13 @@ function lazyHelpers(ctx: Context): Helpers {
     inboundMessage: () => get('InboundMessage', true),
     validateMessage: () => get('validateMessage', false),
     messageHeader: () => get('messageHeader', false),
+    paramFunctionOf: () => {
+      let node = cache.get('@znight/core#ParamFunctionOf')
+      if (node === undefined) {
+        node = ctx.importFrom('@znight/core', 'ParamFunctionOf', { type: true })
+        cache.set('@znight/core#ParamFunctionOf', node)
+      }
+      return node
+    },
   }
 }

package/src/consumers.ts

@@ -3,6 +3,7 @@
  */
 import type { Container, Token } from '@znight/core'
 import type { MessagingDriver } from './driver.ts'
+import type { InboundMessage } from './message.ts'
 import type { ConsumerDefinition, MessageHandlerDefinition, MessagingMetadata } from './metadata.ts'
 import type { RetryOptions, RetryPolicy } from './retry.ts'
 
@@ -22,6 +23,11 @@ import {
 /** A handler ready to be dispatched to. */
 export interface PreparedHandler {
   readonly definition: MessageHandlerDefinition
+  /**
+   * Calls the handler: `definition.invoke`, or for a handler with parameter resolvers (RFC 0010) a
+   * function passing their instances, resolved in the delivery scope.
+   */
+  readonly invoke: (consumer: unknown, message: InboundMessage) => unknown
   readonly method: string
   readonly policy: RetryPolicy
 }
@@ -140,7 +146,7 @@ function prepareConsumer(
   let maxAttempts = 1
   const nativeDelays = new Set<number>()
   for (const handlerDefinition of handlers) {
-    const handler = prepareHandler(handlerDefinition, name, driver, defaults.retry)
+    const handler = prepareHandler(handlerDefinition, name, driver, defaults.retry, container)
     maxAttempts = Math.max(maxAttempts, handler.policy.attempts)
     for (const delay of retryDelays(handler.policy)) {
       if (!isInProcessDelay(delay, driver.capabilities)) nativeDelays.add(delay)
@@ -204,6 +210,7 @@ function prepareHandler(
   consumer: string,
   driver: MessagingDriver,
   defaultPolicy: RetryPolicy,
+  container: Container,
 ): PreparedHandler {
   if (
     definition === null ||
@@ -227,7 +234,29 @@ function prepareHandler(
     driver.name,
     definition.retry === undefined ? `${where} (default retry policy)` : `@Retry on ${where}`,
   )
-  return { definition, method: definition.method, policy }
+  return { definition, invoke: handlerInvoke(definition, container, where), method: definition.method, policy }
+}
+
+/** The generated invoke, or a function passing the parameter resolver instances (resolved per delivery). */
+function handlerInvoke(
+  definition: MessageHandlerDefinition,
+  container: Container,
+  where: string,
+): PreparedHandler['invoke'] {
+  const invoke = definition.invoke
+  const tokens = definition.paramResolvers
+  if (tokens === undefined || tokens.length === 0) return invoke
+  for (const token of tokens) {
+    if (!container.has(token)) {
+      throw consumerError(`${where}: the parameter resolver ${token} is not a provider`, ['Regenerate the metadata'])
+    }
+  }
+  return (consumer, message) =>
+    invoke(
+      consumer,
+      message,
+      tokens.map(token => container.get(token)),
+    )
 }
 
 function duplicateType(consumer: string, type: string): Error {

package/src/message.ts

@@ -1,3 +1,10 @@
+declare module '@znight/core' {
+  /** Custom parameter decorators (`createParamDecorator`) resolve handler parameters from the {@link InboundMessage}. */
+  interface ParamContexts {
+    messaging: InboundMessage
+  }
+}
+
 /**
  * A message being handled by a consumer. It is the value of the request-scoped external
  * `@znight/messaging#InboundMessage` during a delivery (inject it into request-scoped providers, or

package/src/metadata.ts

@@ -49,13 +49,19 @@ export interface MessageHandlerDefinition {
   readonly type?: string
   /** `@Retry` policy, normalized. Default: the plugin's `defaults.retry`. */
   readonly retry?: RetryPolicy
+  /**
+   * Provider classes resolving custom parameters (`ParamResolver`, RFC 0010), in order of first use:
+   * the runtime resolves them in the delivery scope and passes the instances to `invoke` (`x`).
+   * Absent when there is none.
+   */
+  readonly paramResolvers?: readonly Token[]
   /**
    * Calls the handler: extracts and validates the parameters from the message
    * (`@Message(schema)` → `validateMessage(schema, m.payload)`, `@Headers(name)` →
-   * `messageHeader(m, name)`, `@Ctx()` → `m`).
+   * `messageHeader(m, name)`, `@Ctx()` → `m`, a custom parameter → its resolver, awaited).
    */
-  // biome-ignore lint/suspicious/noExplicitAny: generated invokers receive the concrete consumer class
-  readonly invoke: (consumer: any, message: InboundMessage) => unknown
+  // biome-ignore lint/suspicious/noExplicitAny: generated invokers receive the concrete consumer class and resolver tuple
+  readonly invoke: (consumer: any, message: InboundMessage, resolvers?: any) => unknown
 }
 
 declare module '@znight/core' {

package/src/runtime.ts

@@ -251,7 +251,7 @@ export class ConsumerRuntime {
     }
     try {
       const instance = this.#services.container.get(this.consumer.token)
-      await handler.definition.invoke(instance, message)
+      await handler.invoke(instance, message)
     } catch (error) {
       return this.#failure(context, error, true)
     }