UNPKG

4.78 kBTypeScriptView Raw
1import { BindingFilter } from './binding-filter';
2import { BindingAddress } from './binding-key';
3import { BindingComparator } from './binding-sorter';
4import { Context } from './context';
5import { InvocationResult } from './invocation';
6import { ValueOrPromise } from './value-promise';
7/**
8 * Any type except `void`. We use this type to enforce that interceptor functions
9 * always return a value (including undefined or null).
10 */
11export type NonVoid = string | number | boolean | null | undefined | object;
12/**
13 * The `next` function that can be used to invoke next generic interceptor in
14 * the chain
15 */
16export type Next = () => ValueOrPromise<NonVoid>;
17/**
18 * An interceptor function to be invoked in a chain for the given context.
19 * It serves as the base interface for various types of interceptors, such
20 * as method invocation interceptor or request/response processing interceptor.
21 *
22 * @remarks
23 * We choose `NonVoid` as the return type to avoid possible bugs that an
24 * interceptor forgets to return the value from `next()`. For example, the code
25 * below will fail to compile.
26 *
27 * ```ts
28 * const myInterceptor: Interceptor = async (ctx, next) {
29 * // preprocessing
30 * // ...
31 *
32 * // There is a subtle bug that the result from `next()` is not further
33 * // returned back to the upstream interceptors
34 * const result = await next();
35 *
36 * // postprocessing
37 * // ...
38 * // We must have `return ...` here
39 * // either return `result` or another value if the interceptor decides to
40 * // have its own response
41 * }
42 * ```
43 *
44 * @typeParam C - `Context` class or a subclass of `Context`
45 * @param context - Context object
46 * @param next - A function to proceed with downstream interceptors or the
47 * target operation
48 *
49 * @returns The invocation result as a value (sync) or promise (async).
50 */
51export type GenericInterceptor<C extends Context = Context> = (context: C, next: Next) => ValueOrPromise<NonVoid>;
52/**
53 * Interceptor function or a binding key that resolves a generic interceptor
54 * function
55 * @typeParam C - `Context` class or a subclass of `Context`
56 * @typeParam T - Return type of `next()`
57 */
58export type GenericInterceptorOrKey<C extends Context = Context> = BindingAddress<GenericInterceptor<C>> | GenericInterceptor<C>;
59/**
60 * A chain of generic interceptors to be invoked for the given context
61 *
62 * @typeParam C - `Context` class or a subclass of `Context`
63 */
64export declare class GenericInterceptorChain<C extends Context = Context> {
65 private context;
66 /**
67 * A getter for an array of interceptor functions or binding keys
68 */
69 protected getInterceptors: () => GenericInterceptorOrKey<C>[];
70 /**
71 * Create an invocation chain with a list of interceptor functions or
72 * binding keys
73 * @param context - Context object
74 * @param interceptors - An array of interceptor functions or binding keys
75 */
76 constructor(context: C, interceptors: GenericInterceptorOrKey<C>[]);
77 /**
78 * Create an invocation interceptor chain with a binding filter and comparator.
79 * The interceptors are discovered from the context using the binding filter and
80 * sorted by the comparator (if provided).
81 *
82 * @param context - Context object
83 * @param filter - A binding filter function to select interceptors
84 * @param comparator - An optional comparator to sort matched interceptor bindings
85 */
86 constructor(context: C, filter: BindingFilter, comparator?: BindingComparator);
87 /**
88 * Invoke the interceptor chain
89 */
90 invokeInterceptors(finalHandler?: Next): ValueOrPromise<InvocationResult>;
91 /**
92 * Use the interceptor chain as an interceptor
93 */
94 asInterceptor(): GenericInterceptor<C>;
95 /**
96 * Invoke downstream interceptors or the target method
97 */
98 private next;
99 /**
100 * Invoke downstream interceptors
101 */
102 private invokeNextInterceptor;
103 /**
104 * Return the interceptor function or resolve the interceptor function as a binding
105 * from the context
106 *
107 * @param interceptor - Interceptor function or binding key
108 */
109 private loadInterceptor;
110}
111/**
112 * Invoke a chain of interceptors with the context
113 * @param context - Context object
114 * @param interceptors - An array of interceptor functions or binding keys
115 */
116export declare function invokeInterceptors<C extends Context = Context, T = InvocationResult>(context: C, interceptors: GenericInterceptorOrKey<C>[]): ValueOrPromise<T | undefined>;
117/**
118 * Compose a list of interceptors as a single interceptor
119 * @param interceptors - A list of interceptor functions or binding keys
120 */
121export declare function composeInterceptors<C extends Context = Context>(...interceptors: GenericInterceptorOrKey<C>[]): GenericInterceptor<C>;