Harmonize Options API

[deluxe]

Options class exposes mostly options methods with many overloads.
Three methods are outliers: nextElement(E[]), nextElement(List) and nextElement(Collection).

Rename nextElement(List) and nextElement(Collection) to option(List) and option(Collection).
A method option(E...) already exists so no need to rename nextElement(E...).

If modifying in version 2.x, keep existing methods as deprecated, forwarding to renamed methods.
In version 3, remove existing methods.

[asolntsev]

@deluxe The problem is that we are almost releasing 3.0.0 :)

Maybe we can mark nextElement as "deprecated for removal" in 3.0.0? They are not harmful - let them live until 4.0.0 :)

[bodiam]

I'm also not a fan of removing them. I'm not even sure if deprecating then would be the way to go, since we use the options() all over, and deprecations would create almost the same amount of work as removing them. Having said that, I see the motivation for a cleaner API, and I don't think I have issues with introducing them.

[asolntsev]

I would challenge both names.
What if both "nextElement" and "option" are not good?

In fact, this method returns a random element from given collection/list/set/enum/array.

Maybe its name should be "randomElement"? Or "randomValue"? Or just "random"? Or "pickAny"?

[deluxe]

I agree. And I'd prefer a short name so random, pickAny (even any).

But this means changing the whole class.

[kingthorin]

I like the idea of any.

I'd suggest the existing methods be market deprecated for removal. The new any methods get the working code and the old (deprecated) methods call them. (That simplifies future removal IMHO. It also means our unit tests can be updated so we aren't using our own deprecated methods.)

[bodiam]

any reminds me of the Kotlin any, which returns true or false, so I'm not sure if that's great. I'm also not sure if random is great, cause every method in Datafaker returns a random value. But I agree that option and nextElement aren't great either, especially faker.options().option() is not very nice, faker.options().any(list) might be okay, or faker.options().pickOne(list), cause then you could also have a pickMany(list) version. Just thinking out loud here, I'm not sure what's best.

[kingthorin]

faker.options().anyOf(list) ?
or
faker.options().oneOf(list)?

[deluxe]

If we rename all methods, we could also deprecate the whole class and create a new one, with a new method name in faker.
Like faker.select().oneOf() or faker.pick().oneOf() or something alike.

[bodiam]

I like this discussion, and I also like that it becomes a bit of a natural language. Much better than faker.options().option() anyway.

[bodiam]

I've asked ChatGPT, and it likes oneOf, perhaps combined with selection, like this:

faker.selection().oneOf(...)
faker.selection().subsetOf(...)

Reason is that most of our Providers are nouns, not verbs, so I kinda agree with the suggestion here, but I'm not too fuzzed, I do think that select().oneOf() reads more natural.

[deluxe]

Currently working on a proposal PR with selection()...