ai.matey.utils 0.2.0

package/dist/types/system-message.d.ts

@@ -0,0 +1,78 @@
+/**
+ * System Message Normalization Utilities
+ *
+ * Handles different provider strategies for system messages:
+ * - separate-parameter: System as separate parameter (Anthropic)
+ * - in-messages: System messages in message array (OpenAI, Gemini)
+ * - prepend-user: Prepend system to first user message (some providers)
+ * - not-supported: Strip system messages (rare)
+ *
+ * @module
+ */
+import type { IRMessage, SystemMessageStrategy } from 'ai.matey.types';
+/**
+ * Extract system messages from message array.
+ *
+ * Returns both the system messages and the remaining non-system messages.
+ *
+ * @param messages Message array
+ * @returns Object with system messages and remaining messages
+ */
+export declare function extractSystemMessages(messages: readonly IRMessage[]): {
+    systemMessages: IRMessage[];
+    otherMessages: IRMessage[];
+};
+/**
+ * Combine multiple system messages into a single string.
+ *
+ * @param systemMessages Array of system messages
+ * @param separator Separator between messages (default: double newline)
+ * @returns Combined system message content
+ */
+export declare function combineSystemMessages(systemMessages: readonly IRMessage[], separator?: string): string;
+/**
+ * Get first system message as string (for providers that only support one).
+ *
+ * @param messages Message array
+ * @returns First system message content or undefined
+ */
+export declare function getFirstSystemMessage(messages: readonly IRMessage[]): string | undefined;
+/**
+ * Normalize system messages according to provider strategy.
+ *
+ * @param messages Original message array
+ * @param strategy System message strategy
+ * @param supportsMultiple Whether provider supports multiple system messages
+ * @returns Normalized messages and optional system parameter
+ */
+export declare function normalizeSystemMessages(messages: readonly IRMessage[], strategy: SystemMessageStrategy, supportsMultiple?: boolean): {
+    messages: IRMessage[];
+    systemParameter?: string;
+};
+/**
+ * Add system message to message array.
+ *
+ * Handles prepending or replacing existing system messages based on strategy.
+ *
+ * @param messages Existing message array
+ * @param systemContent System message content to add
+ * @param strategy System message strategy
+ * @param supportsMultiple Whether provider supports multiple system messages
+ * @returns New message array with system message added
+ */
+export declare function addSystemMessage(messages: readonly IRMessage[], systemContent: string, strategy?: SystemMessageStrategy, supportsMultiple?: boolean): IRMessage[];
+/**
+ * Check if messages contain any system messages.
+ *
+ * @param messages Message array
+ * @returns true if any message has role 'system'
+ */
+export declare function hasSystemMessages(messages: readonly IRMessage[]): boolean;
+/**
+ * Count system messages in array.
+ *
+ * @param messages Message array
+ * @returns Number of system messages
+ */
+export declare function countSystemMessages(messages: readonly IRMessage[]): number;
+//# sourceMappingURL=system-message.d.ts.map

package/dist/types/system-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-message.d.ts","sourceRoot":"","sources":["../../src/system-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAMvE;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,GAAG;IACrE,cAAc,EAAE,SAAS,EAAE,CAAC;IAC5B,aAAa,EAAE,SAAS,EAAE,CAAC;CAC5B,CAaA;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,SAAS,SAAS,EAAE,EACpC,SAAS,SAAS,GACjB,MAAM,CAcR;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,GAAG,SAAS,CAiBxF;AAMD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,SAAS,EAAE,EAC9B,QAAQ,EAAE,qBAAqB,EAC/B,gBAAgB,GAAE,OAAe,GAChC;IACD,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CA8EA;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,SAAS,EAAE,EAC9B,aAAa,EAAE,MAAM,EACrB,QAAQ,GAAE,qBAAqC,EAC/C,gBAAgB,GAAE,OAAe,GAChC,SAAS,EAAE,CA8Bb;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAE1E"}

