ai.matey.react.stream 0.2.0

package/dist/types/stream-text.d.ts

@@ -0,0 +1,89 @@
+/**
+ * StreamText Component
+ *
+ * React component for rendering streaming text with typing effect.
+ *
+ * @module
+ */
+import { type ReactNode } from 'react';
+/**
+ * StreamText props.
+ */
+export interface StreamTextProps {
+    /** Text to display */
+    text: string;
+    /** Whether streaming is active */
+    isStreaming?: boolean;
+    /** Show cursor while streaming */
+    showCursor?: boolean;
+    /** Cursor character */
+    cursor?: string;
+    /** Cursor blink interval in ms */
+    cursorBlinkInterval?: number;
+    /** Custom className */
+    className?: string;
+    /** Custom render function */
+    renderText?: (text: string) => ReactNode;
+    /** Children to render after text */
+    children?: ReactNode;
+}
+/**
+ * StreamText - Display streaming text with optional cursor.
+ *
+ * @example
+ * ```tsx
+ * import { StreamText } from 'ai.matey.react.stream';
+ *
+ * function ChatMessage({ text, isStreaming }) {
+ *   return (
+ *     <StreamText
+ *       text={text}
+ *       isStreaming={isStreaming}
+ *       showCursor={true}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function StreamText({ text, isStreaming, showCursor, cursor, cursorBlinkInterval, className, renderText, children, }: StreamTextProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * TypeWriter props.
+ */
+export interface TypeWriterProps {
+    /** Text to type */
+    text: string;
+    /** Typing speed in ms per character */
+    speed?: number;
+    /** Delay before starting in ms */
+    delay?: number;
+    /** Called when typing completes */
+    onComplete?: () => void;
+    /** Custom className */
+    className?: string;
+    /** Show cursor */
+    showCursor?: boolean;
+    /** Cursor character */
+    cursor?: string;
+}
+/**
+ * TypeWriter - Display text with typewriter effect.
+ *
+ * Simulates typing effect for non-streaming text.
+ *
+ * @example
+ * ```tsx
+ * import { TypeWriter } from 'ai.matey.react.stream';
+ *
+ * function WelcomeMessage() {
+ *   return (
+ *     <TypeWriter
+ *       text="Welcome to AI Matey!"
+ *       speed={50}
+ *       onComplete={() => console.log('Done typing')}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare function TypeWriter({ text, speed, delay, onComplete, className, showCursor, cursor, }: TypeWriterProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=stream-text.d.ts.map

package/dist/types/stream-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-text.d.ts","sourceRoot":"","sources":["../../src/stream-text.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,kCAAkC;IAClC,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC;IACzC,oCAAoC;IACpC,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,WAAmB,EACnB,UAAiB,EACjB,MAAY,EACZ,mBAAyB,EACzB,SAAS,EACT,UAAU,EACV,QAAQ,GACT,EAAE,eAAe,2CAsCjB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,uBAAuB;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,KAAU,EACV,KAAS,EACT,UAAU,EACV,SAAS,EACT,UAAiB,EACjB,MAAY,GACb,EAAE,eAAe,2CAyCjB"}

package/dist/types/stream-utils.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Stream Utilities
+ *
+ * Helper functions for working with streams in React.
+ *
+ * @module
+ */
+/**
+ * Options for creating a text stream.
+ */
+export interface CreateTextStreamOptions {
+    /** Called for each chunk */
+    onChunk?: (chunk: string) => void;
+    /** Called when stream completes */
+    onComplete?: (fullText: string) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Create a controlled text stream from a fetch response.
+ *
+ * @param response - Fetch response with streaming body
+ * @param options - Stream options
+ * @returns Promise resolving to full text
+ */
+export declare function createTextStream(response: Response, options?: CreateTextStreamOptions): Promise<string>;
+/**
+ * Parse Server-Sent Events (SSE) stream.
+ *
+ * @param response - Fetch response with SSE body
+ * @param options - Stream options
+ * @returns Async generator yielding parsed events
+ */
+export declare function parseSSEStream(response: Response, options?: {
+    signal?: AbortSignal;
+}): AsyncGenerator<SSEEvent, void, unknown>;
+/**
+ * SSE Event structure.
+ */
+export interface SSEEvent {
+    /** Event type */
+    event?: string;
+    /** Event data */
+    data: string;
+    /** Event ID */
+    id?: string;
+    /** Retry interval */
+    retry?: number;
+}
+/**
+ * Transform a ReadableStream with a function.
+ *
+ * @param stream - Source stream
+ * @param transform - Transform function
+ * @returns Transformed stream
+ */
+export declare function transformStream<T, U>(stream: ReadableStream<T>, transform: (chunk: T) => U | Promise<U>): ReadableStream<U>;
+/**
+ * Merge multiple streams into one.
+ *
+ * @param streams - Streams to merge
+ * @returns Merged stream
+ */
+export declare function mergeStreams<T>(...streams: ReadableStream<T>[]): ReadableStream<T>;
+/**
+ * Create a stream from an async iterable.
+ *
+ * @param iterable - Async iterable source
+ * @returns ReadableStream
+ */
+export declare function fromAsyncIterable<T>(iterable: AsyncIterable<T>): ReadableStream<T>;
+/**
+ * Convert a ReadableStream to an async iterable.
+ *
+ * @param stream - ReadableStream source
+ * @returns Async iterable
+ */
+export declare function toAsyncIterable<T>(stream: ReadableStream<T>): AsyncGenerator<T, void, unknown>;
+//# sourceMappingURL=stream-utils.d.ts.map

package/dist/types/stream-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-utils.d.ts","sourceRoot":"","sources":["../../src/stream-utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,mCAAmC;IACnC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,sBAAsB;IACtB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IACjC,mBAAmB;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,MAAM,CAAC,CAoCjB;AAED;;;;;;GAMG;AACH,wBAAuB,cAAc,CACnC,QAAQ,EAAE,QAAQ,EAClB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACrC,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAgDzC;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAiCD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,CAAC,EAClC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,EACzB,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACtC,cAAc,CAAC,CAAC,CAAC,CAmBnB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC,CAiClF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,CAkBlF;AAED;;;;;GAKG;AACH,wBAAuB,eAAe,CAAC,CAAC,EACtC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,GACxB,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAgBlC"}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "ai.matey.react.stream",
+  "version": "0.2.0",
+  "description": "React streaming utilities for AI Matey - StreamProvider, StreamContext",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "readme.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "ai.matey.types": "*",
+    "ai.matey.react.core": "*"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "react",
+    "streaming",
+    "context",
+    "provider",
+    "ai-matey"
+  ],
+  "author": "AI Matey",
+  "license": "MIT",
+  "homepage": "https://github.com/johnhenry/ai.matey#readme",
+  "bugs": {
+    "url": "https://github.com/johnhenry/ai.matey/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/ai.matey.git",
+    "directory": "packages/react-stream"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,192 @@
+# ai.matey.react.stream
+
+React components and utilities for streaming AI responses.
+
+Part of the [ai.matey](https://github.com/johnhenry/ai.matey) monorepo.
+
+## Installation
+
+```bash
+npm install ai.matey.react.stream
+```
+
+## Quick Start
+
+```tsx
+import { StreamProvider, useStreamContext, StreamText } from 'ai.matey.react.stream';
+
+// Wrap your app with StreamProvider
+function App() {
+  return (
+    <StreamProvider maxStreams={10}>
+      <ChatComponent />
+    </StreamProvider>
+  );
+}
+
+// Use streaming in components
+function ChatComponent() {
+  const { startStream, appendToStream, completeStream, getStream } = useStreamContext();
+  const [streamId, setStreamId] = useState<string | null>(null);
+
+  const handleSend = async () => {
+    const id = `msg-${Date.now()}`;
+    setStreamId(id);
+    startStream(id);
+
+    const response = await fetch('/api/chat', { method: 'POST' });
+    const reader = response.body?.getReader();
+    const decoder = new TextDecoder();
+
+    while (reader) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      appendToStream(id, decoder.decode(value));
+    }
+
+    completeStream(id);
+  };
+
+  const stream = streamId ? getStream(streamId) : null;
+
+  return (
+    <div>
+      {stream && (
+        <StreamText
+          text={stream.text}
+          isStreaming={stream.isStreaming}
+          showCursor={true}
+        />
+      )}
+      <button onClick={handleSend}>Send</button>
+    </div>
+  );
+}
+```
+
+## Exports
+
+### Components
+
+- `StreamProvider` - Context provider for stream state management
+- `StreamText` - Display streaming text with cursor
+- `TypeWriter` - Typewriter effect for static text
+
+### Hooks
+
+- `useStreamContext` - Access stream management functions
+- `useStreamState` - Get state for a specific stream
+
+### Utilities
+
+- `createTextStream` - Create controlled text stream from fetch response
+- `parseSSEStream` - Parse Server-Sent Events
+- `transformStream` - Transform stream data
+- `mergeStreams` - Merge multiple streams
+- `fromAsyncIterable` - Convert async iterable to stream
+- `toAsyncIterable` - Convert stream to async iterable
+
+### Types
+
+- `StreamState`, `StreamContextValue`, `StreamProviderProps`
+- `StreamTextProps`, `TypeWriterProps`
+- `CreateTextStreamOptions`, `SSEEvent`
+
+## API Reference
+
+### StreamProvider
+
+Context provider for managing multiple concurrent streams.
+
+```tsx
+<StreamProvider maxStreams={100}>
+  {children}
+</StreamProvider>
+```
+
+**Props:**
+- `maxStreams` - Maximum streams to keep (default: 100, oldest completed removed when exceeded)
+
+### useStreamContext
+
+Access stream management functions.
+
+```tsx
+const {
+  streams,          // Map<string, StreamState> - All streams
+  getStream,        // (id: string) => StreamState | undefined
+  startStream,      // (id: string, metadata?: object) => void
+  updateStream,     // (id: string, text: string) => void - Replace text
+  appendToStream,   // (id: string, chunk: string) => void - Append text
+  completeStream,   // (id: string) => void - Mark complete
+  setStreamError,   // (id: string, error: Error) => void
+  removeStream,     // (id: string) => void
+  clearAllStreams,  // () => void
+} = useStreamContext();
+```
+
+### useStreamState
+
+Get state for a specific stream by ID.
+
+```tsx
+const stream = useStreamState('message-1');
+// stream: { id, text, isStreaming, error, metadata } | undefined
+```
+
+### StreamText
+
+Display streaming text with optional blinking cursor.
+
+```tsx
+<StreamText
+  text="Hello world"
+  isStreaming={true}
+  showCursor={true}           // Show cursor while streaming
+  cursor="▋"                  // Cursor character
+  cursorBlinkInterval={500}   // Blink speed in ms
+  className="my-class"
+  renderText={(text) => <Markdown>{text}</Markdown>}
+/>
+```
+
+### TypeWriter
+
+Simulate typing effect for non-streaming text.
+
+```tsx
+<TypeWriter
+  text="Welcome to AI Matey!"
+  speed={30}                  // ms per character
+  delay={500}                 // ms before starting
+  showCursor={true}
+  cursor="▋"
+  onComplete={() => console.log('Done!')}
+/>
+```
+
+### Stream Utilities
+
+```tsx
+import {
+  createTextStream,
+  parseSSEStream,
+  fromAsyncIterable,
+} from 'ai.matey.react.stream';
+
+// Create text stream from fetch response
+const text = await createTextStream(response, {
+  onChunk: (chunk) => console.log(chunk),
+  onComplete: (fullText) => console.log('Done:', fullText),
+  signal: abortController.signal,
+});
+
+// Parse SSE events
+for await (const event of parseSSEStream(response)) {
+  console.log(event.data); // { type: 'data' | 'event', data: string }
+}
+```
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details.