[FEATURE ember-runtime-enumerable-includes] Implements Array.includes and deprecates Array.contains

[bmeurant]

Implementation of emberjs/rfcs#136

TODO :

• Implement Enumerable.includes
• Implement Array.includes
• Deprecate contains under feature flag
• Replace usages of contains by includes
• Update docs, guides (Update documentation to move from contains to includes guides#1439) & API. To be merged once feature enabled.
• Write deprecation guide (Add Enumerable.contains to deprecation guide website#2600) & add url in deprecate call
• Rebase / squash

[alexspeller]

Oh awesome, thanks for getting this implementation done!

[bmeurant]

Here is a first proposal for emberjs/rfcs#136. Work is in progress and feedbacks expected.

I made the asumption that we have to keep Enumerable & Array APIs consistent and then have to provide a consistent includes method in Enumerable (with no index). Let me know if this is not expected.

Aliasing contains with the new includes method can break some existing apps because, according to the spec (https://tc39.github.io/ecma262/2016/#sec-array.prototype.includes), includes relies on the SameValueZero algorithm and actual contains relies on strict equality leading to differences in NaN detections (I will document it). Can we still make this ?

[mixonic]

@bmeurant Thanks :-)

contains should not be aliased to includes. Contains should keep its current implementation, and we can deprecate it though we will likely do that in a separate PR. In this PR it should simply retain its current behavior.

[bmeurant]

@mixonic thx for your feedback.

I updated this PR to keep current implementation for Enumerable.contains & Array.contains.

we can deprecate it though we will likely do that in a separate PR

Does it means that I should also remove @deprecated and deprecation warning for now ?

[rwjblue]

I believe that the deprecation should be included here when the feature flag is enabled.

[mixonic]

@rwjblue I am easily convinced, was just erring on the conservative side. @bmeurant please include the deprecation behind the feature flag! :-)

[bmeurant]

@mixonic I added feature flag and move deprecation behind it. Let me know if I forgotten something.

I also removed @deprecated from API because contains is not actually deprecated if feature is not enabled, right ?

But I was wondering: doing that, users will loose the information that contains will be deprecated soon and that they should use includes instead. Is it exists a way to provide this kind of information in APIs ?

[mixonic]

@bmeurant Yeah the documentation may require some followup tweaks. Feature flagging things like the @deprecated flag is tricky :-/. I think you should feel free to create a followup issue of things to do once the feature is "go'd" for beta.

[mixonic]

Again here I lean toward Enumerable#contains, per emberjs/website#2600 (comment). It is a Rubyish approach, curious if there are other thoughts.

[alexspeller]

I think Enumerable#contains is the convention in Ember even though it was originally a rubyism - at least it has the advantage that it's not valid syntax for something that is completely different

(See for example the changelog where it's used extensively)

[mixonic]

@bmeurant heh, there are no tests for Array#contains?! Can you add one asserting basic behavior and the deprecation please?

This is looking pretty good after some tweaks!

[mixonic]

This function (and the enumerable one) must be added only when the feature flag is enabled. For example:

let ArrayMixin = Mixin.create(Enumerable, {
 /* snip */
});
if (isEnabled('ember-runtime-enumerable-includes')) {
  ArrayMixin.reopen({
    includes(obj, startAt) {
      /* ... */
    }
  });
}
export default ArrayMixin;

[bmeurant]

Thx for feedbacks, I'll work on it ASAP

[bmeurant]

It seemed to me that Array#contains tests are also imported and run from Enumerable#contains tests. Did I miss something ?

[mixonic]

Ah I see @bmeurant :-) right there is no contains on arrays, only on enumerable 👍

[bmeurant]

I wanted to add a test to verify assertion calling Enumerable#includes with a second argument but, because tests defined on Enumerable are also run on Array suites, I did not find a good way to do it. Any advice ?

[bmeurant]

I think we have a problem line 832 during k !== value. If the feature is enabled, without becomes inconsistent because NaN !== NaN is true

[bmeurant]

I prefered replacing without behind feature flag to not add multiple isEnabled calls in original method

[mixonic]

👍

[mixonic]

@bmeurant it seems ok to add a test for contains without an offset in packages/ember-runtime/tests/mixins/enumerable_test.js, since it only impacts enumerables.

[mixonic]

Thanks for your continued work on this 😄 it looks really close, and quite nice!

[mixonic]

Looking nice. A rebase/squash to some number is semantically meaningful commits (one or more) would be great, each prefixed with [FEATURE ember-runtime-enumerable-includes] would be great.

[bmeurant]

Done 👌

[homu]

☔ The latest upstream changes (presumably #13328) made this pull request unmergeable. Please resolve the merge conflicts.

[mixonic]

Looks pretty great to me @bmeurant! Thank you! I'll get someone else on core to review and we can with their 👍

[rwjblue]

Should not use the global here (Ember.isNone), if we need isNone it should be imported. Can we just do the null / undefined check ourselves?

[bmeurant]

@rwjblue using the global here was surely a mistake, sorry. isNone is already imported and used in slice. I'll update. But why do you prefer to not use imported isNone and doing null / undefined check ourselves in this case?

[bmeurant]

Anyway, explicit null check is unnecessary as we only iterating on idx = startAt. I removed it.

[rwjblue]

This looks good, only one small tweak and this is good to go...

[mixonic]

This is great! Thank you @bmeurant!

[rwjblue]

FYI - I created https://github.com/rwjblue/ember-runtime-enumerable-includes-polyfill to make this a bit easier for addons to avoid deprecations, use the newer syntax, and continue to support older versions of Ember.