modality-kit 0.6.5 → 0.7.0

package/dist/index.js

@@ -4267,6 +4267,174 @@ var fileEntrySchema = exports_external.object({
   type: exports_external.enum(["file", "directory"]).describe("Entry type"),
   lastModified: exports_external.number().optional().nullable().describe("Last modified timestamp in milliseconds since epoch")
 });
+// src/schemas/jsonrpc.ts
+var exports_jsonrpc = {};
+__export(exports_jsonrpc, {
+  STANDARD_ERROR_MESSAGES: () => STANDARD_ERROR_MESSAGES,
+  JSONRPC_VERSION: () => JSONRPC_VERSION,
+  JSONRPCUtils: () => JSONRPCUtils,
+  JSONRPCErrorCode: () => JSONRPCErrorCode
+});
+var JSONRPC_VERSION = "2.0";
+var JSONRPCErrorCode;
+((JSONRPCErrorCode2) => {
+  JSONRPCErrorCode2[JSONRPCErrorCode2["PARSE_ERROR"] = -32700] = "PARSE_ERROR";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["INVALID_REQUEST"] = -32600] = "INVALID_REQUEST";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["METHOD_NOT_FOUND"] = -32601] = "METHOD_NOT_FOUND";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["INVALID_PARAMS"] = -32602] = "INVALID_PARAMS";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["INTERNAL_ERROR"] = -32603] = "INTERNAL_ERROR";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["SERVER_ERROR_START"] = -32099] = "SERVER_ERROR_START";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["SERVER_ERROR_END"] = -32000] = "SERVER_ERROR_END";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["TIMEOUT_ERROR"] = -32001] = "TIMEOUT_ERROR";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["CONNECTION_ERROR"] = -32002] = "CONNECTION_ERROR";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["AUTHENTICATION_ERROR"] = -32003] = "AUTHENTICATION_ERROR";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["AUTHORIZATION_ERROR"] = -32004] = "AUTHORIZATION_ERROR";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["RATE_LIMIT_ERROR"] = -32005] = "RATE_LIMIT_ERROR";
+  JSONRPCErrorCode2[JSONRPCErrorCode2["VALIDATION_ERROR"] = -32006] = "VALIDATION_ERROR";
+})(JSONRPCErrorCode ||= {});
+
+class JSONRPCUtils {
+  static validateMessage(message) {
+    if (Array.isArray(message)) {
+      if (message.length === 0) {
+        return {
+          valid: false,
+          error: {
+            code: -32600 /* INVALID_REQUEST */,
+            message: "Invalid request: batch array cannot be empty"
+          }
+        };
+      }
+      for (const item of message) {
+        const itemValidation = this.validateSingleMessage(item);
+        if (!itemValidation.valid) {
+          return itemValidation;
+        }
+      }
+      return {
+        valid: true,
+        messageType: "batch"
+      };
+    }
+    return this.validateSingleMessage(message);
+  }
+  static validateSingleMessage(message) {
+    if (!message || typeof message !== "object") {
+      return {
+        valid: false,
+        error: {
+          code: -32600 /* INVALID_REQUEST */,
+          message: "Invalid request: message must be an object"
+        }
+      };
+    }
+    if (message.jsonrpc !== JSONRPC_VERSION) {
+      return {
+        valid: false,
+        error: {
+          code: -32600 /* INVALID_REQUEST */,
+          message: `Invalid request: expect ${JSONRPC_VERSION}, received ${message.jsonrpc}`
+        }
+      };
+    }
+    if (!message.method || typeof message.method !== "string") {
+      if ("result" in message || "error" in message) {
+        return {
+          valid: true,
+          messageType: "response"
+        };
+      }
+      return {
+        valid: false,
+        error: {
+          code: -32600 /* INVALID_REQUEST */,
+          message: "Invalid request: method must be a string"
+        }
+      };
+    }
+    const hasId = "id" in message;
+    const messageType = hasId ? "request" : "notification";
+    return {
+      valid: true,
+      messageType
+    };
+  }
+  static createRequest(method, params, id) {
+    return {
+      jsonrpc: JSONRPC_VERSION,
+      method,
+      params,
+      id: id ?? this.generateId()
+    };
+  }
+  static createNotification(method, params) {
+    return {
+      jsonrpc: JSONRPC_VERSION,
+      method,
+      params
+    };
+  }
+  static createSuccessResponse(result, id) {
+    return {
+      jsonrpc: JSONRPC_VERSION,
+      result,
+      id
+    };
+  }
+  static createErrorResponse(error, id) {
+    return {
+      jsonrpc: JSONRPC_VERSION,
+      error,
+      id
+    };
+  }
+  static createError(code, message, data) {
+    return { code, message, data };
+  }
+  static generateId() {
+    return Math.random().toString(36).substring(2) + Date.now().toString(36);
+  }
+  static isRequest(message) {
+    return message && message.jsonrpc === JSONRPC_VERSION && typeof message.method === "string" && "id" in message;
+  }
+  static isNotification(message) {
+    return message && message.jsonrpc === JSONRPC_VERSION && typeof message.method === "string" && !("id" in message);
+  }
+  static isResponse(message) {
+    return message && message.jsonrpc === JSONRPC_VERSION && (("result" in message) || ("error" in message)) && "id" in message;
+  }
+  static isSuccessResponse(response) {
+    return "result" in response;
+  }
+  static isErrorResponse(response) {
+    return "error" in response;
+  }
+  static serialize(message) {
+    return JSON.stringify(message);
+  }
+  static deserialize(data) {
+    try {
+      return JSON.parse(data);
+    } catch {
+      return null;
+    }
+  }
+}
+var STANDARD_ERROR_MESSAGES = {
+  [-32700 /* PARSE_ERROR */]: "Parse error",
+  [-32600 /* INVALID_REQUEST */]: "Invalid Request",
+  [-32601 /* METHOD_NOT_FOUND */]: "Method not found",
+  [-32602 /* INVALID_PARAMS */]: "Invalid params",
+  [-32603 /* INTERNAL_ERROR */]: "Internal error",
+  [-32099 /* SERVER_ERROR_START */]: "Server error",
+  [-32000 /* SERVER_ERROR_END */]: "Server error",
+  [-32001 /* TIMEOUT_ERROR */]: "Request timeout",
+  [-32002 /* CONNECTION_ERROR */]: "Connection error",
+  [-32003 /* AUTHENTICATION_ERROR */]: "Authentication required",
+  [-32004 /* AUTHORIZATION_ERROR */]: "Authorization failed",
+  [-32005 /* RATE_LIMIT_ERROR */]: "Rate limit exceeded",
+  [-32006 /* VALIDATION_ERROR */]: "Validation error"
+};
 // src/schemas/schemas_empty.ts
 var emptySchema = exports_external.object({}).describe("No parameters required");
 // src/util_version.ts
