ember-source 4.10.0-beta.2 → 4.11.0-alpha.2

package/types/stable/@ember/destroyable/index.d.ts

@@ -0,0 +1,237 @@
+declare module '@ember/destroyable' {
+  export { assertDestroyablesDestroyed, associateDestroyableChild, destroy, enableDestroyableTracking, isDestroying, isDestroyed, } from '@glimmer/destroyable';
+  /**
+    Ember manages the lifecycles and lifetimes of many built in constructs, such
+    as components, and does so in a hierarchical way - when a parent component is
+    destroyed, all of its children are destroyed as well.
+
+    This destroyables API exposes the basic building blocks for destruction:
+
+    * registering a function to be ran when an object is destroyed
+    * checking if an object is in a destroying state
+    * associate an object as a child of another so that the child object will be destroyed
+      when the associated parent object is destroyed.
+
+    @module @ember/destroyable
+    @public
+  */
+  /**
+    This function is used to associate a destroyable object with a parent. When the parent
+    is destroyed, all registered children will also be destroyed.
+
+    ```js
+    class CustomSelect extends Component {
+      constructor(...args) {
+        super(...args);
+
+        // obj is now a child of the component. When the component is destroyed,
+        // obj will also be destroyed, and have all of its destructors triggered.
+        this.obj = associateDestroyableChild(this, {});
+      }
+    }
+    ```
+
+    Returns the associated child for convenience.
+
+    @method associateDestroyableChild
+    @for @ember/destroyable
+    @param {Object|Function} parent the destroyable to entangle the child destroyables lifetime with
+    @param {Object|Function} child the destroyable to be entangled with the parents lifetime
+    @returns {Object|Function} the child argument
+    @static
+    @public
+  */
+  /**
+   Receives a destroyable, and returns true if the destroyable has begun destroying. Otherwise returns
+   false.
+
+    ```js
+    let obj = {};
+    isDestroying(obj); // false
+    destroy(obj);
+    isDestroying(obj); // true
+    // ...sometime later, after scheduled destruction
+    isDestroyed(obj); // true
+    isDestroying(obj); // true
+    ```
+
+    @method isDestroying
+    @for @ember/destroyable
+    @param {Object|Function} destroyable the object to check
+    @returns {Boolean}
+    @static
+    @public
+  */
+  /**
+    Receives a destroyable, and returns true if the destroyable has finished destroying. Otherwise
+    returns false.
+
+    ```js
+    let obj = {};
+
+    isDestroyed(obj); // false
+    destroy(obj);
+
+    // ...sometime later, after scheduled destruction
+
+    isDestroyed(obj); // true
+    ```
+
+    @method isDestroyed
+    @for @ember/destroyable
+    @param {Object|Function} destroyable the object to check
+    @returns {Boolean}
+    @static
+    @public
+  */
+  /**
+    Initiates the destruction of a destroyable object. It runs all associated destructors, and then
+    destroys all children recursively.
+
+    ```js
+    let obj = {};
+
+    registerDestructor(obj, () => console.log('destroyed!'));
+
+    destroy(obj); // this will schedule the destructor to be called
+
+    // ...some time later, during scheduled destruction
+
+    // destroyed!
+    ```
+
+    Destruction via `destroy()` follows these steps:
+
+    1, Mark the destroyable such that `isDestroying(destroyable)` returns `true`
+    2, Call `destroy()` on each of the destroyable's associated children
+    3, Schedule calling the destroyable's destructors
+    4, Schedule setting destroyable such that `isDestroyed(destroyable)` returns `true`
+
+    This results in the entire tree of destroyables being first marked as destroying,
+    then having all of their destructors called, and finally all being marked as isDestroyed.
+    There won't be any in between states where some items are marked as `isDestroying` while
+    destroying, while others are not.
+
+    @method destroy
+    @for @ember/destroyable
+    @param {Object|Function} destroyable the object to destroy
+    @static
+    @public
+  */
+  /**
+    This function asserts that all objects which have associated destructors or associated children
+    have been destroyed at the time it is called. It is meant to be a low level hook that testing
+    frameworks can use to hook into and validate that all destroyables have in fact been destroyed.
+
+    This function requires that `enableDestroyableTracking` was called previously, and is only
+    available in non-production builds.
+
+    @method assertDestroyablesDestroyed
+    @for @ember/destroyable
+    @static
+    @public
+  */
+  /**
+    This function instructs the destroyable system to keep track of all destroyables (their
+    children, destructors, etc). This enables a future usage of `assertDestroyablesDestroyed`
+    to be used to ensure that all destroyable tasks (registered destructors and associated children)
+    have completed when `assertDestroyablesDestroyed` is called.
+
+    @method enableDestroyableTracking
+    @for @ember/destroyable
+    @static
+    @public
+  */
+  /**
+    Receives a destroyable object and a destructor function, and associates the
+    function with it. When the destroyable is destroyed with destroy, or when its
+    parent is destroyed, the destructor function will be called.
+
+    ```js
+    import Component from '@glimmer/component';
+    import { registerDestructor } from '@ember/destroyable';
+
+    class Modal extends Component {
+      @service resize;
+
+      constructor(...args) {
+        super(...args);
+
+        this.resize.register(this, this.layout);
+
+        registerDestructor(this, () => this.resize.unregister(this));
+      }
+    }
+    ```
+
+    Multiple destructors can be associated with a given destroyable, and they can be
+    associated over time, allowing libraries to dynamically add destructors as needed.
+    `registerDestructor` also returns the associated destructor function, for convenience.
+
+    The destructor function is passed a single argument, which is the destroyable itself.
+    This allows the function to be reused multiple times for many destroyables, rather
+    than creating a closure function per destroyable.
+
+    ```js
+    import Component from '@glimmer/component';
+    import { registerDestructor } from '@ember/destroyable';
+
+    function unregisterResize(instance) {
+      instance.resize.unregister(instance);
+    }
+
+    class Modal extends Component {
+      @service resize;
+
+      constructor(...args) {
+        super(...args);
+
+        this.resize.register(this, this.layout);
+
+        registerDestructor(this, unregisterResize);
+      }
+    }
+    ```
+
+    @method registerDestructor
+    @for @ember/destroyable
+    @param {Object|Function} destroyable the destroyable to register the destructor function with
+    @param {Function} destructor the destructor to run when the destroyable object is destroyed
+    @static
+    @public
+  */
+  export function registerDestructor<T extends object>(destroyable: T, destructor: (destroyable: T) => void): (destroyable: T) => void;
+  /**
+    Receives a destroyable and a destructor function, and de-associates the destructor
+    from the destroyable.
+
+    ```js
+    import Component from '@glimmer/component';
+    import { registerDestructor, unregisterDestructor } from '@ember/destroyable';
+
+    class Modal extends Component {
+      @service modals;
+
+      constructor(...args) {
+        super(...args);
+
+        this.modals.add(this);
+
+        this.modalDestructor = registerDestructor(this, () => this.modals.remove(this));
+      }
+
+      @action pinModal() {
+        unregisterDestructor(this, this.modalDestructor);
+      }
+    }
+    ```
+
+    @method unregisterDestructor
+    @for @ember/destroyable
+    @param {Object|Function} destroyable the destroyable to unregister the destructor function from
+    @param {Function} destructor the destructor to remove from the destroyable
+    @static
+    @public
+  */
+  export function unregisterDestructor<T extends object>(destroyable: T, destructor: (destroyable: T) => void): void;
+}

package/types/stable/@ember/engine/index.d.ts

@@ -0,0 +1,347 @@
+declare module '@ember/engine' {
+  export { getEngineParent, setEngineParent } from './lib/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<T> {
+      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<typeof Namespace> & (new (owner?: import("../owner").default | undefined) => Namespace);
+  class Engine extends Engine_base {
+      static initializers: Record<string, Initializer<Engine>>;
+      static instanceInitializers: Record<string, Initializer<EngineInstance>>;
+      /**
+        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<Engine>) => 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<EngineInstance>) => 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<Engine>): void;
+      /**
+        @private
+        @method instanceInitializer
+      */
+      instanceInitializer(initializer: Initializer<EngineInstance>): void;
+      /**
+        @private
+        @method runInitializers
+      */
+      runInitializers(): void;
+      /**
+        @private
+        @since 1.12.0
+        @method runInstanceInitializers
+      */
+      runInstanceInitializers<T extends EngineInstance>(instance: T): void;
+      _runInitializer<B extends 'initializers' | 'instanceInitializers', T extends B extends 'initializers' ? Engine : EngineInstance>(bucketName: B, cb: (name: string, initializer: Initializer<T> | 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<T>) => void;
+  export default Engine;
+}