taskbuffer/ts/taskbuffer.interfaces.ts

import type { ITaskStep } from './taskbuffer.classes.taskstep.js';
import type { Task } from './taskbuffer.classes.task.js';

export interface IRateLimitConfig {
  maxPerWindow: number;  // max completions allowed within the sliding window
  windowMs: number;      // sliding window duration in ms
}

export type TResultSharingMode = 'none' | 'share-latest';

export interface ITaskConstraintGroupOptions<TData extends Record<string, unknown> = Record<string, unknown>> {
  name: string;
  constraintKeyForExecution: (task: Task<any, any, TData>, input?: any) => string | null | undefined;
  maxConcurrent?: number;  // default: Infinity
  cooldownMs?: number;     // default: 0
  shouldExecute?: (task: Task<any, any, TData>, input?: any) => boolean | Promise<boolean>;
  rateLimit?: IRateLimitConfig;
  resultSharingMode?: TResultSharingMode;  // default: 'none'
}

export interface ITaskExecution<TData extends Record<string, unknown> = Record<string, unknown>> {
  task: Task<any, any, TData>;
  input: any;
}

export interface IConstrainedTaskEntry {
  task: Task<any, any, any>;
  input: any;
  deferred: import('@push.rocks/smartpromise').Deferred<any>;
  constraintKeys: Map<string, string>;  // groupName -> key
}

export interface ITaskMetadata {
  name: string;
  version?: string;
  status: 'idle' | 'running' | 'completed' | 'failed';
  steps: ITaskStep[];
  currentStep?: string;
  currentProgress: number; // 0-100
  lastRun?: Date;
  nextRun?: Date; // For scheduled tasks
  runCount: number;
  averageDuration?: number;
  cronSchedule?: string;
  buffered?: boolean;
  bufferMax?: number;
  timeout?: number;
  lastError?: string;
  errorCount?: number;
  labels?: Record<string, string>;
}

export interface ITaskExecutionReport {
  taskName: string;
  startTime: number;
  endTime: number;
  duration: number;
  steps: ITaskStep[];
  stepsCompleted: string[];
  progress: number;
  result?: any;
  error?: Error;
}

export interface IScheduledTaskInfo {
  name: string;
  schedule: string;
  nextRun: Date;
  lastRun?: Date;
  steps?: ITaskStep[];
  metadata?: ITaskMetadata;
}

export type TTaskEventType = 'started' | 'step' | 'completed' | 'failed';

export interface ITaskEvent {
  type: TTaskEventType;
  task: ITaskMetadata;
  timestamp: number;
  stepName?: string;   // present when type === 'step'
  error?: string;      // present when type === 'failed'
}