Confusing singleWhereOrNull extension method

[jaripekkala]

https://github.com/dart-lang/collection/blob/v1.17.2/lib/src/iterable_extensions.dart#L296-L304

My proposal: Deprecate and delete singleWhereOrNull, and introduce more clear methods

Reasoning:
Many use the singleWhere method as replacement to firstWhere when the list should not contain more than one matching value, in cases when the logic would not work if code somewhere later changes in way that there are multiple matching values, so throwing error would make sense (developer need to go and handle the case).

But when also no matching value is acceptable, developer can mistakenly use singleWhereOrNull and have different behaviour than intended. These cases are not so commonly unit tested, as these cases are preventing mistakes in the future.

[lrhn]

I can see how the singleWhereOrNull behavior might not be what someone wants, if they're really asking for a zeroOrOneWhere: If there is none, give me null, if there is one, give me it, if there are more, something is seriously wrong, so throw.

I do think that elements.singleWhereOrNull(test) should behave like elements.where(test).singleOrNull, so maybe we just need to add another method to cover the zeroOrOneWhere/optionalSingleWhere case.

[mattsimgithub]

Chiming in that the implementation of this method is confusing, for the reasons discussed here. I expect a single... method to throw if multiple matches are found.

[lrhn]

I expect a single... method to throw if multiple matches are found.

Do you expect single... method to throw if zero matches are found? The single getter and singleWhere function does.

The singleOrNull and singleWhereOrNull both return null where the other variant would have thrown.
(The "or Null" doesn't mean "or None". It means "or return Null if a single value isn't found.").

[mattsimgithub]

Do you expect single... method to throw if zero matches are found? The single getter and singleWhere function does.

Not if the suffix is OrNull. My expectation was the OrNull would apply in the case of zero matches, but not in the case of multiple matches.

(The "or Null" doesn't mean "or None". It means "or return Null if a single value isn't found.").

Understood, that is what it does. It's not what I expected, and I'm glad I read the docs.

What you call zeroOrOneWhere, I want commonly. What singleWhereOrNull actually does, I doubt I will ever use.

I agree with jaripekkala that the behavior of this method is confusing, and I think it's likely that others are wrongly expecting singleWhereOrNull to throw on multiple matches. But whether we are common in this or outliers I don't know.