UNPKG

12.2 kBTypeScriptView Raw
1/// <reference types="node" />
2import { Binding, BindingFromClassOptions, Constructor, Context, DynamicValueProviderClass, Interceptor, InterceptorBindingOptions, JSONObject, Provider, ValueOrPromise } from '@loopback/context';
3import { Component } from './component';
4import { LifeCycleObserver } from './lifecycle';
5import { Server } from './server';
6import { ServiceOptions } from './service';
7/**
8 * Application is the container for various types of artifacts, such as
9 * components, servers, controllers, repositories, datasources, connectors,
10 * and models.
11 */
12export declare class Application extends Context implements LifeCycleObserver {
13 readonly options: ApplicationConfig;
14 /**
15 * A flag to indicate that the application is being shut down
16 */
17 private _isShuttingDown;
18 private _shutdownOptions;
19 private _signalListener;
20 private _initialized;
21 /**
22 * State of the application
23 */
24 private _state;
25 /**
26 * Get the state of the application. The initial state is `created` and it can
27 * transition as follows by `start` and `stop`:
28 *
29 * 1. start
30 * - !started -> starting -> started
31 * - started -> started (no-op)
32 * 2. stop
33 * - (started | initialized) -> stopping -> stopped
34 * - ! (started || initialized) -> stopped (no-op)
35 *
36 * Two types of states are expected:
37 * - stable, such as `started` and `stopped`
38 * - in process, such as `booting` and `starting`
39 *
40 * Operations such as `start` and `stop` can only be called at a stable state.
41 * The logic should immediately set the state to a new one indicating work in
42 * process, such as `starting` and `stopping`.
43 */
44 get state(): string;
45 /**
46 * Create an application with the given parent context
47 * @param parent - Parent context
48 */
49 constructor(parent: Context);
50 /**
51 * Create an application with the given configuration and parent context
52 * @param config - Application configuration
53 * @param parent - Parent context
54 */
55 constructor(config?: ApplicationConfig, parent?: Context);
56 /**
57 * Register a controller class with this application.
58 *
59 * @param controllerCtor - The controller class
60 * (constructor function).
61 * @param name - Optional controller name, default to the class name
62 * @returns The newly created binding, you can use the reference to
63 * further modify the binding, e.g. lock the value to prevent further
64 * modifications.
65 *
66 * @example
67 * ```ts
68 * class MyController {
69 * }
70 * app.controller(MyController).lock();
71 * ```
72 */
73 controller<T>(controllerCtor: ControllerClass<T>, nameOrOptions?: string | BindingFromClassOptions): Binding<T>;
74 /**
75 * Bind a Server constructor to the Application's master context.
76 * Each server constructor added in this way must provide a unique prefix
77 * to prevent binding overlap.
78 *
79 * @example
80 * ```ts
81 * app.server(RestServer);
82 * // This server constructor will be bound under "servers.RestServer".
83 * app.server(RestServer, "v1API");
84 * // This server instance will be bound under "servers.v1API".
85 * ```
86 *
87 * @param server - The server constructor.
88 * @param nameOrOptions - Optional override for name or options.
89 * @returns Binding for the server class
90 *
91 */
92 server<T extends Server>(ctor: Constructor<T>, nameOrOptions?: string | BindingFromClassOptions): Binding<T>;
93 /**
94 * Bind an array of Server constructors to the Application's master
95 * context.
96 * Each server added in this way will automatically be named based on the
97 * class constructor name with the "servers." prefix.
98 *
99 * @remarks
100 * If you wish to control the binding keys for particular server instances,
101 * use the app.server function instead.
102 * ```ts
103 * app.servers([
104 * RestServer,
105 * GRPCServer,
106 * ]);
107 * // Creates a binding for "servers.RestServer" and a binding for
108 * // "servers.GRPCServer";
109 * ```
110 *
111 * @param ctors - An array of Server constructors.
112 * @returns An array of bindings for the registered server classes
113 *
114 */
115 servers<T extends Server>(ctors: Constructor<T>[]): Binding[];
116 /**
117 * Retrieve the singleton instance for a bound server.
118 *
119 * @typeParam T - Server type
120 * @param ctor - The constructor that was used to make the
121 * binding.
122 * @returns A Promise of server instance
123 *
124 */
125 getServer<T extends Server>(target: Constructor<T> | string): Promise<T>;
126 /**
127 * Assert there is no other operation is in progress, i.e., the state is not
128 * `*ing`, such as `starting` or `stopping`.
129 *
130 * @param op - The operation name, such as 'boot', 'start', or 'stop'
131 */
132 protected assertNotInProcess(op: string): void;
133 /**
134 * Assert current state of the application to be one of the expected values
135 * @param op - The operation name, such as 'boot', 'start', or 'stop'
136 * @param states - Valid states
137 */
138 protected assertInStates(op: string, ...states: string[]): void;
139 /**
140 * Transition the application to a new state and emit an event
141 * @param state - The new state
142 */
143 protected setState(state: string): void;
144 protected awaitState(state: string): Promise<void>;
145 /**
146 * Initialize the application, and all of its registered observers. The
147 * application state is checked to ensure the integrity of `initialize`.
148 *
149 * If the application is already initialized, no operation is performed.
150 *
151 * This method is automatically invoked by `start()` if the application is not
152 * initialized.
153 */
154 init(): Promise<void>;
155 /**
156 * Register a function to be called when the application initializes.
157 *
158 * This is a shortcut for adding a binding for a LifeCycleObserver
159 * implementing a `init()` method.
160 *
161 * @param fn The function to invoke, it can be synchronous (returning `void`)
162 * or asynchronous (returning `Promise<void>`).
163 * @returns The LifeCycleObserver binding created.
164 */
165 onInit(fn: () => ValueOrPromise<void>): Binding<LifeCycleObserver>;
166 /**
167 * Start the application, and all of its registered observers. The application
168 * state is checked to ensure the integrity of `start`.
169 *
170 * If the application is not initialized, it calls first `init()` to
171 * initialize the application. This only happens if `start()` is called for
172 * the first time.
173 *
174 * If the application is already started, no operation is performed.
175 */
176 start(): Promise<void>;
177 /**
178 * Register a function to be called when the application starts.
179 *
180 * This is a shortcut for adding a binding for a LifeCycleObserver
181 * implementing a `start()` method.
182 *
183 * @param fn The function to invoke, it can be synchronous (returning `void`)
184 * or asynchronous (returning `Promise<void>`).
185 * @returns The LifeCycleObserver binding created.
186 */
187 onStart(fn: () => ValueOrPromise<void>): Binding<LifeCycleObserver>;
188 /**
189 * Stop the application instance and all of its registered observers. The
190 * application state is checked to ensure the integrity of `stop`.
191 *
192 * If the application is already stopped or not started, no operation is
193 * performed.
194 */
195 stop(): Promise<void>;
196 /**
197 * Register a function to be called when the application starts.
198 *
199 * This is a shortcut for adding a binding for a LifeCycleObserver
200 * implementing a `start()` method.
201 *
202 * @param fn The function to invoke, it can be synchronous (returning `void`)
203 * or asynchronous (returning `Promise<void>`).
204 * @returns The LifeCycleObserver binding created.
205 */
206 onStop(fn: () => ValueOrPromise<void>): Binding<LifeCycleObserver>;
207 private getLifeCycleObserverRegistry;
208 /**
209 * Add a component to this application and register extensions such as
210 * controllers, providers, and servers from the component.
211 *
212 * @param componentCtor - The component class to add.
213 * @param nameOrOptions - Optional component name or options, default to the
214 * class name
215 *
216 * @example
217 * ```ts
218 *
219 * export class ProductComponent {
220 * controllers = [ProductController];
221 * repositories = [ProductRepo, UserRepo];
222 * providers = {
223 * [AUTHENTICATION_STRATEGY]: AuthStrategy,
224 * [AUTHORIZATION_ROLE]: Role,
225 * };
226 * };
227 *
228 * app.component(ProductComponent);
229 * ```
230 */
231 component<T extends Component = Component>(componentCtor: Constructor<T>, nameOrOptions?: string | BindingFromClassOptions): Binding<T>;
232 /**
233 * Set application metadata. `@loopback/boot` calls this method to populate
234 * the metadata from `package.json`.
235 *
236 * @param metadata - Application metadata
237 */
238 setMetadata(metadata: ApplicationMetadata): void;
239 /**
240 * Register a life cycle observer class
241 * @param ctor - A class implements LifeCycleObserver
242 * @param nameOrOptions - Optional name or options for the life cycle observer
243 */
244 lifeCycleObserver<T extends LifeCycleObserver>(ctor: Constructor<T>, nameOrOptions?: string | BindingFromClassOptions): Binding<T>;
245 /**
246 * Add a service to this application.
247 *
248 * @param cls - The service or provider class
249 *
250 * @example
251 *
252 * ```ts
253 * // Define a class to be bound via ctx.toClass()
254 * @injectable({scope: BindingScope.SINGLETON})
255 * export class LogService {
256 * log(msg: string) {
257 * console.log(msg);
258 * }
259 * }
260 *
261 * // Define a class to be bound via ctx.toProvider()
262 * import {v4 as uuidv4} from 'uuid';
263 * export class UuidProvider implements Provider<string> {
264 * value() {
265 * return uuidv4();
266 * }
267 * }
268 *
269 * // Register the local services
270 * app.service(LogService);
271 * app.service(UuidProvider, 'uuid');
272 *
273 * export class MyController {
274 * constructor(
275 * @inject('services.uuid') private uuid: string,
276 * @inject('services.LogService') private log: LogService,
277 * ) {
278 * }
279 *
280 * greet(name: string) {
281 * this.log(`Greet request ${this.uuid} received: ${name}`);
282 * return `${this.uuid}: ${name}`;
283 * }
284 * }
285 * ```
286 */
287 service<S>(cls: ServiceOrProviderClass<S>, nameOrOptions?: string | ServiceOptions): Binding<S>;
288 /**
289 * Register an interceptor
290 * @param interceptor - An interceptor function or provider class
291 * @param nameOrOptions - Binding name or options
292 */
293 interceptor(interceptor: Interceptor | Constructor<Provider<Interceptor>>, nameOrOptions?: string | InterceptorBindingOptions): Binding<Interceptor>;
294 /**
295 * Set up signals that are captured to shutdown the application
296 */
297 protected setupShutdown(): (signal: string) => Promise<void>;
298 private registerSignalListener;
299 private removeSignalListener;
300}
301/**
302 * Options to set up application shutdown
303 */
304export type ShutdownOptions = {
305 /**
306 * An array of signals to be trapped for graceful shutdown
307 */
308 signals?: NodeJS.Signals[];
309 /**
310 * Period in milliseconds to wait for the grace shutdown to finish before
311 * exiting the process
312 */
313 gracePeriod?: number;
314};
315/**
316 * Configuration for application
317 */
318export interface ApplicationConfig {
319 /**
320 * Name of the application context
321 */
322 name?: string;
323 /**
324 * Configuration for signals that shut down the application
325 */
326 shutdown?: ShutdownOptions;
327 /**
328 * Other properties
329 */
330 [prop: string]: any;
331}
332export type ControllerClass<T = any> = Constructor<T>;
333export type ServiceOrProviderClass<T = any> = Constructor<T | Provider<T>> | DynamicValueProviderClass<T>;
334/**
335 * Type description for `package.json`
336 */
337export interface ApplicationMetadata extends JSONObject {
338 name: string;
339 version: string;
340 description: string;
341}
342
\No newline at end of file