UNPKG

9.51 kBTypeScriptView Raw
1import { MetadataMap } from '@loopback/metadata';
2import { Binding, BindingTag } from './binding';
3import { BindingFilter, BindingSelector } from './binding-filter';
4import { BindingAddress, BindingKey } from './binding-key';
5import { BindingComparator } from './binding-sorter';
6import { BindingCreationPolicy, Context } from './context';
7import { JSONObject } from './json-types';
8import { ResolutionOptions, ResolutionSession } from './resolution-session';
9import { BoundValue, Constructor, ValueOrPromise } from './value-promise';
10/**
11 * A function to provide resolution of injected values.
12 *
13 * @example
14 * ```ts
15 * const resolver: ResolverFunction = (ctx, injection, session) {
16 * return session.currentBinding?.key;
17 * }
18 * ```
19 */
20export interface ResolverFunction {
21 (ctx: Context, injection: Readonly<Injection>, session: ResolutionSession): ValueOrPromise<BoundValue>;
22}
23/**
24 * An object to provide metadata for `@inject`
25 */
26export interface InjectionMetadata extends Omit<ResolutionOptions, 'session'> {
27 /**
28 * Name of the decorator function, such as `@inject` or `@inject.setter`.
29 * It's usually set by the decorator implementation.
30 */
31 decorator?: string;
32 /**
33 * Optional comparator for matched bindings
34 */
35 bindingComparator?: BindingComparator;
36 /**
37 * Other attributes
38 */
39 [attribute: string]: BoundValue;
40}
41/**
42 * Descriptor for an injection point
43 */
44export interface Injection<ValueType = BoundValue> {
45 target: Object;
46 member?: string;
47 methodDescriptorOrParameterIndex?: TypedPropertyDescriptor<ValueType> | number;
48 bindingSelector: BindingSelector<ValueType>;
49 metadata: InjectionMetadata;
50 resolve?: ResolverFunction;
51}
52/**
53 * A decorator to annotate method arguments for automatic injection
54 * by LoopBack IoC container.
55 *
56 * @example
57 * Usage - Typescript:
58 *
59 * ```ts
60 * class InfoController {
61 * @inject('authentication.user') public userName: string;
62 *
63 * constructor(@inject('application.name') public appName: string) {
64 * }
65 * // ...
66 * }
67 * ```
68 *
69 * Usage - JavaScript:
70 *
71 * - TODO(bajtos)
72 *
73 * @param bindingSelector - What binding to use in order to resolve the value of the
74 * decorated constructor parameter or property.
75 * @param metadata - Optional metadata to help the injection
76 * @param resolve - Optional function to resolve the injection
77 *
78 */
79export declare function inject(bindingSelector: BindingSelector, metadata?: InjectionMetadata, resolve?: ResolverFunction): (target: Object, member: string | undefined, methodDescriptorOrParameterIndex?: TypedPropertyDescriptor<BoundValue> | number) => void;
80/**
81 * The function injected by `@inject.getter(bindingSelector)`. It can be used
82 * to fetch bound value(s) from the underlying binding(s). The return value will
83 * be an array if the `bindingSelector` is a `BindingFilter` function.
84 */
85export type Getter<T> = () => Promise<T>;
86export declare namespace Getter {
87 /**
88 * Convert a value into a Getter returning that value.
89 * @param value
90 */
91 function fromValue<T>(value: T): Getter<T>;
92}
93/**
94 * The function injected by `@inject.setter(bindingKey)`. It sets the underlying
95 * binding to a constant value using `binding.to(value)`.
96 *
97 * @example
98 *
99 * ```ts
100 * setterFn('my-value');
101 * ```
102 * @param value - The value for the underlying binding
103 */
104export type Setter<T> = (value: T) => void;
105/**
106 * Metadata for `@inject.binding`
107 */
108export interface InjectBindingMetadata extends InjectionMetadata {
109 /**
110 * Controls how the underlying binding is resolved/created
111 */
112 bindingCreation?: BindingCreationPolicy;
113}
114export declare namespace inject {
115 /**
116 * Inject a function for getting the actual bound value.
117 *
118 * This is useful when implementing Actions, where
119 * the action is instantiated for Sequence constructor, but some
120 * of action's dependencies become bound only after other actions
121 * have been executed by the sequence.
122 *
123 * See also `Getter<T>`.
124 *
125 * @param bindingSelector - The binding key or filter we want to eventually get
126 * value(s) from.
127 * @param metadata - Optional metadata to help the injection
128 */
129 const getter: (bindingSelector: BindingSelector<unknown>, metadata?: InjectionMetadata) => (target: Object, member: string | undefined, methodDescriptorOrParameterIndex?: number | TypedPropertyDescriptor<any> | undefined) => void;
130 /**
131 * Inject a function for setting (binding) the given key to a given
132 * value. (Only static/constant values are supported, it's not possible
133 * to bind a key to a class or a provider.)
134 *
135 * This is useful e.g. when implementing Actions that are contributing
136 * new Elements.
137 *
138 * See also `Setter<T>`.
139 *
140 * @param bindingKey - The key of the value we want to set.
141 * @param metadata - Optional metadata to help the injection
142 */
143 const setter: (bindingKey: BindingAddress, metadata?: InjectBindingMetadata) => (target: Object, member: string | undefined, methodDescriptorOrParameterIndex?: number | TypedPropertyDescriptor<any> | undefined) => void;
144 /**
145 * Inject the binding object for the given key. This is useful if a binding
146 * needs to be set up beyond just a constant value allowed by
147 * `@inject.setter`. The injected binding is found or created based on the
148 * `metadata.bindingCreation` option. See `BindingCreationPolicy` for more
149 * details.
150 *
151 * @example
152 *
153 * ```ts
154 * class MyAuthAction {
155 * @inject.binding('current-user', {
156 * bindingCreation: BindingCreationPolicy.ALWAYS_CREATE,
157 * })
158 * private userBinding: Binding<UserProfile>;
159 *
160 * async authenticate() {
161 * this.userBinding.toDynamicValue(() => {...});
162 * }
163 * }
164 * ```
165 *
166 * @param bindingKey - Binding key
167 * @param metadata - Metadata for the injection
168 */
169 const binding: (bindingKey?: string | BindingKey<unknown>, metadata?: InjectBindingMetadata) => (target: Object, member: string | undefined, methodDescriptorOrParameterIndex?: number | TypedPropertyDescriptor<any> | undefined) => void;
170 /**
171 * Inject an array of values by a tag pattern string or regexp
172 *
173 * @example
174 * ```ts
175 * class AuthenticationManager {
176 * constructor(
177 * @inject.tag('authentication.strategy') public strategies: Strategy[],
178 * ) {}
179 * }
180 * ```
181 * @param bindingTag - Tag name, regex or object
182 * @param metadata - Optional metadata to help the injection
183 */
184 const tag: (bindingTag: BindingTag | RegExp, metadata?: InjectionMetadata) => (target: Object, member: string | undefined, methodDescriptorOrParameterIndex?: number | TypedPropertyDescriptor<any> | undefined) => void;
185 /**
186 * Inject matching bound values by the filter function
187 *
188 * @example
189 * ```ts
190 * class MyControllerWithView {
191 * @inject.view(filterByTag('foo'))
192 * view: ContextView<string[]>;
193 * }
194 * ```
195 * @param bindingFilter - A binding filter function
196 * @param metadata
197 */
198 const view: (bindingFilter: BindingFilter, metadata?: InjectionMetadata) => (target: Object, member: string | undefined, methodDescriptorOrParameterIndex?: number | TypedPropertyDescriptor<any> | undefined) => void;
199 /**
200 * Inject the context object.
201 *
202 * @example
203 * ```ts
204 * class MyProvider {
205 * constructor(@inject.context() private ctx: Context) {}
206 * }
207 * ```
208 */
209 const context: () => (target: Object, member: string | undefined, methodDescriptorOrParameterIndex?: number | TypedPropertyDescriptor<any> | undefined) => void;
210}
211/**
212 * Assert the target type inspected from TypeScript for injection to be the
213 * expected type. If the types don't match, an error is thrown.
214 * @param injection - Injection information
215 * @param expectedType - Expected type
216 * @param expectedTypeName - Name of the expected type to be used in the error
217 * @returns The name of the target
218 */
219export declare function assertTargetType(injection: Readonly<Injection>, expectedType: Function, expectedTypeName?: string): string;
220/**
221 * Return an array of injection objects for parameters
222 * @param target - The target class for constructor or static methods,
223 * or the prototype for instance methods
224 * @param method - Method name, undefined for constructor
225 */
226export declare function describeInjectedArguments(target: Object, method?: string): Readonly<Injection>[];
227/**
228 * Inspect the target type for the injection to find out the corresponding
229 * JavaScript type
230 * @param injection - Injection information
231 */
232export declare function inspectTargetType(injection: Readonly<Injection>): Function | undefined;
233/**
234 * Return a map of injection objects for properties
235 * @param target - The target class for static properties or
236 * prototype for instance properties.
237 */
238export declare function describeInjectedProperties(target: Object): MetadataMap<Readonly<Injection>>;
239/**
240 * Inspect injections for a binding created with `toClass` or `toProvider`
241 * @param binding - Binding object
242 */
243export declare function inspectInjections(binding: Readonly<Binding<unknown>>): JSONObject;
244/**
245 * Check if the given class has `@inject` or other decorations that map to
246 * `@inject`.
247 *
248 * @param cls - Class with possible `@inject` decorations
249 */
250export declare function hasInjections(cls: Constructor<unknown>): boolean;