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

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

@@ -0,0 +1,127 @@
+declare module '@ember/engine/instance.d.ts' {
+  /**
+  @module @ember/engine
+  */
+  import EmberObject from '@ember/object';
+  import { RSVP } from '@ember/-internals/runtime';
+  import { Registry } from '@ember/-internals/container';
+  import { ENGINE_PARENT } from './lib/engine-parent';
+  import { ContainerProxyMixin, RegistryProxyMixin } from '@ember/-internals/runtime';
+  import type { InternalOwner } from '@ember/-internals/owner';
+  import type Owner from '@ember/-internals/owner';
+  import { type FullName } from '@ember/-internals/owner';
+  import Engine from '@ember/engine';
+  import type Application from '@ember/application';
+  import type { SimpleElement } from '@simple-dom/interface';
+  export interface BootOptions {
+      isBrowser?: boolean;
+      shouldRender?: boolean;
+      document?: Document | null;
+      rootElement?: string | SimpleElement | null;
+      location?: string | null;
+      isInteractive?: boolean;
+      _renderMode?: string;
+  }
+  export interface EngineInstanceOptions {
+      mountPoint?: string;
+      routable?: boolean;
+  }
+  /**
+    The `EngineInstance` encapsulates all of the stateful aspects of a
+    running `Engine`.
+
+    @public
+    @class EngineInstance
+    @extends EmberObject
+    @uses RegistryProxyMixin
+    @uses ContainerProxyMixin
+  */
+  interface EngineInstance extends RegistryProxyMixin, ContainerProxyMixin, InternalOwner, Owner {
+  }
+  const EngineInstance_base: Readonly<typeof EmberObject> & (new (owner?: Owner | undefined) => EmberObject);
+  class EngineInstance extends EngineInstance_base {
+      /**
+       @private
+       @method setupRegistry
+       @param {Registry} registry
+       @param {BootOptions} options
+       */
+      static setupRegistry(_registry: Registry, _options?: BootOptions): void;
+      /**
+        The base `Engine` for which this is an instance.
+    
+        @property {Engine} engine
+        @private
+      */
+      base: Engine;
+      application: Application;
+      mountPoint?: string;
+      routable?: boolean;
+      [ENGINE_PARENT]?: EngineInstance;
+      _booted: boolean;
+      init(properties: object | undefined): void;
+      _bootPromise: RSVP.Promise<this> | null;
+      /**
+        Initialize the `EngineInstance` and return a promise that resolves
+        with the instance itself when the boot process is complete.
+    
+        The primary task here is to run any registered instance initializers.
+    
+        See the documentation on `BootOptions` for the options it takes.
+    
+        @public
+        @method boot
+        @param options {Object}
+        @return {Promise<EngineInstance,Error>}
+      */
+      boot(options?: BootOptions): Promise<this>;
+      /**
+        Unfortunately, a lot of existing code assumes booting an instance is
+        synchronous – specifically, a lot of tests assume the last call to
+        `app.advanceReadiness()` or `app.reset()` will result in a new instance
+        being fully-booted when the current runloop completes.
+    
+        We would like new code (like the `visit` API) to stop making this
+        assumption, so we created the asynchronous version above that returns a
+        promise. But until we have migrated all the code, we would have to expose
+        this method for use *internally* in places where we need to boot an instance
+        synchronously.
+    
+        @private
+      */
+      _bootSync(options?: BootOptions): this;
+      setupRegistry(options?: BootOptions): void;
+      /**
+       Unregister a factory.
+    
+       Overrides `RegistryProxy#unregister` in order to clear any cached instances
+       of the unregistered factory.
+    
+       @public
+       @method unregister
+       @param {String} fullName
+       */
+      unregister(fullName: FullName): void;
+      /**
+        Build a new `EngineInstance` that's a child of this instance.
+    
+        Engines must be registered by name with their parent engine
+        (or application).
+    
+        @private
+        @method buildChildEngineInstance
+        @param name {String} the registered name of the engine.
+        @param options {Object} options provided to the engine instance.
+        @return {EngineInstance,Error}
+      */
+      buildChildEngineInstance(name: string, options?: EngineInstanceOptions): EngineInstance;
+      /**
+        Clone dependencies shared between an engine instance and its parent.
+    
+        @private
+        @method cloneParentDependencies
+      */
+      cloneParentDependencies(): void;
+  }
+  export default EngineInstance;
+}

package/types/stable/@ember/engine/lib/engine-parent.d.ts

