ember-source 4.8.0-alpha.5 → 4.8.0-beta.2

package/types/preview/@ember/object/-private/types.d.ts

@@ -0,0 +1,63 @@
+declare module '@ember/object/-private/types' {
+  import type Mixin from '@ember/object/mixin';
+
+  /**
+   * Map type `T` to a plain object hash with the identity mapping.
+   *
+   * Discards any additional object identity like the ability to `new()` up the class.
+   * The `new()` capability is added back later by merging `EmberClassConstructor<T>`
+   *
+   * Implementation is carefully chosen for the reasons described in
+   * https://github.com/typed-ember/ember-typings/pull/29
+   */
+  export type Objectify<T> = Readonly<T>;
+
+  export type ExtractPropertyNamesOfType<T, S> = {
+    [K in keyof T]: T[K] extends S ? K : never;
+  }[keyof T];
+
+  export type Fix<T> = { [K in keyof T]: T[K] };
+
+  /**
+   * Used to infer the type of ember classes of type `T`.
+   *
+   * Generally you would use `EmberClass.create()` instead of `new EmberClass()`.
+   *
+   * The single-arg constructor is required by the typescript compiler.
+   * The multi-arg constructor is included for better ergonomics.
+   *
+   * Implementation is carefully chosen for the reasons described in
+   * https://github.com/typed-ember/ember-typings/pull/29
+   */
+  export type EmberClassConstructor<T> = (new (properties?: object) => T) &
+    (new (...args: any[]) => T);
+
+  /**
+   * Check that any arguments to `create()` match the type's properties.
+   *
+   * Accept any additional properties and add merge them into the instance.
+   */
+  export type EmberInstanceArguments<T> = Partial<T> & {
+    [key: string]: unknown;
+  };
+
+  /**
+   * Accept any additional properties and add merge them into the prototype.
+   */
+  export interface EmberClassArguments {
+    [key: string]: unknown;
+  }
+
+  /**
+   * Ember.Object.extend(...) accepts any number of mixins or literals.
+   */
+  export type MixinOrLiteral<T> = Mixin | T;
+
+  export type ObserverMethod<Target, Sender> =
+    | keyof Target
+    | ((this: Target, sender: Sender, key: string, value: any, rev: number) => void);
+
+  // This type looks weird, but is correct: from a list of "bottom" to "top", in
+  // type theory terms.
+  export type AnyFunction = (...args: never[]) => unknown;
+}

package/types/preview/@ember/object/compat.d.ts

@@ -0,0 +1,9 @@
+declare module '@ember/object/compat' {
+  /**
+   * `@dependentKeyCompat` is a decorator that can be used on native getters that
+   * use tracked properties. It exposes the getter to Ember's classic computed
+   * property and observer systems, so they can watch it for changes. It can be
+   * used in both native and classic classes.
+   */
+  export const dependentKeyCompat: PropertyDecorator;
+}

package/types/preview/@ember/object/computed.d.ts