@@ -4989,6 +5157,276 @@ async function compressWithLanguageDetection(text, maxTokens = DEFAULT_CONFIG.ma
     compressionLevel: "moderate"
   });
 }
+// src/util_pending.ts
+var getUUID = () => crypto.randomUUID();
+
+class PendingOperationsBase {
+  operations = new Map;
+  config;
+  cleanupIntervalHandle;
+  eventHandlers = {};
+  constructor(config = {}, eventHandlers = {}) {
+    this.config = {
+      defaultTimeout: 30000,
+      cleanupInterval: 1e4,
+      enableAutoCleanup: true,
+      generateId: getUUID,
+      ...config
+    };
+    this.eventHandlers = eventHandlers;
+    if (this.config.enableAutoCleanup) {
+      this.startAutoCleanup();
+    }
+  }
+  resolve(id, result) {
+    const operation = this.operations.get(id);
+    if (!operation) {
+      return false;
+    }
+    if (operation.timeoutHandle) {
+      clearTimeout(operation.timeoutHandle);
+    }
+    if (operation.type === "promise") {
+      operation.resolve(result);
+    }
+    if (this.eventHandlers.onResolve) {
+      this.eventHandlers.onResolve(operation, result);
+    }
+    this.operations.delete(id);
+    return true;
+  }
+  reject(id, reason) {
+    const operation = this.operations.get(id);
+    if (!operation) {
+      return false;
+    }
+    if (operation.timeoutHandle) {
+      clearTimeout(operation.timeoutHandle);
+    }
+    if (operation.type === "promise") {
+      operation.reject(reason);
+    }
+    if (this.eventHandlers.onReject) {
+      this.eventHandlers.onReject(operation, reason);
+    }
+    this.operations.delete(id);
+    return true;
+  }
+  get(id) {
+    return this.operations.get(id);
+  }
+  has(id) {
+    return this.operations.has(id);
+  }
+  remove(id) {
+    const operation = this.operations.get(id);
+    if (!operation) {
+      return false;
+    }
+    if (operation.timeoutHandle) {
+      clearTimeout(operation.timeoutHandle);
+    }
+    if (this.eventHandlers.onCleanup) {
+      this.eventHandlers.onCleanup(operation);
+    }
+    this.operations.delete(id);
+    return true;
+  }
+  getAll() {
+    return new Map(this.operations);
+  }
+  getByType(type) {
+    return Array.from(this.operations.values()).filter((op) => op.type === type);
+  }
+  clear(reason) {
+    const count = this.operations.size;
+    const keys = Array.from(this.operations.keys());
+    for (const id of keys) {
+      this.reject(id, reason || "All operations cleared");
+    }
+    return count;
+  }
+  cleanupExpired() {
+    const now = Date.now();
+    const expiredOperations = [];
+    for (const [id, operation] of Array.from(this.operations.entries())) {
+      if (operation.timeout && operation.timeout > 0) {
+        const expirationTime = operation.timestamp + operation.timeout;
+        if (now >= expirationTime) {
+          expiredOperations.push(id);
+        }
+      }
+    }
+    for (const id of expiredOperations) {
+      this.handleTimeout(this.operations.get(id));
+    }
+    return expiredOperations.length;
+  }
+  getStats() {
+    const now = Date.now();
+    const operations = Array.from(this.operations.values());
+    const byType = {};
+    let totalAge = 0;
+    let expiringSoon = 0;
+    let oldestTimestamp;
+    for (const operation of operations) {
+      byType[operation.type] = (byType[operation.type] || 0) + 1;
+      const age = now - operation.timestamp;
+      totalAge += age;
+      if (!oldestTimestamp || operation.timestamp < oldestTimestamp) {
+        oldestTimestamp = operation.timestamp;
+      }
+      if (operation.timeout && operation.timeout > 0) {
+        const expirationTime = operation.timestamp + operation.timeout;
+        const timeToExpiry = expirationTime - now;
+        if (timeToExpiry <= 60000 && timeToExpiry > 0) {
+          expiringSoon++;
+        }
+      }
+    }
+    return {
+      total: operations.length,
+      byType,
+      expiringSoon,
+      oldestTimestamp,
+      averageAge: operations.length > 0 ? totalAge / operations.length : 0
+    };
+  }
+  startAutoCleanup() {
+    if (this.cleanupIntervalHandle) {
+      return;
+    }
+    this.cleanupIntervalHandle = setInterval(() => {
+      this.cleanupExpired();
+    }, this.config.cleanupInterval);
+  }
+  stopAutoCleanup() {
+    if (this.cleanupIntervalHandle) {
+      clearInterval(this.cleanupIntervalHandle);
+      this.cleanupIntervalHandle = undefined;
+    }
+  }
+  handleTimeout({ id }) {
+    const operation = this.operations.get(id);
+    if (operation) {
+      if (this.eventHandlers.onTimeout) {
+        this.eventHandlers.onTimeout(operation);
+      }
+      this.reject(operation.id, new Error(`Operation timed out after ${operation.timeout}ms`));
+    }
+  }
+  destroy(reason) {
+    this.stopAutoCleanup();
+    this.clear(reason || "PendingOperations destroyed");
+  }
+  getConfig() {
+    return { ...this.config };
+  }
+  setEventHandlers(handlers) {
+    this.eventHandlers = { ...this.eventHandlers, ...handlers };
+  }
+  handleAdd(options = {}) {
+    const id = options.customId ?? this.config.generateId();
+    const timeout = options.timeout ?? this.config.defaultTimeout;
+    if (options.customId && this.operations.has(options.customId)) {
+      throw new Error(`Operation with ID '${options.customId}' already exists`);
+    }
+    const timeoutHandle = timeout > 0 ? setTimeout(() => {
+      this.handleTimeout({ id });
+    }, timeout) : undefined;
+    return { id, timeout, timeoutHandle };
+  }
+}
+
+class PromisePendingOperations extends PendingOperationsBase {
+  add(data, options = {}) {
+    const { id, timeout, timeoutHandle } = this.handleAdd(options);
+    const promise = new Promise((resolve, reject) => {
+      const operation = {
+        id,
+        type: "promise",
+        timestamp: Date.now(),
+        timeout,
+        timeoutHandle,
+        data,
+        resolve,
+        reject
+      };
+      this.operations.set(id, operation);
+    });
+    return { id, promise };
+  }
+}
+
+class DataPendingOperations extends PendingOperationsBase {
+  add(data, options = {}) {
+    const { id, timeout, timeoutHandle } = this.handleAdd(options);
+    const operation = {
+      id,
+      type: "data",
+      timestamp: Date.now(),
+      timeout,
+      timeoutHandle,
+      data
+    };
+    this.operations.set(id, operation);
+    return { id };
+  }
+}
+function createPromisePendingOperations(config, eventHandlers) {
+  return new PromisePendingOperations({
+    defaultTimeout: 30000,
+    cleanupInterval: 30000,
+    enableAutoCleanup: true,
+    ...config
+  }, eventHandlers);
+}
+function createDataPendingOperations(config, eventHandlers) {
+  return new DataPendingOperations({
+    defaultTimeout: 30000,
+    cleanupInterval: 30000,
+    enableAutoCleanup: true,
+    ...config
+  }, eventHandlers);
+}
+
+class JSONRPCCall {
+  pendingRequests;
+  constructor(config = {}) {
+    const pendingEventHandlers = {
+      onTimeout: (operation) => {
+        console.warn(`JSON-RPC operation timed out:`, operation.id);
+      },
+      onResolve: (operation, _result) => {
+        console.log(`JSON-RPC operation resolved:`, operation.id);
+      },
+      onReject: (operation, reason) => {
+        console.error(`JSON-RPC operation rejected:`, operation.id, reason);
+      }
+    };
+    this.pendingRequests = createPromisePendingOperations(config, pendingEventHandlers);
+  }
+  handleResponse(response) {
+    const id = response.id;
+    if (JSONRPCUtils.isSuccessResponse(response)) {
+      this.pendingRequests.resolve(id, response.result);
+    } else {
+      this.pendingRequests.reject(id, new Error(response.error.message));
+    }
+  }
+  async handleRequest(method, params, options = {}) {
+    const { promise } = this.pendingRequests.add({ method, params }, options);
+    return promise;
+  }
+  getStats() {
+    return {
+      pendingRequests: this.pendingRequests.getStats()
+    };
+  }
+  destroy() {
+    this.pendingRequests.destroy("JSONRPCManager destroyed");
+  }
+}
 export {
   withErrorHandling,
   setupAITools,
@@ -4997,7 +5435,10 @@ export {
   formatSuccessResponse,
   formatErrorResponse,
   emptySchema,
+  createDataPendingOperations,
   compressWithLanguageDetection as compressText,
   exports_schemas_symbol as SymbolType,
+  exports_jsonrpc as JSONRPCType,
+  JSONRPCCall,
   ErrorCode
 };

package/dist/types/__tests__/pending-operations.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Unit Tests for PendingOperations Library
+ *
+ * Tests all functionality of the PendingOperations class including:
+ * - Promise-based operations
+ * - Request-based operations
+ * - Context-based operations
+ * - Timeout handling
+ * - Cleanup functionality
+ * - Statistics and monitoring
+ */
+export {};

package/dist/types/index.d.ts

@@ -4,7 +4,9 @@ export { formatErrorResponse, formatSuccessResponse } from "./util_response";
 export { getLoggerInstance, type ModalityLogger } from "./util_logger";
 export { withErrorHandling, ErrorCode } from "./util_error";
 export * as SymbolType from "./schemas/schemas_symbol";
+export * as JSONRPCType from "./schemas/jsonrpc";
 export type { EmptyType } from "./schemas/schemas_empty";
 export { emptySchema } from "./schemas/schemas_empty";
 export { loadVersion } from "./util_version";
 export { compressWithLanguageDetection as compressText } from "./util_text_compression";
+export { JSONRPCCall, createDataPendingOperations } from "./util_pending";

package/dist/types/schemas/jsonrpc.d.ts

@@ -0,0 +1,212 @@
+/**
+ * JSON-RPC 2.0 Types and Interfaces
+ * @see https://www.jsonrpc.org/specification
+ *
+ * Comprehensive TypeScript definitions for JSON-RPC 2.0 specification
+ * Provides type-safe interfaces for request/response/notification patterns
+ * and utilities for message handling and validation.
+ */
+/**
+ * Generic JSON-RPC method type for type-safe method definitions
+ * Usage: type MyMethod = JSONRPCMethod<MyParams, MyResult>
+ * Or as object: { methodName: JSONRPCMethod<MyParams, MyResult> }
+ */
+export type JSONRPCMethod<TParams = JSONRPCParams, TResult = any> = (method: string, params?: TParams, options?: any) => Promise<TResult>;
+/**
+ * JSON-RPC 2.0 version identifier
+ */
+export declare const JSONRPC_VERSION: "2.0";
+/**
+ * Standard JSON-RPC 2.0 error codes as defined in the specification
+ */
+export declare enum JSONRPCErrorCode {
+    PARSE_ERROR = -32700,
+    INVALID_REQUEST = -32600,
+    METHOD_NOT_FOUND = -32601,
+    INVALID_PARAMS = -32602,
+    INTERNAL_ERROR = -32603,
+    SERVER_ERROR_START = -32099,
+    SERVER_ERROR_END = -32000,
+    TIMEOUT_ERROR = -32001,
+    CONNECTION_ERROR = -32002,
+    AUTHENTICATION_ERROR = -32003,
+    AUTHORIZATION_ERROR = -32004,
+    RATE_LIMIT_ERROR = -32005,
+    VALIDATION_ERROR = -32006
+}
+/**
+ * JSON-RPC 2.0 parameter types - can be object, array, or null
+ *
+ * IMPORTANT: DO NOT add 'undefined' to this type!
+ *
+ * Reasoning per JSON-RPC 2.0 specification (https://www.jsonrpc.org/specification):
+ * 1. JSON specification does not support 'undefined' - only null, objects, arrays, etc.
+ * 2. JSON.stringify() omits undefined values, making {params: undefined} equivalent to {}
+ * 3. JSON-RPC 2.0 spec defines params as: Object | Array | omitted entirely
+ * 4. Use cases:
+ *    - No parameters: omit 'params' field entirely
+ *    - Explicit null: use 'params: null'
+ *    - Empty object: use 'params: {}'
+ *    - Empty array: use 'params: []'
+ *
+ * This ensures strict JSON-RPC 2.0 compliance and wire protocol compatibility.
+ * See: https://www.jsonrpc.org/specification#parameter_structures
+ */
+export type JSONRPCParams = object | any[] | null;
+/**
+ * JSON-RPC 2.0 ID type - string, number, or null
+ */
+export type JSONRPCId = string | number | null;
+/**
+ * JSON-RPC 2.0 Error object
+ */
+export interface JSONRPCError {
+    /** Error code indicating the error type */
+    code: JSONRPCErrorCode | number;
+    /** Human-readable error message */
+    message: string;
+    /** Optional additional error data */
+    data?: any;
+}
+/**
+ * JSON-RPC 2.0 Request object
+ */
+export interface JSONRPCRequest {
+    /** JSON-RPC version identifier */
+    jsonrpc: typeof JSONRPC_VERSION;
+    /** Method name to be invoked */
+    method: string;
+    /** Optional parameters for the method */
+    params?: JSONRPCParams;
+    /** Request identifier for correlation with response */
+    id: JSONRPCId;
+}
+/**
+ * JSON-RPC 2.0 Notification object (request without id)
+ */
+export interface JSONRPCNotification {
+    /** JSON-RPC version identifier */
+    jsonrpc: typeof JSONRPC_VERSION;
+    /** Method name to be invoked */
+    method: string;
+    /** Optional parameters for the method */
+    params?: JSONRPCParams;
+}
+/**
+ * JSON-RPC 2.0 Success Response object
+ */
+export interface JSONRPCSuccessResponse {
+    /** JSON-RPC version identifier */
+    jsonrpc: typeof JSONRPC_VERSION;
+    /** Method result */
+    result: any;
+    /** Request identifier matching the original request */
+    id: JSONRPCId;
+}
+/**
+ * JSON-RPC 2.0 Error Response object
+ */
+export interface JSONRPCErrorResponse {
+    /** JSON-RPC version identifier */
+    jsonrpc: typeof JSONRPC_VERSION;
+    /** Error information */
+    error: JSONRPCError;
+    /** Request identifier matching the original request */
+    id: JSONRPCId;
+}
+/**
+ * Union type for JSON-RPC 2.0 Response objects
+ */
+export type JSONRPCResponse = JSONRPCSuccessResponse | JSONRPCErrorResponse;
+/**
+ * JSON-RPC 2.0 Batch Request (array of requests and/or notifications)
+ */
+export type JSONRPCBatchRequest = (JSONRPCRequest | JSONRPCNotification)[];
+/**
+ * JSON-RPC 2.0 Batch Response (array of responses)
+ */
+export type JSONRPCBatchResponse = JSONRPCResponse[];
+/**
+ * Union type for all JSON-RPC 2.0 message types
+ */
+export type JSONRPCMessage = JSONRPCRequest | JSONRPCNotification | JSONRPCResponse | JSONRPCBatchRequest | JSONRPCBatchResponse;
+/**
+ * JSON-RPC message validation result
+ */
+export interface JSONRPCValidationResult {
+    /** Whether the message is valid */
+    valid: boolean;
+    /** Error information if validation failed */
+    error?: JSONRPCError;
+    /** Parsed message type */
+    messageType?: "request" | "notification" | "response" | "batch";
+}
+/**
+ * Utility functions for JSON-RPC message handling
+ */
+export declare class JSONRPCUtils {
+    /**
+     * Validate a JSON-RPC message (supports batch requests)
+     */
+    static validateMessage(message: any): JSONRPCValidationResult;
+    /**
+     * Validate a single JSON-RPC message
+     */
+    static validateSingleMessage(message: any): JSONRPCValidationResult;
+    /**
+     * Create a JSON-RPC request
+     */
+    static createRequest(method: string, params?: JSONRPCParams, id?: JSONRPCId): JSONRPCRequest;
+    /**
+     * Create a JSON-RPC notification
+     */
+    static createNotification(method: string, params?: JSONRPCParams): JSONRPCNotification;
+    /**
+     * Create a JSON-RPC success response
+     */
+    static createSuccessResponse(result: any, id: JSONRPCId): JSONRPCSuccessResponse;
+    /**
+     * Create a JSON-RPC error response
+     */
+    static createErrorResponse(error: JSONRPCError, id: JSONRPCId): JSONRPCErrorResponse;
+    /**
+     * Create a standard JSON-RPC error
+     */
+    static createError(code: JSONRPCErrorCode | number, message: string, data?: any): JSONRPCError;
+    /**
+     * Generate a unique ID for requests
+     */
+    static generateId(): string;
+    /**
+     * Check if a message is a JSON-RPC request
+     */
+    static isRequest(message: any): message is JSONRPCRequest;
+    /**
+     * Check if a message is a JSON-RPC notification
+     */
+    static isNotification(message: any): message is JSONRPCNotification;
+    /**
+     * Check if a message is a JSON-RPC response
+     */
+    static isResponse(message: any): message is JSONRPCResponse;
+    /**
+     * Check if a response is a success response
+     */
+    static isSuccessResponse(response: JSONRPCResponse): response is JSONRPCSuccessResponse;
+    /**
+     * Check if a response is an error response
+     */
+    static isErrorResponse(response: JSONRPCResponse): response is JSONRPCErrorResponse;
+    /**
+     * Serialize a JSON-RPC message to string
+     */
+    static serialize(message: JSONRPCMessage): string;
+    /**
+     * Deserialize a JSON-RPC message from string
+     */
+    static deserialize(data: string): JSONRPCMessage | null;
+}
+/**
+ * Standard error messages for common JSON-RPC errors
+ */
+export declare const STANDARD_ERROR_MESSAGES: Record<JSONRPCErrorCode, string>;

package/dist/types/util_pending.d.ts

@@ -0,0 +1,330 @@
+/**
+ * Sharable Pending Operations Library
+ *
+ * A generic library for managing pending operations with timeout, cleanup,
+ * and lifecycle management. Can be used on both client and server sides
+ * for WebSocket communication or any async operation tracking.
+ */
+import { JSONRPCResponse } from "./schemas/jsonrpc";
+/**
+ * Configuration options for PendingOperations
+ *
+ * @interface PendingOperationsConfig
+ * @description Configures timeout behavior, cleanup intervals, and ID generation for pending operations
+ */
+export interface PendingOperationsConfig {
+    /**
+     * Default timeout in milliseconds for operations (default: 30000)
+     * @default 30000
+     * @description Sets the default timeout for operations that don't specify their own timeout
+     */
+    defaultTimeout?: number;
+    /**
+     * Cleanup interval in milliseconds for expired operations (default: 10000)
+     * @default 10000
+     * @description How often the system checks for and cleans up expired operations
+     */
+    cleanupInterval?: number;
+    /**
+     * Enable automatic cleanup of expired operations (default: true)
+     * @default true
+     * @description Whether to automatically clean up expired operations in the background
+     */
+    enableAutoCleanup?: boolean;
+    /**
+     * Custom ID generator function (default: randomUUIDv7)
+     * @default getUUID
+     * @description Function to generate unique IDs for operations. Must return unique strings.
+     */
+    generateId?: () => string;
+}
+/**
+ * Base interface for all pending operation data
+ *
+ * @interface PendingOperationBase
+ * @description Common properties shared by all pending operation types
+ */
+export interface PendingOperationBase {
+    /**
+     * Unique identifier for the operation
+     * @description Generated automatically by the ID generator function
+     */
+    id: string;
+    /**
+     * Timestamp when the operation was created
+     * @description Used for age calculations and timeout management
+     */
+    timestamp: number;
+    /**
+     * Timeout in milliseconds for this specific operation
+     * @description Overrides the default timeout if specified
+     */
+    timeout?: number;
+    /**
+     * Optional data for the operation
+     * @description Arbitrary data for application-specific use
+     */
+    data?: any;
+}
+/**
+ * Promise-based pending operation (used for server-to-client calls)
+ *
+ * @interface PromisePendingOperation
+ * @extends PendingOperationBase
+ * @description Represents an operation that provides a Promise interface for async resolution
+ * @example
+ * ```typescript
+ * const { id, promise } = pendingOps.addPromiseOperation();
+ * promise.then(result => console.log('Success:', result));
+ * // Later: pendingOps.resolve(id, { data: 'result' });
+ * ```
+ */
+export interface PromisePendingOperation extends PendingOperationBase {
+    /** Operation type identifier */
+    type: "promise";
+    /**
+     * Promise resolve function
+     * @description Called when the operation completes successfully
+     */
+    resolve: (value: any) => void;
+    /**
+     * Promise reject function
+     * @description Called when the operation fails or times out
+     */
+    reject: (reason?: any) => void;
+    /**
+     * Optional timeout handle for cleanup
+     * @description Internal timeout handle for automatic cleanup
+     */
+    timeoutHandle?: NodeJS.Timeout;
+}
+/**
+ * Data-based pending operation (used for request tracking and context storage)
+ * Replaces both RequestPendingOperation and ContextPendingOperation
+ *
+ * @interface DataPendingOperation
+ * @extends PendingOperationBase
+ * @description Flexible operation type that can store any data payload. Use for client-server requests, context tracking, or any data-centric operations.
+ * @example
+ * ```typescript
+ * // Request-style usage
+ * const id = pendingOps.addDataOperation(
+ *   { requestType: 'getUserProfile', payload: { userId: 123 } },
+ *   { connectionId: 'client-001', timeout: 30000 }
+ * );
+ *
+ * // Context-style usage
+ * const id2 = pendingOps.addDataOperation(
+ *   { functionName: 'processCommand', context: { command: 'export' } },
+ *   { timeout: 60000 }
+ * );
+ * ```
+ */
+export interface DataPendingOperation extends PendingOperationBase {
+    /** Operation type identifier */
+    type: "data";
+    /**
+     * Arbitrary data payload for the operation
+     * @description Can contain requestType/payload, functionName/context, connectionId, connection, or any other data structure
+     */
+    data: any;
+    /**
+     * Optional timeout handle for cleanup
+     * @description Internal timeout handle for automatic cleanup
+     */
+    timeoutHandle?: NodeJS.Timeout;
+}
+/**
+ * Union type for all pending operation types
+ */
+export type PendingOperation = PromisePendingOperation | DataPendingOperation;
+/**
+ * Event handlers for pending operations
+ */
+export interface PendingOperationEventHandlers {
+    /** Called when an operation times out */
+    onTimeout?: (operation: PendingOperation) => void;
+    /** Called when an operation is resolved */
+    onResolve?: (operation: PendingOperation, result?: any) => void;
+    /** Called when an operation is rejected */
+    onReject?: (operation: PendingOperation, reason?: any) => void;
+    /** Called when an operation is removed/cleaned up */
+    onCleanup?: (operation: PendingOperation) => void;
+}
+/**
+ * Statistics about pending operations
+ */
+export interface PendingOperationStats {
+    /** Total number of pending operations */
+    total: number;
+    /** Number of operations by type */
+    byType: Record<string, number>;
+    /** Number of operations that will expire soon (within next minute) */
+    expiringSoon: number;
+    /** Oldest operation timestamp */
+    oldestTimestamp?: number;
+    /** Average age of operations in milliseconds */
+    averageAge: number;
+}
+/**
+ * Abstract base class for pending operations management
+ * Contains all common functionality while allowing specialized subclasses
+ */
+export declare abstract class PendingOperationsBase {
+    protected operations: Map<string, PendingOperation>;
+    protected config: Required<PendingOperationsConfig>;
+    protected cleanupIntervalHandle?: NodeJS.Timeout;
+    protected eventHandlers: PendingOperationEventHandlers;
+    constructor(config?: PendingOperationsConfig, eventHandlers?: PendingOperationEventHandlers);
+    /**
+     * Resolve a pending operation with a result
+     */
+    resolve(id: string, result?: any): boolean;
+    /**
+     * Reject a pending operation with a reason
+     */
+    reject(id: string, reason?: any): boolean;
+    /**
+     * Get a pending operation by ID
+     */
+    get(id: string): PendingOperation | undefined;
+    /**
+     * Check if an operation exists
+     */
+    has(id: string): boolean;
+    /**
+     * Remove an operation without resolving or rejecting
+     */
+    remove(id: string): boolean;
+    /**
+     * Get all pending operations
+     */
+    getAll(): Map<string, PendingOperation>;
+    /**
+     * Get pending operations by type
+     */
+    getByType(type: PendingOperation["type"]): PendingOperation[];
+    /**
+     * Clear all pending operations
+     */
+    clear(reason?: any): number;
+    /**
+     * Clean up expired operations
+     */
+    cleanupExpired(): number;
+    /**
+     * Get statistics about pending operations
+     */
+    getStats(): PendingOperationStats;
+    /**
+     * Start automatic cleanup of expired operations
+     */
+    private startAutoCleanup;
+    /**
+     * Stop automatic cleanup
+     */
+    stopAutoCleanup(): void;
+    /**
+     * Handle operation timeout
+     */
+    protected handleTimeout({ id }: {
+        id: string;
+    }): void;
+    /**
+     * Destroy the pending operations manager
+     */
+    destroy(reason?: any): void;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): Required<PendingOperationsConfig>;
+    /**
+     * Update event handlers
+     */
+    setEventHandlers(handlers: PendingOperationEventHandlers): void;
+    /**
+     * Abstract method that subclasses must implement for their specific operation type
+     */
+    abstract add(...args: any[]): any;
+    handleAdd(options?: {
+        timeout?: number;
+        customId?: string;
+    }): {
+        id: string;
+        timeout: number;
+        timeoutHandle: NodeJS.Timeout | undefined;
+    };
+}
+/**
+ * Specialized class for promise-based operations only
+ * Enforces type safety by only exposing promise-related methods
+ */
+export declare class PromisePendingOperations extends PendingOperationsBase {
+    /**
+     * Add a promise-based pending operation
+     */
+    add(data: any, options?: {
+        timeout?: number;
+        customId?: string;
+    }): {
+        id: string;
+        promise: Promise<any>;
+    };
+}
+/**
+ * Specialized class for data-based operations only
+ * Enforces type safety by only exposing data-related methods
+ */
+export declare class DataPendingOperations extends PendingOperationsBase {
+    /**
+     * Add a data-based pending operation
+     */
+    add(data: any, options?: {
+        timeout?: number;
+        customId?: string;
+    }): {
+        id: string;
+    };
+}
+/**
+ * Create a PendingOperations instance with Promise-based operations
+ * Optimized for server-to-client function calls
+ *
+ * @param config Optional configuration for the pending operations
+ * @param eventHandlers Optional event handlers for operation lifecycle
+ * @returns PromisePendingOperations instance that only allows promise operations
+ */
+export declare function createPromisePendingOperations(config?: PendingOperationsConfig, eventHandlers?: PendingOperationEventHandlers): PromisePendingOperations;
+/**
+ * Create a PendingOperations instance with Data-based operations
+ * Optimized for both request processing and context handling
+ *
+ * @param config Optional configuration for the pending operations
+ * @param eventHandlers Optional event handlers for operation lifecycle
+ * @returns DataPendingOperations instance that only allows data operations
+ */
+export declare function createDataPendingOperations(config?: PendingOperationsConfig, eventHandlers?: PendingOperationEventHandlers): DataPendingOperations;
+export declare class JSONRPCCall {
+    private pendingRequests;
+    constructor(config?: PendingOperationsConfig);
+    /**
+     * Process a JSON-RPC response
+     */
+    handleResponse(response: JSONRPCResponse): void;
+    /**
+     * Send a JSON-RPC request and return a promise for the response
+     */
+    handleRequest(method: string, params?: any, options?: {
+        timeout?: number;
+    }): Promise<any>;
+    /**
+     * Get manager statistics
+     */
+    getStats(): {
+        pendingRequests: PendingOperationStats;
+    };
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}

