task-o-matic 0.0.13 → 0.0.14

package/dist/utils/file-utils.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Validates that a file exists at the given path (synchronous).
+ * Throws an error with a custom message if the file doesn't exist.
+ *
+ * @param filePath - Path to the file to validate
+ * @param customMessage - Optional custom error message
+ * @throws Error if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * validateFileExists("./config.json", "Configuration file not found");
+ * // Throws: Error("Configuration file not found") if file doesn't exist
+ * ```
+ */
+export declare function validateFileExists(filePath: string, customMessage?: string): void;
+/**
+ * Validates that a file exists at the given path (asynchronous).
+ * Throws an error with a custom message if the file doesn't exist.
+ *
+ * @param filePath - Path to the file to validate
+ * @param customMessage - Optional custom error message
+ * @throws Error if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * await validateFileExistsAsync("./data.json");
+ * // Throws: Error("File not found: ./data.json") if file doesn't exist
+ * ```
+ */
+export declare function validateFileExistsAsync(filePath: string, customMessage?: string): Promise<void>;
+/**
+ * Checks if a file exists at the given path (synchronous).
+ * Returns true if file exists, false otherwise.
+ * Unlike validateFileExists, this doesn't throw an error.
+ *
+ * @param filePath - Path to check
+ * @returns true if file exists, false otherwise
+ */
+export declare function fileExists(filePath: string): boolean;
+/**
+ * Checks if a file exists at the given path (asynchronous).
+ * Returns true if file exists, false otherwise.
+ * Unlike validateFileExistsAsync, this doesn't throw an error.
+ *
+ * @param filePath - Path to check
+ * @returns Promise resolving to true if file exists, false otherwise
+ */
+export declare function fileExistsAsync(filePath: string): Promise<boolean>;
+//# sourceMappingURL=file-utils.d.ts.map

package/dist/utils/file-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-utils.d.ts","sourceRoot":"","sources":["../../src/utils/file-utils.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,IAAI,CAIN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE"}

