Better documentation for `streamObject`

[bernaferrari]

Feature Description

1. Can streamObject throw an Error if there is no internet, if any issues happen, or finishReason via other already guarantees that the error was handled and I don't need to try/catch anything?
2. ✅ What is an example of the output? Will it "close" the JSON like { a: "bcd", e: "f" (got cut) } or will it just get the last part that successfully finished like { a: "bcd" } ? Maybe even allow both, but configurable somewhere? This has a good example: https://github.com/Operator-technology/json-autocomplete/tree/main

Edit for 2: it is going to do { a: "bcd", e: "f" (got cut) }, but I wish there were a way to do the other way, since sometimes streaming properties that didn't finish cause bugs and I have no way to verify (https://github.com/vercel/ai/issues/1486)

3. What will partialObjectStream vs fullStream work? How do I even "build it", do I sum the pieces like text delta, how do I make it work together? Maybe you could improve the streamText to already give the "whole" text instead of the delta. How do I use fullStream? If I wait for fullStream, it is basically no streaming?

4. Could show one or two execution flow examples in the docs so all of these are super clear.

5. You say the schema is not guaranteed but at the same time you already type-cast as the schema. How maxRetries is related to this? Will it retry if the schema fails, or only if connection fails? How/when it decides to retry?

6. Same as 5, but is there a way to know if the json worked? Should I use result.finishReason !== "stop" && result.finishReason !== "length" to see if it completed successfully, and then compare the fields to see if they are the type they are supposed to be? Maybe you could lift this boilerplate too. I don't understand this on the docs:

The partialObjectStream is typed with a deep partial type, but not validated. If you want to be certain that the actual content matches your schema, you need to implement your own validation for partial results, e.g. using Zod.

Since you are already lifting so much, perhaps you could also solve this? Even if it is a dead simple validation to see if fields exist and match what you asked, else retry/return a sample value?

Use Case

No response

Additional context

No response