zcw-shared 1.2.0

package/types/worker.d.ts

@@ -0,0 +1,364 @@
+/**
+ * Worker 相关的应用层类型定义
+ * 
+ * @description
+ * 定义 Worker hooks 使用的接口和类型，不包含环境相关的类型
+ * 环境相关的类型请从 references/worker.d 导入
+ * 
+ * @since 1.0.0
+ * @author Assistant
+ */
+
+/**
+ * 响应式值接口
+ */
+export interface ReactiveValue<T> {
+  value: T
+}
+
+/**
+ * Worker消息接口
+ */
+export interface WorkerMessage {
+  /** 消息ID */
+  id?: number
+  /** 消息数据 */
+  data: any
+  /** 错误信息 */
+  error?: string
+  /** 消息类型 */
+  type?: string
+}
+
+/**
+ * Web Worker配置选项
+ */
+export interface WebWorkerOptions {
+  /** Worker脚本URL */
+  scriptURL: string
+  /** 最大重试次数 */
+  maxRetries?: number
+  /** 消息超时时间（毫秒） */
+  timeout?: number
+  /** 是否自动重启 */
+  autoRestart?: boolean
+  /** 是否支持Transferable对象 */
+  transferable?: boolean
+}
+
+/**
+ * Web Worker结果接口
+ */
+export interface WebWorkerResult<T> {
+  /** 操作是否成功 */
+  success: boolean
+  /** 返回数据 */
+  data: T | null
+  /** 错误信息 */
+  error: Error | null
+}
+
+/**
+ * useWebWorker返回值接口
+ */
+export interface UseWebWorkerReturn {
+  /** Worker是否准备就绪 */
+  isReady: ReactiveValue<boolean>
+  /** 是否正在加载 */
+  isLoading: ReactiveValue<boolean>
+  /** 错误状态 */
+  error: ReactiveValue<Error | null>
+  /** 发送消息 */
+  postMessage: <T>(data: any, transfer?: Transferable[]) => Promise<WebWorkerResult<T>>
+  /** 批量发送消息 */
+  postMessages: <T>(messages: any[], transfer?: Transferable[][]) => Promise<WebWorkerResult<T>[]>
+  /** 终止Worker */
+  terminate: () => void
+  /** 重启Worker */
+  restart: () => Promise<void>
+  /** 获取状态 */
+  getStatus: () => {
+    isReady: boolean
+    isLoading: boolean
+    error: Error | null
+    pendingMessages: number
+  }
+}
+
+/**
+ * Worker任务接口
+ */
+export interface WorkerTask {
+  /** 任务数据 */
+  data: any
+  /** 任务优先级 */
+  priority?: 'low' | 'normal' | 'high'
+  /** Transferable对象 */
+  transfer?: Transferable[]
+  /** 任务类型 */
+  type?: string
+  /** 任务ID */
+  id?: string
+}
+
+/**
+ * Worker池配置选项
+ */
+export interface WorkerPoolOptions {
+  /** Worker脚本URL */
+  scriptURL: string
+  /** 池大小 */
+  poolSize?: number
+  /** 最大队列大小 */
+  maxQueueSize?: number
+  /** 任务超时时间（毫秒） */
+  taskTimeout?: number
+  /** 是否自动扩展 */
+  autoScale?: boolean
+  /** 最小池大小 */
+  minPoolSize?: number
+  /** 最大池大小 */
+  maxPoolSize?: number
+}
+
+/**
+ * Worker池结果接口
+ */
+export interface WorkerPoolResult<T> {
+  /** 操作是否成功 */
+  success: boolean
+  /** 返回数据 */
+  data: T | null
+  /** 错误信息 */
+  error: Error | null
+  /** 执行的Worker ID */
+  workerId: number
+  /** 执行时间（毫秒） */
+  executionTime: number
+}
+
+/**
+ * Worker池统计信息
+ */
+export interface WorkerPoolStats {
+  /** 池大小 */
+  poolSize: number
+  /** 忙碌的Worker数量 */
+  busyWorkers: number
+  /** 空闲的Worker数量 */
+  idleWorkers: number
+  /** 队列大小 */
+  queueSize: number
+  /** 活动任务数量 */
+  activeTasks: number
+  /** 已处理的总任务数 */
+  totalTasksProcessed: number
+  /** 是否准备就绪 */
+  isReady: boolean
+  /** 是否正在加载 */
+  isLoading: boolean
+  /** 错误状态 */
+  error: Error | null
+}
+
+/**
+ * Worker函数类型
+ */
+export type WorkerFunction<T extends any[], R> = (...args: T) => R | Promise<R>
+
+/**
+ * Worker函数配置选项
+ */
+export interface WorkerFunctionOptions {
+  /** 执行超时时间（毫秒） */
+  timeout?: number
+  /** 最大重试次数 */
+  maxRetries?: number
+  /** 是否自动重启Worker */
+  autoRestart?: boolean
+}
+
+/**
+ * Worker函数执行结果
+ */
+export interface WorkerFunctionResult<R> {
+  /** 是否执行成功 */
+  success: boolean
+  /** 执行结果数据 */
+  data?: R
+  /** 错误信息 */
+  error?: Error
+  /** 执行时间（毫秒） */
+  executionTime: number
+}
+
+/**
+ * useWorkerFunction返回类型
+ */
+export interface UseWorkerFunctionReturn<T extends any[], R> {
+  /** Worker是否准备就绪 */
+  isReady: ReactiveValue<boolean>
+  /** 是否正在加载 */
+  isLoading: ReactiveValue<boolean>
+  /** 错误状态 */
+  error: ReactiveValue<Error | null>
+  /** 执行函数 */
+  execute: (...args: T) => Promise<WorkerFunctionResult<R>>
+  /** 终止Worker */
+  terminate: () => void
+  /** 获取状态信息 */
+  getStatus: () => {
+    isReady: boolean
+    isLoading: boolean
+    error: Error | null
+    executionCount: number
+  }
+}
+
+/**
+ * useWorkerPool返回值接口
+ */
+export interface UseWorkerPoolReturn {
+  /** 池是否准备就绪 */
+  isReady: ReactiveValue<boolean>
+  /** 是否正在加载 */
+  isLoading: ReactiveValue<boolean>
+  /** 错误状态 */
+  error: ReactiveValue<Error | null>
+  /** 执行任务 */
+  execute: <T>(task: WorkerTask) => Promise<WorkerPoolResult<T>>
+  /** 批量执行任务 */
+  executeBatch: <T>(tasks: WorkerTask[]) => Promise<WorkerPoolResult<T>[]>
+  /** 取消任务 */
+  cancelTask: (taskId: number) => boolean
+  /** 清空队列 */
+  clearQueue: () => void
+  /** 调整池大小 */
+  resize: (newSize: number) => Promise<void>
+  /** 获取统计信息 */
+  getStats: () => WorkerPoolStats
+  /** 终止池 */
+  terminate: () => void
+  /** 重启池 */
+  restart: () => Promise<void>
+  /** 清理资源 */
+  cleanup: () => void
+}
+
+/**
+ * Worker事件类型
+ */
+export type WorkerEventType = 'message' | 'error' | 'messageerror'
+
+/**
+ * Worker状态类型
+ */
+export type WorkerStatus = 'idle' | 'loading' | 'ready' | 'busy' | 'error' | 'terminated'
+
+/**
+ * 任务优先级类型
+ */
+export type TaskPriority = 'low' | 'normal' | 'high'
+
+/**
+ * Worker池策略类型
+ */
+export type PoolStrategy = 'round-robin' | 'least-busy' | 'random' | 'priority'
+
+/**
+ * 负载均衡策略接口
+ */
+export interface LoadBalancingStrategy {
+  /** 策略名称 */
+  name: PoolStrategy
+  /** 选择Worker的函数 */
+  selectWorker: (workers: WorkerInfo[], task: WorkerTask) => number
+}
+
+/**
+ * Worker信息接口
+ */
+export interface WorkerInfo {
+  /** Worker ID */
+  id: number
+  /** 是否忙碌 */
+  busy: boolean
+  /** 任务计数 */
+  taskCount: number
+  /** 最后使用时间 */
+  lastUsed: number
+  /** Worker状态 */
+  status: WorkerStatus
+  /** 错误计数 */
+  errorCount: number
+}
+
+/**
+ * 任务执行上下文
+ */
+export interface TaskExecutionContext {
+  /** 任务ID */
+  taskId: number
+  /** Worker ID */
+  workerId: number
+  /** 开始时间 */
+  startTime: number
+  /** 超时ID */
+  timeoutId: NodeJS.Timeout
+  /** 任务数据 */
+  task: WorkerTask
+}
+
+/**
+ * Worker池配置
+ */
+export interface WorkerPoolConfig extends WorkerPoolOptions {
+  /** 负载均衡策略 */
+  strategy?: PoolStrategy
+  /** 健康检查间隔（毫秒） */
+  healthCheckInterval?: number
+  /** Worker空闲超时（毫秒） */
+  idleTimeout?: number
+  /** 最大错误次数 */
+  maxErrors?: number
+}
+
+/**
+ * 任务队列项
+ */
+export interface TaskQueueItem {
+  /** 任务 */
+  task: WorkerTask
+  /** 解决函数 */
+  resolve: (value: WorkerPoolResult<any>) => void
+  /** 拒绝函数 */
+  reject: (error: Error) => void
+  /** 优先级数值 */
+  priority: number
+  /** 时间戳 */
+  timestamp: number
+  /** 任务ID */
+  taskId: number
+}
+
+/**
+ * Worker性能指标
+ */
+export interface WorkerMetrics {
+  /** 总任务数 */
+  totalTasks: number
+  /** 成功任务数 */
+  successfulTasks: number
+  /** 失败任务数 */
+  failedTasks: number
+  /** 平均执行时间 */
+  averageExecutionTime: number
+  /** 最大执行时间 */
+  maxExecutionTime: number
+  /** 最小执行时间 */
+  minExecutionTime: number
+  /** 错误率 */
+  errorRate: number
+  /** 吞吐量（任务/秒） */
+  throughput: number
+}