@@ -0,0 +1,27 @@
+declare module '@ember/engine/lib/engine-parent.d.ts' {
+  /**
+  @module @ember/engine
+  */
+  import type EngineInstance from '../instance';
+  export const ENGINE_PARENT: unique symbol;
+  /**
+    `getEngineParent` retrieves an engine instance's parent instance.
+
+    @method getEngineParent
+    @param {EngineInstance} engine An engine instance.
+    @return {EngineInstance} The parent engine instance.
+    @for @ember/engine
+    @static
+    @private
+  */
+  export function getEngineParent(engine: EngineInstance): EngineInstance | undefined;
+  /**
+    `setEngineParent` sets an engine instance's parent instance.
+
+    @method setEngineParent
+    @param {EngineInstance} engine An engine instance.
+    @param {EngineInstance} parent The parent engine instance.
+    @private
+  */
+  export function setEngineParent(engine: EngineInstance, parent: EngineInstance): void;
+}

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

@@ -0,0 +1,19 @@
+declare module '@ember/enumerable' {
+  import Mixin from '@ember/object/mixin';
+  /**
+  @module @ember/enumerable
+  @private
+  */
+  /**
+    The methods in this mixin have been moved to [MutableArray](/ember/release/classes/MutableArray). This mixin has
+    been intentionally preserved to avoid breaking Enumerable.detect checks
+    until the community migrates away from them.
+
+    @class Enumerable
+    @private
+  */
+  interface Enumerable {
+  }
+  const Enumerable: Mixin;
+  export default Enumerable;
+}

package/types/stable/@ember/enumerable/mutable.d.ts

@@ -0,0 +1,21 @@
+declare module '@ember/enumerable/mutable.d.ts' {
+  import Enumerable from '@ember/enumerable';
+  import Mixin from '@ember/object/mixin';
+  /**
+  @module ember
+  */
+  /**
+    The methods in this mixin have been moved to MutableArray. This mixin has
+    been intentionally preserved to avoid breaking MutableEnumerable.detect
+    checks until the community migrates away from them.
+
+    @class MutableEnumerable
+    @namespace Ember
+    @uses Enumerable
+    @private
+  */
+  interface MutableEnumerable extends Enumerable {
+  }
+  const MutableEnumerable: Mixin;
+  export default MutableEnumerable;
+}

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

@@ -0,0 +1,15 @@
+declare module '@ember/error' {
+  /**
+   @module @ember/error
+  */
+  /**
+    The JavaScript Error object used by Ember.assert.
+
+    @class Error
+    @namespace Ember
+    @extends Error
+    @constructor
+    @public
+  */
+  export default Error;
+}

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

