aparavi-client 1.0.2

package/dist/types/types/task.d.ts

@@ -0,0 +1,265 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2024 Aparavi Development Team
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * Task Management Types: Comprehensive Status Tracking and Event Management System.
+ *
+ * This module defines the complete type system for sophisticated task lifecycle management,
+ * real-time status monitoring, and event-driven communication in distributed computational
+ * pipeline systems. It provides structured data models for tracking complex task execution
+ * states, processing statistics, error management, and pipeline flow visualization.
+ */
+/**
+ * Task lifecycle state enumeration for comprehensive state management.
+ *
+ * This enumeration defines all possible states in the task execution lifecycle,
+ * providing clear state transitions and enabling proper resource management,
+ * error handling, and client notification. Each state represents a distinct
+ * phase with specific characteristics and available operations.
+ *
+ * Lifecycle Phases:
+ * ----------------
+ * NONE: Initial state before any resources are allocated or configuration
+ *       is processed. Tasks in this state can be safely discarded without
+ *       cleanup operations.
+ *
+ * STARTING: Resource allocation and initial setup phase. Ports are allocated,
+ *           temporary files created, and subprocess preparation occurs.
+ *
+ * INITIALIZING: Subprocess has been created and is performing pipeline
+ *               initialization. Service interfaces are being established.
+ *
+ * RUNNING: Task is operational and processing requests. All interfaces
+ *          are available and the pipeline is actively executing.
+ *
+ * STOPPING: Graceful shutdown initiated. Subprocess is being terminated
+ *           and resources are being cleaned up.
+ *
+ * COMPLETED: Task finished successfully. All resources cleaned up and
+ *            final status available for client queries.
+ *
+ * CANCELLED: Task was terminated before completion. Resources cleaned up
+ *            and termination reason available in status.
+ *
+ * State Transitions:
+ * -----------------
+ * Normal execution flow:
+ * NONE → STARTING → INITIALIZING → RUNNING → STOPPING → COMPLETED
+ *
+ * Cancellation flow:
+ * Any state → STOPPING → CANCELLED
+ *
+ * Error handling:
+ * Any state → STOPPING → COMPLETED (with error exit code)
+ *
+ * Resource Management:
+ * -------------------
+ * - NONE/COMPLETED/CANCELLED: No active resources requiring cleanup
+ * - STARTING/INITIALIZING/RUNNING: Active resources requiring cleanup
+ * - STOPPING: Cleanup in progress, resources being deallocated
+ *
+ * Client Operations:
+ * -----------------
+ * - NONE: Configuration and launch operations available
+ * - STARTING/INITIALIZING: Status monitoring available
+ * - RUNNING: Full debugging and data processing operations available
+ * - STOPPING: Limited status monitoring, operations being rejected
+ * - COMPLETED/CANCELLED: Status queries only, task cleanup may be initiated
+ *
+ * Wait Operations:
+ * ---------------
+ * Clients can wait for specific state transitions using wait_for_running()
+ * and similar methods. State transitions trigger event notifications to
+ * all subscribed monitoring clients.
+ */
+export declare enum TASK_STATE {
+    /** Initial state - no resources allocated */
+    NONE = 0,
+    /** Resource allocation and subprocess preparation */
+    STARTING = 1,
+    /** Subprocess initialization and service startup */
+    INITIALIZING = 2,
+    /** Operational state - processing requests */
+    RUNNING = 3,
+    /** Graceful shutdown and resource cleanup in progress */
+    STOPPING = 4,
+    /** Successful completion - resources cleaned up */
+    COMPLETED = 5,
+    /** Terminated before completion - resources cleaned up */
+    CANCELLED = 6
+}
+/**
+ * Pipeline component execution flow tracking and visualization model.
+ *
+ * This model provides detailed tracking of pipeline component execution flow,
+ * enabling real-time visualization of which components are currently executing
+ * in each pipeline instance. It supports complex pipeline architectures with
+ * multiple concurrent execution paths and nested component hierarchies.
+ *
+ * Flow Tracking Features:
+ * ----------------------
+ * - Multi-pipeline execution tracking with per-instance component stacks
+ * - Real-time component entry/exit monitoring for performance analysis
+ * - Visual pipeline flow representation for debugging and monitoring
+ * - Component execution depth tracking for nested pipeline architectures
+ * - Concurrent execution visibility across multiple pipeline instances
+ *
+ * Data Structure:
+ * --------------
+ * totalPipes: Total number of concurrent pipeline execution instances
+ * byPipe: Dictionary mapping pipeline instance IDs to component execution stacks
+ *
+ * Component Stack Behavior:
+ * ------------------------
+ * Each pipeline instance maintains a stack of currently executing components:
+ * - Component entry pushes component name onto the stack
+ * - Component exit pops component name from the stack
+ * - Stack depth indicates nesting level of component execution
+ * - Empty stack indicates pipeline instance is idle or completed
+ *
+ * Visualization Applications:
+ * --------------------------
+ * - Real-time pipeline execution diagrams showing active components
+ * - Performance analysis identifying bottlenecks and execution patterns
+ * - Debugging support for component-level execution tracing
+ * - Monitoring dashboards displaying pipeline health and activity
+ *
+ * Concurrent Execution Support:
+ * ----------------------------
+ * Multiple pipeline instances can execute simultaneously, each maintaining
+ * independent component execution stacks. This enables complex parallel
+ * processing scenarios with full visibility into each execution path.
+ *
+ * Example Flow Tracking:
+ * ---------------------
+ * Pipeline 0: ['source', 'transform', 'filter'] - Currently in filter component
+ * Pipeline 1: ['source', 'transform']           - Currently in transform component
+ * Pipeline 2: []                                - Idle or completed
+ */
+export interface TASK_STATUS_FLOW {
+    /** Total number of concurrent pipeline execution instances */
+    totalPipes: number;
+    /** Component execution stacks by pipeline instance ID */
+    byPipe: Record<number, string[]>;
+}
+/**
+ * Comprehensive task status model with real-time processing statistics and metrics.
+ *
+ * This model provides complete task execution status including processing statistics,
+ * error tracking, performance metrics, resource usage, and operational state.
+ * It serves as the central status repository for task monitoring, client updates,
+ * and administrative dashboards.
+ *
+ * Status Categories:
+ * -----------------
+ * - Job Information: Basic task identification and lifecycle status
+ * - Processing Statistics: Counts, sizes, rates, and completion metrics
+ * - Error Management: Error and warning tracking with message history
+ * - Resource Monitoring: Service health and operational state
+ * - Performance Metrics: Processing rates and resource utilization
+ * - Pipeline Tracking: Component execution flow and pipeline visualization
+ *
+ * Real-Time Updates:
+ * -----------------
+ * Status is updated in real-time as the task processes data and progresses
+ * through its lifecycle. Updates are broadcast to subscribed clients based
+ * on their EVENT_TYPE subscriptions, enabling responsive monitoring and
+ * debugging interfaces.
+ *
+ * Buffer Management:
+ * -----------------
+ * Error and warning lists maintain recent message history with automatic
+ * buffer limits to prevent memory growth in long-running tasks. Trace
+ * buffers preserve debugging information while controlling resource usage.
+ *
+ * Metrics Integration:
+ * -------------------
+ * Processing statistics and performance metrics are continuously updated
+ * to provide real-time visibility into task performance, throughput,
+ * and resource utilization patterns.
+ *
+ * Client Integration:
+ * ------------------
+ * Status information is serialized and broadcast to monitoring clients,
+ * debugging interfaces, and administrative dashboards. Different client
+ * types receive filtered status updates based on their subscription preferences.
+ */
+export interface TASK_STATUS {
+    /** Human-readable task name derived from pipeline source component */
+    name: string;
+    /** Unique identifier for the project associated with the task */
+    project_id: string;
+    /** Source component to execute */
+    source: string;
+    /** Task completion flag - true when task has finished execution */
+    completed: boolean;
+    /** Current task lifecycle state from TASK_STATE enumeration */
+    state: number;
+    /** Task start timestamp (Unix time) for duration calculation */
+    startTime: number;
+    /** Task completion timestamp (Unix time) for duration calculation */
+    endTime: number;
+    /** Debugger attachment status */
+    debuggerAttached: boolean;
+    /** Current status message describing task activity and progress */
+    status: string;
+    /** Warning message history (limited to 50 recent entries) */
+    warnings: string[];
+    /** Error message history (limited to 50 recent entries) */
+    errors: string[];
+    /** Name/identifier of the item currently being processed */
+    currentObject: string;
+    /** Size in bytes of the item currently being processed */
+    currentSize: number;
+    /** Contextual notes and information for status display */
+    notes: string[];
+    /** Total size in bytes of all items to be processed */
+    totalSize: number;
+    /** Total count of all items to be processed */
+    totalCount: number;
+    /** Total size in bytes of successfully processed items */
+    completedSize: number;
+    /** Total count of successfully processed items */
+    completedCount: number;
+    /** Total size in bytes of items that failed processing */
+    failedSize: number;
+    /** Total count of items that failed processing */
+    failedCount: number;
+    /** Total size in bytes of extracted/processed text content */
+    wordsSize: number;
+    /** Total count of words extracted/processed from content */
+    wordsCount: number;
+    /** Current processing rate in bytes per second (instantaneous) */
+    rateSize: number;
+    /** Current processing rate in items per second (instantaneous) */
+    rateCount: number;
+    /** Service operational status - true when ready to process requests */
+    serviceUp: boolean;
+    /** Process exit code - 0 for success, non-zero for errors */
+    exitCode: number;
+    /** Exit message providing details about task termination */
+    exitMessage: string;
+    /** Pipeline component execution flow and visualization data */
+    pipeflow: TASK_STATUS_FLOW;
+}
+//# sourceMappingURL=task.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../../aparavi-client/src/types/task.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,oBAAY,UAAU;IACrB,6CAA6C;IAC7C,IAAI,IAAI;IAER,qDAAqD;IACrD,QAAQ,IAAI;IAEZ,oDAAoD;IACpD,YAAY,IAAI;IAEhB,8CAA8C;IAC9C,OAAO,IAAI;IAEX,yDAAyD;IACzD,QAAQ,IAAI;IAEZ,mDAAmD;IACnD,SAAS,IAAI;IAEb,0DAA0D;IAC1D,SAAS,IAAI;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,WAAW,gBAAgB;IAChC,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IAEnB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,WAAW,WAAW;IAG3B,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IAEb,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IAEnB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IAEf,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;IAEnB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IAEd,gEAAgE;IAChE,SAAS,EAAE,MAAM,CAAC;IAElB,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAEhB,iCAAiC;IACjC,gBAAgB,EAAE,OAAO,CAAC;IAI1B,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IAIf,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,EAAE,CAAC;IAEnB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAC;IAIjB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;IAEtB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IAIpB,0DAA0D;IAC1D,KAAK,EAAE,MAAM,EAAE,CAAC;IAIhB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAElB,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IAEnB,0DAA0D;IAC1D,aAAa,EAAE,MAAM,CAAC;IAEtB,kDAAkD;IAClD,cAAc,EAAE,MAAM,CAAC;IAEvB,0DAA0D;IAC1D,UAAU,EAAE,MAAM,CAAC;IAEnB,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IAEpB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAElB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IAInB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IAEjB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAIlB,uEAAuE;IACvE,SAAS,EAAE,OAAO,CAAC;IAInB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IAEjB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IAIpB,+DAA+D;IAC/D,QAAQ,EAAE,gBAAgB,CAAC;CAC3B"}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "aparavi-client",
+  "version": "1.0.2",
+  "author": "Aparavi Corporation",
+  "license": "MIT",
+  "description": "TypeScript client for Aparavi data processing and AI services",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "bin": {
+    "aparavi": "./dist/cli/cli/aparavi.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/**/*",
+    "README.md"
+  ],
+  "keywords": [
+    "aparavi",
+    "data-processing",
+    "ai",
+    "websocket",
+    "typescript"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "glob": "^10.0.0"
+  },
+  "optionalDependencies": {
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.1.2",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.18.1",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "eslint": "^8.0.0",
+    "jest": "^29.0.0",
+    "rimraf": "^5.0.5",
+    "ts-jest": "^29.4.4",
+    "typescript": "^5.0.0",
+    "ws": "^8.18.3"
+  },
+  "scripts": {
+    "--- Install ---------------------------------------": "",
+    "--- Build -----------------------------------------": "",
+    "build": "pnpm run _build:cjs && pnpm run _build:esm && pnpm run _build:types && pnpm run _build:cli && pnpm run _build:dist && pnpm run _build:package",
+    "_build:cjs": "tsc -p tsconfig.cjs.json",
+    "_build:esm": "tsc -p tsconfig.esm.json",
+    "_build:types": "tsc -p tsconfig.types.json",
+    "_build:cli": "tsc -p tsconfig.cli.json",
+    "_build:dist": "node scripts/post-build.js",
+    "_build:package": "pnpm pack --pack-destination=./dist",
+    "--- Test -------------------------------------------": "",
+    "test": "jest --verbose",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "--- Clean ------------------------------------------": "",
+    "clean": "rimraf dist",
+    "--- Misc -------------------------------------------": "",
+    "lint": "eslint aparavi-client/src/**/*.ts"
+  }
+}