@decaf-ts/utils/lib/types/utils/performanceRunner.d.mts

module management utils for decaf-ts

export type ExecutionMode = "sequential" | "concurrent" | "burst";
export interface PhaseBurstConfig {
    size: number;
    intervalMs?: number;
}
export interface PhaseWarmupConfig<TContext = Record<string, unknown>> {
    iterations: number;
    handler?: PerformanceHandler<TContext>;
    delayBetweenIterationsMs?: number;
}
export interface PhaseConfig<TContext = Record<string, unknown>> {
    iterations: number;
    mode: ExecutionMode;
    concurrency?: number;
    delayBetweenIterationsMs?: number;
    burst?: PhaseBurstConfig;
    loadStart?: number;
    loadStep?: number;
    loadMultiplier?: number;
    context?: Partial<TContext>;
    metadata?: Record<string, unknown>;
    warmup?: PhaseWarmupConfig<TContext>;
    pauseAfterMs?: number;
}
export interface Phase<TContext = Record<string, unknown>> {
    name: string;
    config: PhaseConfig<TContext>;
    generator?: PhaseGenerator<TContext>;
    subPhases?: Phase<TContext>[];
}
export interface PhaseGeneratorPhase<TContext> {
    name?: string;
    config: PhaseConfig<Partial<TContext>>;
}
export type PhaseGeneratorResult<TContext> = PhaseConfig<TContext> | PhaseGeneratorPhase<TContext>;
export type PhaseGenerator<TContext> = (payload: PhaseGeneratorPayload<TContext>) => Promise<PhaseGeneratorResult<TContext> | undefined> | PhaseGeneratorResult<TContext> | undefined;
export interface PhaseResult<TContext = Record<string, unknown>> {
    phase: Phase<TContext>;
    config: PhaseConfig<TContext>;
    iterationMetrics: IterationMetric[];
    aggregated: AggregatedMetrics;
    context: TContext;
    segmentCount: number;
    /** Wall-clock elapsed ms for the segment loop (excludes warmup and pauseAfterMs) */
    wallClockMs: number;
}
export interface PhaseGeneratorMetadata<TContext = Record<string, unknown>> {
    phaseNumber: number;
    phaseName: string;
    iterationCount: number;
    burstSegments: number;
    segmentCount: number;
    mode: ExecutionMode;
    history: PhaseResult<TContext>[];
}
export interface PhaseGeneratorPayload<TContext = Record<string, unknown>> {
    result: PhaseResult<TContext>;
    history: PhaseResult<TContext>[];
    metadata: PhaseGeneratorMetadata<TContext>;
}
export interface AggregatedMetrics {
    totalDurationMs: number;
    minMs: number;
    maxMs: number;
    averageMs: number;
    successCount: number;
    failureCount: number;
    loadStart: number;
    loadEnd: number;
}
export interface IterationMetric {
    iteration: number;
    durationMs: number;
    success: boolean;
    meta?: Record<string, unknown>;
    loadFactor: number;
}
export interface HandlerPayload<TContext = Record<string, unknown>> {
    iteration: number;
    config: PhaseConfig<TContext>;
    loadFactor: number;
    context: TContext;
}
export interface HandlerResult {
    success?: boolean;
    meta?: Record<string, unknown>;
}
export type PerformanceHandler<TContext = Record<string, unknown>> = (payload: HandlerPayload<TContext>) => Promise<HandlerResult> | HandlerResult;
export interface CanvasRenderOptions {
    width?: number;
    height?: number;
    padding?: number;
    backgroundColor?: string;
    headerFont?: string;
    rowFont?: string;
    headerColor?: string;
    rowColor?: string;
}
export interface PerformanceScenario<TContext = Record<string, unknown>> {
    name: string;
    handler: PerformanceHandler<TContext>;
    phases: Phase<TContext>[];
    baseContext?: TContext;
    failOnError?: boolean;
    initialize?: () => Promise<void> | void;
    canvasOptions?: CanvasRenderOptions;
    canvasOutputPath?: string;
    enableCanvas?: boolean;
}
export declare const defaultCanvasOptions: Required<CanvasRenderOptions>;
export declare class PerformanceRunner<TContext = Record<string, unknown>> {
    protected readonly scenario: PerformanceScenario<TContext>;
    constructor(scenario: PerformanceScenario<TContext>);
    run(): Promise<PhaseResult<TContext>[]>;
    protected runPhase(phase: Phase<TContext>, context: TContext): Promise<PhaseResult<TContext>>;
    protected runWarmup(phase: Phase<TContext>, context: TContext): Promise<void>;
    protected computeLoadFactor(config: PhaseConfig<TContext>, iteration: number): number;
    protected buildSegmentIndices(iterations: number, burst?: PhaseBurstConfig): number[][];
    protected mergeContext(phase: Phase<TContext>): TContext;
    protected mergeContexts(a: TContext, b: Partial<TContext>): TContext;
    protected executeSegment(handler: PerformanceHandler<TContext>, config: PhaseConfig<TContext>, context: TContext, indices: number[]): Promise<IterationMetric[]>;
    protected collectSequential(handler: PerformanceHandler<TContext>, config: PhaseConfig<TContext>, context: TContext, indices: number[]): Promise<IterationMetric[]>;
    protected collectConcurrent(handler: PerformanceHandler<TContext>, config: PhaseConfig<TContext>, context: TContext, indices: number[]): Promise<IterationMetric[]>;
    protected runIteration(handler: PerformanceHandler<TContext>, config: PhaseConfig<TContext>, context: TContext, iteration: number): Promise<IterationMetric>;
    protected aggregateMetrics(metrics: IterationMetric[]): AggregatedMetrics;
    protected logPhaseTable(result: PhaseResult<TContext>): void;
    protected logSummary(results: PhaseResult<TContext>[]): Promise<void>;
    protected shouldRenderCanvas(): boolean;
}