@znight/core 0.3.0 → 0.5.0

package/README.md

@@ -93,6 +93,36 @@ export class DatabaseFactory {
 }
 ```
 
+## Custom parameter decorators
+
+`createParamDecorator<T, D>(resolvers)` defines a parameter decorator of your own (RFC 0010), usable
+on HTTP routes, GraphQL fields and message handlers. Each key of `resolvers` is a transport
+(`http`, `graphql`, `messaging`: the installed transport packages declare them in `ParamContexts`)
+and its value computes the parameter: a function `(ctx, data) => T | PromiseLike<T>`, or the class
+of a provider implementing `ParamResolver<C, T, D>` (constructor injection, any scope).
+
+```ts
+import { createParamDecorator } from '@znight/core'
+import type { User } from './user.ts'
+
+/** The authenticated user, stored in the request state by the authentication guard. */
+export const CurrentUser = createParamDecorator<User>({
+  http: ctx => ctx.state.get('user') as User,
+})
+
+// @Get('/me') me(@CurrentUser() user: User) { ... }
+```
+
+- `T` (required) is the injected type; the compiler checks it against every decorated parameter.
+- `D` is the type of the data argument (`@Claim('sub')`): none by default, required when it excludes
+  `undefined`. The argument is a `value` argument: statically evaluable or an exported binding.
+- The definition is an exported top-level `const`: the generated module imports it and calls
+  `CurrentUser.resolvers.http(ctx, data)` (no lookup, no closure, no promise when the resolver
+  returns a value). `resolvers` is frozen.
+- Using the decorator on a handler of a transport it has no resolver for, on a constructor parameter,
+  with a data argument that cannot be emitted or on a parameter whose type does not accept `T` is a
+  ZNIGHT005 at build time.
+
 ## Application
 
 `Application.create(options)` builds the container and runs the plugins:

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`. */
@@ -1159,6 +1219,65 @@ export declare function isDisposable(instance: unknown, disposeMethod?: string):
  * @throws ZnightError (ZNIGHT021) when `disposeMethod` is not a method of `instance`.
  */
 export declare function disposeInstance(instance: unknown, disposeMethod?: string): unknown;
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+interface ParamContexts {}
+/** A provider computing the value of a parameter, in the scope of the call (RFC 0010 §4.6). */
+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. */
+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). */
+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}. */
+type ParamResolverOf<C, T, D> = ParamResolverFunction<C, T, D> | ParamResolverClass<C, T, D>;
+/** The resolvers of a definition, by transport (keys of {@link ParamContexts}). */
+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. */
+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. */
+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.
+ */
+type ParamFunctionOf<P extends {
+  readonly resolvers: object;
+}, K extends keyof P["resolvers"]> = Extract<NonNullable<P["resolvers"][K]>, (...args: any[]) => unknown>;
+/**
+ * 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 declare function createParamDecorator<T, D = undefined>(resolvers: ParamResolvers<T, D>): ParamDecorator<T, D>;
 /**
  * ZNIGHT015: a provider factory threw or rejected.
  *
@@ -1190,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, 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 {
@@ -2236,11 +2243,11 @@ function positive(value, fallback, name) {
 	return value;
 }
 // src/decorators.ts
-function marker() {}
-const classMarker = marker;
-const methodMarker = marker;
-const parameterMarker = marker;
-const classOrMethodMarker = marker;
+function marker$1() {}
+const classMarker = marker$1;
+const methodMarker = marker$1;
+const parameterMarker$1 = marker$1;
+const classOrMethodMarker = marker$1;
 /**
 * Declares a provider class. Its constructor parameters are injected.
 *
@@ -2275,11 +2282,11 @@ function Provides(_options) {
 }
 /** Injects the provider qualified with `name` (see {@link Named}). `name` is static. */
 function Inject(_name) {
-	return parameterMarker;
+	return parameterMarker$1;
 }
 /** Marks a dependency as optional: `undefined` is injected when no provider exists. */
 function Optional() {
-	return parameterMarker;
+	return parameterMarker$1;
 }
 /** Sets the qualifier of a provider class or `@Provides` method. `name` is static. */
 function Named(_name) {
@@ -2301,11 +2308,38 @@ function Primary() {
 function Intercept(_interceptor, ..._options) {
 	return methodMarker;
 }
+// src/params.ts
+function marker() {}
+const 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) { ... }
+* ```
+*/
+function createParamDecorator(resolvers) {
+	const decorator = ((..._data) => parameterMarker);
+	Object.defineProperty(decorator, "resolvers", {
+		value: Object.freeze({ ...resolvers }),
+		enumerable: true
+	});
+	return decorator;
+}
 // src/plugin.ts
 /** Resolves {@link PluginOptions}: calls the function form with the container, returns the others as is. */
 function resolveOptions(options, container) {
 	return typeof options === "function" ? options(container) : options;
 }
-export { Application, Container, CoreTokens, DelegatingLogger, ERROR_DESCRIPTIONS, ErrorCode, Factory, Hooks, Inject, Injectable, InstantiationError, Intercept, METADATA_VERSION, Named, Optional, Primary, Provides, ZnightAggregateError, ZnightError, applyInterceptors, callLifecycleHook, createConsoleLogger, describeToken, displayName, disposeInstance, formatPath, getSuppressedErrors, hasLifecycleHook, interceptMethod, isDisposable, isProviderDefinition, resolveOptions, silentLogger, token };
+export { Application, Container, CoreTokens, DelegatingLogger, ERROR_DESCRIPTIONS, ErrorCode, Factory, Hooks, Inject, Injectable, InstantiationError, Intercept, METADATA_VERSION, Named, Optional, Primary, Provides, ZnightAggregateError, ZnightError, applyInterceptors, callLifecycleHook, createConsoleLogger, createParamDecorator, describeToken, displayName, disposeInstance, formatPath, getSuppressedErrors, hasLifecycleHook, interceptMethod, isDisposable, isProviderDefinition, resolveOptions, silentLogger, token };
 
 //# sourceMappingURL=index.mjs.map