Closed
Description
Objective
Surface per-prop and global streaming status so consumers can show loaders, skeletons, or errors while LLM-generated props stream in.
API
/** Global stream flags */
export interface StreamStatus {
isPending: boolean; // no token for any prop yet
isStreaming: boolean; // ≥1 prop still streaming
isSuccess: boolean; // every prop finished without error
isError: boolean; // a fatal error occurred in any prop or the stream
streamError?: Error; // first fatal error (undefined if none)
}
/** Per-prop flags */
export interface PropStatus {
isPending: boolean; // no token for prop
isStreaming: boolean; // ≥1 token for the prop, next props has <1 token
isSuccess: boolean; // next prop has > 1 token
isError: boolean; // if there is an error during the stream
error?: Error; // the error (undefined if none)
}
function useTamboStreamStatus<Props = unknown>(): {
streamStatus: StreamStatus;
propStatus: Record<keyof Props, PropStatus>;
};
Boolean Lifecycle (per-prop & global)
Phase | isPending | isStreaming | isSuccess | isError |
---|---|---|---|---|
Init | ✅ | ❌ | ❌ | ❌ |
First token | ❌ | ✅ | ❌ | ❌ |
Mid-stream | ❌ | ✅ | ❌ | ❌ |
Prop done | ❌ | ❌ | ✅ | ❌ |
All props done | ❌ | ❌ | ✅ | ❌ |
Fatal error | ❌ | ❌ | ❌ | ✅ |
Derivation rules
- isPending – all props
isPending
- isStreaming – any prop
isStreaming
- isSuccess – all props
isSuccess
- isError – any prop
isError
orstreamError
Usage
// Wait for entire stream
const { streamStatus } = useTamboStreamStatus();
if (!streamStatus.isSuccess) return <Spinner />;
return <Card {...props} />;
// Highlight in-flight props
const { propStatus } = useTamboStreamStatus();
<h2 className={propStatus.title.isStreaming ? "animate-pulse" : ""}>
{title}
</h2>
Error Handling
- Per-prop errors live at
propStatus[key].error
and flagisError
. - First fatal error mirrored to
streamStatus.streamError
.
SSR Guard
The hook throws during SSR/SSG. Use only in browser contexts or wrap in useEffect
/ dynamic import.
Developer Notes
- Namespacing under
streamStatus
eliminates prop-name collisions—no reserved-name guard needed. - For strong generics, expose
createTypedHook(schema)
as a helper.
Acceptance Criteria
- Correct flags and error propagation for single & multiple props.
- Global flags follow derivation rules.
- SSR guard enforced.
- Unit tests cover lifecycle phases and error cases.
- Type safety preserved; no generic loss.
Metadata
Metadata
Assignees
Labels
No labels