@types/ember__routing/route.d.ts

TypeScript definitions for @ember/routing

import EmberObject from "@ember/object";
import ActionHandler from "@ember/object/-private/action-handler";
// eslint-disable-next-line @definitelytyped/no-self-import
import Evented from "@ember/object/evented";
// eslint-disable-next-line @definitelytyped/no-self-import
import Transition from "@ember/routing/transition";
// eslint-disable-next-line @definitelytyped/no-self-import
import Controller from "@ember/controller";
// eslint-disable-next-line @definitelytyped/no-self-import
import { RouteQueryParam } from "@ember/routing/types";

// eslint-disable-next-line @definitelytyped/strict-export-declare-modifiers
type RouteModel = object | string | number;

/**
 * The `Ember.Route` class is used to define individual routes. Refer to
 * the [routing guide](http://emberjs.com/guides/routing/) for documentation.
 */
export default class Route<Model = unknown, Params extends object = object> extends EmberObject {
    // methods
    /**
     * This hook is called after this route's model has resolved. It follows
     * identical async/promise semantics to `beforeModel` but is provided the
     * route's resolved model in addition to the `transition`, and is therefore
     * suited to performing logic that can only take place after the model has
     * already resolved.
     *
     * @returns if the value returned from this hook is a promise, the
     *   transition will pause until the transition resolves. Otherwise,
     *   non-promise return values are not utilized in any way.
     */
    afterModel(resolvedModel: Model, transition: Transition): Promise<unknown> | void;

    /**
     * This hook is the first of the route entry validation hooks called when an
     * attempt is made to transition into a route or one of its children. It is
     * called before `model` and `afterModel`, and is appropriate for cases
     * when:
     *
     * 1. A decision can be made to redirect elsewhere without needing to
     *     resolve the model first.
     * 2. Any async operations need to occur first before the model is attempted
     *     to be resolved.
     *
     * This hook is provided the current `transition` attempt as a parameter,
     * which can be used to `.abort()` the transition, save it for a later
     * `.retry()`, or retrieve values set on it from a previous hook. You can
     * also just call `this.transitionTo` to another route to implicitly abort
     * the `transition`. You can return a promise from this hook to pause the
     * transition until the promise resolves (or rejects). This could be useful,
     * for instance, for retrieving async code from the server that is required
     * to enter a route.
     *
     * @returns if the value returned from this hook is a promise, the
     *   transition will pause until the transition resolves. Otherwise,
     *   non-promise return values are not utilized in any way.
     */
    beforeModel(transition: Transition): Promise<unknown> | void;

    /**
     * Returns the controller of the current route, or a parent (or any
     * ancestor) route in a route hierarchy.
     *
     * The controller instance must already have been created, either through
     * entering the associated route or using `generateController`.
     *
     * @param name the name of the route or controller
     */
    controllerFor(name: string): Controller;

    /**
     * A hook you can implement to convert the URL into the model for
     * this route.
     */
    model(params: Params, transition: Transition): Model | PromiseLike<Model>;

    /**
     * Returns the model of a parent (or any ancestor) route
     * in a route hierarchy.  During a transition, all routes
     * must resolve a model object, and if a route
     * needs access to a parent route's model in order to
     * resolve a model (or just reuse the model from a parent),
     * it can call `this.modelFor(theNameOfParentRoute)` to
     * retrieve it.
     */
    modelFor(name: string): unknown;

    /**
     * Retrieves parameters, for current route using the state.params
     * variable and getQueryParamsFor, using the supplied routeName.
     */
    paramsFor(name: string): object;

    /**
     * A hook you can implement to optionally redirect to another route.
     *
     * If you call `this.transitionTo` from inside of this hook, this route
     * will not be entered in favor of the other hook.
     *
     * `redirect` and `afterModel` behave very similarly and are
     * called almost at the same time, but they have an important
     * distinction in the case that, from one of these hooks, a
     * redirect into a child route of this route occurs: redirects
     * from `afterModel` essentially invalidate the current attempt
     * to enter this route, and will result in this route's `beforeModel`,
     * `model`, and `afterModel` hooks being fired again within
     * the new, redirecting transition. Redirects that occur within
     * the `redirect` hook, on the other hand, will _not_ cause
     * these hooks to be fired again the second time around; in
     * other words, by the time the `redirect` hook has been called,
     * both the resolved model and attempted entry into this route
     * are considered to be fully validated.
     */
    redirect(model: Model, transition: Transition): void;

