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

package/types/preview/@ember/routing/router-service.d.ts

@@ -0,0 +1,351 @@
+declare module '@ember/routing/router-service' {
+  import RouteInfo, { RouteInfoWithAttributes } from '@ember/routing/route-info';
+  import Transition from '@ember/routing/transition';
+  import Service from '@ember/service';
+
+  type RouteModel = object | string | number;
+
+  // https://emberjs.com/api/ember/release/classes/RouterService
+  /**
+   * The Router service is the public API that provides component/view layer access to the router.
+   */
+  export default class RouterService extends Service {
+    //
+    /**
+     * A `RouteInfo` that represents the current leaf route.
+     * It is guaranteed to change whenever a route transition happens
+     * (even when that transition only changes parameters and doesn't change the active route)
+     */
+    readonly currentRoute: RouteInfo;
+    /**
+     * Name of the current route.
+     * This property represent the logical name of the route,
+     * which is comma separated.
+     * For the following router:
+     * ```app/router.js
+     * Router.map(function() {
+     * this.route('about');
+     * this.route('blog', function () {
+     *     this.route('post', { path: ':post_id' });
+     * });
+     * });
+     * ```
+     * It will return:
+     * * `index` when you visit `/`
+     * * `about` when you visit `/about`
+     * * `blog.index` when you visit `/blog`
+     * * `blog.post` when you visit `/blog/some-post-id`
+     */
+    readonly currentRouteName: string;
+    //
+    /**
+     * Current URL for the application.
+     * This property represent the URL path for this route.
+     * For the following router:
+     * ```app/router.js
+     * Router.map(function() {
+     * this.route('about');
+     * this.route('blog', function () {
+     *     this.route('post', { path: ':post_id' });
+     * });
+     * });
+     * ```
+     * It will return:
+     * * `/` when you visit `/`
+     * * `/about` when you visit `/about`
+     * * `/blog` when you visit `/blog`
+     * * `/blog/some-post-id` when you visit `/blog/some-post-id`
+     */
+    readonly currentURL: string;
+
+    /**
+     * The `rootURL` property represents the URL of the root of
+     * the application, '/' by default.
+     * This prefix is assumed on all routes defined on this app.
+     * If you change the `rootURL` in your environment configuration
+     * like so:
+     * ```config/environment.js
+     * 'use strict';
+     * module.exports = function(environment) {
+     *   let ENV = {
+     *     modulePrefix: 'router-service',
+     *     environment,
+     *     rootURL: '/my-root',
+     *   …
+     *   }
+     * ]
+     * ```
+     * This property will return `/my-root`.
+     */
+    readonly rootURL: string;
+
+    /**
+     * Determines whether a route is active.
+     *
+     * @param routeName the name of the route
+     * @param models    the model(s) or identifier(s) to be used while
+     *                  transitioning to the route
+     * @param options   optional hash with a queryParams property containing a
+     *                  mapping of query parameters
+     */
+    isActive(routeName: string, options?: { queryParams: object }): boolean;
+    isActive(routeName: string, models: RouteModel, options?: { queryParams: object }): boolean;
+    isActive(
+      routeName: string,
+      modelsA: RouteModel,
+      modelsB: RouteModel,
+      options?: { queryParams: object }
+    ): boolean;
+    isActive(
+      routeName: string,
+      modelsA: RouteModel,
+      modelsB: RouteModel,
+      modelsC: RouteModel,
+      options?: { queryParams: object }
+    ): boolean;
+    isActive(
+      routeName: string,
+      modelsA: RouteModel,
+      modelsB: RouteModel,
+      modelsC: RouteModel,
+      modelsD: RouteModel,
+      options?: { queryParams: object }
+    ): boolean;
+
+    // https://emberjs.com/api/ember/4.0/classes/RouterService/methods/isActive?anchor=replaceWith
+    /**
+     * Transition into another route while replacing the current URL, if
+     * possible. The route may be either a single route or route path.
+     *
+     * @param routeNameOrUrl the name of the route or a URL
+     * @param models         the model(s) or identifier(s) to be used while
+     *                       transitioning to the route.
+     * @param options        optional hash with a queryParams property
+     *                       containing a mapping of query parameters
+     * @returns              the Transition object associated with this attempted transition
+     */
+    replaceWith(routeNameOrUrl: string, options?: { queryParams: object }): Transition;
+    replaceWith(
+      routeNameOrUrl: string,
+      models: RouteModel,
+      options?: { queryParams: object }
+    ): Transition;
+    replaceWith(
+      routeNameOrUrl: string,
+      modelsA: RouteModel,
+      modelsB: RouteModel,
+      options?: { queryParams: object }
+    ): Transition;
+    replaceWith(
+      routeNameOrUrl: string,
+      modelsA: RouteModel,
+      modelsB: RouteModel,
+      modelsC: RouteModel,
+      options?: { queryParams: object }
+    ): Transition;
+    replaceWith(
+      routeNameOrUrl: string,
+      modelsA: RouteModel,
+      modelsB: RouteModel,
+      modelsC: RouteModel,
+      modelsD: RouteModel,
+      options?: { queryParams: object }
+    ): Transition;
+
+    // https://emberjs.com/api/ember/release/classes/RouterService/methods/isActive?anchor=transitionTo
+    /**
+     * Transition the application into another route. The route may
+     * be either a single route or route path:
+     *
+     * See [transitionTo](https://api.emberjs.com/ember/release/classes/Route/methods/transitionTo?anchor=transitionTo) for more info.
+     *
+     * Calling `transitionTo` from the Router service will cause default query parameter values to be included in the URL.
+     * This behavior is different from calling `transitionTo` on a route or `transitionToRoute` on a controller.
+     * See the [Router Service RFC](https://github.com/emberjs/rfcs/blob/master/text/0095-router-service.md#query-parameter-semantics) for more info.
+     *
+     * In the following example we use the Router service to navigate to a route with a
+     * specific model from a Component.
+     *
+     * ```app/components/example.js
+     * import Component from '@glimmer/component';
+     * import { action } from '@ember/object';
+     * import { inject as service } from '@ember/service';
+     *
+     * export default class extends Component {
+     *   @service router;
+     *
+     *   @action
+     *   goToComments(post) {
+     *     this.router.transitionTo('comments', post);
+     *   }
+     * }
+     * ```
+     *
+     * @param routeNameOrUrl the name of the route or a URL
+     * @param models         the model(s) or identifier(s) to be used while
+     *                       transitioning to the route.
+     * @param options        optional hash with a queryParams property
+     *                       containing a mapping of query parameters. May be
+     *                       supplied as the only parameter to trigger a
+     *                       query-parameter-only transition.
+     * @returns              the Transition object associated with this attempted transition
+     */
+    transitionTo(routeNameOrUrl: string, options?: { queryParams: object }): Transition;
+    transitionTo(
+      routeNameOrUrl: string,
+      models: RouteModel,
+      options?: { queryParams: object }
+    ): Transition;
+    transitionTo(
+      routeNameOrUrl: string,
+      modelsA: RouteModel,
+      modelsB: RouteModel,
+      options?: { queryParams: object }
+    ): Transition;
+    transitionTo(
+      routeNameOrUrl: string,
+      modelsA: RouteModel,
+      modelsB: RouteModel,
+      modelsC: RouteModel,
+      options?: { queryParams: object }
+    ): Transition;
+    transitionTo(
+      routeNameOrUrl: string,
+      modelsA: RouteModel,
+      modelsB: RouteModel,
+      modelsC: RouteModel,
+      modelsD: RouteModel,
+      options?: { queryParams: object }
+    ): Transition;
+    transitionTo(options: { queryParams: object }): Transition;
+
+    // https://emberjs.com/api/ember/4.3.0/classes/RouterService/methods/isActive?anchor=urlFor
+    /**
+     * Generate a URL based on the supplied route name.
+     *
+     * @param routeName the name of the route or a URL
+     * @param models    the model(s) or identifier(s) to be used while
+     *                  transitioning to the route.
+     * @param options   optional hash with a queryParams property containing
+     *                  a mapping of query parameters
+     * @returns         the string representing the generated URL
+     */
+    urlFor(
+      routeName: string,
+      ...args: RouteModel[] | [...RouteModel[], { queryParams: object }]
+    ): string;
+
+    // https://api.emberjs.com/ember/3.6/classes/RouterService/events/routeDidChange?anchor=routeDidChange
+    /**
+     * Register a callback for an event.
+     *
+     * The `routeWillChange` event is fired at the beginning of any attempted transition with a `Transition` object as the sole argument.
+     * This action can be used for aborting, redirecting, or decorating the transition from the currently active routes.
+     *
+     * The `routeDidChange` event only fires once a transition has settled.
+     * This includes aborts and error substates.
+     * Like the `routeWillChange` event it recieves a `Transition` as the sole argument.
+     *
+     * @param name     the name of the event
+     * @param callback the callback to execute
+     */
+    on(
+      name: 'routeDidChange' | 'routeWillChange',
+      callback: (transition: Transition) => void
+    ): RouterService;
+
+    // https://api.emberjs.com/ember/3.28/classes/Evented/methods/off?anchor=off
+    /**
+     * Removes a callback for an event.
+     *
+     * The `routeWillChange` event is fired at the beginning of any attempted transition with a `Transition` object as the sole argument.
+     * This action can be used for aborting, redirecting, or decorating the transition from the currently active routes.
+     *
+     * The `routeDidChange` event only fires once a transition has settled.
+     * This includes aborts and error substates.
+     *
+     * @param name     the name of the event 'routeWillChange' | 'routeDidChange'
+     * @param callback the callback to remove
+     */
+    off(
+      name: 'routeDidChange' | 'routeWillChange',
+      callback: (transition: Transition) => void
+    ): RouterService;
+
+    /**
+     * https://api.emberjs.com/ember/3.28/classes/Evented/methods/off?anchor=has
+     *
+     * Checks to see if object has any subscriptions for named event.
+     *
+     * @param name
+     */
+    has(name: string): boolean;
+
+    /**
+     * https://api.emberjs.com/ember/3.28/classes/Evented/methods/off?anchor=one
+     *
+     * 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.
+     *
+     * @param name     the name of the event
+     * @param callback the callback to execute
+     */
+    one(
+      name: 'routeDidChange' | 'routeWillChange',
+      callback: (transition: Transition) => void
+    ): RouterService;
+
+    /**
+     * https://api.emberjs.com/ember/3.28/classes/Evented/methods/off?anchor=trigger
+     *
+     * Triggers a named event for the object.
+     * Any additional arguments will be passed as parameters to the functions that are subscribed to the event.
+     *
+     * @param name the name of the event
+     * @param args arguments to pass to the event
+     */
+    trigger(name: string, args: any): void;
+
+    /**
+     * Takes a string URL and returns a `RouteInfo` for the leafmost route represented
+     * by the URL. Returns `null` if the URL is not recognized. This method expects to
+     * receive the actual URL as seen by the browser including the app's `rootURL`.
+     * See [RouteInfo](/ember/release/classes/RouteInfo) for more info.
+     * In the following example `recognize` is used to verify if a path belongs to our
+     * application before transitioning to it.
+     * ```
+     * import Component from '@ember/component';
+     * import { inject as service } from '@ember/service';
+     * export default class extends Component {
+     *   @service router;
+     *   path = '/';
+     *   click() {
+     *     if (this.router.recognize(this.path)) {
+     *       this.router.transitionTo(this.path);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    recognize(url: string): RouteInfo;
+
+    /**
+     * Takes a string URL and returns a promise that resolves to a
+     * `RouteInfoWithAttributes` for the leafmost route represented by the URL.
+     * The promise rejects if the URL is not recognized or an unhandled exception
+     * is encountered. This method expects to receive the actual URL as seen by
+     * the browser including the app's `rootURL`.
+     */
+    recognizeAndLoad(url: string): RouteInfoWithAttributes;
+
+    /**
+     * Refreshes all currently active routes, doing a full transition.
+     * If a route name is provided and refers to a currently active route,
+     * it will refresh only that route and its descendents.
+     * Returns a promise that will be resolved once the refresh is complete.
+     * All resetController, beforeModel, model, afterModel, redirect, and setupController
+     * hooks will be called again. You will get new data from the model hook.
+     */
+    refresh(pivotRouteName?: string): Transition;
+  }
+}