@@ -0,0 +1,263 @@
+declare module '@ember/object/computed' {
+  /**
+   * A computed property transforms an objects function into a property.
+   * By default the function backing the computed property will only be called once and the result
+   * will be cached. You can specify various properties that your computed property is dependent on.
+   * This will force the cached result to be recomputed if the dependencies are modified.
+   */
+  export default class ComputedProperty {
+    /**
+     * Call on a computed property to set it into read-only mode. When in this
+     * mode the computed property will throw an error when set.
+     */
+    readOnly(): this;
+    /**
+     * In some cases, you may want to annotate computed properties with additional
+     * metadata about how they function or what values they operate on. For example,
+     * computed property functions may close over variables that are then no longer
+     * available for introspection.
+     */
+    meta(meta: Record<string, unknown>): this;
+    meta(): Record<string, unknown>;
+  }
+
+  // Computed property definitions also act as property decorators, including those
+  // returned from "macros" in third-party code.
+  export type BasicComputedProperty = ComputedProperty & PropertyDecorator;
+
+  /**
+   * Creates a new property that is an alias for another property
+   * on an object. Calls to `get` or `set` this property behave as
+   * though they were called on the original property.
+   */
+  export function alias(dependentKey: string): BasicComputedProperty;
+  /**
+   * A computed property that performs a logical `and` on the
+   * original values for the provided dependent properties.
+   */
+  export function and(...dependentKeys: string[]): BasicComputedProperty;
+  /**
+   * A computed property that converts the provided dependent property
+   * into a boolean value.
+   */
+  export function bool(dependentKey: string): BasicComputedProperty;
+
+  /**
+   * A computed property that returns the array of values
+   * for the provided dependent properties.
+   */
+  export function collect(...dependentKeys: string[]): BasicComputedProperty;
+
+  /**
+   * Creates a new property that is an alias for another property
+   * on an object. Calls to `get` or `set` this property behave as
+   * though they were called on the original property, but also
+   * print a deprecation warning.
+   */
+  export function deprecatingAlias(
+    dependentKey: string,
+    options: { id: string; until: string }
+  ): BasicComputedProperty;
+
+  /**
+   * A computed property that returns true if the value of the dependent
+   * property is null, an empty string, empty array, or empty function.
+   */
+  export function empty(dependentKey: string): BasicComputedProperty;
+  /**
+   * A computed property that returns true if the provided dependent property
+   * is equal to the given value.
+   */
+  export function equal(dependentKey: string, value: unknown): BasicComputedProperty;
+  /**
+   * Expands `pattern`, invoking `callback` for each expansion.
+   */
+  export function expandProperties(pattern: string, callback: (expanded: string) => void): void;
+
+  /**
+   * Filters the array by the callback.
+   */
+  export function filter(
+    dependentKey: string,
+    callback: (value: unknown, index: number, array: unknown[]) => boolean
+  ): BasicComputedProperty;
+
+  /**
+   * Filters the array by the callback and an array of additional dependent keys.
+   */
+  export function filter(
+    dependentKey: string,
+    additionalDependentKeys: string[],
+    callback: (value: unknown, index: number, array: unknown[]) => boolean
+  ): BasicComputedProperty;
+
+  /**
+   * Filters the array by the property and value
+   */
+  export function filterBy(
+    dependentKey: string,
+    propertyKey: string,
+    value?: unknown
+  ): BasicComputedProperty;
+
+  /**
+   * A computed property that returns true if the provided dependent property
+   * is greater than the provided value.
+   */
+  export function gt(dependentKey: string, value: number): BasicComputedProperty;
+  /**
+   * A computed property that returns true if the provided dependent property
+   * is greater than or equal to the provided value.
+   */
+  export function gte(dependentKey: string, value: number): BasicComputedProperty;
+
+  /**
+   * A computed property which returns a new array with all the elements
+   * two or more dependent arrays have in common.
+   */
+  export function intersect(...propertyKeys: string[]): BasicComputedProperty;
+
+  /**
+   * A computed property that returns true if the provided dependent property
+   * is less than the provided value.
+   */
+  export function lt(dependentKey: string, value: number): BasicComputedProperty;
+  /**
+   * A computed property that returns true if the provided dependent property
+   * is less than or equal to the provided value.
+   */
+  export function lte(dependentKey: string, value: number): BasicComputedProperty;
+
+  /**
+   * Returns an array mapped via the callback
+   */
+  export function map(
+    dependentKey: string,
+    callback: (value: unknown, index: number, array: unknown[]) => unknown
+  ): BasicComputedProperty;
+
+  /**
+   * Returns an array mapped to the specified key.
+   */
+  export function mapBy(dependentKey: string, propertyKey: string): BasicComputedProperty;
+
+  /**
+   * A computed property which matches the original value for the
+   * dependent property against a given RegExp, returning `true`
+   * if the value matches the RegExp and `false` if it does not.
+   */
+  export function match(dependentKey: string, regexp: RegExp): BasicComputedProperty;
+
+  /**
+   * A computed property that calculates the maximum value in the
+   * dependent array. This will return `-Infinity` when the dependent
+   * array is empty.
+   */
+  export function max(dependentKey: string): BasicComputedProperty;
+
+  /**
+   * A computed property that calculates the minimum value in the
+   * dependent array. This will return `Infinity` when the dependent
+   * array is empty.
+   */
+  export function min(dependentKey: string): BasicComputedProperty;
+
+  /**
+   * A computed property that returns true if the value of the dependent
+   * property is null or undefined. This avoids errors from JSLint complaining
+   * about use of ==, which can be technically confusing.
+   */
+  export function none(dependentKey: string): BasicComputedProperty;
+  /**
+   * A computed property that returns the inverse boolean value
+   * of the original value for the dependent property.
+   */
+  export function not(dependentKey: string): BasicComputedProperty;
+  /**
+   * A computed property that returns true if the value of the dependent
+   * property is NOT null, an empty string, empty array, or empty function.
+   */
+  export function notEmpty(dependentKey: string): BasicComputedProperty;
+  /**
+   * Where `computed.alias` aliases `get` and `set`, and allows for bidirectional
+   * data flow, `computed.oneWay` only provides an aliased `get`. The `set` will
+   * not mutate the upstream property, rather causes the current property to
+   * become the value set. This causes the downstream property to permanently
+   * diverge from the upstream property.
+   */
+  export function oneWay(dependentKey: string): BasicComputedProperty;
+  /**
+   * A computed property which performs a logical `or` on the
+   * original values for the provided dependent properties.
+   */
+  export function or(...dependentKeys: string[]): BasicComputedProperty;
+  /**
+   * Where `computed.oneWay` provides oneWay bindings, `computed.readOnly` provides
+   * a readOnly one way binding. Very often when using `computed.oneWay` one does
+   * not also want changes to propagate back up, as they will replace the value.
+   */
+  export function readOnly(dependentKey: string): BasicComputedProperty;
+  /**
+   * This is a more semantically meaningful alias of `computed.oneWay`,
+   * whose name is somewhat ambiguous as to which direction the data flows.
+   */
+  export function reads(dependentKey: string): BasicComputedProperty;
+
+  /**
+   * A computed property which returns a new array with all the
+   * properties from the first dependent array that are not in the second
+   * dependent array.
+   */
+  export function setDiff(setAProperty: string, setBProperty: string): BasicComputedProperty;
+
+  /**
+   * A computed property which returns a new array with all the properties from
+   * the first dependent array sorted based on a property or sort function.
+   *
+   * If used with an array of sort properties, it must receive exactly two
+   * arguments: the key of the array to sort, and the key of the array of sort
+   * properties. Alternatively the key of the array to sort, and a the sort
+   * function may be used.
+   */
+  export function sort<T>(
+    itemsKey: string,
+    sortDefinition: string | ((itemA: T, itemB: T) => number)
+  ): BasicComputedProperty;
+
+  /**
+   * A computed property which returns a new array with all the properties from
+   * the first dependent array sorted based on a property or sort function.
+   *
+   * It may receive three arguments: the key of the array to sort, an array of
+   * dependent keys for the computed property, and the sort function.
+   */
+  export function sort<T>(
+    itemsKey: string,
+    dependentKeys: string[],
+    sortDefinition: string | ((itemA: T, itemB: T) => number)
+  ): BasicComputedProperty;
+
+  /**
+   * A computed property that returns the sum of the values
+   * in the dependent array.
+   */
+  export function sum(dependentKey: string): BasicComputedProperty;
+
+  /**
+   * A computed property which returns a new array with all the unique
+   * elements from one or more dependent arrays.
+   */
+  export function uniq(propertyKey: string): BasicComputedProperty;
+
+  /**
+   * A computed property which returns a new array with all the unique
+   * elements from one or more dependent arrays.
+   */
+  export function union(...propertyKeys: string[]): BasicComputedProperty;
+
+  /**
+   * A computed property which returns a new array with all the unique
+   * elements from an array, with uniqueness determined by specific key.
+   */
+  export function uniqBy(dependentKey: string, propertyKey: string): BasicComputedProperty;
+}

