@znight/core 0.3.0 → 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:

package/dist/index.d.mts

@@ -1159,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.
  *
@@ -1190,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

@@ -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