[DEPRECATION canary] Deprecate Ember.String an prototype extension

This PR deprecates the use of String prototype extension and Ember.String namespace. Methods coming from ember-runtime --- A new `StringUtils` object is added, to be used internally by Ember instead of using the same object being exposed as `Ember.String`. This simplifies testing and the changes required in the rest of the code. Also, dropping the deprecated code will be much simpler. Methods coming from ember-glimmer --- Deprecated versions are being added and reexported as the same global the non-deprecated versions were. Besides, the non-deprecated version is being exported under the new global `Ember.Template`.
emberjs · Feb 7, 2018 · 5b80853 · 5b80853
1 parent 89fe612
commit 5b80853
Show file tree

Hide file tree

Showing 29 changed files with 238 additions and 60 deletions.
diff --git a/packages/ember-application/lib/system/resolver.js b/packages/ember-application/lib/system/resolver.js
@@ -6,8 +6,8 @@ import { dictionary } from 'ember-utils';
 import { get } from 'ember-metal';
 import { assert, info } from 'ember-debug';
 import {
-  String as StringUtils,
   Object as EmberObject,
+  StringUtils,
   Namespace
 } from 'ember-runtime';
 import validateType from '../utils/validate-type';

diff --git a/packages/ember-extension-support/lib/container_debug_adapter.js b/packages/ember-extension-support/lib/container_debug_adapter.js
@@ -2,7 +2,7 @@ import Ember from 'ember-metal'; // Ember as namespace
 import {
   A as emberA,
   typeOf,
-  String as StringUtils,
+  StringUtils,
   Namespace,
   Object as EmberObject
 } from 'ember-runtime';

