The generated clients are designed in a way that they are very flexible, as a result they are less ergonomic!
We want a flexible and ergonomic api!
stream and abortSignal
One thing to consider, is the abortSignal. We need to provide this when there is a streaming result. We may provide it when there is no streaming result. So do we either provide it always or only if a stream is possible?
So when a stream is possible, this does not mean that we always get a streaming response. In case of an error we usually don't get a streaming response. In case of a non streaming response there might be a benefit in being able to abort the request. Eh hypothetically that is, cannot really think of a sensible example. It might make sense to provide an abortSignal always so we have a more consistent API.
Another solution would be to return the stream as a function that, when called will return an AsyncIterable. The function will accept a signal. This signal will abort the response. This might make more sense.
Whatever we choose, i think consistency is important. So if we provide an abortsignal as an operation function argument we should always do that with every operation. This will clutter the api a bit with stuff that we don't every use. so for now i think the function returning an async iterable is the best solution.
globals!
Using globals to configure the client makes it easier to work with! For instance we can configure the credentials or base url once and then use the client via functions.
However there are plenty of situations where you would want to configure the credentials, base url and middelware not globally! For instance when testing.
We don't want to create a client class, this would make the api less ergonomic to use and kill tree shakability.
So async hooks might be a solution!
let's investigate that, but... How does that work in a browser. Or in deno? bun?
The generated clients are designed in a way that they are very flexible, as a result they are less ergonomic!
We want a flexible and ergonomic api!
stream and abortSignal
One thing to consider, is the abortSignal. We need to provide this when there is a streaming result. We may provide it when there is no streaming result. So do we either provide it always or only if a stream is possible?
So when a stream is possible, this does not mean that we always get a streaming response. In case of an error we usually don't get a streaming response. In case of a non streaming response there might be a benefit in being able to abort the request. Eh hypothetically that is, cannot really think of a sensible example. It might make sense to provide an abortSignal always so we have a more consistent API.
Another solution would be to return the stream as a function that, when called will return an AsyncIterable. The function will accept a signal. This signal will abort the response. This might make more sense.
Whatever we choose, i think consistency is important. So if we provide an abortsignal as an operation function argument we should always do that with every operation. This will clutter the api a bit with stuff that we don't every use. so for now i think the function returning an async iterable is the best solution.
globals!
Using globals to configure the client makes it easier to work with! For instance we can configure the credentials or base url once and then use the client via functions.
However there are plenty of situations where you would want to configure the credentials, base url and middelware not globally! For instance when testing.
We don't want to create a client class, this would make the api less ergonomic to use and kill tree shakability.
So async hooks might be a solution!
let's investigate that, but... How does that work in a browser. Or in deno? bun?