package/dist/types/validation.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Validation Utilities
+ *
+ * Core validation functions for IR requests, messages, and parameters.
+ *
+ * @module
+ */
+import type { IRChatRequest, IRMessage, IRParameters, MessageRole } from 'ai.matey.types';
+import type { ErrorProvenance } from 'ai.matey.types';
+/**
+ * Validate message role.
+ */
+export declare function isValidMessageRole(role: string): role is MessageRole;
+/**
+ * Validate message content.
+ */
+export declare function validateMessageContent(content: unknown, provenance?: ErrorProvenance): void;
+/**
+ * Validate a single message.
+ */
+export declare function validateMessage(message: unknown, provenance?: ErrorProvenance): asserts message is IRMessage;
+/**
+ * Validate messages array.
+ */
+export declare function validateMessages(messages: unknown, provenance?: ErrorProvenance): asserts messages is IRMessage[];
+/**
+ * Validate temperature parameter.
+ */
+export declare function validateTemperature(temperature: unknown, provenance?: ErrorProvenance): void;
+/**
+ * Validate maxTokens parameter.
+ */
+export declare function validateMaxTokens(maxTokens: unknown, provenance?: ErrorProvenance): void;
+/**
+ * Validate topP parameter.
+ */
+export declare function validateTopP(topP: unknown, provenance?: ErrorProvenance): void;
+/**
+ * Validate parameters object.
+ */
+export declare function validateParameters(parameters: unknown, provenance?: ErrorProvenance): asserts parameters is IRParameters;
+/**
+ * Validate IR chat request.
+ */
+export declare function validateIRChatRequest(request: unknown, provenance?: ErrorProvenance): asserts request is IRChatRequest;
+//# sourceMappingURL=validation.d.ts.map

package/dist/types/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/validation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACT,YAAY,EAEZ,WAAW,EACZ,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAMtD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,IAAI,WAAW,CAEpE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI,CAuF3F;AAED;;GAEG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,OAAO,IAAI,SAAS,CAsE9B;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,OAAO,EACjB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,QAAQ,IAAI,SAAS,EAAE,CAqDjC;AAMD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI,CAoC5F;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI,CAoCxF;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI,CAoC9E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,OAAO,EACnB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,UAAU,IAAI,YAAY,CA2FpC;AAMD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,OAAO,IAAI,aAAa,CA2FlC"}