package/dist/types/util_tests/TimerMockManager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Timer Mock Utilities
+ *
+ * These utilities provide centralized timer mocking for tests that need to control time.
+ * This ensures consistent behavior across all tests that use setTimeout, setInterval, etc.
+ */
+/**
+ * Centralized timer mock manager for controlling time in tests
+ *
+ * Features:
+ * - Mock setTimeout with virtual clock advancement
+ * - Mock Math.random for deterministic jitter elimination
+ * - Track virtual time progression
+ * - Immediate callback execution for fast tests
+ *
+ * Usage:
+ * ```typescript
+ * import { TimerMockManager } from "../util_tests/TimerMockManager.js";
+ *
+ * let timerMock: TimerMockManager;
+ *
+ * beforeEach(() => {
+ *   timerMock = new TimerMockManager();
+ *   timerMock.setup();
+ * });
+ *
+ * afterEach(() => {
+ *   timerMock.restore();
+ * });
+ * ```
+ */
+export declare class TimerMockManager {
+    private originalSetTimeout?;
+    private originalMathRandom?;
+    private mockSetTimeout?;
+    private virtualClock;
+    /**
+     * Setup timer mocks
+     * @param executeImmediately - Whether to execute callbacks immediately (default: true for fast tests)
+     * @param mockRandomValue - Fixed value for Math.random (default: 0 to eliminate jitter)
+     */
+    setup(executeImmediately?: boolean, mockRandomValue?: number): void;
+    /**
+     * Restore original timer functions
+     */
+    restore(): void;
+    /**
+     * Get the current virtual clock time
+     */
+    getVirtualClock(): number;
+    /**
+     * Reset virtual clock to zero
+     */
+    resetClock(): void;
+    /**
+     * Get the mock setTimeout function for assertions
+     */
+    getMockSetTimeout(): any;
+    /**
+     * Verify that setTimeout was called with expected parameters
+     */
+    expectSetTimeoutCalled(times: number, delay?: number): void;
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.6.5",
+  "version": "0.7.0",
   "name": "modality-kit",
   "repository": {
     "type": "git",