package/types/preview/@ember/routing/router.d.ts

@@ -0,0 +1,49 @@
+declare module '@ember/routing/router' {
+  import EmberObject from '@ember/object';
+  import Evented from '@ember/object/evented';
+  import RouterDSL from '@ember/routing/-private/router-dsl';
+  import Transition from '@ember/routing/transition';
+
+  /**
+   * The `Ember.Router` class manages the application state and URLs. Refer to
+   * the [routing guide](http://emberjs.com/guides/routing/) for documentation.
+   */
+  export default class Router extends EmberObject {
+    /**
+     * The `Router.map` function allows you to define mappings from URLs to routes
+     * in your application. These mappings are defined within the
+     * supplied callback function using `this.route`.
+     */
+    static map(callback: (this: RouterDSL) => void): void;
+    /**
+     * The `location` property determines the type of URL's that your
+     * application will use.
+     *
+     * @note the `'auto'` location is [deprecated](https://deprecations.emberjs.com/v4.x/#toc_deprecate-auto-location).
+     */
+    location: 'history' | 'hash' | 'none' | 'auto';
+    /**
+     * Represents the URL of the root of the application, often '/'. This prefix is
+     * assumed on all routes defined on this router.
+     */
+    rootURL: string;
+    /**
+     * Transition the application into another route. The route may
+     * be either a single route or route path:
+     */
+    transitionTo(name: string, options?: {}): Transition;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    transitionTo(name: string, ...models: any[]): Transition;
+    transitionTo(name: string, options: {}): Transition;
+  }
+
+  export default interface RouterService extends Evented {}
+}
+
+declare module '@ember/service' {
+  import RouterService from '@ember/routing/router-service';
+
+  interface Registry {
+    router: RouterService;
+  }
+}