package/dist/types/warnings.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Warning Utilities
+ *
+ * Helpers for creating, formatting, and managing semantic drift warnings.
+ *
+ * @module
+ */
+import type { IRWarning, WarningSeverity, WarningCategory } from 'ai.matey.types';
+/**
+ * Create a warning object.
+ *
+ * @param category Warning category
+ * @param message Human-readable message
+ * @param options Additional warning options
+ * @returns Warning object
+ */
+export declare function createWarning(category: WarningCategory, message: string, options?: {
+    severity?: WarningSeverity;
+    field?: string;
+    originalValue?: unknown;
+    transformedValue?: unknown;
+    source?: string;
+    details?: Record<string, unknown>;
+}): IRWarning;
+/**
+ * Create a parameter normalization warning.
+ *
+ * @param field Parameter field name
+ * @param originalValue Original value
+ * @param transformedValue Transformed value
+ * @param message Optional custom message
+ * @param source Source adapter
+ * @returns Warning object
+ */
+export declare function createNormalizationWarning(field: string, originalValue: unknown, transformedValue: unknown, message?: string, source?: string): IRWarning;
+/**
+ * Create a parameter clamping warning.
+ *
+ * @param field Parameter field name
+ * @param originalValue Original value
+ * @param clampedValue Clamped value
+ * @param min Minimum allowed value
+ * @param max Maximum allowed value
+ * @param source Source adapter
+ * @returns Warning object
+ */
+export declare function createClampingWarning(field: string, originalValue: unknown, clampedValue: unknown, min: number, max: number, source?: string): IRWarning;
+/**
+ * Create an unsupported parameter warning.
+ *
+ * @param field Parameter field name
+ * @param value Parameter value
+ * @param source Source adapter
+ * @returns Warning object
+ */
+export declare function createUnsupportedParameterWarning(field: string, value: unknown, source?: string): IRWarning;
+/**
+ * Create a capability unsupported warning.
+ *
+ * @param capability Capability name
+ * @param source Source adapter
+ * @returns Warning object
+ */
+export declare function createUnsupportedCapabilityWarning(capability: string, source?: string): IRWarning;
+/**
+ * Create a token limit exceeded warning.
+ *
+ * @param estimatedTokens Estimated token count
+ * @param maxTokens Maximum tokens allowed
+ * @param source Source adapter
+ * @returns Warning object
+ */
+export declare function createTokenLimitWarning(estimatedTokens: number, maxTokens: number, source?: string): IRWarning;
+/**
+ * Create a stop sequences truncated warning.
+ *
+ * @param originalCount Original number of stop sequences
+ * @param maxCount Maximum allowed
+ * @param source Source adapter
+ * @returns Warning object
+ */
+export declare function createStopSequencesTruncatedWarning(originalCount: number, maxCount: number, source?: string): IRWarning;
+/**
+ * Merge warning arrays, removing duplicates.
+ *
+ * @param warningArrays Arrays of warnings to merge
+ * @returns Merged and deduplicated warnings
+ */
+export declare function mergeWarnings(...warningArrays: Array<readonly IRWarning[] | undefined>): IRWarning[];
+/**
+ * Filter warnings by severity.
+ *
+ * @param warnings Warnings to filter
+ * @param minSeverity Minimum severity level
+ * @returns Filtered warnings
+ */
+export declare function filterWarningsBySeverity(warnings: readonly IRWarning[], minSeverity: WarningSeverity): IRWarning[];
+/**
+ * Filter warnings by category.
+ *
+ * @param warnings Warnings to filter
+ * @param categories Categories to include
+ * @returns Filtered warnings
+ */
+export declare function filterWarningsByCategory(warnings: readonly IRWarning[], categories: readonly WarningCategory[]): IRWarning[];
+/**
+ * Group warnings by category.
+ *
+ * @param warnings Warnings to group
+ * @returns Map of category to warnings
+ */
+export declare function groupWarningsByCategory(warnings: readonly IRWarning[]): Map<WarningCategory, IRWarning[]>;
+/**
+ * Check if warnings array contains a specific warning type.
+ *
+ * @param warnings Warnings to check
+ * @param category Warning category to look for
+ * @param field Optional field name to match
+ * @returns true if warning exists
+ */
+export declare function hasWarning(warnings: readonly IRWarning[] | undefined, category: WarningCategory, field?: string): boolean;
+/**
+ * Format a single warning as a string.
+ *
+ * @param warning Warning to format
+ * @param includeDetails Include full details
+ * @returns Formatted warning string
+ */
+export declare function formatWarning(warning: IRWarning, includeDetails?: boolean): string;
+/**
+ * Format multiple warnings as a string.
+ *
+ * @param warnings Warnings to format
+ * @param includeDetails Include full details
+ * @returns Formatted warnings string
+ */
+export declare function formatWarnings(warnings: readonly IRWarning[], includeDetails?: boolean): string;
+/**
+ * Get a summary of warnings by category.
+ *
+ * @param warnings Warnings to summarize
+ * @returns Summary object with counts
+ */
+export declare function getWarningSummary(warnings: readonly IRWarning[]): {
+    total: number;
+    byCategory: Record<WarningCategory, number>;
+    bySeverity: Record<WarningSeverity, number>;
+};
+//# sourceMappingURL=warnings.d.ts.map