package/types/preview/@ember/object/core.d.ts

@@ -0,0 +1,89 @@
+declare module '@ember/object/core' {
+  import type { EmberClassConstructor, Objectify } from '@ember/object/-private/types';
+  import type Mixin from '@ember/object/mixin';
+
+  export default class CoreObject {
+    /**
+     * As of Ember 3.1, CoreObject constructor takes initial object properties as an argument.
+     * See: https://github.com/emberjs/ember.js/commit/4709935854d4c29b0d2c054614d53fa2c55309b1
+     */
+    constructor(properties?: object);
+
+    _super(...args: any[]): any;
+
+    /**
+     * An overridable method called when objects are instantiated. By default,
+     * does nothing unless it is overridden during class definition.
+     */
+    init(): void;
+
+    /**
+     * Defines the properties that will be concatenated from the superclass (instead of overridden).
+     * @default null
+     */
+    concatenatedProperties: string[] | null;
+
+    /**
+     * Destroyed object property flag. If this property is true the observers and bindings were
+     * already removed by the effect of calling the destroy() method.
+     * @default false
+     */
+    isDestroyed: boolean;
+    /**
+     * Destruction scheduled flag. The destroy() method has been called. The object stays intact
+     * until the end of the run loop at which point the isDestroyed flag is set.
+     * @default false
+     */
+    isDestroying: boolean;
+
+    /**
+     * Destroys an object by setting the `isDestroyed` flag and removing its
+     * metadata, which effectively destroys observers and bindings.
+     * If you try to set a property on a destroyed object, an exception will be
+     * raised.
+     * Note that destruction is scheduled for the end of the run loop and does not
+     * happen immediately.  It will set an isDestroying flag immediately.
+     * @return receiver
+     */
+    destroy(): CoreObject;
+
+    /**
+     * Override to implement teardown.
+     */
+    willDestroy(): void;
+
+    /**
+     * Returns a string representation which attempts to provide more information than Javascript's toString
+     * typically does, in a generic way for all Ember objects (e.g., "<App.Person:ember1024>").
+     * @return string representation
+     */
+    toString(): string;
+
+    static create<Class extends typeof CoreObject>(
+      this: Class,
+      ...initialValues: Array<Mixin | MembersOf<Class>>
+    ): InstanceType<Class>;
+
+    static extend<Statics, Instance>(
+      this: Statics & EmberClassConstructor<Instance>,
+      ...mixins: Array<Mixin | Record<string, unknown>>
+    ): Objectify<Statics> & EmberClassConstructor<Instance>;
+
+    static reopen<Statics, Instance>(
+      this: Statics & EmberClassConstructor<Instance>,
+      ...mixins: Array<Mixin | Record<string, unknown>>
+    ): Objectify<Statics> & EmberClassConstructor<Instance>;
+
+    static reopenClass<Statics>(
+      this: Statics,
+      ...extraStatics: Array<Mixin | Record<string, unknown>>
+    ): Statics;
+
+    static isClass: boolean;
+    static isMethod: boolean;
+  }
+
+  type MembersOf<Class extends typeof CoreObject> = {
+    [Key in keyof InstanceType<Class>]?: InstanceType<Class>[Key];
+  };
+}