    /**
     * Refresh the model on this route and any child routes, firing the
     * `beforeModel`, `model`, and `afterModel` hooks in a similar fashion
     * to how routes are entered when transitioning in from other route.
     * The current route params (e.g. `article_id`) will be passed in
     * to the respective model hooks, and if a different model is returned,
     * `setupController` and associated route hooks will re-fire as well.
     * An example usage of this method is re-querying the server for the
     * latest information using the same parameters as when the route
     * was first entered.
     * Note that this will cause `model` hooks to fire even on routes
     * that were provided a model object when the route was initially
     * entered.
     */
    refresh(): Transition;

    /**
     * Transition into another route while replacing the current URL, if possible.
     * This will replace the current history entry instead of adding a new one.
     * Beside that, it is identical to `transitionTo` in all other respects. See
     * 'transitionTo' for additional information regarding multiple models.
     *
     * @param name    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
     * @deprecated    until 5.0. Inject the router service and use its methods.
     */
    replaceWith(name: string, ...args: unknown[]): Transition;

    /**
     * A hook you can use to reset controller values either when the model
     * changes or the route is exiting.
     */
    resetController(controller: Controller, isExiting: boolean, transition: Transition): void;

    /**
     * Sends an action to the router, which will delegate it to the currently active
     * route hierarchy per the bubbling rules explained under actions.
     */
    send(name: string, ...args: unknown[]): void;

    /**
     * A hook you can implement to convert the route's model into parameters
     * for the URL.
     *
     * The default `serialize` method will insert the model's `id` into the
     * route's dynamic segment (in this case, `:post_id`) if the segment contains '_id'.
     * If the route has multiple dynamic segments or does not contain '_id', `serialize`
     * will return `Ember.getProperties(model, params)`
     * This method is called when `transitionTo` is called with a context
     * in order to populate the URL.
     */
    serialize(model: Model, params: string[]): string | object;

    /**
     * A hook you can use to setup the controller for the current route.
     * This method is called with the controller for the current route and the
     * model supplied by the `model` hook.
     * By default, the `setupController` hook sets the `model` property of
     * the controller to the `model`.
     * If you implement the `setupController` hook in your Route, it will
     * prevent this default behavior. If you want to preserve that behavior
     * when implementing your `setupController` function, make sure to call
     * `_super`
     */
    setupController(controller: Controller, model: Model, transition: Transition): void;