package/types/preview/@ember/routing/transition.d.ts

@@ -0,0 +1,126 @@
+declare module '@ember/routing/transition' {
+  import RouteInfo, { RouteInfoWithAttributes } from '@ember/routing/route-info';
+
+  /**
+   * A Transition is a thennable (a promise-like object) that represents an
+   * attempt to transition to another route. It can be aborted, either explicitly
+   * via `abort` or by attempting another transition while a previous one is still
+   * underway. An aborted transition can also be `retry()`d later.
+   *
+   * @note This is a non-user-constructible type. The only legal way to get a
+   *   transition is using one of the public API methods on routes, controllers,
+   *   the router service, etc.
+   */
+  export default interface Transition<T = unknown> extends Partial<Promise<T>> {
+    /**
+     * Custom state can be stored on a Transition's `data` object.
+     * This can be useful for decorating a Transition within an earlier hook and shared with a later hook.
+     * Properties set on `data` will be copied to new transitions generated by calling `retry` on this transition.
+     */
+    data: Record<string, unknown>;
+    /**
+     * This property is a `RouteInfo` object that represents where transition originated from.
+     * It's important to note that a `RouteInfo` is a linked list and this property is simply the head node of the list.
+     * In the case of an initial render, `from` will be set to `null`.
+     */
+    readonly from: RouteInfoWithAttributes | null;
+    /**
+     * The Transition's internal promise.
+     * Calling `.then` on this property is that same as calling `.then` on the Transition object itself,
+     * but this property is exposed for when you want to pass around a Transition's promise,
+     * but not the Transition object itself, since Transition object can be externally `abort`ed,
+     * while the promise cannot.
+     */
+    readonly promise: Promise<T>;
+    /**
+     * This property is a `RouteInfo` object that represents where the router is transitioning to.
+     * It's important to note that a `RouteInfo` is a linked list and this property is simply the leafmost route.
+     */
+    readonly to: RouteInfo | RouteInfoWithAttributes;
+    /**
+     * Aborts the Transition. Note you can also implicitly abort a transition
+     * by initiating another transition while a previous one is underway.
+     */
+    abort(): Transition<T>;
+    /**
+     * Forwards to the internal `promise` property which you can use in situations where you want to pass around a thennable,
+     * but not the Transition itself.
+     *
+     * @param onRejection
+     * @param label optional string for labeling the promise. Useful for tooling.
+     */
+    catch<TResult = never>(
+      onRejected?: (reason: unknown) => TResult | PromiseLike<TResult>,
+      label?: string
+    ): Promise<TResult | T>;
+    /**
+     * Forwards to the internal `promise` property which you can use in situations where you want to pass around a thennable,
+     * but not the Transition itself.
+     *
+     * @param onFinally
+     * @param label optional string for labeling the promise. Useful for tooling.
+     */
+    finally(onFinally?: () => void, label?: string): Promise<T>;
+    /**
+     * Transitions are aborted and their promises rejected when redirects occur;
+     * this method returns a promise that will follow any redirects that occur and
+     * fulfill with the value fulfilled by any redirecting transitions that occur.
+     *
+     * @return a promise that fulfills with the same value that the final redirecting transition fulfills with
+     */
+    followRedirects(): Promise<T>;
+    /**
+     * Sets the URL-changing method to be employed at the end of a successful transition.
+     * By default, a new Transition will just use `updateURL`,
+     * but passing 'replace' to this method will cause the URL to update using 'replaceWith' instead.
+     * Omitting a parameter will disable the URL change,
+     * allowing for transitions that don't update the URL at completion
+     * (this is also used for handleURL, since the URL has already changed before the transition took place).
+     *
+     * @param  method the type of URL-changing method to use at the end of a transition. Accepted values are 'replace',
+     *                falsy values, or any other non-falsy value (which is interpreted as an updateURL transition).
+     * @return        This transition
+     */
+    method(method?: string): Transition<T>;
+    /**
+     * Retries a previously-aborted transition (making sure to abort the
+     * transition if it's still active). Returns a new transition that
+     * represents the new attempt to transition.
+     */
+    retry(): Transition<T>;
+    /**
+     * A standard promise hook that resolves if the transition succeeds and rejects if it fails/redirects/aborts.
+     *
+     * Forwards to the internal `promise` property which you can use in situations where you want to pass around a thennable,
+     * but not the Transition itself.
+     *
+     * @param  onFulfilled
+     * @param  onRejected
+     * @param  label label optional string for labeling the promise. Useful for tooling.
+     */
+    then<TResult1 = T, TResult2 = never>(
+      onfulfilled?: (value: T) => TResult1 | PromiseLike<TResult1>,
+      onrejected?: (reason: unknown) => TResult2 | PromiseLike<TResult2>,
+      label?: string
+    ): Promise<TResult1 | TResult2>;
+    /**
+     * Fires an event on the current list of resolved/resolving handlers within this transition.
+     * Useful for firing events on route hierarchies that haven't fully been entered yet.
+     *
+     * @param  ignoreFailure a boolean specifying whether unhandled events throw an error
+     * @param  name          the name of the event to fire
+     */
+    send(ignoreFailure: boolean, name: string): void;
+    /**
+     * Fires an event on the current list of resolved/resolving handlers within this transition.
+     * Useful for firing events on route hierarchies that haven't fully been entered yet.
+     * Note: This method is also aliased as `send`
+     *
+     * @alias send
+     *
+     * @param  ignoreFailure a boolean specifying whether unhandled events throw an error
+     * @param  name          the name of the event to fire
+     */
+    trigger(ignoreFailure: boolean, name: string): void;
+  }
+}

