[RFC#236] Deprecate String prototype extensions

packages/@ember/string/index.ts

@@ -6,6 +6,7 @@ export { getStrings as _getStrings, setStrings as _setStrings } from './lib/stri
 
 import { ENV } from '@ember/-internals/environment';
 import { Cache } from '@ember/-internals/utils';
+import { deprecate } from '@ember/debug';
 import { getString } from './lib/string_registry';
 
 const STRING_DASHERIZE_REGEXP = /[ _]/g;
@@ -279,6 +280,26 @@ export function capitalize(str: string): string {
 }
 
 if (ENV.EXTEND_PROTOTYPES.String) {
+  let deprecateEmberStringPrototypeExtension = function (
+    name: string,
+    fn: (utility: string, ...options: any) => string | string[],
+    message = `String prototype extensions are deprecated. Please import ${name} from '@ember/string' instead.`
+  ) {
+    return function (this: string) {
+      deprecate(message, false, {
+        id: 'ember-string.prototype-extensions',
+        for: 'ember-source',
+        since: {
+          available: '3.24',
+        },
+        until: '4.0.0',
+        url: 'https://deprecations.emberjs.com/v3.x/#toc_ember-string-prototype_extensions',
+      });
+
+      return fn(this, ...arguments);
+    };
+  };
+
   Object.defineProperties(String.prototype, {
     /**
       See [String.w](/ember/release/classes/String/methods/w?anchor=w).
@@ -287,14 +308,13 @@ if (ENV.EXTEND_PROTOTYPES.String) {
       @for @ember/string
       @static
       @private
+      @deprecated
     */
     w: {
       configurable: true,
       enumerable: false,
       writeable: true,
-      value() {
-        return w(this);
-      },
+      value: deprecateEmberStringPrototypeExtension('w', w),
     },
 
     /**
@@ -321,14 +341,13 @@ if (ENV.EXTEND_PROTOTYPES.String) {
       @for @ember/string
       @static
       @private
+      @deprecated
     */
     camelize: {
       configurable: true,
       enumerable: false,
       writeable: true,
-      value() {
-        return camelize(this);
-      },
+      value: deprecateEmberStringPrototypeExtension('camelize', camelize),
     },
 
     /**
@@ -338,14 +357,13 @@ if (ENV.EXTEND_PROTOTYPES.String) {
       @for @ember/string
       @static
       @private
+      @deprecated
     */
     decamelize: {
       configurable: true,
       enumerable: false,
       writeable: true,
-      value() {
-        return decamelize(this);
-      },
+      value: deprecateEmberStringPrototypeExtension('decamelize', decamelize),
     },
 
     /**
@@ -355,14 +373,13 @@ if (ENV.EXTEND_PROTOTYPES.String) {
       @for @ember/string
       @static
       @private
+      @deprecated
     */
     dasherize: {
       configurable: true,
       enumerable: false,
       writeable: true,
-      value() {
-        return dasherize(this);
-      },
+      value: deprecateEmberStringPrototypeExtension('dasherize', dasherize),
     },
 
     /**
@@ -372,14 +389,13 @@ if (ENV.EXTEND_PROTOTYPES.String) {
       @for @ember/string
       @static
       @private
+      @deprecated
     */
     underscore: {
       configurable: true,
       enumerable: false,
       writeable: true,
-      value() {
-        return underscore(this);
-      },
+      value: deprecateEmberStringPrototypeExtension('underscore', underscore),
     },
 
     /**
@@ -389,14 +405,13 @@ if (ENV.EXTEND_PROTOTYPES.String) {
       @for @ember/string
       @static
       @private
+      @deprecated
     */
     classify: {
       configurable: true,
       enumerable: false,
       writeable: true,
-      value() {
-        return classify(this);
-      },
+      value: deprecateEmberStringPrototypeExtension('classify', classify),
     },
 
     /**
@@ -406,14 +421,13 @@ if (ENV.EXTEND_PROTOTYPES.String) {
       @for @ember/string
       @static
       @private
+      @deprecated
     */
     capitalize: {
       configurable: true,
       enumerable: false,
       writeable: true,
-      value() {
-        return capitalize(this);
-      },
+      value: deprecateEmberStringPrototypeExtension('capitalize', capitalize),
     },
   });
 }

packages/@ember/string/tests/camelize_test.js

@@ -5,7 +5,9 @@ import { moduleFor, AbstractTestCase } from 'internal-test-helpers';
 function test(assert, given, expected, description) {
   assert.deepEqual(camelize(given), expected, description);
   if (ENV.EXTEND_PROTOTYPES.String) {
-    assert.deepEqual(given.camelize(), expected, description);
+    expectDeprecation(() => {
+      assert.deepEqual(given.camelize(), expected, description);
+    }, /String prototype extensions are deprecated/);
   }
 }
 

packages/@ember/string/tests/capitalize_test.js

@@ -5,7 +5,9 @@ import { moduleFor, AbstractTestCase } from 'internal-test-helpers';
 function test(assert, given, expected, description) {
   assert.deepEqual(capitalize(given), expected, description);
   if (ENV.EXTEND_PROTOTYPES.String) {
-    assert.deepEqual(given.capitalize(), expected, description);
+    expectDeprecation(() => {
+      assert.deepEqual(given.capitalize(), expected, description);
+    }, /String prototype extensions are deprecated/);
   }
 }
 

packages/@ember/string/tests/classify_test.js

@@ -5,7 +5,9 @@ import { moduleFor, AbstractTestCase } from 'internal-test-helpers';
 function test(assert, given, expected, description) {
   assert.deepEqual(classify(given), expected, description);
   if (ENV.EXTEND_PROTOTYPES.String) {
-    assert.deepEqual(given.classify(), expected, description);
+    expectDeprecation(() => {
+      assert.deepEqual(given.classify(), expected, description);
+    }, /String prototype extensions are deprecated/);
   }
 }
 

packages/@ember/string/tests/dasherize_test.js

@@ -5,7 +5,9 @@ import { moduleFor, AbstractTestCase } from 'internal-test-helpers';
 function test(assert, given, expected, description) {
   assert.deepEqual(dasherize(given), expected, description);
   if (ENV.EXTEND_PROTOTYPES.String) {
-    assert.deepEqual(given.dasherize(), expected, description);
+    expectDeprecation(() => {
+      assert.deepEqual(given.dasherize(), expected, description);
+    }, /String prototype extensions are deprecated/);
   }
 }
 

packages/@ember/string/tests/decamelize_test.js

@@ -5,7 +5,9 @@ import { moduleFor, AbstractTestCase } from 'internal-test-helpers';
 function test(assert, given, expected, description) {
   assert.deepEqual(decamelize(given), expected, description);
   if (ENV.EXTEND_PROTOTYPES.String) {
-    assert.deepEqual(given.decamelize(), expected, description);
+    expectDeprecation(() => {
+      assert.deepEqual(given.decamelize(), expected, description);
+    }, /String prototype extensions are deprecated/);
   }
 }
 

packages/@ember/string/tests/underscore_test.js

@@ -5,7 +5,9 @@ import { moduleFor, AbstractTestCase } from 'internal-test-helpers';
 function test(assert, given, expected, description) {
   assert.deepEqual(underscore(given), expected, description);
   if (ENV.EXTEND_PROTOTYPES.String) {
-    assert.deepEqual(given.underscore(), expected, description);
+    expectDeprecation(() => {
+      assert.deepEqual(given.underscore(), expected, description);
+    }, /String prototype extensions are deprecated/);
   }
 }
 

packages/@ember/string/tests/w_test.js

@@ -5,7 +5,9 @@ import { moduleFor, AbstractTestCase } from 'internal-test-helpers';
 function test(assert, given, expected, description) {
   assert.deepEqual(w(given), expected, description);
   if (ENV.EXTEND_PROTOTYPES.String) {
-    assert.deepEqual(given.w(), expected, description);
+    expectDeprecation(() => {
+      assert.deepEqual(given.w(), expected, description);
+    }, /String prototype extensions are deprecated/);
   }
 }