package/types/preview/@ember/object/evented.d.ts

@@ -0,0 +1,45 @@
+declare module '@ember/object/evented' {
+  import Mixin from '@ember/object/mixin';
+  import { AnyFn, EmberMethod } from 'ember/-private/type-utils';
+
+  /**
+   * This mixin allows for Ember objects to subscribe to and emit events.
+   */
+  interface Evented {
+    /**
+     * Subscribes to a named event with given function.
+     */
+    on<T>(name: string, target: T, method: EmberMethod<T>): this;
+    on(name: string, method: EmberMethod<this>): this;
+    /**
+     * Subscribes a function to a named event and then cancels the subscription
+     * after the first time the event is triggered. It is good to use ``one`` when
+     * you only care about the first time an event has taken place.
+     */
+    one<T>(name: string, target: T, method: EmberMethod<T>): this;
+    one(name: string, method: EmberMethod<this>): this;
+    /**
+     * Triggers a named event for the object. Any additional arguments
+     * will be passed as parameters to the functions that are subscribed to the
+     * event.
+     */
+    trigger(name: string, ...args: unknown[]): unknown;
+    /**
+     * Cancels subscription for given name, target, and method.
+     */
+    off<T>(name: string, target: T, method: EmberMethod<T>): this;
+    off(name: string, method: EmberMethod<this>): this;
+    /**
+     * Checks to see if object has any subscriptions for named event.
+     */
+    has(name: string): boolean;
+  }
+  const Evented: Mixin;
+  export default Evented;
+
+  /**
+   * Define a property as a function that should be executed when
+   * a specified event or events are triggered.
+   */
+  export function on<F extends AnyFn>(...args: [...eventNames: string[], func: F]): F;
+}