diff --git a/packages/ember-extension-support/lib/data_adapter.js b/packages/ember-extension-support/lib/data_adapter.js
@@ -1,7 +1,7 @@
 import { getOwner } from 'ember-utils';
 import { get, run, objectAt } from 'ember-metal';
 import {
-  String as StringUtils,
+  StringUtils,
   Namespace,
   Object as EmberObject,
   A as emberA,

diff --git a/packages/ember-glimmer/lib/component-managers/curly.ts b/packages/ember-glimmer/lib/component-managers/curly.ts
@@ -32,7 +32,7 @@ import { DEBUG } from 'ember-env-flags';
 import {
   _instrumentStart, get,
 } from 'ember-metal';
-import { String as StringUtils } from 'ember-runtime';
+import { StringUtils } from 'ember-runtime';
 import {
   assign,
   getOwner,

diff --git a/packages/ember-glimmer/lib/helpers/-class.ts b/packages/ember-glimmer/lib/helpers/-class.ts
@@ -1,5 +1,5 @@
 import { Arguments, VM } from '@glimmer/runtime';
-import { String as StringUtils } from 'ember-runtime';
+import { StringUtils } from 'ember-runtime';
 import { InternalHelperReference } from '../utils/references';
 
 function classHelper({ positional }: any) {

diff --git a/packages/ember-glimmer/lib/helpers/-normalize-class.ts b/packages/ember-glimmer/lib/helpers/-normalize-class.ts
@@ -1,5 +1,5 @@
 import { Arguments, VM } from '@glimmer/runtime';
-import { String as StringUtils } from 'ember-runtime';
+import { StringUtils } from 'ember-runtime';
 import { InternalHelperReference } from '../utils/references';
 
 function normalizeClass({ positional }: any) {

diff --git a/packages/ember-glimmer/lib/helpers/loc.ts b/packages/ember-glimmer/lib/helpers/loc.ts
@@ -3,7 +3,7 @@
 @module ember
 */
 
-import { String as StringUtils } from 'ember-runtime';
+import { StringUtils } from 'ember-runtime';
 import { helper } from '../helper';
 
 /**

diff --git a/packages/ember-glimmer/lib/index.ts b/packages/ember-glimmer/lib/index.ts
@@ -273,7 +273,9 @@ export {
   SafeString,
   escapeExpression,
   htmlSafe,
-  isHTMLSafe
+  deprecatedHTMLSafe,
+  isHTMLSafe,
+  deprecatedIsHTMLSafe,
 } from './utils/string';
 export {
   Renderer,

diff --git a/packages/ember-glimmer/lib/utils/bindings.ts b/packages/ember-glimmer/lib/utils/bindings.ts
@@ -17,7 +17,7 @@ import {
 import { Core, Ops } from '@glimmer/wire-format';
 import { assert } from 'ember-debug';
 import { get } from 'ember-metal';
-import { String as StringUtils } from 'ember-runtime';
+import { StringUtils } from 'ember-runtime';
 import { ROOT_REF } from '../component';
 import { Component } from './curly-component-state-bucket';
 import { referenceFromParts } from './references';

diff --git a/packages/ember-glimmer/lib/utils/string.ts b/packages/ember-glimmer/lib/utils/string.ts
@@ -2,6 +2,8 @@
 @module @ember/string
 */
 
+import { deprecate } from 'ember-debug';
+
 export class SafeString {
   public string: string;
 
@@ -72,6 +74,7 @@ export function escapeExpression(string: any): string {
   @static
   @return {Handlebars.SafeString} A string that will not be HTML escaped by Handlebars.
   @public
+  @deprecated
 */
 export function htmlSafe(str: string) {
   if (str === null || str === undefined) {
@@ -82,6 +85,19 @@ export function htmlSafe(str: string) {
   return new SafeString(str);
 }
 
+export function deprecatedHTMLSafe(str : string) {
+  deprecate(
+    'Ember.String namespace is deprecated. Please, import `htmlSafe` from `ember/template`.',
+    false,
+    {
+      id: 'ember-glimmer.ember-string-html-safe',
+      until: '3.5.0',
+      url: ''
+    }
+  );
+  return htmlSafe(str);
+}
+
 /**
   Detects if a string was decorated using `htmlSafe`.
 
@@ -100,7 +116,21 @@ export function htmlSafe(str: string) {
   @static
   @return {Boolean} `true` if the string was decorated with `htmlSafe`, `false` otherwise.
   @public
+  @deprecated
 */
 export function isHTMLSafe(str: any | null | undefined): str is SafeString {
   return str !== null && typeof str === 'object' && typeof str.toHTML === 'function';
 }
+
+export function deprecatedIsHTMLSafe(str: string | SafeString): str is SafeString {
+  deprecate(
+    'Ember.String namespace is deprecated. Please, import `isHTMLSafe` from `ember/template`.',
+    false,
+    {
+      id: 'ember-glimmer.ember-string-is-html-safe',
+      until: '3.5.0',
+      url: ''
+    }
+  );
+  return isHTMLSafe(str);
+}
diff --git a/packages/ember-glimmer/tests/utils/helpers.js b/packages/ember-glimmer/tests/utils/helpers.js
@@ -12,7 +12,9 @@ export {
   InteractiveRender,
   InertRenderer,
   htmlSafe,
+  deprecatedHTMLSafe,
   SafeString,
   DOMChanges,
-  isHTMLSafe
+  isHTMLSafe,
+  deprecatedIsHTMLSafe
 } from 'ember-glimmer';
diff --git a/packages/ember-glimmer/tests/utils/string-test.js b/packages/ember-glimmer/tests/utils/string-test.js
@@ -1,8 +1,19 @@
-import { SafeString, htmlSafe, isHTMLSafe } from './helpers';
+import {
+  SafeString,
+  htmlSafe,
+  deprecatedHTMLSafe,
+  isHTMLSafe,
+  deprecatedIsHTMLSafe
+} from './helpers';
 import { TestCase } from './abstract-test-case';
 import { moduleFor } from './test-case';
 
 moduleFor('SafeString', class extends TestCase {
+  ['@test deprecated version is deprecated']() {
+    expectDeprecation(/ember\/template/);
+    deprecatedHTMLSafe("Hello");
+  }
+
   ['@test htmlSafe should return an instance of SafeString']() {
     let safeString = htmlSafe('you need to be more <b>bold</b>');
 
@@ -25,6 +36,11 @@ moduleFor('SafeString', class extends TestCase {
 });
 
 moduleFor('SafeString isHTMLSafe', class extends TestCase {
+  ['@test deprecated version is deprecated']() {
+    expectDeprecation(/ember\/template/);
+    deprecatedIsHTMLSafe("Hello");
+  }
+
   ['@test isHTMLSafe should detect SafeString']() {
     let safeString = htmlSafe('<em>Emphasize</em> the important things.');
 

diff --git a/packages/ember-routing/lib/system/route.js b/packages/ember-routing/lib/system/route.js
@@ -13,7 +13,7 @@ import { DEBUG } from 'ember-env-flags';
 import {
   typeOf,
   copy,
-  String as StringUtils,
+  StringUtils,
   Object as EmberObject,
   A as emberA,
   Evented,

diff --git a/packages/ember-runtime/lib/ext/string.js b/packages/ember-runtime/lib/ext/string.js
@@ -3,6 +3,7 @@
 */
 
 import { ENV } from 'ember-environment';
+import { deprecate } from 'ember-debug';
 import {
   w,
   loc,
@@ -16,7 +17,24 @@ import {
 
 const StringPrototype = String.prototype;
 
+function deprecateEmberStringPrototypeExtension(name, fn, opts = {}) {
+  return function (...args) {
+    deprecate(
+      opts.message || `String prototype extensions are deprecated. Please, use ${name} from '@ember/string' instead.`,
+      false,
+      opts.options || {
+        id: 'ember-string.prototype_extensions',
+        until: '3.5.0',
+        url: 'https://emberjs.com/deprecations/v2.x/#toc_ember-string-prototype-extensions'
+      }
+    );
+
+    return fn(this, ...args);
+  };
+}
+
 if (ENV.EXTEND_PROTOTYPES.String) {
+
   /**
     See [String.w](/api/ember/release/classes/String/methods/w?anchor=w).
 
@@ -29,9 +47,7 @@ if (ENV.EXTEND_PROTOTYPES.String) {
     configurable: true,
     enumerable: false,
     writeable: true,
-    value: function() {
-      return w(this);
-    }
+    value: deprecateEmberStringPrototypeExtension('w', w)
   });
 
   /**
@@ -46,9 +62,9 @@ if (ENV.EXTEND_PROTOTYPES.String) {
     configurable: true,
     enumerable: false,
     writeable: true,
-    value: function(...args) {
-      return loc(this, args);
-    }
+    value: deprecateEmberStringPrototypeExtension('loc', loc, {
+      message: '`loc` is deprecated. Please, use an i18n addon instead. See https://emberobserver.com/categories/internationalization for a list of them.',
+    })
   });
 
   /**
@@ -63,9 +79,7 @@ if (ENV.EXTEND_PROTOTYPES.String) {
     configurable: true,
     enumerable: false,
     writeable: true,
-    value: function() {
-      return camelize(this);
-    }
+    value: deprecateEmberStringPrototypeExtension('camelize', camelize)
   });
 
   /**
@@ -80,9 +94,7 @@ if (ENV.EXTEND_PROTOTYPES.String) {
     configurable: true,
     enumerable: false,
     writeable: true,
-    value: function() {
-      return decamelize(this);
-    }
+    value: deprecateEmberStringPrototypeExtension('decamelize', decamelize)
   });
 
   /**
@@ -97,9 +109,7 @@ if (ENV.EXTEND_PROTOTYPES.String) {
     configurable: true,
     enumerable: false,
     writeable: true,
-    value: function() {
-      return dasherize(this);
-    }
+    value: deprecateEmberStringPrototypeExtension('dasherize', dasherize)
   });
 
   /**
@@ -114,9 +124,7 @@ if (ENV.EXTEND_PROTOTYPES.String) {
     configurable: true,
     enumerable: false,
     writeable: true,
-    value: function() {
-      return underscore(this);
-    }
+    value: deprecateEmberStringPrototypeExtension('underscore', underscore)
   });
 
   /**
@@ -131,9 +139,7 @@ if (ENV.EXTEND_PROTOTYPES.String) {
     configurable: true,
     enumerable: false,
     writeable: true,
-    value: function() {
-      return classify(this);
-    }
+    value: deprecateEmberStringPrototypeExtension('classify', classify)
   });
 
   /**
@@ -148,8 +154,6 @@ if (ENV.EXTEND_PROTOTYPES.String) {
     configurable: true,
     enumerable: false,
     writeable: true,
-    value: function() {
-      return capitalize(this);
-    }
+    value: deprecateEmberStringPrototypeExtension('capitalize', capitalize)
   });
 }
diff --git a/packages/ember-runtime/lib/index.d.ts b/packages/ember-runtime/lib/index.d.ts
@@ -18,6 +18,20 @@ export const String: {
   loc(s: string, ...args: string[]): string;
 };
 
+export const StringUtils: {
+  fmt(s: string, ...args: any[]): string,
+  loc(s: string, ...args: any[]): string,
+  w(s: string): string[],
+  decamelize(s: string): string,
+  dasherize(s: string): string,
+  camelize(s: string): string,
+  classify(s: string): string,
+  underscore(s: string): string,
+  capitalize(s: string): string
+}
+
+export function objectAt(arr: any, i: number): any;
+
 export function isEmberArray(arr: any): boolean;
 
 export function _contentFor(proxy: any): any;
diff --git a/packages/ember-runtime/lib/index.js b/packages/ember-runtime/lib/index.js
@@ -1,5 +1,5 @@
 export { default as Object, FrameworkObject } from './system/object';
-export { default as String } from './system/string';
+export { default as String, StringUtils } from './system/string';
 export {
   default as RegistryProxyMixin,
 } from './mixins/registry_proxy';