    /**
     * Transition the application into another route. The route may
     * be either a single route or route path:
     *
     * ```javascript
     * this.transitionTo('blogPosts');
     * this.transitionTo('blogPosts.recentEntries');
     * ```
     *
     * Optionally supply a model for the route in question. The model
     * will be serialized into the URL using the `serialize` hook of
     * the route:
     *
     * ```javascript
     * this.transitionTo('blogPost', aPost);
     * ```
     *
     * If a literal is passed (such as a number or a string), it will
     * be treated as an identifier instead. In this case, the `model`
     * hook of the route will be triggered:
     *
     * ```javascript
     * this.transitionTo('blogPost', 1);
     * ```
     *
     * Multiple models will be applied last to first recursively up the
     * route tree.
     *
     * ```app/routes.js
     * // ...
     *
     * Router.map(function() {
     *   this.route('blogPost', { path:':blogPostId' }, function() {
     *     this.route('blogComment', { path: ':blogCommentId' });
     *   });
     * });
     *
     * export default Router;
     * ```
     *
     * ```javascript
     * this.transitionTo('blogComment', aPost, aComment);
     * this.transitionTo('blogComment', 1, 13);
     * ```
     *
     * It is also possible to pass a URL (a string that starts with a
     * `/`).
     *
     * ```javascript
     * this.transitionTo('/');
     * this.transitionTo('/blog/post/1/comment/13');
     * this.transitionTo('/blog/posts?sort=title');
     * ```
     *
     * An options hash with a `queryParams` property may be provided as
     * the final argument to add query parameters to the destination URL.
     *
     * ```javascript
     * this.transitionTo('blogPost', 1, {
     *   queryParams: { showComments: 'true' }
     * });
     *
     * // if you just want to transition the query parameters without changing the route
     * this.transitionTo({ queryParams: { sort: 'date' } });
     * ```
     *
     * See also [replaceWith](#method_replaceWith).
     *
     * Simple Transition Example
     *
     * ```app/routes.js
     * // ...
     *
     * Router.map(function() {
     *   this.route('index');
     *   this.route('secret');
     *   this.route('fourOhFour', { path: '*:' });
     * });
     *
     * export default Router;
     * ```
     *
     * ```app/routes/index.js
     * import Route from '@ember/routing/route';
     * import { action } from '@ember/object';
     *
     * export default class IndexRoute extends Route {
     *   @action
     *   moveToSecret(context) {
     *     if (authorized()) {
     *       this.transitionTo('secret', context);
     *     } else {
     *       this.transitionTo('fourOhFour');
     *     }
     *   }
     * }
     * ```
     *
     * Transition to a nested route
     *
     * ```app/router.js
     * // ...
     *
     * Router.map(function() {
     *   this.route('articles', { path: '/articles' }, function() {
     *     this.route('new');
     *   });
     * });
     *
     * export default Router;
     * ```
     *
     * ```app/routes/index.js
     * import Route from '@ember/routing/route';
     * import { action } from '@ember/object';
     *
     * export default class IndexRoute extends Route {
     *   @action
     *   transitionToNewArticle() {
     *     this.transitionTo('articles.new');
     *   }
     * }
     * ```
     *
     * Multiple Models Example
     *
     * ```app/router.js
     * // ...
     *
     * Router.map(function() {
     *   this.route('index');
     *
     *   this.route('breakfast', { path: ':breakfastId' }, function() {
     *     this.route('cereal', { path: ':cerealId' });
     *   });
     * });
     *
     * export default Router;
     * ```
     *
     * ```app/routes/index.js
     * import Route from '@ember/routing/route';
     * import { action } from '@ember/object';
     *
     * export default class IndexRoute extends Route {
     *   @action
     *   moveToChocolateCereal() {
     *     let cereal = { cerealId: 'ChocolateYumminess' };
     *     let breakfast = { breakfastId: 'CerealAndMilk' };
     *
     *     this.transitionTo('breakfast.cereal', breakfast, cereal);
     *   }
     * }
     * ```
     *
     * Nested Route with Query String Example
     *
     * ```app/routes.js
     * // ...
     *
     * Router.map(function() {
     *   this.route('fruits', function() {
     *     this.route('apples');
     *   });
     * });
     *
     * export default Router;
     * ```
     *
     * ```app/routes/index.js
     * import Route from '@ember/routing/route';
     *
     * export default class IndexRoute extends Route {
     *   @action
     *   transitionToApples() {
     *     this.transitionTo('fruits.apples', { queryParams: { color: 'red' } });
     *   }
     * }
     * ```
     *
     * @param name    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
     * @deprecated    until 5.0. Inject the router service and use its methods.
     */
    transitionTo(name: string, options?: { queryParams: object }): Transition;
    transitionTo(name: string, modelsA: RouteModel, options?: { queryParams: object }): Transition;
    transitionTo(name: string, modelsA: RouteModel, modelsB: RouteModel, options?: { queryParams: object }): Transition;
    transitionTo(
        name: string,
        modelsA: RouteModel,
        modelsB: RouteModel,
        modelsC: RouteModel,
        options?: { queryParams: object },
    ): Transition;
    transitionTo(
        name: string,
        modelsA: RouteModel,
        modelsB: RouteModel,
        modelsC: RouteModel,
        modelsD: RouteModel,
        options?: { queryParams: object },
    ): Transition;
    transitionTo(options: { queryParams: object }): Transition;

