@jsonstudio/llms 0.4.2

package/dist/conversion/conversion-v3/sse/shared/utils.js

@@ -0,0 +1,543 @@
+/**
+ * 共享工具函数
+ * 提供JSON↔SSE双向转换中常用的工具函数
+ */
+import { randomUUID } from 'crypto';
+import { Readable } from 'stream';
+/**
+ * 字符串工具
+ */
+export class StringUtils {
+    /**
+     * 安全地将值转换为字符串
+     */
+    static safeStringify(value) {
+        try {
+            return JSON.stringify(value ?? {});
+        }
+        catch {
+            return '{}';
+        }
+    }
+    /**
+     * 安全地解析JSON字符串
+     */
+    static safeParse(text) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * 检查字符串是否为空或只包含空白字符
+     */
+    static isEmpty(str) {
+        return !str || str.trim().length === 0;
+    }
+    /**
+     * 检查字符串是否为有效的JSON
+     */
+    static isValidJson(str) {
+        try {
+            JSON.parse(str);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * 截断字符串到指定长度
+     */
+    static truncate(str, maxLength, suffix = '...') {
+        if (str.length <= maxLength)
+            return str;
+        return str.slice(0, maxLength - suffix.length) + suffix;
+    }
+    /**
+     * 生成随机字符串
+     */
+    static random(length = 8) {
+        return randomUUID().replace(/-/g, '').slice(0, length);
+    }
+    /**
+     * 分割字符串为块
+     */
+    static chunkString(text, chunkSize, boundary) {
+        const chunks = [];
+        let buf = '';
+        const boundaryCharMatcher = /[\s,.!?;:]/;
+        const flush = () => {
+            if (buf.length) {
+                chunks.push(buf);
+                buf = '';
+            }
+        };
+        for (const ch of Array.from(text)) {
+            buf += ch;
+            const matchesBoundary = boundaryCharMatcher.test(ch) ||
+                (boundary.test(ch) && !/\\b/.test(boundary.source));
+            if (buf.length >= chunkSize || (matchesBoundary && buf.length >= Math.max(4, Math.floor(chunkSize / 2)))) {
+                flush();
+            }
+            boundary.lastIndex = 0;
+        }
+        flush();
+        return chunks;
+    }
+}
+/**
+ * 对象工具
+ */
+export class ObjectUtils {
+    /**
+     * 深度冻结对象
+     */
+    static deepFreeze(obj) {
+        Object.getOwnPropertyNames(obj).forEach(prop => {
+            const value = obj[prop];
+            if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+                ObjectUtils.deepFreeze(value);
+            }
+        });
+        return Object.freeze(obj);
+    }
+    /**
+     * 深度克隆对象
+     */
+    static deepClone(obj) {
+        if (obj === null || typeof obj !== 'object')
+            return obj;
+        if (obj instanceof Date)
+            return new Date(obj.getTime());
+        if (obj instanceof Array)
+            return obj.map(item => ObjectUtils.deepClone(item));
+        if (typeof obj === 'object') {
+            const cloned = {};
+            Object.keys(obj).forEach(key => {
+                cloned[key] = ObjectUtils.deepClone(obj[key]);
+            });
+            return cloned;
+        }
+        return obj;
+    }
+    /**
+     * 安全地获取嵌套对象属性
+     */
+    static get(obj, path, defaultValue = undefined) {
+        const keys = path.split('.');
+        let result = obj;
+        for (const key of keys) {
+            if (result == null || typeof result !== 'object') {
+                return defaultValue;
+            }
+            result = result[key];
+        }
+        return result !== undefined ? result : defaultValue;
+    }
+    /**
+     * 安全地设置嵌套对象属性
+     */
+    static set(obj, path, value) {
+        const keys = path.split('.');
+        let current = obj;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const key = keys[i];
+            if (current[key] == null || typeof current[key] !== 'object') {
+                current[key] = {};
+            }
+            current = current[key];
+        }
+        current[keys[keys.length - 1]] = value;
+    }
+    /**
+     * 检查对象是否为空
+     */
+    static isEmpty(obj) {
+        if (obj == null)
+            return true;
+        if (Array.isArray(obj))
+            return obj.length === 0;
+        if (typeof obj === 'object')
+            return Object.keys(obj).length === 0;
+        return false;
+    }
+    /**
+     * 合并对象
+     */
+    static merge(target, source) {
+        return { ...target, ...source };
+    }
+}
+/**
+ * 数组工具
+ */
+export class ArrayUtils {
+    /**
+     * 数组去重
+     */
+    static unique(arr) {
+        return [...new Set(arr)];
+    }
+    /**
+     * 分组数组
+     */
+    static groupBy(arr, keyFn) {
+        return arr.reduce((groups, item) => {
+            const key = keyFn(item);
+            groups[key] = groups[key] || [];
+            groups[key].push(item);
+            return groups;
+        }, {});
+    }
+    /**
+     * 分块数组
+     */
+    static chunk(arr, size) {
+        const chunks = [];
+        for (let i = 0; i < arr.length; i += size) {
+            chunks.push(arr.slice(i, i + size));
+        }
+        return chunks;
+    }
+    /**
+     * 扁平化数组
+     */
+    static flatten(arr) {
+        const result = [];
+        for (const item of arr) {
+            if (Array.isArray(item)) {
+                result.push(...ArrayUtils.flatten(item));
+            }
+            else {
+                result.push(item);
+            }
+        }
+        return result;
+    }
+    /**
+     * 找到数组中的差异
+     */
+    static diff(arr1, arr2) {
+        const set1 = new Set(arr1);
+        const set2 = new Set(arr2);
+        return {
+            added: arr2.filter(item => !set1.has(item)),
+            removed: arr1.filter(item => !set2.has(item)),
+            common: arr1.filter(item => set2.has(item))
+        };
+    }
+}
+/**
+ * 时间工具
+ */
+export class TimeUtils {
+    /**
+     * 获取当前时间戳（毫秒）
+     */
+    static now() {
+        return Date.now();
+    }
+    /**
+     * 获取当前时间戳（秒）
+     */
+    static nowSeconds() {
+        return Math.floor(Date.now() / 1000);
+    }
+    /**
+     * 格式化时间戳
+     */
+    static formatTimestamp(timestamp, format = 'ISO') {
+        const date = new Date(timestamp);
+        switch (format) {
+            case 'ISO':
+                return date.toISOString();
+            case 'locale':
+                return date.toLocaleString();
+            case 'time':
+                return date.toTimeString();
+            case 'date':
+                return date.toDateString();
+            default:
+                return date.toString();
+        }
+    }
+    /**
+     * 延迟指定时间
+     */
+    static delay(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * 带超时的Promise
+     */
+    static timeout(promise, timeoutMs) {
+        return Promise.race([
+            promise,
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`Timeout after ${timeoutMs}ms`)), timeoutMs))
+        ]);
+    }
+}
+/**
+ * 验证工具
+ */
+export class ValidationUtils {
+    /**
+     * 检查值是否为对象
+     */
+    static isObject(value) {
+        return !!value && typeof value === 'object' && !Array.isArray(value);
+    }
+    /**
+     * 检查值是否为有效的ID
+     */
+    static isValidId(value, pattern) {
+        return pattern.test(value);
+    }
+    /**
+     * 验证序列号
+     */
+    static isValidSequenceNumber(value, max = 10000) {
+        return Number.isInteger(value) && value >= 0 && value < max;
+    }
+    /**
+     * 验证时间戳
+     */
+    static isValidTimestamp(value) {
+        return Number.isInteger(value) && value > 0 && value <= Date.now() + 86400000; // 允许未来1天
+    }
+    /**
+     * 验证JSON结构
+     */
+    static validateJsonStructure(obj, schema) {
+        const errors = [];
+        const validate = (value, schemaNode, path = '') => {
+            if (schemaNode.required && (value == null || value === '')) {
+                errors.push(`${path}: Required field missing`);
+                return;
+            }
+            if (value == null)
+                return; // 可选字段且为空
+            if (schemaNode.type) {
+                const actualType = Array.isArray(value) ? 'array' : typeof value;
+                if (actualType !== schemaNode.type) {
+                    errors.push(`${path}: Expected ${schemaNode.type}, got ${actualType}`);
+                    return;
+                }
+            }
+            if (schemaNode.properties && typeof value === 'object') {
+                Object.entries(schemaNode.properties).forEach(([key, subSchema]) => {
+                    validate(value[key], subSchema, path ? `${path}.${key}` : key);
+                });
+            }
+        };
+        validate(obj, schema);
+        return {
+            valid: errors.length === 0,
+            errors
+        };
+    }
+}
+/**
+ * 流工具
+ */
+export class StreamUtils {
+    /**
+     * 创建可读流
+     */
+    static createReadable(data) {
+        let index = 0;
+        return new Readable({
+            objectMode: true,
+            read() {
+                if (index < data.length) {
+                    this.push(data[index++]);
+                }
+                else {
+                    this.push(null);
+                }
+            }
+        });
+    }
+    /**
+     * 将异步生成器转换为流
+     */
+    static asyncGeneratorToStream(generator) {
+        return new Readable({
+            objectMode: true,
+            async read() {
+                try {
+                    const { value, done } = await generator.next();
+                    if (done) {
+                        this.push(null);
+                    }
+                    else {
+                        this.push(value);
+                    }
+                }
+                catch (error) {
+                    this.destroy(error);
+                }
+            }
+        });
+    }
+    /**
+     * 将流转换为数组
+     */
+    static async streamToArray(stream) {
+        const chunks = [];
+        for await (const chunk of stream) {
+            chunks.push(chunk);
+        }
+        return chunks;
+    }
+    /**
+     * 管道流超时
+     */
+    static pipeWithTimeout(source, destination, timeoutMs) {
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                source.destroy();
+                const destroy = destination.destroy;
+                if (typeof destroy === 'function') {
+                    destroy.call(destination);
+                }
+                reject(new Error(`Pipe timeout after ${timeoutMs}ms`));
+            }, timeoutMs);
+            source.pipe(destination);
+            destination.on('finish', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            destination.on('error', (error) => {
+                clearTimeout(timeout);
+                reject(error);
+            });
+        });
+    }
+}
+/**
+ * ID生成工具
+ */
+export class IdUtils {
+    /**
+     * 生成请求ID
+     */
+    static generateRequestId() {
+        return `req_${Date.now()}`;
+    }
+    /**
+     * 生成响应ID
+     */
+    static generateResponseId() {
+        return `resp_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+    }
+    /**
+     * 生成推理项目ID
+     */
+    static generateReasoningId() {
+        return `rs_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+    }
+    /**
+     * 生成函数调用ID
+     */
+    static generateFunctionCallId() {
+        return `fc_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+    }
+    /**
+     * 生成工具调用ID
+     */
+    static generateToolCallId() {
+        return `call_${randomUUID().replace(/-/g, '').slice(0, 8)}`;
+    }
+    /**
+     * 生成消息ID
+     */
+    static generateMessageId() {
+        return `msg_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
+    }
+}
+/**
+ * 错误处理工具
+ */
+export class ErrorUtils {
+    /**
+     * 创建标准错误
+     */
+    static createError(message, code, context) {
+        const error = new Error(message);
+        error.code = code;
+        error.context = context;
+        return error;
+    }
+    /**
+     * 包装错误
+     */
+    static wrapError(error, context) {
+        if (error instanceof Error) {
+            if (context) {
+                error.message = `${context}: ${error.message}`;
+            }
+            return error;
+        }
+        return new Error(`${context || 'Unknown'}: ${String(error)}`);
+    }
+    /**
+     * 判断是否为超时错误
+     */
+    static isTimeoutError(error) {
+        return error.message.toLowerCase().includes('timeout') ||
+            error.name === 'TimeoutError' ||
+            error.code === 'TIMEOUT';
+    }
+    /**
+     * 判断是否为网络错误
+     */
+    static isNetworkError(error) {
+        return error.message.toLowerCase().includes('network') ||
+            error.message.toLowerCase().includes('connection') ||
+            error.code === 'ECONNRESET' ||
+            error.code === 'ENOTFOUND';
+    }
+}
+/**
+ * 正则表达式模式
+ */
+export const REGEX_PATTERNS = {
+    WORD_BOUNDARY: /\s|\b|[,.!?;:]/
+};
+/**
+ * 性能监控工具
+ */
+export class PerformanceUtils {
+    /**
+     * 创建性能计时器
+     */
+    static createTimer() {
+        const start = performance.now();
+        return () => performance.now() - start;
+    }
+    /**
+     * 测量函数执行时间
+     */
+    static async measureTime(fn) {
+        const timer = PerformanceUtils.createTimer();
+        const result = await fn();
+        const duration = timer();
+        return { result, duration };
+    }
+    /**
+     * 创建内存使用快照
+     */
+    static createMemorySnapshot() {
+        const usage = process.memoryUsage();
+        return {
+            rss: usage.rss,
+            heapUsed: usage.heapUsed,
+            heapTotal: usage.heapTotal,
+            external: usage.external
+        };
+    }
+}

