@znight/core 0.4.0 → 0.5.0

package/dist/index.d.mts

@@ -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
@@ -132,6 +132,12 @@ export declare const ErrorCode: {
    * type or argument the SDL does not declare, a signature that does not conform to the SDL types.
    */
   readonly GraphQLSchemaMismatch: "ZNIGHT068";
+  /**
+   * 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.
+   */
+  readonly InvalidEventListener: "ZNIGHT070";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** Short human readable description of every error code. */
@@ -652,6 +658,17 @@ 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;
 }
 /**
  * Instrumentation event of the `http:request` hook. Defined in core so that producers
@@ -833,6 +850,49 @@ interface GraphQLOperationEvent {
   /** Errors of the response (field and request errors), set before `hooks.run` resolves. */
   errors?: readonly GraphQLOperationError[];
 }
+/** How an application event was published (`EventPublishEvent.mode`). */
+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.
+ */
+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.
+ */
+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. */
 type HookName = keyof ZnightHooks;
 /** Event type of hook `K`. */
@@ -1249,5 +1309,5 @@ export declare class ZnightAggregateError extends ZnightError {
  * that were attached to it instead of being thrown. Empty when there are none.
  */
 export declare function getSuppressedErrors(error: unknown): readonly unknown[];
-export type { ApplicationOptions, ApplicationState, ClassKey, ClassMarker, ConsoleLike, ConsoleLoggerOptions, CoreLogger, GraphQLOperationError, GraphQLOperationEvent, GraphQLOperationOutcome, GraphQLOperationTransport, GraphQLOperationType, HookEvent, HookListener, HookName, HookWrapper, HooksOptions, HotContext, HttpRequestEvent, InitOptions, InjectableOptions, InterceptMethodOptions, InterceptOptionsArgs, InterceptorClass, InterceptorLink, LogContext, LogLevel, ManagedInstance, MessageDeliveryEvent, MessagePublishEvent, MethodInterceptor, MethodInvocation, MethodMarker, OnReady, OnStart, OnStop, OpenedScope, ParamContexts, ParamDataArgs, ParamDecorator, ParamFunctionOf, ParamResolver, ParamResolverClass, ParamResolverFunction, ParamResolverOf, ParamResolvers, ParameterMarker, Plugin, PluginContext, PluginHook, PluginOptions, PluginRootsContext, ProcessLike, ProviderKey, ProviderValues, ProvidesOptions, ScheduledRunAbortReason, ScheduledRunEvent, ScheduledRunOutcome, ScheduledRunTrigger, ScopeContext, ScopeValues, ShutdownOptions, ShutdownSignal, TypedToken, ZnightHooks };
+export type { ApplicationOptions, ApplicationState, ClassKey, ClassMarker, ConsoleLike, ConsoleLoggerOptions, CoreLogger, EventListenerEvent, EventPublishEvent, EventPublishMode, GraphQLOperationError, GraphQLOperationEvent, GraphQLOperationOutcome, GraphQLOperationTransport, GraphQLOperationType, HookEvent, HookListener, HookName, HookWrapper, HooksOptions, HotContext, HttpRequestEvent, InitOptions, InjectableOptions, InterceptMethodOptions, InterceptOptionsArgs, InterceptorClass, InterceptorLink, LogContext, LogLevel, ManagedInstance, MessageDeliveryEvent, MessagePublishEvent, MethodInterceptor, MethodInvocation, MethodMarker, OnReady, OnStart, OnStop, OpenedScope, ParamContexts, ParamDataArgs, ParamDecorator, ParamFunctionOf, ParamResolver, ParamResolverClass, ParamResolverFunction, ParamResolverOf, ParamResolvers, ParameterMarker, Plugin, PluginContext, PluginHook, PluginOptions, PluginRootsContext, ProcessLike, ProviderKey, ProviderValues, ProvidesOptions, ScheduledRunAbortReason, ScheduledRunEvent, ScheduledRunOutcome, ScheduledRunTrigger, ScopeContext, ScopeValues, ShutdownOptions, ShutdownSignal, TypedToken, ZnightHooks };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -9,7 +9,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 *   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
@@ -133,7 +133,13 @@ const ErrorCode = {
 	* Schema-first resolvers do not match the SDL (RFC 0007): a field without resolver, a resolver,
 	* type or argument the SDL does not declare, a signature that does not conform to the SDL types.
 	*/
-	GraphQLSchemaMismatch: "ZNIGHT068"
+	GraphQLSchemaMismatch: "ZNIGHT068",
+	/**
+	* 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"
 };
 /** Short human readable description of every error code. */
 const ERROR_DESCRIPTIONS = {
@@ -181,7 +187,8 @@ const ERROR_DESCRIPTIONS = {
 	ZNIGHT065: "Invalid loader: not a Loader of a BatchLoad provider, or a batch returning the wrong number of values",
 	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"
+	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"
 };
 /** Base class of every error thrown by Znight at runtime. */
 var ZnightError = class extends Error {