package/types/preview/@ember/object/events.d.ts

@@ -0,0 +1,47 @@
+declare module '@ember/object/events' {
+  import { AnyFunction } from '@ember/object/-private/types';
+
+  /**
+   * Add an event listener
+   */
+  export function addListener<Context>(
+    obj: Context,
+    eventName: string,
+    target: unknown,
+    method: keyof Context | AnyFunction,
+    once?: boolean
+  ): void;
+  export function addListener<Context>(
+    obj: Context,
+    eventName: string,
+    method: keyof Context | AnyFunction,
+    once?: boolean
+  ): void;
+
+  /**
+   * Remove an event listener
+   */
+  export function removeListener<Context>(
+    obj: Context,
+    eventName: string,
+    target: unknown,
+    method: keyof Context | AnyFunction
+  ): void;
+  export function removeListener<Context>(
+    obj: Context,
+    eventName: string,
+    method: keyof Context | AnyFunction
+  ): void;
+
+  /**
+   * Send an event. The execution of suspended listeners
+   * is skipped, and once listeners are removed. A listener without
+   * a target is executed on the passed object. If an array of actions
+   * is not passed, the actions stored on the passed object are invoked.
+   *
+   * @param eventName
+   * @param params Optional parameters for each listener.
+   * @returns if the event was delivered to one or more actions
+   */
+  export function sendEvent(obj: unknown, eventName: string, params?: unknown[]): boolean;
+}

package/types/preview/@ember/object/index.d.ts