package/dist/conversion/conversion-v3/sse/shared/writer.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 统一的SSE事件流写入器
+ * 处理backpressure、超时、心跳、错误处理等通用流管理逻辑
+ */
+import { PassThrough } from 'stream';
+import { BaseSseEvent } from '../types/core-interfaces.js';
+import { ChatSseEvent, ResponsesSseEvent } from '../types/index.js';
+export interface StreamWriterConfig {
+    timeoutMs?: number;
+    enableHeartbeat?: boolean;
+    heartbeatIntervalMs?: number;
+    maxBufferSize?: number;
+    enableBackpressure?: boolean;
+    onEvent?: (event: BaseSseEvent) => void;
+    onError?: (error: Error) => void;
+    onComplete?: () => void;
+}
+export interface StreamWriterStats {
+    totalEvents: number;
+    bytesWritten: number;
+    startTime: number;
+    lastWriteTime: number;
+    errors: number;
+}
+/**
+ * 统一的SSE流写入器
+ */
+export declare class StreamWriter {
+    private stream;
+    private config;
+    private stats;
+    private heartbeatInterval?;
+    private isActive;
+    private writeQueue;
+    private isWriting;
+    constructor(stream: PassThrough, config?: StreamWriterConfig);
+    /**
+     * 设置心跳
+     */
+    private setupHeartbeat;
+    /**
+     * 设置错误处理
+     */
+    private setupErrorHandling;
+    /**
+     * 发送心跳事件
+     */
+    private sendHeartbeat;
+    /**
+     * 写入单个事件
+     */
+    private writeEvent;
+    /**
+     * 处理背压
+     */
+    private handleBackpressure;
+    /**
+     * 序列化Responses事件（临时实现，需要 ResponsesSerializer）
+     * TODO: 等Responses协议修复后，实现完整的ResponsesSerializer
+     * 当前为临时实现，仅用于避免编译错误
+     */
+    private serializeResponsesEvent;
+    /**
+     * 异步写入事件流
+     */
+    writeEventStream(events: AsyncIterable<BaseSseEvent>): Promise<void>;
+    /**
+     * 同步写入事件数组
+     */
+    writeEvents(events: BaseSseEvent[]): Promise<void>;
+    /**
+     * 写入Chat事件流
+     */
+    writeChatEvents(events: AsyncIterable<ChatSseEvent> | ChatSseEvent[]): Promise<void>;
+    /**
+     * 写入Responses事件流
+     */
+    writeResponsesEvents(events: AsyncIterable<ResponsesSseEvent> | ResponsesSseEvent[]): Promise<void>;
+    /**
+     * 完成流写入
+     */
+    complete(): void;
+    /**
+     * 中止流写入
+     */
+    abort(error?: Error): void;
+    /**
+     * 获取写入统计
+     */
+    getStats(): StreamWriterStats;
+    /**
+     * 检查流是否活跃
+     */
+    isStreamActive(): boolean;
+    /**
+     * 清理资源
+     */
+    private cleanup;
+    /**
+     * 获取底层流
+     */
+    getUnderlyingStream(): PassThrough;
+}
+/**
+ * 创建Chat流写入器工厂函数
+ */
+export declare function createChatStreamWriter(stream: PassThrough, config?: StreamWriterConfig): StreamWriter;
+/**
+ * 创建Responses流写入器工厂函数
+ */
+export declare function createResponsesStreamWriter(stream: PassThrough, config?: StreamWriterConfig): StreamWriter;