@znight/core 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znight/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Znight core runtime: compile-time DI container, lifecycle, plugins and marker decorators",
   "license": "MIT",
   "author": "Ugho STEPHAN",

package/src/errors.ts

@@ -7,7 +7,7 @@
  *   messaging, config, observability).
  * - From `ZNIGHT030`, each first-party package reserves a block of ten: `ZNIGHT030`–`039`
  *   `@znight/openapi`, `ZNIGHT040`–`049` `@znight/schedule`, `ZNIGHT050`–`059` `@znight/websocket`
- *   (reserved), `ZNIGHT060`–`069` `@znight/graphql`.
+ *   (reserved), `ZNIGHT060`–`069` `@znight/graphql`, `ZNIGHT070`–`079` `@znight/events`.
  *
  * Within a range, codes are allocated in order without gaps. A package uses its block for its own
  * failure modes, with one catch-all code for invalid usage and options, and reuses a lower code
@@ -138,6 +138,14 @@ export const ErrorCode = {
    * type or argument the SDL does not declare, a signature that does not conform to the SDL types.
    */
   GraphQLSchemaMismatch: 'ZNIGHT068',
+
+  // ZNIGHT070–079: @znight/events (RFC 0011)
+  /**
+   * Invalid event listener: an `@OnEvent` method whose parameter is not a class (or a union of
+   * classes), a generic or optional event, an event class the generated module cannot import, invalid
+   * options, the NestJS string form, a detached listener depending on a request-scoped external.
+   */
+  InvalidEventListener: 'ZNIGHT070',
 } as const
 
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode]
@@ -189,6 +197,7 @@ export const ERROR_DESCRIPTIONS: Readonly<Record<ErrorCode, string>> = {
   ZNIGHT066: 'Invalid GraphQL setup: metadata, schema, GraphQLPlugin options, driver or HttpPlugin missing',
   ZNIGHT067: 'Invalid GraphQL SDL: the schema-first .graphql files cannot be read, parsed or validated',
   ZNIGHT068: 'GraphQL schema mismatch: schema-first resolvers do not cover or conform to the SDL',
+  ZNIGHT070: 'Invalid event listener: an @OnEvent method does not listen to a class, or its options are invalid',
 }
 
 export interface ZnightErrorOptions extends ErrorOptions {

package/src/hooks.ts

@@ -33,6 +33,17 @@ export interface ZnightHooks {
    * emitted when listeners exist.
    */
   'graphql:operation': GraphQLOperationEvent
+  /**
+   * One publication of `@znight/events` (`EventPublisher.publish()` or `emit()`) that matched at least
+   * one listener (RFC 0011): wraps the inline phase with `hooks.run` when wrappers exist, then is
+   * emitted when listeners exist. A publication without listener produces nothing.
+   */
+  'events:publish': EventPublishEvent
+  /**
+   * One listener invocation of `@znight/events` (RFC 0011), inline or detached: wrapped with
+   * `hooks.run` when wrappers exist, then emitted when listeners exist.
+   */
+  'events:listener': EventListenerEvent
 }
 
 /**
@@ -227,6 +238,52 @@ export interface GraphQLOperationEvent {
   errors?: readonly GraphQLOperationError[]
 }
 
+/** How an application event was published (`EventPublishEvent.mode`). */
+export type EventPublishMode = 'publish' | 'emit'
+
+/**
+ * Instrumentation event of the `events:publish` hook, produced by `@znight/events` (RFC 0011) for a
+ * publication that matched at least one listener. The wrappers surround the inline phase (the
+ * detached listeners are scheduled after it succeeded); `error` and `failedListener` are set before
+ * `next()` rejects.
+ */
+export interface EventPublishEvent {
+  /** Class name of the event (`UserCreated`). */
+  readonly event: string
+  /** The published object. */
+  readonly payload: object
+  readonly mode: EventPublishMode
+  /** Number of inline listeners matched. */
+  readonly inline: number
+  /** Number of detached listeners matched. */
+  readonly detached: number
+  /** `performance.now()` when the publication started. */
+  readonly startTime: number
+  /** First inline error, set before `next()` rejects in the wrappers. */
+  error?: unknown
+  /** `Class.method` of the inline listener that failed. */
+  failedListener?: string
+}
+
+/**
+ * Instrumentation event of the `events:listener` hook, produced by `@znight/events` (RFC 0011) for
+ * every listener invocation. Inline listeners run in the publisher's async context, detached ones in
+ * a fresh scope of their own; `error` is set before `next()` rejects.
+ */
+export interface EventListenerEvent {
+  /** Class name of the event. */
+  readonly event: string
+  /** The published object. */
+  readonly payload: object
+  /** `Class.method` of the listener (`WelcomeMail.send`). */
+  readonly listener: string
+  readonly detached: boolean
+  /** `performance.now()` when the invocation started. */
+  readonly startTime: number
+  /** What the listener threw or rejected with. */
+  error?: unknown
+}
+
 /** Name of a declared hook. */
 export type HookName = keyof ZnightHooks
 

package/src/index.ts

@@ -38,6 +38,9 @@ export {
 export { isProviderDefinition } from './definition.ts'
 export * from './errors.ts'
 export {
+  type EventListenerEvent,
+  type EventPublishEvent,
+  type EventPublishMode,
   type GraphQLOperationError,
   type GraphQLOperationEvent,
   type GraphQLOperationOutcome,
@@ -78,6 +81,18 @@ export {
   silentLogger,
 } from './logger.ts'
 export * from './metadata.ts'
+export {
+  createParamDecorator,
+  type ParamContexts,
+  type ParamDataArgs,
+  type ParamDecorator,
+  type ParamFunctionOf,
+  type ParamResolver,
+  type ParamResolverClass,
+  type ParamResolverFunction,
+  type ParamResolverOf,
+  type ParamResolvers,
+} from './params.ts'
 export {
   type Plugin,
   type PluginContext,

package/src/params.ts

@@ -0,0 +1,89 @@
+/**
+ * Custom parameter decorators (RFC 0010). `createParamDecorator` returns a marker decorator, read
+ * by `@znight/compiler`, and keeps the resolvers that the generated `invoke` of each transport calls.
+ */
+import type { ParameterMarker } from './decorators.ts'
+
+/**
+ * Resolver contexts by transport. Each transport package adds its own entry through declaration
+ * merging (`http: HttpContext` in `@znight/http`, `graphql: ResolverContext`, `messaging:
+ * InboundMessage`); a transport that is not installed has no entry.
+ *
+ * ```ts
+ * declare module '@znight/core' {
+ *   interface ParamContexts {
+ *     http: HttpContext
+ *   }
+ * }
+ * ```
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: augmented by the transport packages (declaration merging)
+export interface ParamContexts {}
+
+/** A provider computing the value of a parameter, in the scope of the call (RFC 0010 §4.6). */
+export interface ParamResolver<C, T, D = undefined> {
+  resolve(ctx: C, data: D): T | PromiseLike<T>
+}
+
+/** A resolver function: receives the context of its transport and the data argument of the use. */
+export type ParamResolverFunction<C, T, D> = (ctx: C, data: D) => T | PromiseLike<T>
+
+/** The class of a provider implementing {@link ParamResolver} (bound at build time, resolved in the scope of the call). */
+export type ParamResolverClass<C, T, D> = abstract new (...args: never[]) => ParamResolver<C, T, D>
+
+/** Computes the value of a parameter: a function, or the class of a provider implementing {@link ParamResolver}. */
+export type ParamResolverOf<C, T, D> = ParamResolverFunction<C, T, D> | ParamResolverClass<C, T, D>
+
+/** The resolvers of a definition, by transport (keys of {@link ParamContexts}). */
+export type ParamResolvers<T, D> = {
+  readonly [K in keyof ParamContexts]?: ParamResolverOf<ParamContexts[K], T, D>
+}
+
+/** Arguments of a use: none when `D` is `undefined`, optional when `D` includes `undefined`, required otherwise. */
+export type ParamDataArgs<D> = undefined extends D ? [data?: D] : [data: D]
+
+/** What {@link createParamDecorator} returns: the decorator (a no-op marker) and its resolvers, for generated code. */
+export interface ParamDecorator<T, D = undefined> {
+  (...data: ParamDataArgs<D>): ParameterMarker
+  /** The resolvers of the definition, frozen. */
+  readonly resolvers: ParamResolvers<T, D>
+}
+
+/**
+ * The resolver function of a definition for a transport, as generated code calls it:
+ * `(CurrentUser.resolvers.http as ParamFunctionOf<typeof CurrentUser, 'http'>)(ctx, undefined)`.
+ * The compiler emits it only for function resolvers.
+ */
+export type ParamFunctionOf<P extends { readonly resolvers: object }, K extends keyof P['resolvers']> = Extract<
+  NonNullable<P['resolvers'][K]>,
+  // biome-ignore lint/suspicious/noExplicitAny: matches every function type, whatever its parameters
+  (...args: any[]) => unknown
+>
+
+function marker(): void {
+  // intentionally empty: decorators are compile-time markers
+}
+
+const parameterMarker: ParameterMarker = marker
+
+/**
+ * Defines a parameter decorator whose value is computed per call by a resolver of the handler's
+ * transport (RFC 0010). `T` (required) is the injected type, checked at build time against every
+ * decorated parameter; `D` is the type of the data argument (none by default). The definition must
+ * be an exported top-level `const`: the generated module imports it.
+ *
+ * ```ts
+ * export const CurrentUser = createParamDecorator<User>({
+ *   http: ctx => userOf(ctx.state),
+ *   graphql: ctx => userOf(ctx.operation.state),
+ * })
+ *
+ * @Get('/me')
+ * me(@CurrentUser() user: User) { ... }
+ * ```
+ */
+export function createParamDecorator<T, D = undefined>(resolvers: ParamResolvers<T, D>): ParamDecorator<T, D> {
+  const decorator = ((..._data: ParamDataArgs<D>): ParameterMarker => parameterMarker) as ParamDecorator<T, D>
+  Object.defineProperty(decorator, 'resolvers', { value: Object.freeze({ ...resolvers }), enumerable: true })
+  return decorator
+}