package/types/preview/@ember/routing/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../tsconfig.json"
+}

package/types/preview/@ember/routing/types.d.ts

@@ -0,0 +1,15 @@
+declare module '@ember/routing/types' {
+  export interface RenderOptions {
+    into?: string | undefined;
+    controller?: string | undefined;
+    model?: unknown;
+    outlet?: string | undefined;
+    view?: string | undefined;
+  }
+
+  export interface RouteQueryParam {
+    refreshModel?: boolean | undefined;
+    replace?: boolean | undefined;
+    as?: string | undefined;
+  }
+}

package/types/preview/@ember/runloop/-private/backburner.d.ts

@@ -0,0 +1,43 @@
+declare module '@ember/runloop/-private/backburner' {
+  import { EmberMethod, EmberMethodParams } from 'ember/-private/type-utils';
+
+  export interface QueueItem {
+    method: string;
+    target: object;
+    args: object[];
+    stack: string | undefined;
+  }
+
+  export interface DeferredActionQueues {
+    [index: string]: unknown;
+    queues: object;
+    schedule<T, M extends EmberMethod<T>>(
+      ...args: [
+        queueName: string,
+        target: T,
+        method: M,
+        ...methodArgs: EmberMethodParams<T, M>,
+        onceFlag: boolean,
+        stack: unknown
+      ]
+    ): any;
+    flush(fromAutorun: boolean): any;
+  }
+
+  export interface DebugInfo {
+    autorun: Error | undefined | null;
+    counters: object;
+    timers: QueueItem[];
+    instanceStack: DeferredActionQueues[];
+  }
+
+  export interface Backburner {
+    join(...args: any[]): void;
+    on(...args: any[]): void;
+    scheduleOnce(...args: any[]): void;
+    schedule(queueName: string, target: object | null, method: () => void | string): void;
+    ensureInstance(): void;
+    DEBUG: boolean;
+    getDebugInfo(): DebugInfo;
+  }
+}

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

@@ -0,0 +1,9 @@
+declare module '@ember/runloop/-private/types' {
+  export type EmberRunQueues =
+    | 'sync'
+    | 'actions'
+    | 'routerTransitions'
+    | 'render'
+    | 'afterRender'
+    | 'destroy';
+}