@@ -0,0 +1,314 @@
+declare module '@ember/helper' {
+  /**
+  @module @ember/helper
+  */
+  /**
+    `capabilities` returns a capabilities configuration which can be used to modify
+    the behavior of the manager. Manager capabilities _must_ be provided using the
+    `capabilities` function, as the underlying implementation can change over time.
+
+    The first argument to capabilities is a version string, which is the version of
+    Ember that the capabilities were defined in. Ember can add new versions at any
+    time, and these may have entirely different behaviors, but it will not remove
+    old versions until the next major version.
+
+    ```js
+    capabilities('3.23');
+    ```
+
+    The second argument is an object of capabilities and boolean values indicating
+    whether they are enabled or disabled.
+
+    ```js
+    capabilities('3.23', {
+      hasValue: true,
+      hasDestructor: true,
+    });
+    ```
+
+    If no value is specified, then the default value will be used.
+
+    ### `3.23` capabilities
+
+    #### `hasDestroyable`
+
+    - Default value: false
+
+    Determines if the helper has a destroyable to include in the destructor
+    hierarchy. If enabled, the `getDestroyable` hook will be called, and its result
+    will be associated with the destroyable parent block.
+
+    #### `hasValue`
+
+    - Default value: false
+
+    Determines if the helper has a value which can be used externally. The helper's
+    `getValue` hook will be run whenever the value of the helper is accessed if this
+    capability is enabled.
+
+    @method capabilities
+    @for @ember/helper
+    @static
+    @param {String} managerApiVersion The version of capabilities that are being used
+    @param options The capabilities values
+    @return {Capabilities} The capabilities object instance
+    @public
+  */
+  /**
+    Sets the helper manager for an object or function.
+
+    ```js
+    setHelperManager((owner) => new ClassHelperManager(owner), Helper)
+    ```
+
+    When a value is used as a helper in a template, the helper manager is looked up
+    on the object by walking up its prototype chain and finding the first helper
+    manager. This manager then receives the value and can create and manage an
+    instance of a helper from it. This provides a layer of indirection that allows
+    users to design high-level helper APIs, without Ember needing to worry about the
+    details. High-level APIs can be experimented with and iterated on while the
+    core of Ember helpers remains stable, and new APIs can be introduced gradually
+    over time to existing code bases.
+
+    `setHelperManager` receives two arguments:
+
+    1. A factory function, which receives the `owner` and returns an instance of a
+      helper manager.
+    2. A helper definition, which is the object or function to associate the factory function with.
+
+    The first time the object is looked up, the factory function will be called to
+    create the helper manager. It will be cached, and in subsequent lookups the
+    cached helper manager will be used instead.
+
+    Only one helper manager is guaranteed to exist per `owner` and per usage of
+    `setHelperManager`, so many helpers will end up using the same instance of the
+    helper manager. As such, you should only store state that is related to the
+    manager itself. If you want to store state specific to a particular helper
+    definition, you should assign a unique helper manager to that helper. In
+    general, most managers should either be stateless, or only have the `owner` they
+    were created with as state.
+
+    Helper managers must fulfill the following interface (This example uses
+    [TypeScript interfaces](https://www.typescriptlang.org/docs/handbook/interfaces.html)
+    for precision, you do not need to write helper managers using TypeScript):
+
+    ```ts
+    interface HelperManager<HelperStateBucket> {
+      capabilities: HelperCapabilities;
+
+      createHelper(definition: HelperDefinition, args: TemplateArgs): HelperStateBucket;
+
+      getValue?(bucket: HelperStateBucket): unknown;
+
+      runEffect?(bucket: HelperStateBucket): void;
+
+      getDestroyable?(bucket: HelperStateBucket): object;
+    }
+    ```
+
+    The capabilities property _must_ be provided using the `capabilities()` function
+    imported from the same module as `setHelperManager`:
+
+    ```js
+    import { capabilities } from '@ember/helper';
+
+    class MyHelperManager {
+      capabilities = capabilities('3.21.0', { hasValue: true });
+
+      // ...snip...
+    }
+    ```
+
+    Below is a description of each of the methods on the interface and their
+    functions.
+
+    #### `createHelper`
+
+    `createHelper` is a required hook on the HelperManager interface. The hook is
+    passed the definition of the helper that is currently being created, and is
+    expected to return a _state bucket_. This state bucket is what represents the
+    current state of the helper, and will be passed to the other lifecycle hooks at
+    appropriate times. It is not necessarily related to the definition of the
+    helper itself - for instance, you could return an object _containing_ an
+    instance of the helper:
+
+    ```js
+    class MyManager {
+      createHelper(Definition, args) {
+        return {
+          instance: new Definition(args);
+        };
+      }
+    }
+    ```
+
+    This allows the manager to store metadata that it doesn't want to expose to the
+    user.
+
+    This hook is _not_ autotracked - changes to tracked values used within this hook
+    will _not_ result in a call to any of the other lifecycle hooks. This is because
+    it is unclear what should happen if it invalidates, and rather than make a
+    decision at this point, the initial API is aiming to allow as much expressivity
+    as possible. This could change in the future with changes to capabilities and
+    their behaviors.
+
+    If users do want to autotrack some values used during construction, they can
+    either create the instance of the helper in `runEffect` or `getValue`, or they
+    can use the `cache` API to autotrack the `createHelper` hook themselves. This
+    provides maximum flexibility and expressiveness to manager authors.
+
+    This hook has the following timing semantics:
+
+    **Always**
+    - called as discovered during DOM construction
+    - called in definition order in the template
+
+    #### `getValue`
+
+    `getValue` is an optional hook that should return the value of the helper. This
+    is the value that is returned from the helper and passed into the template.
+
+    This hook is called when the value is requested from the helper (e.g. when the
+    template is rendering and the helper value is needed). The hook is autotracked,
+    and will rerun whenever any tracked values used inside of it are updated.
+    Otherwise it does not rerun.
+
+    > Note: This means that arguments which are not _consumed_ within the hook will
+    > not trigger updates.
+
+    This hook is only called for helpers with the `hasValue` capability enabled.
+    This hook has the following timing semantics:
+
+    **Always**
+    - called the first time the helper value is requested
+    - called after autotracked state has changed
+
+    **Never**
+    - called if the `hasValue` capability is disabled
+
+    #### `runEffect`
+
+    `runEffect` is an optional hook that should run the effect that the helper is
+    applying, setting it up or updating it.
+
+    This hook is scheduled to be called some time after render and prior to paint.
+    There is not a guaranteed, 1-to-1 relationship between a render pass and this
+    hook firing. For instance, multiple render passes could occur, and the hook may
+    only trigger once. It may also never trigger if it was dirtied in one render
+    pass and then destroyed in the next.
+
+    The hook is autotracked, and will rerun whenever any tracked values used inside
+    of it are updated. Otherwise it does not rerun.
+
+    The hook is also run during a time period where state mutations are _disabled_
+    in Ember. Any tracked state mutation will throw an error during this time,
+    including changes to tracked properties, changes made using `Ember.set`, updates
+    to computed properties, etc. This is meant to prevent infinite rerenders and
+    other antipatterns.
+
+    This hook is only called for helpers with the `hasScheduledEffect` capability
+    enabled. This hook is also not called in SSR currently, though this could be
+    added as a capability in the future. It has the following timing semantics:
+
+    **Always**
+    - called after the helper was first created, if the helper has not been
+      destroyed since creation
+    - called after autotracked state has changed, if the helper has not been
+      destroyed during render
+
+    **Never**
+    - called if the `hasScheduledEffect` capability is disabled
+    - called in SSR
+
+    #### `getDestroyable`
+
+    `getDestroyable` is an optional hook that users can use to register a
+    destroyable object for the helper. This destroyable will be registered to the
+    containing block or template parent, and will be destroyed when it is destroyed.
+    See the [Destroyables RFC](https://github.com/emberjs/rfcs/blob/master/text/0580-destroyables.md)
+    for more details.
+
+    `getDestroyable` is only called if the `hasDestroyable` capability is enabled.
+
+    This hook has the following timing semantics:
+
+    **Always**
+    - called immediately after the `createHelper` hook is called
+
+    **Never**
+    - called if the `hasDestroyable` capability is disabled
+
+    @method setHelperManager
+    @for @ember/helper
+    @static
+    @param {Function} factory A factory function which receives an optional owner, and returns a helper manager
+    @param {object} definition The definition to associate the manager factory with
+    @return {object} The definition passed into setHelperManager
+    @public
+  */
+  /**
+    The `invokeHelper` function can be used to create a helper instance in
+    JavaScript.
+
+    To access a helper's value you have to use `getValue` from
+    `@glimmer/tracking/primitives/cache`.
+
+    ```js
+    // app/components/data-loader.js
+    import Component from '@glimmer/component';
+    import { getValue } from '@glimmer/tracking/primitives/cache';
+    import Helper from '@ember/component/helper';
+    import { invokeHelper } from '@ember/helper';
+
+    class PlusOne extends Helper {
+      compute([number]) {
+        return number + 1;
+      }
+    }
+
+    export default class PlusOneComponent extends Component {
+      plusOne = invokeHelper(this, PlusOne, () => {
+        return {
+          positional: [this.args.number],
+        };
+      });
+
+      get value() {
+        return getValue(this.plusOne);
+      }
+    }
+    ```
+    ```hbs
+    {{this.value}}
+    ```
+
+    It receives three arguments:
+
+    * `context`: The parent context of the helper. When the parent is torn down and
+      removed, the helper will be as well.
+    * `definition`: The definition of the helper.
+    * `computeArgs`: An optional function that produces the arguments to the helper.
+      The function receives the parent context as an argument, and must return an
+      object with a `positional` property that is an array and/or a `named`
+      property that is an object.
+
+    And it returns a Cache instance that contains the most recent value of the
+    helper. You can access the helper using `getValue()` like any other cache. The
+    cache is also destroyable, and using the `destroy()` function on it will cause
+    the helper to be torn down.
+
+    Note that using `getValue()` on helpers that have scheduled effects will not
+    trigger the effect early. Effects will continue to run at their scheduled time.
+
+    @method invokeHelper
+    @for @ember/helper
+    @static
+    @param {object} context The parent context of the helper
+    @param {object} definition The helper definition
+    @param {Function} computeArgs An optional function that produces args
+    @returns
+    @public
+  */
+  export { setHelperManager, helperCapabilities as capabilities } from '@glimmer/manager';
+  export { invokeHelper, hash, array, concat, get, fn } from '@glimmer/runtime';
+}

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

