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

package/types/stable/@ember/-internals/owner/index.d.ts

@@ -0,0 +1,646 @@
+declare module '@ember/-internals/owner' {
+  /**
+    @module @ember/owner
+   */
+  /**
+    The name for a factory consists of a namespace and the name of a specific type
+    within that namespace, like `'service:session'`.
+
+    **Note:** `FullName` is *not* a class, just a contract for strings used in the
+    DI system. It is currently documented as a class only due to limits in our
+    documentation infrastructure.
+
+    @for @ember/owner
+    @class FullName
+    @public
+   */
+  export type FullName<Type extends string = string, Name extends string = string> = `${Type}:${Name}`;
+  /**
+    A type registry for the DI system, which other participants in the DI system
+    can register themselves into with declaration merging. The contract for this
+    type is that its keys are the `Type` from a `FullName`, and each value for a
+    `Type` is another registry whose keys are the `Name` from a `FullName`. The
+    mechanic for providing a registry is [declaration merging][handbook].
+
+    [handbook]: https://www.typescriptlang.org/docs/handbook/declaration-merging.html
+
+    For example, Ember's `@ember/service` module includes this set of definitions:
+
+    ```ts
+    export default class Service extends EmberObject {}
+
+    // For concrete singleton classes to be merged into.
+    interface Registry extends Record<string, Service> {}
+
+    declare module '@ember/owner' {
+      service: Registry;
+    }
+    ```
+
+    Declarations of services can then include the registry:
+
+    ```ts
+    import Service from '@ember/service';
+
+    export default class Session extends Service {
+      login(username: string, password: string) {
+        // ...
+      }
+    }
+
+    declare module '@ember/service' {
+      interface Registry {
+        session: Session;
+      }
+    }
+    ```
+
+    Then users of the `Owner` API will be able to do things like this with strong
+    type safety guarantees:
+
+    ```ts
+    getOwner(this)?.lookup('service:session').login("hello", "1234abcd");
+    ```
+
+    @for @ember/owner
+    @private
+   */
+  export interface DIRegistry extends Record<string, Record<string, unknown>> {
+  }
+  /**
+    @private
+   */
+  type ResolveFactoryManager<Type extends string, Name extends string> = DIRegistry[Type][Name] extends object ? FactoryManager<DIRegistry[Type][Name]> : FactoryManager<object> | undefined;
+  /**
+    The common interface for the ability to `register()` an item, shared by the
+    `Owner` and `RegistryProxy` interfaces.
+
+    @for @ember/owner
+    @class BasicRegistry
+    @private
+   */
+  interface BasicRegistry {
+      /**
+        Registers a factory that can be used for dependency injection (with
+        `inject`) or for service lookup. Each factory is registered with
+        a full name including two parts: `type:name`.
+    
+        A simple example:
+    
+        ```javascript
+        import Application from '@ember/application';
+        import EmberObject from '@ember/object';
+    
+        let App = Application.create();
+    
+        App.Orange = EmberObject.extend();
+        App.register('fruit:favorite', App.Orange);
+        ```
+    
+        Ember will resolve factories from the `App` namespace automatically.
+        For example `App.CarsController` will be discovered and returned if
+        an application requests `controller:cars`.
+    
+        An example of registering a controller with a non-standard name:
+    
+        ```javascript
+        import Application from '@ember/application';
+        import Controller from '@ember/controller';
+    
+        let App = Application.create();
+        let Session = Controller.extend();
+    
+        App.register('controller:session', Session);
+    
+        // The Session controller can now be treated like a normal controller,
+        // despite its non-standard name.
+        App.ApplicationController = Controller.extend({
+          needs: ['session']
+        });
+        ```
+    
+        Registered factories are **instantiated** by having `create`
+        called on them. Additionally they are **singletons**, each time
+        they are looked up they return the same instance.
+    
+        Some examples modifying that default behavior:
+    
+        ```javascript
+        import Application from '@ember/application';
+        import EmberObject from '@ember/object';
+    
+        let App = Application.create();
+    
+        App.Person = EmberObject.extend();
+        App.Orange = EmberObject.extend();
+        App.Email = EmberObject.extend();
+        App.session = EmberObject.create();
+    
+        App.register('model:user', App.Person, { singleton: false });
+        App.register('fruit:favorite', App.Orange);
+        App.register('communication:main', App.Email, { singleton: false });
+        App.register('session', App.session, { instantiate: false });
+        ```
+    
+        @method register
+        @param  fullName {String} type:name (e.g., 'model:user')
+        @param  factory {Factory|object} (e.g., App.Person)
+        @param  options {Object} (optional) disable instantiation or singleton usage
+        @public
+       */
+      register(fullName: FullName, factory: Factory<object> | object, options?: RegisterOptions): void;
+  }
+  type ValidType = keyof DIRegistry & string;
+  type ValidName<Type extends ValidType> = keyof DIRegistry[Type] & string;
+  /**
+    The common interface for the ability to `lookup()` or get the `factoryFor` an
+    item, shared by the `Owner` and `ContainerProxy` interfaces.
+
+    @for @ember/owner
+    @class BasicContainer
+    @private
+   */
+  interface BasicContainer {
+      /**
+       Given a fullName return a corresponding instance.
+    
+       The default behavior is for lookup to return a singleton instance.
+       The singleton is scoped to the container, allowing multiple containers
+       to all have their own locally scoped singletons.
+    
+       ```javascript
+       let registry = new Registry();
+       let container = registry.container();
+    
+       registry.register('api:twitter', Twitter);
+    
+       let twitter = container.lookup('api:twitter');
+    
+       twitter instanceof Twitter; // => true
+    
+       // by default the container will return singletons
+       let twitter2 = container.lookup('api:twitter');
+       twitter2 instanceof Twitter; // => true
+    
+       twitter === twitter2; //=> true
+       ```
+    
+       If singletons are not wanted an optional flag can be provided at lookup.
+    
+       ```javascript
+       let registry = new Registry();
+       let container = registry.container();
+    
+       registry.register('api:twitter', Twitter);
+    
+       let twitter = container.lookup('api:twitter', { singleton: false });
+       let twitter2 = container.lookup('api:twitter', { singleton: false });
+    
+       twitter === twitter2; //=> false
+       ```
+    
+       @public
+       @method lookup
+       @param {string} fullName
+       @param {RegisterOptions} options
+       @return {any}
+       */
+      lookup<Type extends ValidType, Name extends ValidName<Type>>(fullName: FullName<Type, Name>, options?: RegisterOptions): DIRegistry[Type][Name];
+      /**
+        Given a `FullName`, of the form `"type:name"` return a `FactoryManager`.
+    
+        This method returns a manager which can be used for introspection of the
+        factory's class or for the creation of factory instances with initial
+        properties. The manager is an object with the following properties:
+    
+        * `class` - The registered or resolved class.
+        * `create` - A function that will create an instance of the class with
+          any dependencies injected.
+    
+        For example:
+    
+        ```javascript
+        import { getOwner } from '@ember/application';
+    
+        let owner = getOwner(otherInstance);
+        // the owner is commonly the `applicationInstance`, and can be accessed via
+        // an instance initializer.
+    
+        let factory = owner.factoryFor('service:bespoke');
+    
+        factory.class;
+        // The registered or resolved class. For example when used with an Ember-CLI
+        // app, this would be the default export from `app/services/bespoke.js`.
+    
+        let instance = factory.create({
+          someProperty: 'an initial property value'
+        });
+        // Create an instance with any injections and the passed options as
+        // initial properties.
+        ```
+    
+        Any instances created via the factory's `.create()` method *must* be destroyed
+        manually by the caller of `.create()`. Typically, this is done during the creating
+        objects own `destroy` or `willDestroy` methods.
+    
+        @public
+        @method factoryFor
+        @param {string} fullName
+        @return {FactoryManager}
+      */
+      factoryFor<Type extends ValidType, Name extends ValidName<Type>>(fullName: FullName<Type, Name>): ResolveFactoryManager<Type, Name>;
+  }
+  /**
+    Framework objects in an Ember application (components, services, routes,
+    etc.) are created via a factory and dependency injection system. Each of
+    these objects is the responsibility of an "owner", which handles its
+    instantiation and manages its lifetime.
+
+    An `Owner` is not a class you construct; it is one the framework constructs
+    for you. The normal way to get access to the relevant `Owner` is using the
+    `getOwner` function.
+
+    @for @ember/owner
+    @uses BasicRegistry
+    @uses BasicContainer
+    @class Owner
+    @since 4.10.0
+    @public
+   */
+  export default interface Owner extends BasicRegistry, BasicContainer {
+  }
+  /**
+   * Interface representing the options for registering an item as a factory.
+   *
+   * @for @ember/owner
+   * @class RegisterOptions
+   * @public
+   */
+  export interface RegisterOptions {
+      /**
+        Whether to instantiate the item when returning it from a lookup. Defaults
+        to `true`.
+    
+        @property instantiate
+        @type Boolean
+        @optional
+        @default true
+        @public
+       */
+      instantiate?: boolean | undefined;
+      /**
+        Whether the item is a singleton (like a service) and so should return the
+        same instance every time, or should generate a new instance on each call.
+        Defaults to `true`.
+    
+        @property singleton
+        @type Boolean
+        @optional
+        @default true
+        @public
+       */
+      singleton?: boolean | undefined;
+  }
+  /**
+    Registered factories are instantiated by having create called on them.
+    Additionally they are singletons by default, so each time they are looked up
+    they return the same instance.
+
+    However, that behavior can be modified with the `instantiate` and `singleton`
+    options to the `Owner.register()` method.
+
+    @for @ember/owner
+    @class Factory
+    @since 4.10.0
+    @public
+   */
+  export interface Factory<T extends object> {
+      /**
+       * A function that will create an instance of the class with any
+       * dependencies injected.
+       *
+       * @method create
+       * @param  initialValues {Object} Any values to set on an instance of the class
+       * @return {Object} The item produced by the factory.
+       * @public
+       */
+      create(initialValues?: object): T;
+  }
+  /**
+    The interface representing a manager which can be used for introspection of
+    the factory's class or for the creation of factory instances with initial
+    properties. The manager is an object with the following properties:
+
+    - `class` - The registered or resolved class.
+    - `create` - A function that will create an instance of the class with any
+    dependencies injected.
+
+    **Note:** `FactoryManager` is *not* user-constructible; the only legal way
+    to get a `FactoryManager` is via `Owner.factoryFor`.
+
+    @for @ember/owner
+    @class FactoryManager
+    @extends Factory
+    @public
+   */
+  export interface FactoryManager<T extends object> extends Factory<T> {
+      /**
+        The registered or resolved class.
+    
+        @property class
+        @type Factory
+        @public
+       */
+      readonly class: Factory<T>;
+  }
+  /**
+   * A record mapping all known items of a given type: if the item is known it
+   * will be `true`; otherwise it will be `false` or `undefined`.
+   */
+  export type KnownForTypeResult<Type extends string> = {
+      [Key in FullName<Type, string>]: boolean | undefined;
+  };
+  /**
+    A `Resolver` is the mechanism responsible for looking up code in your
+    application and converting its naming conventions into the actual classes,
+    functions, and templates that Ember needs to resolve its dependencies, for
+    example, what template to render for a given route. It is a system that helps
+    the app resolve the lookup of JavaScript modules agnostic of what kind of
+    module system is used, which can be AMD, CommonJS or just plain globals. It
+    is used to lookup routes, models, components, templates, or anything that is
+    used in your Ember app.
+
+    This interface is not a concrete class; instead, it represents the contract a
+    custom resolver must implement. Most apps never need to think about this: in
+    the default blueprint, this is supplied by the `ember-resolver` package.
+
+    @for @ember/owner
+    @class Resolver
+    @since 4.10.0
+    @public
+   */
+  export interface Resolver {
+      /**
+        The one required method for a `Resolver`. Given a string, resolve it to a
+        `Factory`, if one exists.
+    
+        @method resolve
+        @param name {String}
+        @public
+       */
+      resolve: (name: string) => Factory<object> | object | undefined;
+      /**
+        @method knownForType
+        @param  type {String}
+        @return {Object}
+        @public
+       */
+      knownForType?: <Type extends string>(type: Type) => KnownForTypeResult<Type>;
+      /**
+        @method lookupDescription
+        @param  fullName {String}
+        @return {String}
+        @public
+       */
+      lookupDescription?: (fullName: FullName) => string;
+      /**
+        @method makeToString
+        @param  factory {Factory}
+        @param  fullName {String}
+        @return {String}
+        @public
+       */
+      makeToString?: (factory: Factory<object>, fullName: FullName) => string;
+      /**
+        @method normalize
+        @param  fullName {String}
+        @return {String}
+        @public
+      */
+      normalize?: (fullName: FullName) => FullName;
+  }
+  export interface FactoryClass {
+      positionalParams?: string | string[] | undefined | null;
+  }
+  /**
+    The internal representation of a `Factory`, for the extra detail available for
+    private use internally than we expose to consumers.
+
+    @for @ember/owner
+    @class InternalFactory
+    @private
+   */
+  export interface InternalFactory<T extends object, C extends FactoryClass | object = FactoryClass> extends Factory<T> {
+      /**
+        @property class
+        @optional
+        @private
+       */
+      class?: C;
+      /**
+        @property name
+        @type String
+        @optional
+        @private
+       */
+      name?: string;
+      /**
+        @property fullName
+        @type String
+        @optional
+        @private
+       */
+      fullName?: FullName;
+      /**
+        @property normalizedName
+        @type String
+        @optional
+        @private
+       */
+      normalizedName?: string;
+  }
+  /**
+    @private
+    @method isFactory
+    @param {Object} obj
+    @return {Boolean}
+    @static
+   */
+  export function isFactory(obj: unknown): obj is InternalFactory<object>;
+  export function getOwner(object: object): InternalOwner | undefined;
+  /**
+    `setOwner` forces a new owner on a given object instance. This is primarily
+    useful in some testing cases.
+
+    @method setOwner
+    @static
+    @for @ember/owner
+    @param {Object} object An object instance.
+    @param {Owner} object The new owner object of the object instance.
+    @since 2.3.0
+    @public
+  */
+  export function setOwner(object: object, owner: Owner): void;
+  /**
+   * The interface for a container proxy, which is itself a private API used
+   * by the private `ContainerProxyMixin` as part of the base definition of
+   * `EngineInstance`.
+   *
+   * @class ContainerProxy
+   * @for @ember/owner
+   * @private
+   * @extends BasicContainer
+   */
+  export interface ContainerProxy extends BasicContainer {
+      /**
+       Returns an object that can be used to provide an owner to a
+       manually created instance.
+    
+       Example:
+    
+       ```
+       import { getOwner } from '@ember/application';
+    
+       let owner = getOwner(this);
+    
+       User.create(
+         owner.ownerInjection(),
+         { username: 'rwjblue' }
+       )
+       ```
+    
+       @public
+       @method ownerInjection
+       @since 2.3.0
+       @return {Object}
+      */
+      ownerInjection(): object;
+  }
+  /**
+   * @class RegistryProxy
+   * @extends BasicRegistry
+   * @private
+   * @for @ember/owner
+   */
+  export interface RegistryProxy extends BasicRegistry {
+      /**
+        Given a fullName return the corresponding factory.
+    
+        @public
+        @method resolveRegistration
+        @param  fullName {String}
+        @return {Function} fullName's factory
+       */
+      resolveRegistration(fullName: FullName): Factory<object> | object | undefined;
+      /**
+        Unregister a factory.
+    
+        ```javascript
+        import Application from '@ember/application';
+        import EmberObject from '@ember/object';
+    
+        let App = Application.create();
+        let User = EmberObject.extend();
+        App.register('model:user', User);
+    
+        App.resolveRegistration('model:user').create() instanceof User //=> true
+    
+        App.unregister('model:user')
+        App.resolveRegistration('model:user') === undefined //=> true
+        ```
+    
+        @public
+        @method unregister
+        @param {String} fullName
+       */
+      unregister(fullName: FullName): void;
+      /**
+        Check if a factory is registered.
+    
+        @public
+        @method hasRegistration
+        @param {String} fullName
+        @return {Boolean}
+       */
+      hasRegistration(fullName: FullName): boolean;
+      /**
+        Return a specific registered option for a particular factory.
+    
+        @public
+        @method registeredOption
+        @param  {String} fullName
+        @param  {String} optionName
+        @return {Object} options
+       */
+      registeredOption<K extends keyof RegisterOptions>(fullName: FullName, optionName: K): RegisterOptions[K] | undefined;
+      /**
+        Register options for a particular factory.
+    
+        @public
+        @method registerOptions
+        @param {String} fullName
+        @param {Object} options
+       */
+      registerOptions(fullName: FullName, options: RegisterOptions): void;
+      /**
+        Return registered options for a particular factory.
+    
+        @public
+        @method registeredOptions
+        @param  {String} fullName
+        @return {Object} options
+       */
+      registeredOptions(fullName: FullName): RegisterOptions | undefined;
+      /**
+        Allow registering options for all factories of a type.
+    
+        ```javascript
+        import Application from '@ember/application';
+    
+        let App = Application.create();
+        let appInstance = App.buildInstance();
+    
+        // if all of type `connection` must not be singletons
+        appInstance.registerOptionsForType('connection', { singleton: false });
+    
+        appInstance.register('connection:twitter', TwitterConnection);
+        appInstance.register('connection:facebook', FacebookConnection);
+    
+        let twitter = appInstance.lookup('connection:twitter');
+        let twitter2 = appInstance.lookup('connection:twitter');
+    
+        twitter === twitter2; // => false
+    
+        let facebook = appInstance.lookup('connection:facebook');
+        let facebook2 = appInstance.lookup('connection:facebook');
+    
+        facebook === facebook2; // => false
+        ```
+    
+        @public
+        @method registerOptionsForType
+        @param {String} type
+        @param {Object} options
+       */
+      registerOptionsForType(type: string, options: RegisterOptions): void;
+      /**
+        Return the registered options for all factories of a type.
+    
+        @public
+        @method registeredOptionsForType
+        @param {String} type
+        @return {Object} options
+       */
+      registeredOptionsForType(type: string): RegisterOptions | undefined;
+  }
+  /**
+   * @internal This is the same basic interface which is implemented (via the
+   *   mixins) by `EngineInstance` and therefore `ApplicationInstance`, which are
+   *   the normal interfaces to an `Owner` for end user applications now. However,
+   *   going forward, we expect to progressively deprecate and remove the "extra"
+   *   APIs which are not exposed on `Owner` itself.
+   */
+  export interface InternalOwner extends RegistryProxy, ContainerProxy {
+  }
+  export {};
+}

