ai.matey.utils 0.2.0

package/dist/esm/streaming-modes.js

@@ -0,0 +1,265 @@
+/**
+ * Streaming Mode Conversion Utilities
+ *
+ * This module handles conversion between delta and accumulated streaming modes.
+ * Use these utilities when you need to transform IR stream chunks between formats.
+ *
+ * For general stream operations (map, filter, collect), see ./streaming.ts
+ *
+ * @example Converting stream modes
+ * ```typescript
+ * import { convertStreamMode, createAccumulatorState } from 'ai.matey.utils';
+ *
+ * const converter = createAccumulatorState();
+ * const accumulated = await convertStreamMode(deltaStream, 'accumulated', { converter });
+ * ```
+ *
+ * @module streaming-modes
+ */
+import { DEFAULT_CONVERSION_OPTIONS, DEFAULT_STREAMING_CONFIG } from 'ai.matey.types';
+/**
+ * Create a new stream accumulator state.
+ */
+export function createAccumulatorState() {
+    return {
+        accumulated: '',
+        chunkCount: 0,
+        lastSequence: -1,
+    };
+}
+// ============================================================================
+// Mode Detection
+// ============================================================================
+/**
+ * Detect the streaming mode of a content chunk.
+ *
+ * @param chunk Content chunk to inspect
+ * @returns Detected streaming mode
+ */
+export function detectChunkMode(chunk) {
+    // If both delta and accumulated are present, it's providing both
+    if (chunk.delta && chunk.accumulated) {
+        return 'accumulated'; // Preferred mode when both available
+    }
+    // If only accumulated, it's accumulated mode
+    if (chunk.accumulated) {
+        return 'accumulated';
+    }
+    // Default: delta mode
+    return 'delta';
+}
+/**
+ * Check if a chunk needs conversion to target mode.
+ *
+ * @param chunk Content chunk to check
+ * @param targetMode Desired streaming mode
+ * @param preserveIfMatch Whether to skip conversion if already in target mode
+ * @returns true if conversion is needed
+ */
+export function needsConversion(chunk, targetMode, preserveIfMatch = true) {
+    if (!preserveIfMatch) {
+        return true;
+    }
+    const currentMode = detectChunkMode(chunk);
+    // No conversion needed if already in target mode
+    if (currentMode === targetMode) {
+        return false;
+    }
+    // If target is delta and chunk has delta, no conversion needed
+    if (targetMode === 'delta' && chunk.delta) {
+        return false;
+    }
+    // If target is accumulated and chunk has accumulated, no conversion needed
+    if (targetMode === 'accumulated' && chunk.accumulated) {
+        return false;
+    }
+    return true;
+}
+// ============================================================================
+// Stream Conversion
+// ============================================================================
+/**
+ * Convert IR stream to target streaming mode.
+ *
+ * This function transforms an IR stream to use the specified streaming mode:
+ * - Delta mode: Only incremental deltas
+ * - Accumulated mode: Full text in each chunk
+ *
+ * @param stream Source IR stream
+ * @param options Conversion options
+ * @returns Converted IR stream
+ *
+ * @example
+ * ```typescript
+ * // Convert to accumulated mode
+ * const accumulated = convertStreamMode(deltaStream, { mode: 'accumulated' });
+ *
+ * // Convert to delta mode
+ * const delta = convertStreamMode(accumulatedStream, { mode: 'delta' });
+ * ```
+ */
+export async function* convertStreamMode(stream, options = {}) {
+    const { mode = DEFAULT_CONVERSION_OPTIONS.mode, preserveIfMatch = DEFAULT_CONVERSION_OPTIONS.preserveIfMatch, transform, validateSequence = DEFAULT_CONVERSION_OPTIONS.validateSequence, } = options;
+    const state = createAccumulatorState();
+    for await (const chunk of stream) {
+        // Only convert content chunks
+        if (chunk.type !== 'content') {
+            yield chunk;
+            continue;
+        }
+        // Validate sequence if requested
+        if (validateSequence && chunk.sequence !== undefined) {
+            if (chunk.sequence <= state.lastSequence) {
+                throw new Error(`Out of order chunk: expected sequence > ${state.lastSequence}, got ${chunk.sequence}`);
+            }
+            state.lastSequence = chunk.sequence;
+        }
+        // Check if conversion is needed
+        if (!needsConversion(chunk, mode, preserveIfMatch)) {
+            yield chunk;
+            continue;
+        }
+        // Convert chunk to target mode
+        const converted = convertChunkMode(chunk, mode, state, transform);
+        yield converted;
+        state.chunkCount++;
+    }
+}
+/**
+ * Convert a single content chunk to target mode.
+ *
+ * @param chunk Source content chunk
+ * @param targetMode Target streaming mode
+ * @param state Accumulator state (updated in place)
+ * @param transform Optional transform function
+ * @returns Converted content chunk
+ */
+export function convertChunkMode(chunk, targetMode, state, transform) {
+    // Update accumulated state
+    state.accumulated += chunk.delta;
+    if (targetMode === 'delta') {
+        // Delta mode: ensure only delta is present
+        return {
+            type: 'content',
+            sequence: chunk.sequence,
+            delta: chunk.delta,
+            role: chunk.role,
+        };
+    }
+    else {
+        // Accumulated mode: provide accumulated text
+        const accumulated = transform ? transform(state.accumulated) : state.accumulated;
+        return {
+            type: 'content',
+            sequence: chunk.sequence,
+            delta: chunk.delta, // Still provide delta for compatibility
+            accumulated,
+            role: chunk.role,
+        };
+    }
+}
+// ============================================================================
+// Configuration Helpers
+// ============================================================================
+/**
+ * Get effective streaming mode from cascading configuration.
+ *
+ * Priority order (highest to lowest):
+ * 1. Request-level streamMode
+ * 2. Conversion options mode
+ * 3. Streaming config mode
+ * 4. Default ('delta')
+ *
+ * @param requestMode Stream mode from request
+ * @param conversionMode Stream mode from conversion options
+ * @param config Streaming configuration
+ * @returns Effective streaming mode
+ */
+export function getEffectiveStreamMode(requestMode, conversionMode, config) {
+    return requestMode || conversionMode || config?.mode || DEFAULT_STREAMING_CONFIG.mode;
+}
+/**
+ * Merge streaming configurations with priority.
+ *
+ * @param configs Configuration objects in priority order (first wins)
+ * @returns Merged configuration
+ */
+export function mergeStreamingConfig(...configs) {
+    const result = { ...DEFAULT_STREAMING_CONFIG };
+    // Apply configs in reverse order (last has lowest priority)
+    for (let i = configs.length - 1; i >= 0; i--) {
+        const config = configs[i];
+        if (!config) {
+            continue;
+        }
+        if (config.mode !== undefined) {
+            result.mode = config.mode;
+        }
+        if (config.includeBoth !== undefined) {
+            result.includeBoth = config.includeBoth;
+        }
+        if (config.bufferStrategy !== undefined) {
+            result.bufferStrategy = config.bufferStrategy;
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Stream Utilities
+// ============================================================================
+/**
+ * Ensure all chunks in a stream have a specific mode.
+ *
+ * If chunks don't have the required format, converts them.
+ *
+ * @param stream Source stream
+ * @param mode Required mode
+ * @returns Stream with all chunks in required mode
+ */
+export async function* ensureStreamMode(stream, mode) {
+    yield* convertStreamMode(stream, { mode, preserveIfMatch: true });
+}
+/**
+ * Add accumulated field to all content chunks (dual-mode streaming).
+ *
+ * Useful for backends that want to provide both delta and accumulated.
+ *
+ * @param stream Source stream (delta-only)
+ * @returns Stream with both delta and accumulated in content chunks
+ */
+export async function* addAccumulatedToStream(stream) {
+    const state = createAccumulatorState();
+    for await (const chunk of stream) {
+        if (chunk.type === 'content') {
+            state.accumulated += chunk.delta;
+            yield {
+                ...chunk,
+                accumulated: state.accumulated,
+            };
+            state.chunkCount++;
+        }
+        else {
+            yield chunk;
+        }
+    }
+}
+/**
+ * Strip accumulated field from all content chunks (delta-only streaming).
+ *
+ * Useful for reducing bandwidth when accumulated isn't needed.
+ *
+ * @param stream Source stream
+ * @returns Stream with only delta in content chunks
+ */
+export async function* stripAccumulatedFromStream(stream) {
+    for await (const chunk of stream) {
+        if (chunk.type === 'content') {
+            const { accumulated: _accumulated, ...deltaOnly } = chunk;
+            yield deltaOnly;
+        }
+        else {
+            yield chunk;
+        }
+    }
+}
+//# sourceMappingURL=streaming-modes.js.map

package/dist/esm/streaming-modes.js.map

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