@znight/core 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@znight/core",
-  "version": "0.4.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,