package/types/stable/@ember/-internals/routing/index.d.ts

@@ -0,0 +1,3 @@
+declare module '@ember/-internals/routing' {
+  export { controllerFor, generateController, generateControllerFactory, DSL as RouterDSL, } from '@ember/routing/-internals';
+}

package/types/stable/@ember/-internals/runtime/index.d.ts

@@ -0,0 +1,11 @@
+declare module '@ember/-internals/runtime' {
+  export { default as RegistryProxyMixin } from './lib/mixins/registry_proxy';
+  export { default as ContainerProxyMixin } from './lib/mixins/container_proxy';
+  export { default as Comparable } from './lib/mixins/comparable';
+  export { NativeArray } from '@ember/array';
+  export { default as ActionHandler } from './lib/mixins/action_handler';
+  export { default as _ProxyMixin, contentFor as _contentFor } from './lib/mixins/-proxy';
+  export { default as MutableEnumerable } from '@ember/enumerable/mutable';
+  export { default as TargetActionSupport } from './lib/mixins/target_action_support';
+  export { default as RSVP, onerrorDefault } from './lib/ext/rsvp';
+}

package/types/stable/@ember/-internals/runtime/lib/ext/rsvp.d.ts

@@ -0,0 +1,5 @@
+declare module '@ember/-internals/runtime/lib/ext/rsvp.d.ts' {
+  import * as RSVP from 'rsvp';
+  export function onerrorDefault(reason: unknown): void;
+  export default RSVP;
+}

package/types/stable/@ember/-internals/runtime/lib/mixins/-proxy.d.ts

@@ -0,0 +1,34 @@
+declare module '@ember/-internals/runtime/lib/mixins/-proxy.d.ts' {
+  /**
+  @module ember
+  */
+  import Mixin from '@ember/object/mixin';
+  export function contentFor<T>(proxy: ProxyMixin<T>): T | null;
+  /**
+    `Ember.ProxyMixin` forwards all properties not defined by the proxy itself
+    to a proxied `content` object.  See ObjectProxy for more details.
+
+    @class ProxyMixin
+    @namespace Ember
+    @private
+  */
+  interface ProxyMixin<T = unknown> {
+      /**
+        The object whose properties will be forwarded.
+    
+        @property content
+        @type {unknown}
+        @default null
+        @public
+      */
+      content: T | null;
+      willDestroy(): void;
+      isTruthy: boolean;
+      unknownProperty<K extends keyof T>(key: K): T[K] | undefined;
+      unknownProperty(key: string): unknown;
+      setUnknownProperty<K extends keyof T>(key: K, value: T[K]): T[K];
+      setUnknownProperty<V>(key: string, value: V): V;
+  }
+  const ProxyMixin: Mixin;
+  export default ProxyMixin;
+}