declare module '@ember/engine' { export { getEngineParent, setEngineParent } from '@ember/engine/parent'; import Namespace from '@ember/application/namespace'; import { Registry } from '@ember/-internals/container'; import type { ResolverClass } from '@ember/-internals/container'; import type { EngineInstanceOptions } from '@ember/engine/instance'; import EngineInstance from '@ember/engine/instance'; import { RegistryProxyMixin } from '@ember/-internals/runtime'; export interface Initializer { name: string; initialize: (target: T) => void; before?: string | string[]; after?: string | string[]; } /** @module @ember/engine */ /** The `Engine` class contains core functionality for both applications and engines. Each engine manages a registry that's used for dependency injection and exposed through `RegistryProxy`. Engines also manage initializers and instance initializers. Engines can spawn `EngineInstance` instances via `buildInstance()`. @class Engine @extends Ember.Namespace @uses RegistryProxyMixin @public */ interface Engine extends RegistryProxyMixin {} const Engine_base: Readonly & (new (owner?: import('@ember/owner').default | undefined) => Namespace) & import('@ember/object/mixin').default; class Engine extends Engine_base { static initializers: Record>; static instanceInitializers: Record>; /** The goal of initializers should be to register dependencies and injections. This phase runs once. Because these initializers may load code, they are allowed to defer application readiness and advance it. If you need to access the container or store you should use an InstanceInitializer that will be run after all initializers and therefore after all code is loaded and the app is ready. Initializer receives an object which has the following attributes: `name`, `before`, `after`, `initialize`. The only required attribute is `initialize`, all others are optional. * `name` allows you to specify under which name the initializer is registered. This must be a unique name, as trying to register two initializers with the same name will result in an error. ```app/initializer/named-initializer.js import { debug } from '@ember/debug'; export function initialize() { debug('Running namedInitializer!'); } export default { name: 'named-initializer', initialize }; ``` * `before` and `after` are used to ensure that this initializer is ran prior or after the one identified by the value. This value can be a single string or an array of strings, referencing the `name` of other initializers. An example of ordering initializers, we create an initializer named `first`: ```app/initializer/first.js import { debug } from '@ember/debug'; export function initialize() { debug('First initializer!'); } export default { name: 'first', initialize }; ``` ```bash // DEBUG: First initializer! ``` We add another initializer named `second`, specifying that it should run after the initializer named `first`: ```app/initializer/second.js import { debug } from '@ember/debug'; export function initialize() { debug('Second initializer!'); } export default { name: 'second', after: 'first', initialize }; ``` ``` // DEBUG: First initializer! // DEBUG: Second initializer! ``` Afterwards we add a further initializer named `pre`, this time specifying that it should run before the initializer named `first`: ```app/initializer/pre.js import { debug } from '@ember/debug'; export function initialize() { debug('Pre initializer!'); } export default { name: 'pre', before: 'first', initialize }; ``` ```bash // DEBUG: Pre initializer! // DEBUG: First initializer! // DEBUG: Second initializer! ``` Finally we add an initializer named `post`, specifying it should run after both the `first` and the `second` initializers: ```app/initializer/post.js import { debug } from '@ember/debug'; export function initialize() { debug('Post initializer!'); } export default { name: 'post', after: ['first', 'second'], initialize }; ``` ```bash // DEBUG: Pre initializer! // DEBUG: First initializer! // DEBUG: Second initializer! // DEBUG: Post initializer! ``` * `initialize` is a callback function that receives one argument, `application`, on which you can operate. Example of using `application` to register an adapter: ```app/initializer/api-adapter.js import ApiAdapter from '../utils/api-adapter'; export function initialize(application) { application.register('api-adapter:main', ApiAdapter); } export default { name: 'post', after: ['first', 'second'], initialize }; ``` @method initializer @param initializer {Object} @public */ static initializer: (this: typeof Engine, initializer: Initializer) => void; /** Instance initializers run after all initializers have run. Because instance initializers run after the app is fully set up. We have access to the store, container, and other items. However, these initializers run after code has loaded and are not allowed to defer readiness. Instance initializer receives an object which has the following attributes: `name`, `before`, `after`, `initialize`. The only required attribute is `initialize`, all others are optional. * `name` allows you to specify under which name the instanceInitializer is registered. This must be a unique name, as trying to register two instanceInitializer with the same name will result in an error. ```app/initializer/named-instance-initializer.js import { debug } from '@ember/debug'; export function initialize() { debug('Running named-instance-initializer!'); } export default { name: 'named-instance-initializer', initialize }; ``` * `before` and `after` are used to ensure that this initializer is ran prior or after the one identified by the value. This value can be a single string or an array of strings, referencing the `name` of other initializers. * See Application.initializer for discussion on the usage of before and after. Example instanceInitializer to preload data into the store. ```app/initializer/preload-data.js export function initialize(application) { var userConfig, userConfigEncoded, store; // We have a HTML escaped JSON representation of the user's basic // configuration generated server side and stored in the DOM of the main // index.html file. This allows the app to have access to a set of data // without making any additional remote calls. Good for basic data that is // needed for immediate rendering of the page. Keep in mind, this data, // like all local models and data can be manipulated by the user, so it // should not be relied upon for security or authorization. // Grab the encoded data from the meta tag userConfigEncoded = document.querySelector('head meta[name=app-user-config]').attr('content'); // Unescape the text, then parse the resulting JSON into a real object userConfig = JSON.parse(unescape(userConfigEncoded)); // Lookup the store store = application.lookup('service:store'); // Push the encoded JSON into the store store.pushPayload(userConfig); } export default { name: 'named-instance-initializer', initialize }; ``` @method instanceInitializer @param instanceInitializer @public */ static instanceInitializer: ( this: typeof Engine, initializer: Initializer ) => void; /** This creates a registry with the default Ember naming conventions. It also configures the registry: * registered views are created every time they are looked up (they are not singletons) * registered templates are not factories; the registered value is returned directly. * the router receives the application as its `namespace` property * all controllers receive the router as their `target` and `controllers` properties * all controllers receive the application as their `namespace` property * the application view receives the application controller as its `controller` property * the application view receives the application template as its `defaultTemplate` property @method buildRegistry @static @param {Application} namespace the application for which to build the registry @return {Ember.Registry} the built registry @private */ static buildRegistry(namespace: Engine): Registry; /** Set this to provide an alternate class to `DefaultResolver` @property resolver @public */ Resolver: ResolverClass; init(properties: object | undefined): void; /** A private flag indicating whether an engine's initializers have run yet. @private @property _initializersRan */ _initializersRan: boolean; /** Ensure that initializers are run once, and only once, per engine. @private @method ensureInitializers */ ensureInitializers(): void; /** Create an EngineInstance for this engine. @public @method buildInstance @return {EngineInstance} the engine instance */ buildInstance(options?: EngineInstanceOptions): EngineInstance; /** Build and configure the registry for the current engine. @private @method buildRegistry @return {Ember.Registry} the configured registry */ buildRegistry(): Registry; /** @private @method initializer */ initializer(initializer: Initializer): void; /** @private @method instanceInitializer */ instanceInitializer(initializer: Initializer): void; /** @private @method runInitializers */ runInitializers(): void; /** @private @since 1.12.0 @method runInstanceInitializers */ runInstanceInitializers(instance: T): void; _runInitializer< B extends 'initializers' | 'instanceInitializers', T extends B extends 'initializers' ? Engine : EngineInstance >(bucketName: B, cb: (name: string, initializer: Initializer | undefined) => void): void; } /** @internal */ export function buildInitializerMethod< B extends 'initializers' | 'instanceInitializers', T extends B extends 'initializers' ? Engine : EngineInstance >(bucketName: B, humanName: string): (this: typeof Engine, initializer: Initializer) => void; export default Engine; }