    // https://emberjs.com/api/ember/release/classes/Route/methods/intermediateTransitionTo?anchor=intermediateTransitionTo
    /**
     * Perform a synchronous transition into another route without attempting to resolve promises,
     * update the URL, or abort any currently active asynchronous transitions
     * (i.e. regular transitions caused by transitionTo or URL changes).
     *
     * @param name           the name of the route or a URL
     * @param models         the model(s) or identifier(s) to be used while
     *                       transitioning to the route.
     * @returns              the Transition object associated with this attempted transition
     */
    intermediateTransitionTo(name: string, ...models: unknown[]): Transition;

    // properties
    /**
     * The controller associated with this route.
     */
    controller: Controller;

    /**
     * The name of the controller to associate with this route.
     * By default, Ember will lookup a route's controller that matches the name
     * of the route (i.e. `App.PostController` for `App.PostRoute`). However,
     * if you would like to define a specific controller to use, you can do so
     * using this property.
     * This is useful in many ways, as the controller specified will be:
     * * p assed to the `setupController` method.
     * * used as the controller for the view being rendered by the route.
     * * returned from a call to `controllerFor` for the route.
     */
    controllerName: string;

    /**
     * The name of the route, dot-delimited, including the engine prefix if applicable.
     */
    fullRouteName: string;

    /**
     * Configuration hash for this route's queryParams.
     */
    queryParams: { [key: string]: RouteQueryParam };

    /**
     * The name of the route, dot-delimited
     */
    routeName: string;

    /**
     * The name of the template to use by default when rendering this routes
     * template.
     * This is similar with `viewName`, but is useful when you just want a custom
     * template without a view.
     */
    templateName: string;

    // events
    /**
     * This hook is executed when the router enters the route. It is not executed
     * when the model for the route changes.
     */
    activate(transition: Transition): void;

    /**
     * This hook is executed when the router completely exits this route. It is
     * not executed when the model for the route changes.
     */
    deactivate(transition: Transition): void;

    /**
     * The didTransition action is fired after a transition has successfully been
     * completed. This occurs after the normal model hooks (beforeModel, model,
     * afterModel, setupController) have resolved. The didTransition action has
     * no arguments, however, it can be useful for tracking page views or resetting
     * state on the controller.
     */
    didTransition(): void;

    /**
     * When attempting to transition into a route, any of the hooks may return a promise
     * that rejects, at which point an error action will be fired on the partially-entered
     * routes, allowing for per-route error handling logic, or shared error handling logic
     * defined on a parent route.
     */
    error(error: unknown, transition: Transition): void;

    /**
     * The loading action is fired on the route when a route's model hook returns a
     * promise that is not already resolved. The current Transition object is the first
     * parameter and the route that triggered the loading event is the second parameter.
     */
    loading(transition: Transition, route: Route): void;

    /**
     * The willTransition action 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.
     */
    willTransition(transition: Transition): void;

    /**
     * Allows you to produce custom metadata for the route.
     * The return value of this method will be attached to
     * its corresponding RouteInfoWithAttributes object.
     * Example
     * ```app/routes/posts/index.js
     * import Route from '@ember/routing/route';
     * export default class PostsIndexRoute extends Route {
     *   buildRouteInfoMetadata() {
     *     return { title: 'Posts Page' }
     *   }
     * }
     * ```
     * ```app/routes/application.js
     * import Route from '@ember/routing/route';
     * import { inject as service } from '@ember/service';
     * export default class ApplicationRoute extends Route {
     *   @service router
     *   constructor() {
     *     super(...arguments);
     *     this.router.on('routeDidChange', transition => {
     *       document.title = transition.to.metadata.title;
     *       // would update document's title to "Posts Page"
     *     });
     *   }
     * }
     * ```
     */
    buildRouteInfoMetadata(): unknown;
}

// eslint-disable-next-line @typescript-eslint/no-empty-interface -- used for declaration merge
export default interface Route<Model = unknown, Params extends object = object> extends ActionHandler, Evented {}