@@ -0,0 +1,126 @@
+declare module '@ember/object' {
+  import CoreObject from '@ember/object/core';
+  import type Observable from '@ember/object/observable';
+  import type ComputedProperty from '@ember/object/computed';
+  import type { BasicComputedProperty } from '@ember/object/computed';
+  import type { AnyFunction } from '@ember/object/-private/types';
+
+  /**
+   * `Ember.Object` is the main base class for all Ember objects. It is a subclass
+   * of `Ember.CoreObject` with the `Ember.Observable` mixin applied. For details,
+   * see the documentation for each of these.
+   */
+  export default class EmberObject extends CoreObject {}
+  export default interface EmberObject extends Observable {}
+
+  /**
+   * This helper returns a new property descriptor that wraps the passed computed
+   * property function. You can use this helper to define properties with native
+   * decorator syntax, mixins, or via `defineProperty()`.
+   *
+   * @param dependentKeys Optional dependent keys that trigger this computed
+   *   property.
+   */
+  export function computed(...dependentKeys: string[]): ComputedProperty & MethodDecorator;
+
+  export function computed(
+    ...args: [...dependentKeys: string[], callback: AnyFunction]
+  ): BasicComputedProperty;
+
+  /**
+   * Specify a method that observes property changes.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  export function observer<Fn extends (target: any, key: string) => void>(
+    ...args: [...propertyNames: string[], func: Fn]
+  ): Fn;
+
+  /**
+   * Gets the value of a property on an object. If the property is computed,
+   * the function will be invoked. If the property is not defined but the
+   * object implements the `unknownProperty` method then that will be invoked.
+   */
+  export function get<T, K extends keyof T>(obj: T, key: K): T[K];
+  export function get(obj: unknown, key: string): unknown;
+
+  /**
+   * Sets the value of a property on an object, respecting computed properties
+   * and notifying observers and other listeners of the change. If the
+   * property is not defined but the object implements the `setUnknownProperty`
+   * method then that will be invoked as well.
+   */
+  export function set<T, K extends keyof T, V extends T[K]>(obj: T, key: K, value: V): V;
+
+  /**
+   * To get multiple properties at once, call `getProperties` with an object
+   * followed by a list of strings or an array.
+   */
+  export function getProperties<T, K extends keyof T>(obj: T, list: K[]): Pick<T, K>;
+  export function getProperties<T, K extends keyof T>(obj: T, ...list: K[]): Pick<T, K>;
+
+  /**
+   * Set a list of properties on an object. These properties are set inside
+   * a single `beginPropertyChanges` and `endPropertyChanges` batch, so
+   * observers will be buffered.
+   */
+  export function setProperties<T, K extends keyof T>(obj: T, hash: Pick<T, K>): Pick<T, K>;
+
+  /**
+   * Error-tolerant form of `Ember.set`. Will not blow up if any part of the
+   * chain is `undefined`, `null`, or destroyed.
+   */
+  export function trySet(root: object, path: string, value: unknown): unknown;
+
+  /**
+   * NOTE: This is a low-level method used by other parts of the API. You almost
+   * never want to call this method directly. Instead you should use mixin() to
+   * define new properties.
+   *
+   * @param obj the object to define this property on. This may be a prototype.
+   * @param keyName the name of the property
+   * @param desc an instance of `Descriptor` (typically a computed property) or an
+   *   ES5 descriptor. You must provide this or `data` but not both.
+   * @param meta Normally this method takes only three parameters. However if you
+   *   pass an instance of Descriptor as the third param then you can pass an
+   *   optional value as the fourth parameter. This is often more efficient than
+   *   creating new descriptor hashes for each property.
+   */
+  export function defineProperty(
+    obj: object,
+    keyName: string,
+    desc: PropertyDescriptor | ComputedProperty,
+    meta?: unknown
+  ): void;
+
+  /**
+   * NOTE: This is a low-level method used by other parts of the API. You almost
+   * never want to call this method directly. Instead you should use mixin() to
+   * define new properties.
+   *
+   * @param obj the object to define this property on. This may be a prototype.
+   * @param keyName the name of the property
+   * @param desc an instance of `Descriptor` (typically a computed property) or an
+   *   ES5 descriptor. You must provide this or `data` but not both.
+   * @param data something other than a descriptor, that will become the explicit
+   *   value of this property.
+   */
+  export function defineProperty(
+    obj: object,
+    keyName: string,
+    desc: undefined,
+    data: unknown
+  ): void;
+
+  export function notifyPropertyChange(obj: object, keyName: string): void;
+
+  export const action: MethodDecorator;
+}
+
+declare module '@ember/utils/-private/types' {
+  import EmberObject from '@ember/object';
+
+  interface TypeLookup {
+    class: typeof EmberObject;
+    instance: EmberObject;
+  }
+}

package/types/preview/@ember/object/internals.d.ts

@@ -0,0 +1,17 @@
+declare module '@ember/object/internals' {
+  /**
+   * Returns the cached value for a property, if one exists.
+   * This can be useful for peeking at the value of a computed
+   * property that is generated lazily, without accidentally causing
+   * it to be created.
+   */
+  export function cacheFor<T, K extends keyof T>(obj: T, key: K): T[K] | undefined;
+
+  /**
+   * Returns a unique id for the object. If the object does not yet have a guid,
+   * one will be assigned to it. You can call this on any object,
+   * `Ember.Object`-based or not, but be aware that it will add a `_guid`
+   * property.
+   */
+  export function guidFor(obj: unknown): string;
+}

package/types/preview/@ember/object/mixin.d.ts

@@ -0,0 +1,19 @@
+declare module '@ember/object/mixin' {
+  const __ember_mixin__: unique symbol;
+
+  /**
+   * The `Ember.Mixin` class allows you to create mixins, whose properties can be
+   * added to other classes.
+   */
+  export default class Mixin {
+    /**
+     * Mixin needs to have *something* on its prototype, otherwise it's treated
+     * like an empty interface. It cannot be private, sadly. We can use this to
+     * carry around the types of the mixin so they don't get lost, though, so
+     * that's... something?
+     */
+    [__ember_mixin__]: never;
+
+    static create(...args: Array<Record<string, unknown> | Mixin>): Mixin;
+  }
+}