@znight/core 0.2.2 → 0.4.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:
@@ -344,7 +374,7 @@ without depending on each other:
 | `messaging:message` | `MessageDeliveryEvent`  | `@znight/messaging`, one delivery                                            |
 | `messaging:publish` | `MessagePublishEvent`   | `@znight/messaging`, one `MessageBroker` publication                         |
 | `schedule:run`      | `ScheduledRunEvent`     | `@znight/schedule`, one occurrence of a job (executed or not, see `outcome`) |
-| `graphql:operation` | `GraphQLOperationEvent` | `@znight/graphql` (planned, RFC 0005), one GraphQL operation                 |
+| `graphql:operation` | `GraphQLOperationEvent` | `@znight/graphql` (RFC 0005), one GraphQL operation                          |
 
 `ScheduledRunEvent` carries `job`, `kind` (`cron` / `interval` / `timeout`), `host`, `method`,
 `runId`, `trigger` (`schedule` / `start` / `manual` / `queued`), `scheduledAt` (epoch ms),
@@ -361,8 +391,10 @@ threw), so a wrapper that reports it reads `event.outcome ?? (nextRejected ? 'fa
 
 `GraphQLOperationEvent` carries `operationType` (`query` / `mutation` / `subscription`, `undefined`
 when the request was rejected before an operation was selected), `operationName`, `documentId`
-(SHA-256 of the query text), `transport` (`http` / `sse` / `direct`), `requestId`, `context` (the
-`GraphQLContext`), `startTime`, and, once settled, `outcome` (`success` / `partial` / `error` /
+(SHA-256 of the query text), `transport` (`http` / `sse` / `ws` / `direct`; `ws` is reserved for
+`graphql-ws`), `driver` (the GraphQL driver that received the operation: `builtin` for the built-in
+transport and direct calls, `yoga`...), `requestId`, `context` (the `GraphQLContext`), `startTime`,
+and, once settled, `outcome` (`success` / `partial` / `error` /
 `rejected`) and `errors` (`{ message, code, path? }`, as sent to the client). A subscription is one
 operation from its start to its end.
 

package/dist/index.d.mts

@@ -783,9 +783,10 @@ interface ScheduledRunEvent {
 type GraphQLOperationType = "query" | "mutation" | "subscription";
 /**
  * How a GraphQL operation reached the server (`GraphQLOperationEvent.transport`): GraphQL over HTTP,
- * GraphQL over Server-Sent Events, or a direct call (`execute()` / `subscribe()` of the plugin).
+ * GraphQL over Server-Sent Events, GraphQL over WebSocket (`ws`, reserved for `graphql-ws`), or a
+ * direct call (`execute()` / `subscribe()` of the plugin).
  */
-type GraphQLOperationTransport = "http" | "sse" | "direct";
+type GraphQLOperationTransport = "http" | "sse" | "ws" | "direct";
 /**
  * Outcome of a GraphQL operation (`GraphQLOperationEvent.outcome`):
  *
@@ -817,6 +818,11 @@ interface GraphQLOperationEvent {
   /** SHA-256 (hex) of the query text, cached with the parsed document; `undefined` without a query. */
   readonly documentId: string | undefined;
   readonly transport: GraphQLOperationTransport;
+  /**
+   * The GraphQL driver that received the operation (RFC 0009): `'builtin'` for the built-in
+   * transport and for direct calls, `'yoga'`, `'apollo'` or a third-party driver's name otherwise.
+   */
+  readonly driver: string;
   readonly requestId: string;
   /** `GraphQLContext` from `@znight/graphql`. */
   readonly context: unknown;
@@ -1153,6 +1159,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.
  *
@@ -1184,5 +1249,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, 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

@@ -179,7 +179,7 @@ const ERROR_DESCRIPTIONS = {
 	ZNIGHT063: "Invalid GraphQL input: a type cannot be used in an input position",
 	ZNIGHT064: "Unresolvable abstract type: the members of a GraphQL union or interface cannot be told apart at runtime",
 	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 or HttpPlugin missing",
+	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"
 };
@@ -2236,11 +2236,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 +2275,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 +2301,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