Why not another approach

[lambdaR]

I have noticed from the NATS Slack that there are many questions that have been asked regarding Jetstream - Stream - Consumer - Subscription indicating a confusion among devs on how to use the API and i think it bowels down to two facts:

• the documentation is not vivid enough in explaining the subject.

• the API is somehow designed and built with a technical debt coming from the NATS core.

I know that you are working on a new docs for JestStream to help mitigate the confusion which is pretty good and necessary.

When i took a quick look at the API one question came up instantly, why the team did not use the following approach instead:
An interface that defines a contract for a Stream and from there we could create different types of Streams, each with its own methods. So, for example we could have:

• A DurableStream: nats-server tracks the subscriber’s history

• A ConsumedStream: subscriber must acknowledge the received message in order to delete it from the stream.

• A BatchedStream: subscriber expects a batch of messages that need to be acknowledged.

• An OrderedStream: subscriber and OrderedStream work together to guarantee orders.

And so on, we could even make it pluggable i.e users can create their own Stream type and accompanying methods that suit their use case.

[wallyqs]

I like the idea of a taxonomy of types to describe how to persist and consume the messages. About the JetStream API, it is a work in progress but you can take a look at some of the new ideas for the next iteration of the JetStream API in this branch: https://github.com/nats-io/nats.go/blob/f4c8896b9451d01670d3398487955dd55668bba4/jsv2/jetstream/README.md

[lambdaR]

Nice, I will take a look for sure … maybe it is too late now but in general I think engaging the community with projects like this one (via polls or something else) in the future would be beneficial for all.

[bruth]

Thanks for the feedback @lambdaR. I agree that the current JS API, specifically the convenience functions that do a lot implicitly, take more time explaining and fully understanding the implications than they are provide convenience 😅 That was a big motivation for the new API.

Regarding the interfaces for the Go API, there may be two factors at play here. One is that creating different stream or consumer types (from NATS perspective) is not really supported, since these are driven by the server. I do agree, however, that differentiating the types/making the API more tailored to the JS concepts.

The second factor is that there is general effort to maintain some semblance of parity between the client libraries, in terms of naming, while also ensuring libraries feel idiomatic to the language.

maybe it is too late now but in general I think engaging the community with projects like this one (via polls or something else) in the future would be beneficial for all

We may be at a tipping point in the community where we could get some sufficient feedback from folks on certain design decisions. I would be in favor of a "call for feedback" using this v2 of the JS API. This can be delicate topic to manage opinions, but it never hurts to see the feedback we would get.

[lambdaR]

Thanks for the explanation ... one good outcome though, if the JetStream Documentation and its API were not relatively confusing and hard to ingest, NATS by Example wouldn't be born :)

[bruth]

😄 That is likely true!