From 342c03f0c6cfad158c74c9e3db6772d74e5fb4c2 Mon Sep 17 00:00:00 2001 From: snewcomer Date: Tue, 22 May 2018 21:37:28 -0700 Subject: [PATCH 01/10] deprecate isEmpty,isNone,isPresent,isBlank --- text/0000-deprecate-some-utils.md | 52 +++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 text/0000-deprecate-some-utils.md diff --git a/text/0000-deprecate-some-utils.md b/text/0000-deprecate-some-utils.md new file mode 100644 index 0000000000..778f42a251 --- /dev/null +++ b/text/0000-deprecate-some-utils.md @@ -0,0 +1,52 @@ +- Start Date: 2018-05-22 +- RFC PR: (leave this empty) +- Ember Issue: (leave this empty) + +# Deprecate Ember.{isEmpty,isBlank,isNone,isPresent} + +## Summary + +This RFC suggests the deprecation of the following [methods](https://www.emberjs.com/api/ember/3.1/modules/@ember%2Futils): +- `Ember.isEmpty` +- `Ember.isBlank` +- `Ember.isNone` +- `Ember.isPresent` + +Once deprecated, these methods will move to an external addon to allow users to still take advantage of the succinctness of these utility methods. + +## Motivation + +To further Ember's goal of a svelte core and moving functionality to separate packages, this RFC attempts to deprecate a few utility methods. A part from the aforementioned goal, in many cases, these utility methods does not add a whole lot of value over writing plain old JavaScript. Moreover, these methods generally have a negative cognitive impact on the code in question. In order to reduce code liability and advocate for users to write plain JavaScript, these methods could be removed from Ember core and extracted to an addon. + +A simple example of this cognitive load would be checking for the presence of a variable of type String that can only have four states - `undefined`, `null`, `''` or `'MYSTRING'`. One might check if the variable is truthy with `!!myVariable`. However, a utility method such as `isPresent(myVariable)` can increase the cognitive load of the truthy check in question as it checks for many different types. + +In addition, when checking whether a primitive value is truthy, a user can choose from `isPresent`, `isBlank`, `isNone`, or `isEmpty`. This can can lead to some confusion for users as there are many options to do the same thing. + +Lastly, `Ember.isEmpty` documented [here](https://www.emberjs.com/api/ember/release/functions/@ember%2Futils/isEmpty) will return false for an empty object. Defining what an empty object is can be a bit tricky and `isEmpty` provided specific semantics that may not fit a users definition. This idea of specific semantics that do not fit a users definition also applies to the other utility methods as well. + +## Detailed design + +`Ember.isEmpty`, `Ember.isBlank`, `Ember.isNone`, `Ember.isPresent` will be deprecated at first with an addon that extracts these methods for users that still find value in these utility methods. Any instantiation of one of these functions will log a deprecation warning, notifying the user that this method is deprecated and provide a link to the supported addon. + +Addons that previously relied on these utility methods would also be expected to install this package. + +## How we teach this + +Since using Ember in IE9, IE10, and PhantomJS is deprecated as of the 3.0 release and ES5/ES6 brings improved language semantics, we have as a community, a guarantee of results across browsers when using plain old JavaScript. Some of the benefits from these utility methods eminated from a need to guarantee results with ES3 browsers. With that not a concern anymore, we can nudge users to use JavaScript where needed and install an addon if need be. + +This would require an update to the guides to indicate that the use of any of these utility methods are now available in an addon. Moreover, in the README of the addon, we can provide specific examples of when using JavaScript is easier than reaching for one of these utility methods. Lastly, we can also point them to a utility library like [lodash](https://lodash.com/docs). + +For many users with existing codebases, it should be as simple as installing the extracted addon. However, users not utilizing these methods will not have these methods bundled by default. + +## Drawbacks + +This change may impact quite a few codebases. Moreover, users who heavily rely on these utility methods will have to install another addon. Some users may desire this functionality out of the box. + +Given the example above, some users see a lot of value for the safety checks `isPresent(myVariable)` provides. The type of variable could be of type String or of type Object and wiring this up to check manually is laborious. + +## Alternatives + +Another option would be to improve existing utility cases such as `isEmpty({}) === true`. Moreover, we could also consider scoping existing utility methods to specific types. For example, `isEmpty` would be specific to checking objects, collections, maps or sets to reduce confusion of when these utility methods should be used. + +## Unresolved questions + From 2c10c3ad61512ed27dfd46dfe0b45b1a0ea283f1 Mon Sep 17 00:00:00 2001 From: snewcomer Date: Fri, 2 Aug 2019 21:00:44 -0700 Subject: [PATCH 02/10] Update rfc based on feedback --- text/0000-deprecate-some-utils.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/text/0000-deprecate-some-utils.md b/text/0000-deprecate-some-utils.md index 778f42a251..def2a444d1 100644 --- a/text/0000-deprecate-some-utils.md +++ b/text/0000-deprecate-some-utils.md @@ -6,17 +6,22 @@ ## Summary -This RFC suggests the deprecation of the following [methods](https://www.emberjs.com/api/ember/3.1/modules/@ember%2Futils): +This RFC suggests the deprecation of the following [methods](http://api.emberjs.com/ember/release/modules/@ember%2Futils): - `Ember.isEmpty` - `Ember.isBlank` - `Ember.isNone` - `Ember.isPresent` +As well as [computed properties](http://api.emberjs.com/ember/release/modules/@ember%2Fobject) that rely on these methods: +- `notEmpty` +- `empty` +- `none` + Once deprecated, these methods will move to an external addon to allow users to still take advantage of the succinctness of these utility methods. ## Motivation -To further Ember's goal of a svelte core and moving functionality to separate packages, this RFC attempts to deprecate a few utility methods. A part from the aforementioned goal, in many cases, these utility methods does not add a whole lot of value over writing plain old JavaScript. Moreover, these methods generally have a negative cognitive impact on the code in question. In order to reduce code liability and advocate for users to write plain JavaScript, these methods could be removed from Ember core and extracted to an addon. +To further Ember's goal of a svelte core and moving functionality to separate packages, this RFC attempts to deprecate a few utility methods and extract them to their own addon. A part from the aforementioned goal, in many cases, these utility methods do not add a whole lot of value over writing plain old JavaScript. Moreover, these methods generally have a negative cognitive impact on the code in question. In order to reduce code liability and advocate for users to write plain JavaScript, these methods could be removed from Ember core and extracted to an addon. A simple example of this cognitive load would be checking for the presence of a variable of type String that can only have four states - `undefined`, `null`, `''` or `'MYSTRING'`. One might check if the variable is truthy with `!!myVariable`. However, a utility method such as `isPresent(myVariable)` can increase the cognitive load of the truthy check in question as it checks for many different types. @@ -26,13 +31,13 @@ Lastly, `Ember.isEmpty` documented [here](https://www.emberjs.com/api/ember/rele ## Detailed design -`Ember.isEmpty`, `Ember.isBlank`, `Ember.isNone`, `Ember.isPresent` will be deprecated at first with an addon that extracts these methods for users that still find value in these utility methods. Any instantiation of one of these functions will log a deprecation warning, notifying the user that this method is deprecated and provide a link to the supported addon. +`Ember.isEmpty`, `Ember.isBlank`, `Ember.isNone`, `Ember.isPresent`, `notEmpty`, `empty`, and `none` will be deprecated at first with an addon that extracts these methods for users that still find value in these utility methods. Any instantiation of one of these functions will log a deprecation warning, notifying the user that this method is deprecated and provide a link to the supported addon. -Addons that previously relied on these utility methods would also be expected to install this package. +Addons that previously relied on these utility methods would also be expected to install this package. Moreover, to ease adoption of the external addon, a codemod will become available for the community. ## How we teach this -Since using Ember in IE9, IE10, and PhantomJS is deprecated as of the 3.0 release and ES5/ES6 brings improved language semantics, we have as a community, a guarantee of results across browsers when using plain old JavaScript. Some of the benefits from these utility methods eminated from a need to guarantee results with ES3 browsers. With that not a concern anymore, we can nudge users to use JavaScript where needed and install an addon if need be. +Since using Ember in IE9, IE10, and PhantomJS is deprecated as of the 3.0 release and ES5/ES6 brings improved language semantics, we have, as a community, a guarantee of results across browsers when using plain old JavaScript. Some of the benefits from these utility methods eminated from a need to guarantee results with ES3 browsers. Today, we can nudge users to use JavaScript where needed and install an addon in cases where you feel it is necessary. This would require an update to the guides to indicate that the use of any of these utility methods are now available in an addon. Moreover, in the README of the addon, we can provide specific examples of when using JavaScript is easier than reaching for one of these utility methods. Lastly, we can also point them to a utility library like [lodash](https://lodash.com/docs). From 1f06120133b0ca4aa0b739b4dd464c5d76495bef Mon Sep 17 00:00:00 2001 From: snewcomer Date: Sat, 10 Aug 2019 15:23:16 -0700 Subject: [PATCH 03/10] update title --- text/0000-deprecate-some-utils.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-deprecate-some-utils.md b/text/0000-deprecate-some-utils.md index def2a444d1..9117fa390e 100644 --- a/text/0000-deprecate-some-utils.md +++ b/text/0000-deprecate-some-utils.md @@ -2,7 +2,7 @@ - RFC PR: (leave this empty) - Ember Issue: (leave this empty) -# Deprecate Ember.{isEmpty,isBlank,isNone,isPresent} +# Deprecate Existence Utils & Computed Properties ## Summary From 94d04e51b965a1b3a93fc5df74e74ca97cf77610 Mon Sep 17 00:00:00 2001 From: Scott Newcomer Date: Fri, 9 Oct 2020 12:12:27 -0700 Subject: [PATCH 04/10] Address examples in How to teach section --- text/0000-deprecate-some-utils.md | 44 ++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 6 deletions(-) diff --git a/text/0000-deprecate-some-utils.md b/text/0000-deprecate-some-utils.md index 9117fa390e..4c5ded1bfa 100644 --- a/text/0000-deprecate-some-utils.md +++ b/text/0000-deprecate-some-utils.md @@ -6,7 +6,7 @@ ## Summary -This RFC suggests the deprecation of the following [methods](http://api.emberjs.com/ember/release/modules/@ember%2Futils): +This RFC proposes the deprecation of the following [methods](http://api.emberjs.com/ember/release/modules/@ember%2Futils): - `Ember.isEmpty` - `Ember.isBlank` - `Ember.isNone` @@ -17,7 +17,7 @@ As well as [computed properties](http://api.emberjs.com/ember/release/modules/@e - `empty` - `none` -Once deprecated, these methods will move to an external addon to allow users to still take advantage of the succinctness of these utility methods. +Once deprecated, these methods will move to an external addon to allow users to still take advantage of the succinctness these utility methods provide. ## Motivation @@ -27,19 +27,51 @@ A simple example of this cognitive load would be checking for the presence of a In addition, when checking whether a primitive value is truthy, a user can choose from `isPresent`, `isBlank`, `isNone`, or `isEmpty`. This can can lead to some confusion for users as there are many options to do the same thing. -Lastly, `Ember.isEmpty` documented [here](https://www.emberjs.com/api/ember/release/functions/@ember%2Futils/isEmpty) will return false for an empty object. Defining what an empty object is can be a bit tricky and `isEmpty` provided specific semantics that may not fit a users definition. This idea of specific semantics that do not fit a users definition also applies to the other utility methods as well. +Lastly, `Ember.isEmpty` documented [here](https://www.emberjs.com/api/ember/release/functions/@ember%2Futils/isEmpty) will return false for an empty object. Defining what an empty object is can be a bit tricky and `isEmpty` provided specific semantics that may not fit a users definition. This problem of specific semantics not fitting a users definition also applies to the other utility methods as well. ## Detailed design -`Ember.isEmpty`, `Ember.isBlank`, `Ember.isNone`, `Ember.isPresent`, `notEmpty`, `empty`, and `none` will be deprecated at first with an addon that extracts these methods for users that still find value in these utility methods. Any instantiation of one of these functions will log a deprecation warning, notifying the user that this method is deprecated and provide a link to the supported addon. +`Ember.isEmpty`, `Ember.isBlank`, `Ember.isNone`, `Ember.isPresent`, `notEmpty`, `empty`, and `none` will be deprecated at first with an addon that extracts these methods for users that still find value in these utility methods. Any instantiation of one of these functions imported from `@ember/utils` will log a deprecation warning, notifying the user that this method is deprecated and provide a link to the supported addon. Addons that previously relied on these utility methods would also be expected to install this package. Moreover, to ease adoption of the external addon, a codemod will become available for the community. ## How we teach this -Since using Ember in IE9, IE10, and PhantomJS is deprecated as of the 3.0 release and ES5/ES6 brings improved language semantics, we have, as a community, a guarantee of results across browsers when using plain old JavaScript. Some of the benefits from these utility methods eminated from a need to guarantee results with ES3 browsers. Today, we can nudge users to use JavaScript where needed and install an addon in cases where you feel it is necessary. +ES5/ES6 brings improved language semantics. Moreover, using Ember in IE9, IE10, and PhantomJS is not supported as of Ember 3.0. As a result, we as a community can guarantee results across browsers when using just JavaScript. Some of the benefits from these utility methods eminated from a need to guarantee results with ES3 browsers. Today, we can nudge users to use JavaScript where needed and install an addon in cases where they feel it is necessary. -This would require an update to the guides to indicate that the use of any of these utility methods are now available in an addon. Moreover, in the README of the addon, we can provide specific examples of when using JavaScript is easier than reaching for one of these utility methods. Lastly, we can also point them to a utility library like [lodash](https://lodash.com/docs). +This would require an update to the guides to indicate that the use of any of these utility methods are now available in an addon. Moreover, in the README of the addon, we can provide specific examples of when using JavaScript is easier than reaching for one of these utility methods. + +```js +import { isEmpty } from '@ember/utils'; + +function isTomster(attributes) { + if (isEmpty(attributes)) { + return false; + } +} +``` + +Depending on the source data, this can be migrated to something as simple as the following. Let us assume the shape of attributes is an object: + +```js +function isTomster(attributes?: Record): boolean { + if (!attributes || Object.keys(attributes).length === 0) { + return false; + } +} +``` + +If it is an array: + +```js +function isTomster(attributes?: Array): boolean { + if (!attributes || attributes.length === 0) { + return false; + } +} +``` + +Lastly, the guides can also point them to a utility library like [lodash](https://lodash.com/docs). For many users with existing codebases, it should be as simple as installing the extracted addon. However, users not utilizing these methods will not have these methods bundled by default. From ca95a46d6b613d4f532af5eee6c3388b9714efab Mon Sep 17 00:00:00 2001 From: Scott Newcomer Date: Sun, 11 Oct 2020 12:39:27 -0700 Subject: [PATCH 05/10] Improve examples part --- text/0000-deprecate-some-utils.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/text/0000-deprecate-some-utils.md b/text/0000-deprecate-some-utils.md index 4c5ded1bfa..dbf809b5a5 100644 --- a/text/0000-deprecate-some-utils.md +++ b/text/0000-deprecate-some-utils.md @@ -42,6 +42,7 @@ ES5/ES6 brings improved language semantics. Moreover, using Ember in IE9, IE10, This would require an update to the guides to indicate that the use of any of these utility methods are now available in an addon. Moreover, in the README of the addon, we can provide specific examples of when using JavaScript is easier than reaching for one of these utility methods. ```js +// Current state import { isEmpty } from '@ember/utils'; function isTomster(attributes) { @@ -51,7 +52,20 @@ function isTomster(attributes) { } ``` -Depending on the source data, this can be migrated to something as simple as the following. Let us assume the shape of attributes is an object: +If you prefer to install the addon directly, we will provide a codemod to update the import path. + +```js +// With an addon +import { isEmpty } from 'addon-name'; + +function isTomster(attributes: any): boolean { + if (isEmpty(attributes)) { + return false; + } +} +``` + +However, depending on the source data, this logic can be migrated to the following. Let us assume the shape of attributes is an object: ```js function isTomster(attributes?: Record): boolean { @@ -71,9 +85,9 @@ function isTomster(attributes?: Array): boolean { } ``` -Lastly, the guides can also point them to a utility library like [lodash](https://lodash.com/docs). +Lastly, the guides can also point users to a utility library like [lodash](https://lodash.com/docs). -For many users with existing codebases, it should be as simple as installing the extracted addon. However, users not utilizing these methods will not have these methods bundled by default. +For many existing codebases, it should be as simple as installing the extracted addon and running the codemod. However, users not utilizing these methods will not have these methods bundled by default. ## Drawbacks From 6e3cac680b3c25314dbc6353de0d59084d622256 Mon Sep 17 00:00:00 2001 From: Scott Newcomer Date: Sun, 22 Nov 2020 21:06:43 -0800 Subject: [PATCH 06/10] Update to address deprecation guide need --- ...-utils.md => 0334-deprecate-some-utils.md} | 202 +++++++++++++++++- 1 file changed, 196 insertions(+), 6 deletions(-) rename text/{0000-deprecate-some-utils.md => 0334-deprecate-some-utils.md} (52%) diff --git a/text/0000-deprecate-some-utils.md b/text/0334-deprecate-some-utils.md similarity index 52% rename from text/0000-deprecate-some-utils.md rename to text/0334-deprecate-some-utils.md index dbf809b5a5..353b2bfc1b 100644 --- a/text/0000-deprecate-some-utils.md +++ b/text/0334-deprecate-some-utils.md @@ -1,16 +1,20 @@ - Start Date: 2018-05-22 -- RFC PR: (leave this empty) -- Ember Issue: (leave this empty) +- RFC PR: https://github.com/emberjs/rfcs/pull/334 +- Ember Issue: https://github.com/emberjs/rfcs/issues/333 # Deprecate Existence Utils & Computed Properties ## Summary -This RFC proposes the deprecation of the following [methods](http://api.emberjs.com/ember/release/modules/@ember%2Futils): -- `Ember.isEmpty` +This RFC proposes the deprecation of the following [methods](https://api.emberjs.com/ember/release/modules/@ember%2Futils): +- `Ember.compare` - `Ember.isBlank` +- `Ember.isEmpty` +- `Ember.isEqual` - `Ember.isNone` - `Ember.isPresent` +- `Ember.tryInvoke` +- `Ember.typeOf` As well as [computed properties](http://api.emberjs.com/ember/release/modules/@ember%2Fobject) that rely on these methods: - `notEmpty` @@ -31,7 +35,7 @@ Lastly, `Ember.isEmpty` documented [here](https://www.emberjs.com/api/ember/rele ## Detailed design -`Ember.isEmpty`, `Ember.isBlank`, `Ember.isNone`, `Ember.isPresent`, `notEmpty`, `empty`, and `none` will be deprecated at first with an addon that extracts these methods for users that still find value in these utility methods. Any instantiation of one of these functions imported from `@ember/utils` will log a deprecation warning, notifying the user that this method is deprecated and provide a link to the supported addon. +`Ember.compare`, `Ember.isBlank`, `Ember.isEmpty`, `Ember.isEqual`, `Ember.isNone`, `Ember.isPresent`, `Ember.tryInvoke`, `Ember.typeOf`, `notEmpty`, `empty`, and `none` will be deprecated at first with an addon that extracts these methods for users that still find value in these utility methods. Any instantiation of one of these functions imported from `@ember/utils` will log a deprecation warning, notifying the user that this method is deprecated and provide a link to the supported addon. Addons that previously relied on these utility methods would also be expected to install this package. Moreover, to ease adoption of the external addon, a codemod will become available for the community. @@ -56,7 +60,7 @@ If you prefer to install the addon directly, we will provide a codemod to update ```js // With an addon -import { isEmpty } from 'addon-name'; +import { isEmpty } from 'ember-utils'; function isTomster(attributes: any): boolean { if (isEmpty(attributes)) { @@ -89,6 +93,192 @@ Lastly, the guides can also point users to a utility library like [lodash](https For many existing codebases, it should be as simple as installing the extracted addon and running the codemod. However, users not utilizing these methods will not have these methods bundled by default. +## Deprecation Guide + +### compare + +Install and import `ember-util` to `compare` two types. +until: 4.0.0 +id: use-ember-util-package--compare + +```js +import { compare } from '@ember/util'; + +compare(['code'], ['code', 'is', 'lovely']); // -1 +compare(['code'], ['code']); // 0 +compare(['code'], []); // 1 +``` + +To avoid the `compare` deprecation, you can install the `ember-util` package and do the following + +```js +import { compare } from 'ember-util'; + +compare(['code'], ['code', 'is', 'lovely']); // -1 +compare(['code'], ['code']); // 0 +compare(['code'], []); // 1 +``` + +### isBlank + +Install and import `ember-util` to check `isBlank` status. +until: 4.0.0 +id: use-ember-util-package--isBlank + +```js +import { isBlank } from '@ember/util'; + +isBlank(['code']); // false +isBlank([]); // true +``` + +To avoid the `isBlank` deprecation, you can install the `ember-util` package and do the following + +```js +import { isBlank } from 'ember-util'; + +isBlank(['code']); // false +isBlank([]); // true +``` + +### isEmpty + +Install and import `ember-util` to check `isEmpty` status. +until: 4.0.0 +id: use-ember-util-package--isEmpty + +```js +import { isEmpty } from '@ember/util'; + +isEmpty(['code']); // false +isEmpty([]); // true +``` + +To avoid the `isEmpty` deprecation, you can install the `ember-util` package and do the following + +```js +import { isEmpty } from 'ember-util'; + +isEmpty(['code']); // false +isEmpty([]); // true +``` + +### isEqual + +Install and import `ember-util` to check `isEqual` status. +until: 4.0.0 +id: use-ember-util-package--isEqual + +```js +import { isEqual } from '@ember/util'; + +isEqual({}, { a: 'key' }); // false +isEqual({ a: 'key' }, { a: 'key' }); // true +isEqual(['code'], ['code']); // false +``` + +To avoid the `isEqual` deprecation, you can install the `ember-util` package and do the following + +```js +import { isEqual } from 'ember-util'; + +isEqual({}, { a: 'key' }); // false +isEqual({ a: 'key' }, { a: 'key' }); // true +isEqual(['code'], ['code']); // false +``` + +### isNone + +Install and import `ember-util` to check `isNone` status. +until: 4.0.0 +id: use-ember-util-package--isNone + +```js +import { isNone } from '@ember/util'; + +isNone(undefined); // true +isNone([]); // false +isNone(''); // false +``` + +To avoid the `isNone` deprecation, you can install the `ember-util` package and do the following + +```js +import { isNone } from 'ember-util'; + +isNone(undefined); // true +isNone([]); // false +isNone(''); // false +``` + +### isPresent + +Install and import `ember-util` to check `isPresent` status. +until: 4.0.0 +id: use-ember-util-package--isPresent + +```js +import { isPresent } from '@ember/util'; + +isPresent(undefined); // false +isPresent([]); // false +isPresent('hi der'); // true +``` + +To avoid the `isPresent` deprecation, you can install the `ember-util` package and do the following + +```js +import { isPresent } from 'ember-util'; + +isPresent(undefined); // false +isPresent([]); // false +isPresent('hi der'); // true +``` + +### tryInvoke + +Install and import `ember-util` to invoke a method on a target object. +until: 4.0.0 +id: use-ember-util-package--tryInvoke + +```js +import { tryInvoke } from '@ember/util'; + +let d = new Date('03/15/2013'); +tryInvoke(d, 'getMilliseconds'); // 0 +``` + +To avoid the `tryInvoke` deprecation, you can install the `ember-util` package and do the following + +```js +import { tryInvoke } from 'ember-util'; + +let d = new Date('03/15/2013'); +tryInvoke(d, 'getMilliseconds'); // 0 +``` + +### typeOf + +Install and import `ember-util` to check `typeOf` on an input. +until: 4.0.0 +id: use-ember-util-package--typeOf + +```js +import { typeOf } from '@ember/util'; + +let noop = () => {}; +typeOf(noop); // 'function' +``` + +To avoid the `typeOf` deprecation, you can install the `ember-util` package and do the following + +```js +import { typeOf } from 'ember-util'; + +let noop = () => {}; +typeOf(noop); // 'function' +``` + ## Drawbacks This change may impact quite a few codebases. Moreover, users who heavily rely on these utility methods will have to install another addon. Some users may desire this functionality out of the box. From 1ce9290e0866485c9a6388e74d03653b307e413e Mon Sep 17 00:00:00 2001 From: Scott Newcomer Date: Sun, 22 Nov 2020 21:15:33 -0800 Subject: [PATCH 07/10] change file name for more informative purposes --- ...0334-deprecate-some-utils.md => 0334-deprecate-ember-utils.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename text/{0334-deprecate-some-utils.md => 0334-deprecate-ember-utils.md} (100%) diff --git a/text/0334-deprecate-some-utils.md b/text/0334-deprecate-ember-utils.md similarity index 100% rename from text/0334-deprecate-some-utils.md rename to text/0334-deprecate-ember-utils.md From 23f183fb9760671b4e0bd00e5884da3ef4582c82 Mon Sep 17 00:00:00 2001 From: Scott Newcomer Date: Mon, 23 Nov 2020 13:21:10 -0800 Subject: [PATCH 08/10] Add computed properties deprecation notes --- text/0334-deprecate-ember-utils.md | 88 ++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/text/0334-deprecate-ember-utils.md b/text/0334-deprecate-ember-utils.md index 353b2bfc1b..c9b895b63d 100644 --- a/text/0334-deprecate-ember-utils.md +++ b/text/0334-deprecate-ember-utils.md @@ -279,6 +279,94 @@ let noop = () => {}; typeOf(noop); // 'function' ``` +### notEmpty + +Install and import `ember-util` to check `notEmpty` on a property. +until: 4.0.0 +id: use-ember-util-package--notEmpty + +```js +import { notEmpty } from '@ember/object/computed'; + +class ToDoList { + constructor(todos) { + set(this, 'todos', todos); + } + + @notEmpty('args.todos') isDone; +} +``` + +To avoid the `notEmpty` deprecation, you can install the `ember-util` package and do the following + +```js +import { notEmpty } from 'ember-util'; + +class ToDoList { + constructor(todos) { + set(this, 'todos', todos); + } + + @notEmpty('todos') isDone; +} +``` + +### empty + +Install and import `ember-util` to check `empty` on a property. +until: 4.0.0 +id: use-ember-util-package--empty + +```js +import { empty } from '@ember/object/computed'; + +class ToDoList { + constructor(todos) { + set(this, 'todos', todos); + } + + @empty('todos') isDone; +} +``` + +To avoid the `empty` deprecation, you can install the `ember-util` package and do the following + +```js +import { empty } from 'ember-util'; + +class ToDoList { + constructor(todos) { + set(this, 'todos', todos); + } + + @empty('todos') isDone; +} +``` + +### none + +Install and import `ember-util` to check `none` on a property. +until: 4.0.0 +id: use-ember-util-package--none + +```js +import { none } from '@ember/object/computed'; + +class ToDoList { + @none('args.todos') isDone; +} +``` + +To avoid the `none` deprecation, you can install the `ember-util` package and do the following + +```js +import { none } from 'ember-util'; + +class ToDoList { + @none('args.todos') isDone; +} +``` + ## Drawbacks This change may impact quite a few codebases. Moreover, users who heavily rely on these utility methods will have to install another addon. Some users may desire this functionality out of the box. From ed6e211dd09b7b40752c7a9d4e7f0b2ce5677df2 Mon Sep 17 00:00:00 2001 From: Scott Newcomer Date: Mon, 23 Nov 2020 13:24:26 -0800 Subject: [PATCH 09/10] Fix title to reflect whole package --- text/0334-deprecate-ember-utils.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0334-deprecate-ember-utils.md b/text/0334-deprecate-ember-utils.md index c9b895b63d..05f1aaeb39 100644 --- a/text/0334-deprecate-ember-utils.md +++ b/text/0334-deprecate-ember-utils.md @@ -2,7 +2,7 @@ - RFC PR: https://github.com/emberjs/rfcs/pull/334 - Ember Issue: https://github.com/emberjs/rfcs/issues/333 -# Deprecate Existence Utils & Computed Properties +# Deprecate Ember Utils & dependent Computed Properties ## Summary From 0d50d13ebcc6d55f3f57a6291aae64cba9cc9528 Mon Sep 17 00:00:00 2001 From: Edward Faulkner Date: Fri, 1 Jul 2022 14:49:30 -0400 Subject: [PATCH 10/10] Updating for newer RFC format and version numbers --- text/0334-deprecate-ember-utils.md | 93 +++++++++++++++--------------- 1 file changed, 45 insertions(+), 48 deletions(-) diff --git a/text/0334-deprecate-ember-utils.md b/text/0334-deprecate-ember-utils.md index 05f1aaeb39..6f6b5fe17f 100644 --- a/text/0334-deprecate-ember-utils.md +++ b/text/0334-deprecate-ember-utils.md @@ -1,22 +1,39 @@ -- Start Date: 2018-05-22 -- RFC PR: https://github.com/emberjs/rfcs/pull/334 -- Ember Issue: https://github.com/emberjs/rfcs/issues/333 +--- +Stage: Accepted +Start Date: 2018-05-22 +Release Date: Unreleased +Release Versions: + ember-source: vX.Y.Z + ember-data: vX.Y.Z +Relevant Team(s): Ember.js +RFC PR: https://github.com/emberjs/rfcs/pull/334 +--- + + # Deprecate Ember Utils & dependent Computed Properties ## Summary -This RFC proposes the deprecation of the following [methods](https://api.emberjs.com/ember/release/modules/@ember%2Futils): -- `Ember.compare` -- `Ember.isBlank` -- `Ember.isEmpty` -- `Ember.isEqual` -- `Ember.isNone` -- `Ember.isPresent` -- `Ember.tryInvoke` -- `Ember.typeOf` - -As well as [computed properties](http://api.emberjs.com/ember/release/modules/@ember%2Fobject) that rely on these methods: +This RFC proposes the deprecation of the following [methods](https://api.emberjs.com/ember/4.4/modules/@ember%2Futils): +- `compare` +- `isBlank` +- `isEmpty` +- `isEqual` +- `isNone` +- `isPresent` +- `typeOf` + +As well as [computed properties](http://api.emberjs.com/ember/4.4/modules/@ember%2Fobject#functions-computed) that rely on these methods: - `notEmpty` - `empty` - `none` @@ -31,11 +48,11 @@ A simple example of this cognitive load would be checking for the presence of a In addition, when checking whether a primitive value is truthy, a user can choose from `isPresent`, `isBlank`, `isNone`, or `isEmpty`. This can can lead to some confusion for users as there are many options to do the same thing. -Lastly, `Ember.isEmpty` documented [here](https://www.emberjs.com/api/ember/release/functions/@ember%2Futils/isEmpty) will return false for an empty object. Defining what an empty object is can be a bit tricky and `isEmpty` provided specific semantics that may not fit a users definition. This problem of specific semantics not fitting a users definition also applies to the other utility methods as well. +Lastly, `isEmpty` documented [here](https://www.emberjs.com/api/ember/release/functions/@ember%2Futils/isEmpty) will return false for an empty object. Defining what an empty object is can be a bit tricky and `isEmpty` provided specific semantics that may not fit a users definition. This problem of specific semantics not fitting a users definition also applies to the other utility methods as well. ## Detailed design -`Ember.compare`, `Ember.isBlank`, `Ember.isEmpty`, `Ember.isEqual`, `Ember.isNone`, `Ember.isPresent`, `Ember.tryInvoke`, `Ember.typeOf`, `notEmpty`, `empty`, and `none` will be deprecated at first with an addon that extracts these methods for users that still find value in these utility methods. Any instantiation of one of these functions imported from `@ember/utils` will log a deprecation warning, notifying the user that this method is deprecated and provide a link to the supported addon. +`compare`, `isBlank`, `isEmpty`, `isEqual`, `isNone`, `isPresent`, `typeOf`, `notEmpty`, `empty`, and `none` will be deprecated at first with an addon that extracts these methods for users that still find value in these utility methods. Any instantiation of one of these functions imported from `@ember/utils` will log a deprecation warning, notifying the user that this method is deprecated and provide a link to the supported addon. Addons that previously relied on these utility methods would also be expected to install this package. Moreover, to ease adoption of the external addon, a codemod will become available for the community. @@ -98,7 +115,7 @@ For many existing codebases, it should be as simple as installing the extracted ### compare Install and import `ember-util` to `compare` two types. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--compare ```js @@ -122,7 +139,7 @@ compare(['code'], []); // 1 ### isBlank Install and import `ember-util` to check `isBlank` status. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--isBlank ```js @@ -144,7 +161,7 @@ isBlank([]); // true ### isEmpty Install and import `ember-util` to check `isEmpty` status. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--isEmpty ```js @@ -166,7 +183,7 @@ isEmpty([]); // true ### isEqual Install and import `ember-util` to check `isEqual` status. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--isEqual ```js @@ -190,7 +207,7 @@ isEqual(['code'], ['code']); // false ### isNone Install and import `ember-util` to check `isNone` status. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--isNone ```js @@ -214,7 +231,7 @@ isNone(''); // false ### isPresent Install and import `ember-util` to check `isPresent` status. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--isPresent ```js @@ -235,32 +252,10 @@ isPresent([]); // false isPresent('hi der'); // true ``` -### tryInvoke - -Install and import `ember-util` to invoke a method on a target object. -until: 4.0.0 -id: use-ember-util-package--tryInvoke - -```js -import { tryInvoke } from '@ember/util'; - -let d = new Date('03/15/2013'); -tryInvoke(d, 'getMilliseconds'); // 0 -``` - -To avoid the `tryInvoke` deprecation, you can install the `ember-util` package and do the following - -```js -import { tryInvoke } from 'ember-util'; - -let d = new Date('03/15/2013'); -tryInvoke(d, 'getMilliseconds'); // 0 -``` - ### typeOf Install and import `ember-util` to check `typeOf` on an input. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--typeOf ```js @@ -282,7 +277,7 @@ typeOf(noop); // 'function' ### notEmpty Install and import `ember-util` to check `notEmpty` on a property. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--notEmpty ```js @@ -314,7 +309,7 @@ class ToDoList { ### empty Install and import `ember-util` to check `empty` on a property. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--empty ```js @@ -346,7 +341,7 @@ class ToDoList { ### none Install and import `ember-util` to check `none` on a property. -until: 4.0.0 +until: 5.0.0 id: use-ember-util-package--none ```js @@ -377,5 +372,7 @@ Given the example above, some users see a lot of value for the safety checks `is Another option would be to improve existing utility cases such as `isEmpty({}) === true`. Moreover, we could also consider scoping existing utility methods to specific types. For example, `isEmpty` would be specific to checking objects, collections, maps or sets to reduce confusion of when these utility methods should be used. +Instead of deprecating the `notEmpty`, `empty`, `none` computed macros one-by-one, it would probably be good to deprecate the entire `@ember/object/computed` module because everything else in there is not aligned with current idioms. + ## Unresolved questions