diff --git a/text/0000-deprecation-ember-string.md b/text/0000-deprecation-ember-string.md index ac3ad51f64..b13dcb0819 100644 --- a/text/0000-deprecation-ember-string.md +++ b/text/0000-deprecation-ember-string.md @@ -10,10 +10,22 @@ This RFC proposes to deprecate the prototype extensions done by `Ember.String`, Much of the public API of Ember was designed and published some time ago, when the client-side landscape looked much different. It was a time without without many utilities and methods that have been introduced to JavaScript since, without the current rich npm ecosystem, and without ES6 modules. On the Ember side, Ember CLI the subsequent addons were still to be introduced. Global mode was the way to go, and extending native prototypes like Ember does for `String`, `Array` and `Function` was a common practice. -With the introduction of [RFC #176](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md), an opportunity to reduce the API that is shipped by default with an Ember application appears. A lot of nice-to-have functionality that was added at that time can now be moved to optional packages and addons, where they can be maintained and evolved without being tied to the core of the framework. +With the introduction of [RFC #176](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md), an opportunity to reduce and reorganize the API that is shipped by default with an Ember application appears. A lot of nice-to-have functionality that was added at that time can now be moved to optional packages and addons, where they can be maintained and evolved without being tied to the core of the framework. In the specific case of `Ember.String`, our goal is that users that need who these utility functions will include `@ember/string` in their dependencies, or rely on common utility packages like [`lodash.camelcase`](https://lodash.com/docs/#camelCase). +To achieve the above goal we will move the `isHTMLSafe`/`htmlSafe` pair into a new package, deprecate `String.prototype` extensions, and deprecate the utility functions under the `Ember.String` namespace. + +Thehe ["Organize by Mental Model"](https://github.com/emberjs/rfcs/blob/master/text/0176-javascript-module-api.md#organize-by-mental-model) section of RFC #176 mentions the concept of chunking. In the current setup, `isHTMLSafe`/`htmlSafe` make sense in the `Ember.String` namespace because they operate on strings, and they are available on the prototype, `"myString".htmlSafe()`. +However, once prototype extensions are removed, it becomes clearer that while this pair operates on strings, they don't transform them in the same way as `capitalize` or `dasherize`, but are instead a templating concern. +For this reason, we are moving them to `@ember/templating`. + +Extending native prototypes, like we do for `String` with `"myString".dasherize()` and the rest of the API, has been falling out of favour more as time goes by. +While the tradeoff might have been positive at the beginning, as it allowed users access to a richer API, prototype extensions blur the line between what is the framework and what is the language in a way that is not benefitial in the current module-driven and package-rich ecosystem. + +Relatedly, deprecating `Ember.String` and requiring `@ember/string` as a dependency allows Ember to provide a leaner default core to all users, as well as iterate faster on the `@ember/string` package if desired. +Doing this will also open a path to extract more packages in the future. + # Transition Path It is important to understand that the transition path will be done in the context of the new modules API defined in RFC #176, which is scheduled to land in 2.16. @@ -23,7 +35,7 @@ As this will likely be first of many packages to be extracted from the Ember sou The order of operations will be as follows: -1. Move `htmlSafe` and `isHTMLSafe` to `@ember/component` +1. Move `htmlSafe` and `isHTMLSafe` to `@ember/templating` * Update https://github.com/ember-cli/ember-rfc176-data 2. Create an `@ember/string` package with the remaining public API 3. Create an `ember-string-prototype-extensions` package that introduces `String` prototype extensions to aid in transitioning @@ -49,6 +61,7 @@ If you are using the `String` prototype extensions, like `'myString'.dasherize() * `String` protoype extensions are deprecated * `Ember.String` functions are deprecated * `loc` is completely deprecated + * `isHTMLSafe` and `htmlSafe` are moved to `@ember/templating` * Transition packages are introduced - Ember 2.x * `@ember/string`, which replaced `Ember.String` * `ember-string-prototype-extensions`, which brings `String` prototype extensions back @@ -69,7 +82,7 @@ Resources owned by the Ember teams, such and Ember and Ember Data code bases, th ## `Ember.String.htmlSafe` and `Ember.String.isHTMLSafe` -The move of `htmlSafe` and `isHTMLSafe` from `Ember.String` to `@ember/component` should be documented as part of the [ember-rfc176-data](https://github.com/ember-cli/ember-rfc176-data) and related codemods efforts, as that project is the source of truth for the mappings between the `Ember` global namespace and `@ember`-scoped modules. +The move of `htmlSafe` and `isHTMLSafe` from `Ember.String` to `@ember/templating` should be documented as part of the [ember-rfc176-data](https://github.com/ember-cli/ember-rfc176-data) and related codemods efforts, as that project is the source of truth for the mappings between the `Ember` global namespace and `@ember`-scoped modules. ## `Ember.String.loc` and `import { loc } from '@ember/string';`, `Ember.String` to `@ember/string`, `String` prototype extensions @@ -106,3 +119,5 @@ Another side-effect of this change is that certain users might be shipping dupli Leave things as they are. # Unresolved questions + +None.