@@ -0,0 +1,127 @@
+declare module '@ember/instrumentation' {
+  export interface Listener<T> {
+      before: (name: string, timestamp: number, payload: object) => T;
+      after: (name: string, timestamp: number, payload: object, beforeValue: T) => void;
+  }
+  export interface Subscriber<T> {
+      pattern: string;
+      regex: RegExp;
+      object: Listener<T>;
+  }
+  export interface PayloadWithException {
+      exception?: any;
+  }
+  export interface StructuredProfilePayload {
+      object: string | object;
+  }
+  /**
+  @module @ember/instrumentation
+  @private
+  */
+  /**
+    The purpose of the Ember Instrumentation module is
+    to provide efficient, general-purpose instrumentation
+    for Ember.
+
+    Subscribe to a listener by using `subscribe`:
+
+    ```javascript
+    import { subscribe } from '@ember/instrumentation';
+
+    subscribe("render", {
+      before(name, timestamp, payload) {
+
+      },
+
+      after(name, timestamp, payload) {
+
+      }
+    });
+    ```
+
+    If you return a value from the `before` callback, that same
+    value will be passed as a fourth parameter to the `after`
+    callback.
+
+    Instrument a block of code by using `instrument`:
+
+    ```javascript
+    import { instrument } from '@ember/instrumentation';
+
+    instrument("render.handlebars", payload, function() {
+      // rendering logic
+    }, binding);
+    ```
+
+    Event names passed to `instrument` are namespaced
+    by periods, from more general to more specific. Subscribers
+    can listen for events by whatever level of granularity they
+    are interested in.
+
+    In the above example, the event is `render.handlebars`,
+    and the subscriber listened for all events beginning with
+    `render`. It would receive callbacks for events named
+    `render`, `render.handlebars`, `render.container`, or
+    even `render.handlebars.layout`.
+
+    @class Instrumentation
+    @static
+    @private
+  */
+  export let subscribers: Subscriber<any>[];
+  type InstrumentCallback<Binding, Result> = (this: Binding) => Result;
+  /**
+    Notifies event's subscribers, calls `before` and `after` hooks.
+
+    @method instrument
+    @for @ember/instrumentation
+    @static
+    @param {String} [name] Namespaced event name.
+    @param {Object} payload
+    @param {Function} callback Function that you're instrumenting.
+    @param {Object} binding Context that instrument function is called with.
+    @private
+  */
+  export function instrument<Result>(name: string, callback: InstrumentCallback<undefined, Result>): Result;
+  export function instrument<Binding, Result>(name: string, callback: InstrumentCallback<Binding, Result>, binding: Binding): Result;
+  export function instrument<Result>(name: string, payload: object, callback: InstrumentCallback<undefined, Result>): Result;
+  export function instrument<Binding, Result>(name: string, payload: object, callback: InstrumentCallback<Binding, Result>, binding: Binding): Result;
+  export function flaggedInstrument<Result>(_name: string, _payload: object, callback: () => Result): Result;
+  export function _instrumentStart(name: string, payloadFunc: () => object): () => void;
+  export function _instrumentStart<Arg>(name: string, payloadFunc: (arg: Arg) => object, payloadArg: Arg): () => void;
+  /**
+    Subscribes to a particular event or instrumented block of code.
+
+    @method subscribe
+    @for @ember/instrumentation
+    @static
+
+    @param {String} [pattern] Namespaced event name.
+    @param {Object} [object] Before and After hooks.
+
+    @return {Subscriber}
+    @private
+  */
+  export function subscribe<T>(pattern: string, object: Listener<T>): Subscriber<T>;
+  /**
+    Unsubscribes from a particular event or instrumented block of code.
+
+    @method unsubscribe
+    @for @ember/instrumentation
+    @static
+
+    @param {Object} [subscriber]
+    @private
+  */
+  export function unsubscribe(subscriber: Subscriber<any>): void;
+  /**
+    Resets `Instrumentation` by flushing list of subscribers.
+
+    @method reset
+    @for @ember/instrumentation
+    @static
+    @private
+  */
+  export function reset(): void;
+  export {};
+}

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

@@ -0,0 +1,5 @@
+declare module '@ember/modifier' {
+  export { setModifierManager } from '@glimmer/manager';
+  export { modifierCapabilities as capabilities } from '@ember/-internals/glimmer';
+  export { on } from '@glimmer/runtime';
+}

package/types/stable/@ember/object/-internals.d.ts

@@ -0,0 +1,9 @@
+declare module '@ember/object/-internals.d.ts' {
+  export { getCachedValueFor as cacheFor } from '@ember/-internals/metal';
+  export { guidFor } from '@ember/-internals/utils';
+  import EmberObject from '.';
+  interface FrameworkObject extends EmberObject {
+  }
+  let FrameworkObject: typeof EmberObject;
+  export { FrameworkObject };
+}