@aid-on/qwiks

Qwik x nagare Stream<T> integration

Hook library that seamlessly bridges Nagare Streams to Qwik Signals

English | 日本語

Why qwiks?

nagare Stream<T> → Qwik Signal

// Use nagare Streams directly in Qwik components
const aiResponse = useStreamText(() =>
  unilmp.stream("Hello AI")  // Returns nagare Stream<string>
);

// Automatically converted to Qwik Signals
return <div>{aiResponse.text}</div>  // Reactively updates

Edge-Optimized

• Full Cloudflare Workers support
• Native WebStreams
• Memory-efficient streaming
• Backpressure handling

Aid-On Ecosystem Integration

// Integrates with all Aid-On libraries
useStream(() => unilmp.stream(...))     // LLM streaming
useStream(() => embersm.watch(...))     // Memory updates
useStream(() => synapser.reports(...))  // Agent reports

Installation

npm install @aid-on/qwiks

Usage

useStreamText - Text Streaming

import { component$ } from "@builder.io/qwik";
import { useStreamText } from "@aid-on/qwiks";
import { unilmp } from "@aid-on/unilmp";

export default component$(() => {
  const chat = useStreamText(() =>
    unilmp()
      .model("groq:llama-3.3-70b-versatile")
      .credentials({ groqApiKey: "..." })
      .stream("Tell me a story")
  );

  return (
    <div>
      <div class="message">{chat.text}</div>

      <div class="status">
        {chat.status === "streaming" && "Generating..."}
        {chat.status === "completed" && "Done"}
        {chat.status === "error" && `Error: ${chat.error}`}
      </div>

      <div class="metrics">
        Characters: {chat.metrics.charCount}
        Words: {chat.metrics.wordCount}
      </div>

      <button onClick$={chat.stop}>Stop</button>
      <button onClick$={chat.restart}>Restart</button>
    </div>
  );
});

useStream - Generic Streaming

import { useStream } from "@aid-on/qwiks";
import type { Stream } from "@aid-on/nagare";

interface DataEvent {
  timestamp: number;
  value: number;
}

export default component$(() => {
  const dataStream = useStream<DataEvent>(() =>
    createDataStream()  // Returns Stream<DataEvent>
  );

  return (
    <div>
      <div>Value: {dataStream.value?.value}</div>
      <ul>
        {dataStream.history.map((event, i) => (
          <li key={i}>
            {event.timestamp}: {event.value}
          </li>
        ))}
      </ul>
    </div>
  );
});

useStreamArray - Array Streaming

import { useStreamArray } from "@aid-on/qwiks";

export default component$(() => {
  const items = useStreamArray<string>(() =>
    stream.array(["item1", "item2", "item3"])
      .throttle(1000)
  );

  return (
    <ul>
      {items.array.map((item, i) => (
        <li key={i}>{item}</li>
      ))}
    </ul>
  );
});

useSSEStream - Server-Sent Events

import { useSSEStream } from "@aid-on/qwiks";

export default component$(() => {
  const events = useSSEStream("/api/events");

  return (
    <div>
      <div class={`status ${events.status}`}>
        {events.status === "connecting" && "Connecting..."}
        {events.status === "streaming" && "Connected"}
        {events.status === "error" && "Error"}
      </div>

      <div class="events">
        {events.history.slice(-10).map((event, i) => (
          <div key={i}>{event.type}: {event.data}</div>
        ))}
      </div>
    </div>
  );
});

API Reference

useStreamText

Hook for text streaming.

function useStreamText(
  streamFactory: QRL<() => Stream<string>>,
  options?: UseStreamTextOptions
): StreamTextState

interface StreamTextState {
  text: string;                 // Accumulated text
  chunks: string[];             // Chunk array
  status: StreamStatus;         // Stream status
  error: Error | null;          // Error info
  stop: () => void;             // Stop streaming
  restart: () => Promise<void>; // Restart streaming
  metrics: {
    charCount: number;          // Character count
    wordCount: number;          // Word count
    lineCount: number;          // Line count
  };
}

useStream

Generic streaming hook.

function useStream<T>(
  streamFactory: QRL<() => Stream<T>>,
  options?: UseStreamOptions
): StreamState<T>

interface StreamState<T> {
  value: T | null;              // Latest value
  history: T[];                 // Full history
  status: StreamStatus;         // Status
  error: Error | null;          // Error
  stop: () => void;             // Stop
  restart: () => Promise<void>; // Restart
}

useStreamArray

Array streaming hook.

function useStreamArray<T>(
  streamFactory: QRL<() => Stream<T>>,
  options?: UseStreamArrayOptions
): StreamArrayState<T>

interface StreamArrayState<T> {
  array: T[];                   // Accumulated array
  latest: T | null;             // Latest element
  status: StreamStatus;         // Status
  error: Error | null;          // Error
  stop: () => void;             // Stop
  restart: () => Promise<void>; // Restart
  clear: () => void;            // Clear array
}

Ecosystem Integration

qwiks integrates with all Aid-On Platform libraries:

• @aid-on/nagare - Stream foundation
• @aid-on/unillm - LLM streaming
• @aid-on/embersm - Memory system
• @aid-on/synapser - Agent framework

License

MIT