API design

[cescoffier]

No description provided.

[emmanuelbernard]

You still have in UniSubscribe the inconsistent CompletableFuture asCompletionStage()

[cescoffier]

Why is it inconsistent? You mean it should be adapt().asCompletionStage() ?

[emmanuelbernard]

Katia feedback:

• await is used everywhere else and probably could be less disrupting
• "ca va loin cette API, mais ça fait plaisir :)"
• what's the difference between or() and onAny() (Emmanuel)

[cescoffier]

or vs. any that's a great question and you can ask the same about and vs. zip.

and and or are instance methods. You combine the current Uni with another one.
any and zip are static methods. You pass all participants.

Now I'm not happy with this, and I'm thinking about moving zip and any into createFrom, but it does not "fit" well there either...

[emmanuelbernard]

yeah

[kenfinnigan]

What about instead of Uni.any().of(...)and Uni.zip().unis(...) it becomes Any.uni().of(...) and Zip.unis(...)?

Then for Multi it would be Any.multi().of(...) and Zip.multis(...).

[kenfinnigan]

If we don't need to support Iterable as an argument to of(), it could be shortened to Any.of(...)

[kenfinnigan]

What's the advantage to returning a new instance here instead of having some of the code that the class has around returning if it's the same thing, or returning a completion stage, and only handle actual adaptation in UniAdaptTo?

Doesn't appear to be used anywhere else, so curious

[cescoffier]

Yes, that can definitely be static.

This optimization can be done in a few places where we could pass the upstream as a parameter, and so avoid the useless instantiation. To be honest I didn't focus on this so far.

[Ladicek]

Re Uni.any and Uni.zip -- I'd just call them Uni.anyOf and Uni.allOf, similarly to CompletableFuture.

[Ladicek]

So I'd like to highlight one concern I have with the proposed API. It's probably been decided already, but I'm gonna complain anyway :-)

I really don't like how different parts of the API are split into different pieces, presumably to make it easier to navigate, understand, more fluent, etc. I very much disagree with this reasoning, because:

1. It actually makes the API harder to understand and use, both for beginners and experts. Compared to e.g. RxJava types or java.util.stream.Stream, where the entire API is mostly contained in a single type, here, it's scattered around multiple ones. That probably doesn't matter if you expect people to copy incantations from examples and guides, but it becomes a hindrance very quickly when you start writing code from scratch. As a beginner, I often search for the method I need by skimming the entire API and looking mainly at types (types are a front line of documentation!). With the API split into multiple pieces, I can no longer use types as a guidance and I'm left with method names. As an expert, I already know what I want and having to chain multiple calls is just a nuisance (why do I need to type more?).

   Granted there are some places in the API where fluent API is actually better than a flat one. But uni.onResult().mapToResult(...) / uni.onResult().mapToUni(...) is a complete abomination compared to uni.map(...) / uni.flatMap(...) (I personally hate the flatMap name, but it's better than bind :-) and seems pretty well established in the industry). As another example, uni.await().indefinitely() / uni.await().atMost(long, TimeUnit) is still worse than uni.await() / uni.await(long, TimeUnit) (which is a very recognizable pattern from the JDK APIs), albeit not as much as the map / flatMap thing.

   In short -- IMHO this decision makes API discoverability significantly worse.

2. With reactive types, the less intermediate results you can create and hold on to, the better. In my experience, if it's possible to write everything as a single call chain, it's best. There's nothing wrong with just creating temporary variables holding intermediate state of the pipeline creation, but it's tempting to start calling methods on them, which easily ends up badly.

3. Established libraries don't do this. Being different from established libraries is fine, but the "innovation budget" is only so big, so we better spend it wisely. This aspect is IMHO relatively unimportant and being consistent on this lets us be different where it's important.

4. If you argue with separation of concerns, I argue with principle of locality!

If you've made it here, thanks a lot! We don't have to agree, but I believe this just had to be expressed loudly :-)

[FroMage]

About the deferred prefix. It' actually a question I had for you. What makes more sense to you:

• Uni.createFrom().item(() -> x) - you pass a supplier, it's called at subscription time
• Uni.createFrom().deferredItem(() -> x) - same as previous by explicitly mention the lazyness

I think a parameter of X means eager and Callable<X> means lazy. I don't think there's a need to have both variants, no?

When you retrieve a CS, you are requesting the result, so you subscribe to the Uni. Basically, the CS is your subscriber.

OK, got it. Perhaps this would warrant a shortcut, though.

[cescoffier]

I think a parameter of X means eager and Callable means lazy. I don't think there's a need to have both variants, no?

The idea was to be more explicit in the name.

Initially [taking the item method as exmaple], I add item(T item) and item(Supplier<T> supplier) - so the lazy aspect only described in the javadoc. As it may have been misleading, I renamed to deferredItem. If you think it's not required, happy to drop the prefix!

OK, got it. Perhaps this would warrant a shortcut, though.

Yes, I agree. Created #20 to track this.

[hutchig]

One of the advantages of the Reactor classes is that they have a common superclass that can be used
elsewhere so that things that can be plugged onto either only have to be written once to the common interface.

[hutchig]

I will read the whole proposal carefully, the above is just an intial thought.

[cescoffier]

Having a common interface can be tricky. Typically, it cannot be Publisher, because, on Uni we don't want to be a Publisher (we can be wrapped into one). This allows supporting null, for operation not providing an item.

So instead of having a common interface, I choose to provide a way to convert one to the other one (Uni -> Publisher, Multi -> Uni [potentially dropping elements])

[cescoffier]

BTW, I'm not sure this files is up to date....