[RFC 674] Deprecate transition methods of controller and route

packages/@ember/-internals/glimmer/tests/integration/application/rendering-test.js

@@ -696,7 +696,9 @@ moduleFor(
         'route:index',
         Route.extend({
           activate() {
-            this.transitionTo('a');
+            expectDeprecation(() => {
+              this.transitionTo('a');
+            }, /Calling transitionTo on a route is deprecated/);
           },
         })
       );

packages/@ember/-internals/glimmer/tests/integration/components/link-to/routing-angle-test.js

@@ -1876,7 +1876,7 @@ moduleFor(
     [`@test GJ: <LinkTo /> to a parent root model hook which performs a 'transitionTo' has correct active class #13256`](
       assert
     ) {
-      assert.expect(1);
+      assert.expect(3);
 
       this.router.map(function () {
         this.route('parent', function () {
@@ -1888,7 +1888,9 @@ moduleFor(
         'route:parent',
         Route.extend({
           afterModel() {
-            this.transitionTo('parent.child');
+            expectDeprecation(() => {
+              this.transitionTo('parent.child');
+            }, /Calling transitionTo on a route is deprecated/);
           },
         })
       );

packages/@ember/-internals/glimmer/tests/integration/components/link-to/routing-curly-test.js

@@ -2143,7 +2143,7 @@ moduleFor(
     [`@test GJ: {{link-to}} to a parent root model hook which performs a 'transitionTo' has correct active class #13256`](
       assert
     ) {
-      assert.expect(1);
+      assert.expect(3);
 
       this.router.map(function () {
         this.route('parent', function () {
@@ -2155,7 +2155,9 @@ moduleFor(
         'route:parent',
         Route.extend({
           afterModel() {
-            this.transitionTo('parent.child');
+            expectDeprecation(() => {
+              this.transitionTo('parent.child');
+            }, /Calling transitionTo on a route is deprecated/);
           },
         })
       );

packages/@ember/-internals/routing/lib/ext/controller.ts

@@ -1,6 +1,6 @@
 import { get } from '@ember/-internals/metal';
 import ControllerMixin from '@ember/controller/lib/controller_mixin';
-import { prefixRouteNameArg } from '../utils';
+import { deprecateTransitionMethods, prefixRouteNameArg } from '../utils';
 
 /**
 @module ember
@@ -149,9 +149,12 @@ ControllerMixin.reopen({
     @method transitionToRoute
     @return {Transition} the transition object associated with this
       attempted transition
+    @deprecated Use transitionTo from the Router service instead.
     @public
   */
   transitionToRoute(...args: any[]) {
+    deprecateTransitionMethods('controller', 'transitionToRoute');
+
     // target may be either another controller or a router
     let target = get(this, 'target');
     let method = target.transitionToRoute || target.transitionTo;
@@ -218,6 +221,7 @@ ControllerMixin.reopen({
     @public
   */
   replaceRoute(...args: string[]) {
+    deprecateTransitionMethods('controller', 'replaceRoute');
     // target may be either another controller or a router
     let target = get(this, 'target');
     let method = target.replaceRoute || target.replaceWith;

packages/@ember/-internals/routing/lib/system/route.ts

@@ -38,6 +38,7 @@ import {
 } from 'router_js';
 import {
   calculateCacheKey,
+  deprecateTransitionMethods,
   normalizeControllerQueryParams,
   prefixRouteNameArg,
   stashParamNames,
@@ -805,10 +806,11 @@ class Route extends EmberObject implements IRoute {
     @return {Transition} the transition object associated with this
       attempted transition
     @since 1.0.0
+    @deprecated Use transitionTo from the Router service instead.
     @public
   */
   transitionTo(...args: any[]) {
-    // eslint-disable-line no-unused-vars
+    deprecateTransitionMethods('route', 'transitionTo');
     return this._router.transitionTo(...prefixRouteNameArg(this, args));
   }
 
@@ -903,6 +905,7 @@ class Route extends EmberObject implements IRoute {
     @public
   */
   replaceWith(...args: any[]) {
+    deprecateTransitionMethods('route', 'replaceWith');
     return this._router.replaceWith(...prefixRouteNameArg(this, args));
   }
 

packages/@ember/-internals/routing/lib/utils.ts

@@ -1,5 +1,6 @@
 import { get } from '@ember/-internals/metal';
 import { getOwner } from '@ember/-internals/owner';
+import { deprecate } from '@ember/debug';
 import EmberError from '@ember/error';
 import { assign } from '@ember/polyfills';
 import Router, { STATE_SYMBOL } from 'router_js';
@@ -242,3 +243,19 @@ export function shallowEqual(a: {}, b: {}) {
 
   return aCount === bCount;
 }
+
+export function deprecateTransitionMethods(frameworkClass: string, methodName: string) {
+  deprecate(
+    `Calling ${methodName} on a ${frameworkClass} is deprecated. Use the RouterService instead.`,
+    false,
+    {
+      id: 'routing.transition-methods',
+      for: 'ember-source',
+      since: {
+        enabled: '3.26.0',
+      },
+      until: '4.0.0',
+      url: 'https://deprecations.emberjs.com/v3.x/#toc_routing-transition-methods',
+    }
+  );
+}

packages/@ember/-internals/routing/tests/ext/controller_test.js

@@ -22,27 +22,35 @@ moduleFor(
       let controller = Controller.create({ target: router });
       setOwner(controller, engineInstance);
 
-      assert.strictEqual(
-        controller.transitionToRoute('application'),
-        'foo.bar.application',
-        'properly prefixes application route'
-      );
-      assert.strictEqual(
-        controller.transitionToRoute('posts'),
-        'foo.bar.posts',
-        'properly prefixes child routes'
-      );
-      assert.throws(
-        () => controller.transitionToRoute('/posts'),
-        'throws when trying to use a url'
-      );
+      expectDeprecation(() => {
+        assert.strictEqual(
+          controller.transitionToRoute('application'),
+          'foo.bar.application',
+          'properly prefixes application route'
+        );
+      }, /Calling transitionToRoute on a controller is deprecated/);
+      expectDeprecation(() => {
+        assert.strictEqual(
+          controller.transitionToRoute('posts'),
+          'foo.bar.posts',
+          'properly prefixes child routes'
+        );
+      }, /Calling transitionToRoute on a controller is deprecated/);
+      expectDeprecation(() => {
+        assert.throws(
+          () => controller.transitionToRoute('/posts'),
+          'throws when trying to use a url'
+        );
+      }, /Calling transitionToRoute on a controller is deprecated/);
 
       let queryParams = {};
-      assert.strictEqual(
-        controller.transitionToRoute(queryParams),
-        queryParams,
-        'passes query param only transitions through'
-      );
+      expectDeprecation(() => {
+        assert.strictEqual(
+          controller.transitionToRoute(queryParams),
+          queryParams,
+          'passes query param only transitions through'
+        );
+      }, /Calling transitionToRoute on a controller is deprecated/);
     }
 
     ["@test replaceRoute considers an engine's mountPoint"](assert) {
@@ -62,24 +70,32 @@ moduleFor(
       let controller = Controller.create({ target: router });
       setOwner(controller, engineInstance);
 
-      assert.strictEqual(
-        controller.replaceRoute('application'),
-        'foo.bar.application',
-        'properly prefixes application route'
-      );
-      assert.strictEqual(
-        controller.replaceRoute('posts'),
-        'foo.bar.posts',
-        'properly prefixes child routes'
-      );
-      assert.throws(() => controller.replaceRoute('/posts'), 'throws when trying to use a url');
+      expectDeprecation(() => {
+        assert.strictEqual(
+          controller.replaceRoute('application'),
+          'foo.bar.application',
+          'properly prefixes application route'
+        );
+      }, /Calling replaceRoute on a controller is deprecated/);
+      expectDeprecation(() => {
+        assert.strictEqual(
+          controller.replaceRoute('posts'),
+          'foo.bar.posts',
+          'properly prefixes child routes'
+        );
+      }, /Calling replaceRoute on a controller is deprecated/);
+      expectDeprecation(() => {
+        assert.throws(() => controller.replaceRoute('/posts'), 'throws when trying to use a url');
+      }, /Calling replaceRoute on a controller is deprecated/);
 
       let queryParams = {};
-      assert.strictEqual(
-        controller.replaceRoute(queryParams),
-        queryParams,
-        'passes query param only transitions through'
-      );
+      expectDeprecation(() => {
+        assert.strictEqual(
+          controller.replaceRoute(queryParams),
+          queryParams,
+          'passes query param only transitions through'
+        );
+      }, /Calling replaceRoute on a controller is deprecated/);
     }
   }
 );

packages/@ember/-internals/routing/tests/system/route_test.js

@@ -487,24 +487,32 @@ moduleFor(
       let route = EmberRoute.create({ _router: router });
       setOwner(route, engineInstance);
 
-      assert.strictEqual(
-        route.transitionTo('application'),
-        'foo.bar.application',
-        'properly prefixes application route'
-      );
-      assert.strictEqual(
-        route.transitionTo('posts'),
-        'foo.bar.posts',
-        'properly prefixes child routes'
-      );
-      assert.throws(() => route.transitionTo('/posts'), 'throws when trying to use a url');
+      expectDeprecation(() => {
+        assert.strictEqual(
+          route.transitionTo('application'),
+          'foo.bar.application',
+          'properly prefixes application route'
+        );
+      }, /Calling transitionTo on a route is deprecated/);
+      expectDeprecation(() => {
+        assert.strictEqual(
+          route.transitionTo('posts'),
+          'foo.bar.posts',
+          'properly prefixes child routes'
+        );
+      }, /Calling transitionTo on a route is deprecated/);
+      expectDeprecation(() => {
+        assert.throws(() => route.transitionTo('/posts'), 'throws when trying to use a url');
+      }, /Calling transitionTo on a route is deprecated/);
 
       let queryParams = {};
-      assert.strictEqual(
-        route.transitionTo(queryParams),
-        queryParams,
-        'passes query param only transitions through'
-      );
+      expectDeprecation(() => {
+        assert.strictEqual(
+          route.transitionTo(queryParams),
+          queryParams,
+          'passes query param only transitions through'
+        );
+      }, /Calling transitionTo on a route is deprecated/);
     }
 
     ["@test intermediateTransitionTo considers an engine's mountPoint"](assert) {
@@ -558,24 +566,32 @@ moduleFor(
       let route = EmberRoute.create({ _router: router });
       setOwner(route, engineInstance);
 
-      assert.strictEqual(
-        route.replaceWith('application'),
-        'foo.bar.application',
-        'properly prefixes application route'
-      );
-      assert.strictEqual(
-        route.replaceWith('posts'),
-        'foo.bar.posts',
-        'properly prefixes child routes'
-      );
-      assert.throws(() => route.replaceWith('/posts'), 'throws when trying to use a url');
+      expectDeprecation(() => {
+        assert.strictEqual(
+          route.replaceWith('application'),
+          'foo.bar.application',
+          'properly prefixes application route'
+        );
+      }, /Calling replaceWith on a route is deprecated/);
+      expectDeprecation(() => {
+        assert.strictEqual(
+          route.replaceWith('posts'),
+          'foo.bar.posts',
+          'properly prefixes child routes'
+        );
+      }, /Calling replaceWith on a route is deprecated/);
+      expectDeprecation(() => {
+        assert.throws(() => route.replaceWith('/posts'), 'throws when trying to use a url');
+      }, /Calling replaceWith on a route is deprecated/);
 
       let queryParams = {};
-      assert.strictEqual(
-        route.replaceWith(queryParams),
-        queryParams,
-        'passes query param only transitions through'
-      );
+      expectDeprecation(() => {
+        assert.strictEqual(
+          route.replaceWith(queryParams),
+          queryParams,
+          'passes query param only transitions through'
+        );
+      }, /Calling replaceWith on a route is deprecated/);
     }
   }
 );

packages/@ember/application/tests/visit_test.js

@@ -283,7 +283,9 @@ moduleFor(
         'route:a',
         Route.extend({
           afterModel() {
-            this.replaceWith('b', 'zomg');
+            expectDeprecation(() => {
+              this.replaceWith('b', 'zomg');
+            }, /Calling replaceWith on a route is deprecated/);
           },
         })
       );
@@ -292,7 +294,9 @@ moduleFor(
         'route:b',
         Route.extend({
           afterModel(params) {
-            this.transitionTo('c', params.b);
+            expectDeprecation(() => {
+              this.transitionTo('c', params.b);
+            }, /Calling transitionTo on a route is deprecated/);
           },
         })
       );
@@ -321,7 +325,9 @@ moduleFor(
         'route:a',
         Route.extend({
           afterModel() {
-            this.replaceWith('b', 'zomg');
+            expectDeprecation(() => {
+              this.replaceWith('b', 'zomg');
+            }, /Calling replaceWith on a route is deprecated/);
           },
         })
       );
@@ -330,7 +336,9 @@ moduleFor(
         'route:b',
         Route.extend({
           afterModel(params) {
-            this.transitionTo('c', params.b);
+            expectDeprecation(() => {
+              this.transitionTo('c', params.b);
+            }, /Calling transitionTo on a route is deprecated/);
           },
         })
       );