8000 `useTamboStreamStatus` — expose streaming readiness flags for tambo-ai components · Issue #580 · tambo-ai/tambo · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content
useTamboStreamStatus — expose streaming readiness flags for tambo-ai components #580
Closed
@michaelmagan

Description

@michaelmagan

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 or streamError

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 flag isError.
  • 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
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions

    0