package/dist/utils/file-utils.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateFileExists = validateFileExists;
+exports.validateFileExistsAsync = validateFileExistsAsync;
+exports.fileExists = fileExists;
+exports.fileExistsAsync = fileExistsAsync;
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+/**
+ * Validates that a file exists at the given path (synchronous).
+ * Throws an error with a custom message if the file doesn't exist.
+ *
+ * @param filePath - Path to the file to validate
+ * @param customMessage - Optional custom error message
+ * @throws Error if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * validateFileExists("./config.json", "Configuration file not found");
+ * // Throws: Error("Configuration file not found") if file doesn't exist
+ * ```
+ */
+function validateFileExists(filePath, customMessage) {
+    if (!(0, fs_1.existsSync)(filePath)) {
+        throw new Error(customMessage || `File not found: ${filePath}`);
+    }
+}
+/**
+ * Validates that a file exists at the given path (asynchronous).
+ * Throws an error with a custom message if the file doesn't exist.
+ *
+ * @param filePath - Path to the file to validate
+ * @param customMessage - Optional custom error message
+ * @throws Error if file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * await validateFileExistsAsync("./data.json");
+ * // Throws: Error("File not found: ./data.json") if file doesn't exist
+ * ```
+ */
+async function validateFileExistsAsync(filePath, customMessage) {
+    try {
+        await (0, promises_1.access)(filePath, promises_1.constants.F_OK);
+    }
+    catch {
+        throw new Error(customMessage || `File not found: ${filePath}`);
+    }
+}
+/**
+ * Checks if a file exists at the given path (synchronous).
+ * Returns true if file exists, false otherwise.
+ * Unlike validateFileExists, this doesn't throw an error.
+ *
+ * @param filePath - Path to check
+ * @returns true if file exists, false otherwise
+ */
+function fileExists(filePath) {
+    return (0, fs_1.existsSync)(filePath);
+}
+/**
+ * Checks if a file exists at the given path (asynchronous).
+ * Returns true if file exists, false otherwise.
+ * Unlike validateFileExistsAsync, this doesn't throw an error.
+ *
+ * @param filePath - Path to check
+ * @returns Promise resolving to true if file exists, false otherwise
+ */
+async function fileExistsAsync(filePath) {
+    try {
+        await (0, promises_1.access)(filePath, promises_1.constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/utils/id-generator.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Generates unique task IDs with consistent format.
+ * Uses timestamp + random hex for uniqueness.
+ */
+export declare class TaskIDGenerator {
+    /**
+     * Generates a unique task ID with format: prefix-timestamp-random
+     *
+     * @param prefix - Prefix for the ID (default: "task")
+     * @returns Unique task ID
+     *
+     * @example
+     * ```typescript
+     * const id = TaskIDGenerator.generate();
+     * // Returns: "task-1733750400000-a1b2c3d4"
+     *
+     * const customId = TaskIDGenerator.generate("subtask");
+     * // Returns: "subtask-1733750400000-e5f6g7h8"
+     * ```
+     */
+    static generate(prefix?: string): string;
+    /**
+     * Validates a task ID format.
+     * Accepts three formats:
+     * - Timestamped: "task-1234567890-abcd1234"
+     * - Hierarchical: "1.2.3"
+     * - Numeric: "123"
+     *
+     * @param id - Task ID to validate
+     * @returns true if ID format is valid
+     *
+     * @example
+     * ```typescript
+     * TaskIDGenerator.validate("task-1234-abcd"); // true
+     * TaskIDGenerator.validate("1.2.3"); // true
+     * TaskIDGenerator.validate("123"); // true
+     * TaskIDGenerator.validate("invalid!"); // false
+     * ```
+     */
+    static validate(id: string): boolean;
+    /**
+     * Checks if an ID is unique within a set of existing IDs.
+     *
+     * @param id - ID to check
+     * @param existingIds - Set of existing IDs
+     * @returns true if ID is unique
+     */
+    static isUnique(id: string, existingIds: Set<string>): boolean;
+    /**
+     * Generates a unique ID that doesn't exist in the provided set.
+     * Retries up to maxAttempts times if collisions occur.
+     *
+     * @param existingIds - Set of existing IDs to avoid
+     * @param prefix - Prefix for the ID
+     * @param maxAttempts - Maximum number of generation attempts
+     * @returns Unique task ID
+     * @throws Error if unable to generate unique ID after maxAttempts
+     */
+    static generateUnique(existingIds: Set<string>, prefix?: string, maxAttempts?: number): string;
+    /**
+     * Generates a hierarchical child ID from a parent ID.
+     * If parent is "1.2", generates "1.2.1", "1.2.2", etc.
+     *
+     * @param parentId - Parent task ID
+     * @param childIndex - Index of the child (1-based)
+     * @returns Child task ID
+     *
+     * @example
+     * ```typescript
+     * TaskIDGenerator.generateChildId("1", 1); // "1.1"
+     * TaskIDGenerator.generateChildId("1.2", 3); // "1.2.3"
+     * ```
+     */
+    static generateChildId(parentId: string, childIndex: number): string;
+    /**
+     * Parses a hierarchical ID to extract parent ID and child index.
+     *
+     * @param id - Hierarchical task ID
+     * @returns Object with parentId and childIndex, or null if not hierarchical
+     *
+     * @example
+     * ```typescript
+     * TaskIDGenerator.parseHierarchicalId("1.2.3");
+     * // Returns: { parentId: "1.2", childIndex: 3 }
+     * ```
+     */
+    static parseHierarchicalId(id: string): {
+        parentId: string;
+        childIndex: number;
+    } | null;
+}
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/utils/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAE,MAAe,GAAG,MAAM;IAMhD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IA0BpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO;IAI9D;;;;;;;;;OASG;IACH,MAAM,CAAC,cAAc,CACnB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,EACxB,MAAM,GAAE,MAAe,EACvB,WAAW,GAAE,MAAW,GACvB,MAAM;IAaT;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAIpE;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,mBAAmB,CACxB,EAAE,EAAE,MAAM,GACT;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAcnD"}

package/dist/utils/id-generator.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TaskIDGenerator = void 0;
+const crypto_1 = require("crypto");
+/**
+ * Generates unique task IDs with consistent format.
+ * Uses timestamp + random hex for uniqueness.
+ */
+class TaskIDGenerator {
+    /**
+     * Generates a unique task ID with format: prefix-timestamp-random
+     *
+     * @param prefix - Prefix for the ID (default: "task")
+     * @returns Unique task ID
+     *
+     * @example
+     * ```typescript
+     * const id = TaskIDGenerator.generate();
+     * // Returns: "task-1733750400000-a1b2c3d4"
+     *
+     * const customId = TaskIDGenerator.generate("subtask");
+     * // Returns: "subtask-1733750400000-e5f6g7h8"
+     * ```
+     */
+    static generate(prefix = "task") {
+        const timestamp = Date.now();
+        const random = (0, crypto_1.randomBytes)(4).toString("hex");
+        return `${prefix}-${timestamp}-${random}`;
+    }
+    /**
+     * Validates a task ID format.
+     * Accepts three formats:
+     * - Timestamped: "task-1234567890-abcd1234"
+     * - Hierarchical: "1.2.3"
+     * - Numeric: "123"
+     *
+     * @param id - Task ID to validate
+     * @returns true if ID format is valid
+     *
+     * @example
+     * ```typescript
+     * TaskIDGenerator.validate("task-1234-abcd"); // true
+     * TaskIDGenerator.validate("1.2.3"); // true
+     * TaskIDGenerator.validate("123"); // true
+     * TaskIDGenerator.validate("invalid!"); // false
+     * ```
+     */
+    static validate(id) {
+        if (!id || typeof id !== "string") {
+            return false;
+        }
+        // Format 1: Timestamped (task-timestamp-random)
+        const timestampedPattern = /^[a-z]+-\d+-[a-f0-9]{8}$/;
+        if (timestampedPattern.test(id)) {
+            return true;
+        }
+        // Format 2: Hierarchical (1.2.3)
+        const hierarchicalPattern = /^[\d.]+$/;
+        if (hierarchicalPattern.test(id)) {
+            return true;
+        }
+        // Format 3: Numeric (123)
+        const numericPattern = /^\d+$/;
+        if (numericPattern.test(id)) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Checks if an ID is unique within a set of existing IDs.
+     *
+     * @param id - ID to check
+     * @param existingIds - Set of existing IDs
+     * @returns true if ID is unique
+     */
+    static isUnique(id, existingIds) {
+        return !existingIds.has(id);
+    }
+    /**
+     * Generates a unique ID that doesn't exist in the provided set.
+     * Retries up to maxAttempts times if collisions occur.
+     *
+     * @param existingIds - Set of existing IDs to avoid
+     * @param prefix - Prefix for the ID
+     * @param maxAttempts - Maximum number of generation attempts
+     * @returns Unique task ID
+     * @throws Error if unable to generate unique ID after maxAttempts
+     */
+    static generateUnique(existingIds, prefix = "task", maxAttempts = 10) {
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const id = this.generate(prefix);
+            if (this.isUnique(id, existingIds)) {
+                return id;
+            }
+        }
+        throw new Error(`Failed to generate unique ID after ${maxAttempts} attempts`);
+    }
+    /**
+     * Generates a hierarchical child ID from a parent ID.
+     * If parent is "1.2", generates "1.2.1", "1.2.2", etc.
+     *
+     * @param parentId - Parent task ID
+     * @param childIndex - Index of the child (1-based)
+     * @returns Child task ID
+     *
+     * @example
+     * ```typescript
+     * TaskIDGenerator.generateChildId("1", 1); // "1.1"
+     * TaskIDGenerator.generateChildId("1.2", 3); // "1.2.3"
+     * ```
+     */
+    static generateChildId(parentId, childIndex) {
+        return `${parentId}.${childIndex}`;
+    }
+    /**
+     * Parses a hierarchical ID to extract parent ID and child index.
+     *
+     * @param id - Hierarchical task ID
+     * @returns Object with parentId and childIndex, or null if not hierarchical
+     *
+     * @example
+     * ```typescript
+     * TaskIDGenerator.parseHierarchicalId("1.2.3");
+     * // Returns: { parentId: "1.2", childIndex: 3 }
+     * ```
+     */
+    static parseHierarchicalId(id) {
+        const parts = id.split(".");
+        if (parts.length < 2) {
+            return null;
+        }
+        const childIndex = parseInt(parts[parts.length - 1], 10);
+        if (isNaN(childIndex)) {
+            return null;
+        }
+        const parentId = parts.slice(0, -1).join(".");
+        return { parentId, childIndex };
+    }
+}
+exports.TaskIDGenerator = TaskIDGenerator;

package/dist/utils/stack-formatter.d.ts

@@ -1,5 +1,6 @@
+import type { BTSFrontend } from "../types/index.js";
 export interface StackInfo {
-    frontend: string;
+    frontend: BTSFrontend | BTSFrontend[];
     backend: string;
     database: string;
     orm: string;

package/dist/utils/stack-formatter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stack-formatter.d.ts","sourceRoot":"","sources":["../../src/utils/stack-formatter.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAyB3E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAMjF"}
+{"version":3,"file":"stack-formatter.d.ts","sourceRoot":"","sources":["../../src/utils/stack-formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,WAAW,GAAG,WAAW,EAAE,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CA6B3E;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAUjF"}

package/dist/utils/stack-formatter.js

@@ -6,8 +6,11 @@ function formatStackInfo(stack) {
     if (!stack) {
         return "Not detected";
     }
+    const frontendStr = Array.isArray(stack.frontend)
+        ? stack.frontend.join(", ")
+        : stack.frontend;
     const parts = [
-        `Frontend: ${stack.frontend}`,
+        `Frontend: ${frontendStr}`,
         `Backend: ${stack.backend}`
     ];
     if (stack.database !== 'none') {
@@ -26,5 +29,8 @@ function formatStackForContext(stack) {
     if (!stack) {
         return "";
     }
-    return `Technology Stack: ${stack.frontend} + ${stack.backend} + ${stack.database}`;
+    const frontendStr = Array.isArray(stack.frontend)
+        ? stack.frontend.join(" + ")
+        : stack.frontend;
+    return `Technology Stack: ${frontendStr} + ${stack.backend} + ${stack.database}`;
 }

package/dist/utils/storage-utils.d.ts

@@ -0,0 +1,49 @@
+import { Task } from "../types/index.js";
+/**
+ * Ensures a task is not null, throwing an error if it is.
+ * Useful for enforcing null checks after storage operations.
+ *
+ * @param task - Task that may be null
+ * @param taskId - ID of the task for error message
+ * @returns The task if not null
+ * @throws Error if task is null
+ *
+ * @example
+ * ```typescript
+ * const task = await storage.getTask(taskId);
+ * const validTask = requireTask(task, taskId);
+ * console.log(validTask.title); // Safe - never null
+ * ```
+ */
+export declare function requireTask(task: Task | null, taskId: string): Task;
+/**
+ * Ensures multiple tasks are not null, throwing an error if any is null.
+ *
+ * @param tasks - Array of tasks that may contain nulls
+ * @param context - Context for error message (e.g., "subtasks", "dependencies")
+ * @returns Array of tasks with nulls filtered out
+ * @throws Error if any task is null
+ */
+export declare function requireTasks(tasks: (Task | null)[], context?: string): Task[];
+/**
+ * Filters out null tasks from an array, with type narrowing.
+ *
+ * @param tasks - Array of tasks that may contain nulls
+ * @returns Array of tasks with nulls removed
+ *
+ * @example
+ * ```typescript
+ * const tasks = await Promise.all(ids.map(id => storage.getTask(id)));
+ * const validTasks = filterNullTasks(tasks);
+ * // validTasks has type Task[] (no null)
+ * ```
+ */
+export declare function filterNullTasks(tasks: (Task | null)[]): Task[];
+/**
+ * Validates that a task ID is a non-empty string.
+ *
+ * @param taskId - Task ID to validate
+ * @throws Error if task ID is invalid
+ */
+export declare function validateTaskId(taskId: string): void;
+//# sourceMappingURL=storage-utils.d.ts.map

package/dist/utils/storage-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-utils.d.ts","sourceRoot":"","sources":["../../src/utils/storage-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAEzC;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAKnE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,EACtB,OAAO,GAAE,MAAgB,GACxB,IAAI,EAAE,CAiBR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,CAE9D;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAInD"}

package/dist/utils/storage-utils.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireTask = requireTask;
+exports.requireTasks = requireTasks;
+exports.filterNullTasks = filterNullTasks;
+exports.validateTaskId = validateTaskId;
+/**
+ * Ensures a task is not null, throwing an error if it is.
+ * Useful for enforcing null checks after storage operations.
+ *
+ * @param task - Task that may be null
+ * @param taskId - ID of the task for error message
+ * @returns The task if not null
+ * @throws Error if task is null
+ *
+ * @example
+ * ```typescript
+ * const task = await storage.getTask(taskId);
+ * const validTask = requireTask(task, taskId);
+ * console.log(validTask.title); // Safe - never null
+ * ```
+ */
+function requireTask(task, taskId) {
+    if (!task) {
+        throw new Error(`Task not found: ${taskId}`);
+    }
+    return task;
+}
+/**
+ * Ensures multiple tasks are not null, throwing an error if any is null.
+ *
+ * @param tasks - Array of tasks that may contain nulls
+ * @param context - Context for error message (e.g., "subtasks", "dependencies")
+ * @returns Array of tasks with nulls filtered out
+ * @throws Error if any task is null
+ */
+function requireTasks(tasks, context = "tasks") {
+    const validTasks = [];
+    const missingIds = [];
+    tasks.forEach((task, index) => {
+        if (!task) {
+            missingIds.push(`index ${index}`);
+        }
+        else {
+            validTasks.push(task);
+        }
+    });
+    if (missingIds.length > 0) {
+        throw new Error(`Missing ${context}: ${missingIds.join(", ")}`);
+    }
+    return validTasks;
+}
+/**
+ * Filters out null tasks from an array, with type narrowing.
+ *
+ * @param tasks - Array of tasks that may contain nulls
+ * @returns Array of tasks with nulls removed
+ *
+ * @example
+ * ```typescript
+ * const tasks = await Promise.all(ids.map(id => storage.getTask(id)));
+ * const validTasks = filterNullTasks(tasks);
+ * // validTasks has type Task[] (no null)
+ * ```
+ */
+function filterNullTasks(tasks) {
+    return tasks.filter((task) => task !== null);
+}
+/**
+ * Validates that a task ID is a non-empty string.
+ *
+ * @param taskId - Task ID to validate
+ * @throws Error if task ID is invalid
+ */
+function validateTaskId(taskId) {
+    if (!taskId || typeof taskId !== "string" || !taskId.trim()) {
+        throw new Error("Invalid task ID: must be a non-empty string");
+    }
+}

package/dist/utils/streaming-utils.d.ts

@@ -0,0 +1,38 @@
+import { StreamingOptions } from "../types/index.js";
+/**
+ * Token usage metrics from AI operations
+ */
+export interface TokenUsage {
+    prompt: number;
+    completion: number;
+    total: number;
+}
+export interface MetricsTracker {
+    tokenUsage: TokenUsage;
+    timeToFirstToken: number | undefined;
+}
+export interface MetricsStreamingResult {
+    options: StreamingOptions;
+    getMetrics: () => MetricsTracker;
+}
+/**
+ * Creates streaming options with automatic metrics tracking.
+ * Wraps provided streaming callbacks to capture token usage and timing metrics.
+ *
+ * @param streamingOptions - Optional base streaming options to wrap
+ * @param aiStartTime - Optional timestamp when AI operation started (for measuring time to first token)
+ * @returns Object containing wrapped streaming options and metrics getter
+ *
+ * @example
+ * ```typescript
+ * const aiStartTime = Date.now();
+ * const { options, getMetrics } = createMetricsStreamingOptions(userCallbacks, aiStartTime);
+ *
+ * await generateText({ model, prompt, ...options });
+ *
+ * const { tokenUsage, timeToFirstToken } = getMetrics();
+ * console.log(`Used ${tokenUsage.total} tokens in ${timeToFirstToken}ms`);
+ * ```
+ */
+export declare function createMetricsStreamingOptions(streamingOptions?: StreamingOptions, aiStartTime?: number): MetricsStreamingResult;
+//# sourceMappingURL=streaming-utils.d.ts.map

package/dist/utils/streaming-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming-utils.d.ts","sourceRoot":"","sources":["../../src/utils/streaming-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,UAAU,CAAC;IACvB,gBAAgB,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,gBAAgB,CAAC;IAC1B,UAAU,EAAE,MAAM,cAAc,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,CAAC,EAAE,gBAAgB,EACnC,WAAW,CAAC,EAAE,MAAM,GACnB,sBAAsB,CAsCxB"}

package/dist/utils/streaming-utils.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMetricsStreamingOptions = createMetricsStreamingOptions;
+/**
+ * Creates streaming options with automatic metrics tracking.
+ * Wraps provided streaming callbacks to capture token usage and timing metrics.
+ *
+ * @param streamingOptions - Optional base streaming options to wrap
+ * @param aiStartTime - Optional timestamp when AI operation started (for measuring time to first token)
+ * @returns Object containing wrapped streaming options and metrics getter
+ *
+ * @example
+ * ```typescript
+ * const aiStartTime = Date.now();
+ * const { options, getMetrics } = createMetricsStreamingOptions(userCallbacks, aiStartTime);
+ *
+ * await generateText({ model, prompt, ...options });
+ *
+ * const { tokenUsage, timeToFirstToken } = getMetrics();
+ * console.log(`Used ${tokenUsage.total} tokens in ${timeToFirstToken}ms`);
+ * ```
+ */
+function createMetricsStreamingOptions(streamingOptions, aiStartTime) {
+    let tokenUsage = { prompt: 0, completion: 0, total: 0 };
+    let timeToFirstToken = undefined;
+    const wrappedOptions = {
+        onFinish: async (result) => {
+            // Extract token usage from result
+            if (result.usage) {
+                tokenUsage = {
+                    prompt: result.usage.inputTokens || result.usage.promptTokens || 0,
+                    completion: result.usage.outputTokens || result.usage.completionTokens || 0,
+                    total: result.usage.totalTokens || 0,
+                };
+            }
+            // Call original onFinish callback if provided
+            await streamingOptions?.onFinish?.(result);
+        },
+        onChunk: (chunk) => {
+            // Measure time to first token (ignore empty/whitespace chunks)
+            if (chunk && chunk.trim() && !timeToFirstToken && aiStartTime) {
+                timeToFirstToken = Date.now() - aiStartTime;
+            }
+            // Call original onChunk callback if provided
+            streamingOptions?.onChunk?.(chunk);
+        },
+        onError: (error) => {
+            // Pass through error callback
+            streamingOptions?.onError?.(error);
+        },
+    };
+    return {
+        options: wrappedOptions,
+        getMetrics: () => ({ tokenUsage, timeToFirstToken }),
+    };
+}