package/dist/types/warnings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.d.ts","sourceRoot":"","sources":["../../src/warnings.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "ai.matey.utils",
+  "version": "0.2.0",
+  "description": "Utility functions for AI Matey - Universal AI Adapter System",
+  "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",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "ai.matey.errors": "*",
+    "ai.matey.types": "*"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "utilities",
+    "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/ai.matey.utils"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,280 @@
+# ai.matey.utils
+
+Shared utility functions for streaming, validation, and conversions.
+
+Part of the [ai.matey](https://github.com/johnhenry/ai.matey) monorepo.
+
+## Installation
+
+```bash
+npm install ai.matey.utils
+```
+
+## Stream Utilities
+
+Comprehensive utilities for working with IR chat streams.
+
+### Basic Stream Operations
+
+```typescript
+import {
+  collectStream,        // Collect chunks into array
+  collectStreamFull,    // Collect with rich metadata
+  streamToText,         // Get accumulated text
+  streamToResponse,     // Convert to IR response
+} from 'ai.matey.utils';
+
+// Collect all chunks
+const chunks = await collectStream(stream);
+
+// Collect with full metadata
+const result = await collectStreamFull(stream);
+console.log(result.content);      // Full text
+console.log(result.message);      // IR message
+console.log(result.finishReason); // 'stop', 'length', etc.
+console.log(result.usage);        // Token counts
+
+// Get just the text
+const text = await streamToText(stream);
+```
+
+### Processing Streams
+
+```typescript
+import { processStream, streamToLines, streamToTextIterator } from 'ai.matey.utils';
+
+// Process with callbacks
+const result = await processStream(stream, {
+  onStart: (requestId) => console.log('Started:', requestId),
+  onContent: (delta, accumulated) => process.stdout.write(delta),
+  onDone: (result) => console.log('\nTokens:', result.usage?.totalTokens),
+  onError: (error) => console.error('Error:', error),
+});
+
+// Iterate over text chunks
+for await (const text of streamToTextIterator(stream)) {
+  process.stdout.write(text);
+}
+
+// Buffer and yield complete lines
+for await (const line of streamToLines(stream)) {
+  console.log('Line:', line);
+}
+```
+
+### Transforming Streams
+
+```typescript
+import {
+  transformStream,
+  filterStream,
+  mapStream,
+  tapStream,
+} from 'ai.matey.utils';
+
+// Transform chunks
+const transformed = transformStream(stream, (chunk) => ({
+  ...chunk,
+  delta: chunk.type === 'content' ? chunk.delta.toUpperCase() : chunk.delta,
+}));
+
+// Filter chunks
+const contentOnly = filterStream(stream, (chunk) => chunk.type === 'content');
+
+// Map chunks
+const textOnly = mapStream(stream, (chunk) =>
+  chunk.type === 'content' ? chunk.delta : ''
+);
+
+// Tap for side effects (logging, etc.)
+const logged = tapStream(stream, (chunk) => console.log('Chunk:', chunk.type));
+```
+
+### Stream Control
+
+```typescript
+import {
+  throttleStream,
+  rateLimitStream,
+  teeStream,
+  splitStream,
+} from 'ai.matey.utils';
+
+// Throttle updates (batches content chunks)
+// Great for limiting UI update frequency
+for await (const chunk of throttleStream(stream, 50)) {
+  updateUI(chunk); // Max every 50ms
+}
+
+// Rate limit (delays chunks to max N/second)
+const limited = rateLimitStream(stream, 10); // Max 10 chunks/second
+
+// Split stream for parallel processing
+const [stream1, stream2] = teeStream(stream, 2);
+
+await Promise.all([
+  processStream(stream1, { onContent: (d) => logger.log(d) }),
+  processStream(stream2, { onContent: (d) => ui.append(d) }),
+]);
+```
+
+### Stream Validation
+
+```typescript
+import { validateStream, validateChunkSequence } from 'ai.matey.utils';
+
+// Validate stream structure
+const validated = validateStream(stream, {
+  requireStart: true,
+  requireDone: true,
+  requireContent: true,
+});
+
+// Check if chunk sequence is valid
+const chunks = await collectStream(stream);
+const isValid = validateChunkSequence(chunks);
+```
+
+### Error Handling
+
+```typescript
+import { catchStreamErrors, streamWithTimeout, createStreamError } from 'ai.matey.utils';
+
+// Catch and handle errors
+const safe = catchStreamErrors(stream, (error) => {
+  console.error('Stream error:', error);
+});
+
+// Add timeout
+const withTimeout = streamWithTimeout(stream, 30000); // 30s timeout
+
+// Create error chunks
+const errorChunk = createStreamError(new Error('Something went wrong'));
+```
+
+## Stream Accumulator
+
+Build responses incrementally from chunks:
+
+```typescript
+import {
+  createStreamAccumulator,
+  accumulateChunk,
+  accumulatorToMessage,
+  accumulatorToResponse,
+} from 'ai.matey.utils';
+
+const accumulator = createStreamAccumulator();
+
+for await (const chunk of stream) {
+  accumulateChunk(accumulator, chunk);
+  console.log('Current text:', accumulator.content);
+}
+
+const message = accumulatorToMessage(accumulator);
+const response = accumulatorToResponse(accumulator);
+```
+
+## Content Utilities
+
+```typescript
+import { getContentDeltas, isContentChunk, isDoneChunk, isErrorChunk } from 'ai.matey.utils';
+
+// Get just the text deltas
+for await (const delta of getContentDeltas(stream)) {
+  process.stdout.write(delta);
+}
+
+// Type guards
+for await (const chunk of stream) {
+  if (isContentChunk(chunk)) {
+    console.log('Content:', chunk.delta);
+  } else if (isDoneChunk(chunk)) {
+    console.log('Done:', chunk.finishReason);
+  } else if (isErrorChunk(chunk)) {
+    console.error('Error:', chunk.error);
+  }
+}
+```
+
+## Web Stream Conversion
+
+```typescript
+import {
+  asyncGeneratorToReadableStream,
+  readableStreamToAsyncGenerator,
+} from 'ai.matey.utils';
+
+// Convert async generator to Web ReadableStream
+const readable = asyncGeneratorToReadableStream(stream);
+
+// Convert back to async generator
+const generator = readableStreamToAsyncGenerator(readable);
+```
+
+## Types
+
+```typescript
+import type {
+  CollectedStream,      // Rich result from collectStreamFull
+  ProcessStreamOptions, // Options for processStream
+  StreamValidationOptions,
+} from 'ai.matey.utils';
+```
+
+## API Reference
+
+### Collection Functions
+
+| Function | Description |
+|----------|-------------|
+| `collectStream(stream)` | Collect chunks into array |
+| `collectStreamFull(stream)` | Collect with rich metadata |
+| `streamToText(stream)` | Get accumulated text |
+| `streamToResponse(stream)` | Convert to IR response |
+
+### Processing Functions
+
+| Function | Description |
+|----------|-------------|
+| `processStream(stream, options)` | Process with callbacks |
+| `streamToLines(stream)` | Yield complete lines |
+| `streamToTextIterator(stream)` | Yield text deltas |
+| `getContentDeltas(stream)` | Yield only content |
+
+### Transform Functions
+
+| Function | Description |
+|----------|-------------|
+| `transformStream(stream, fn)` | Transform each chunk |
+| `filterStream(stream, predicate)` | Filter chunks |
+| `mapStream(stream, fn)` | Map chunks to new values |
+| `tapStream(stream, fn)` | Side effects without modification |
+
+### Control Functions
+
+| Function | Description |
+|----------|-------------|
+| `throttleStream(stream, ms)` | Batch chunks by time interval |
+| `rateLimitStream(stream, rate)` | Limit chunks per second |
+| `teeStream(stream, count)` | Split into multiple streams |
+| `splitStream(stream, count)` | Split into multiple streams |
+
+### Validation Functions
+
+| Function | Description |
+|----------|-------------|
+| `validateStream(stream, options)` | Validate stream structure |
+| `validateChunkSequence(chunks)` | Check sequence validity |
+
+### Error Functions
+
+| Function | Description |
+|----------|-------------|
+| `catchStreamErrors(stream, handler)` | Handle errors gracefully |
+| `streamWithTimeout(stream, ms)` | Add timeout |
+| `createStreamError(error)` | Create error chunk |
+
+## License
+
+MIT - see [LICENSE](./LICENSE) for details.