@decaf-ts/utils 1.1.0 → 1.2.0

package/lib/types/utils/md.d.cts

@@ -0,0 +1,156 @@
+/**
+ * @description Single line markdown element type
+ * @summary Represents the possible header levels in markdown
+ * @typedef {"h1"|"h2"|"h3"|"h4"|"h5"|"h6"} MdSingleLineElement
+ * @memberOf module:utils
+ */
+export type MdSingleLineElement = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+/**
+ * @description Multi-line element types in markdown
+ * @summary Defines the available multi-line element types
+ * @typedef {"p"|"blockquote"} MdMultiLineElement
+ * @memberOf module:utils
+ */
+export type MdMultiLineElement = "p" | "blockquote";
+/**
+ * @description List element types in markdown
+ * @summary Defines the available list types
+ * @typedef {"ul"|"ol"} MdListElement
+ * @memberOf module:utils
+ */
+export type MdListElement = "ul" | "ol";
+/**
+ * @description List element types in markdown
+ * @summary Defines the available list types
+ * @typedef {Object} MdSingleLine
+ * @property {string} [ul] - unordered list
+ * @property {string} [ol] - ordered list
+ * @memberOf module:utils
+ */
+export type MdSingleLine = {
+    [k in MdSingleLineElement]?: string;
+};
+/**
+ * @description Multi-line markdown element type
+ * @summary Represents markdown elements that can contain multiple lines of text
+ * @typedef {Object} MdMultiLine
+ * @property {string|string[]} [p] - Paragraph content
+ * @property {string|string[]} [blockquote] - Blockquote content
+ * @memberOf module:utils
+ */
+export type MdMultiLine = {
+    [k in MdMultiLineElement]?: string | string[];
+};
+/**
+ * @description Image definition type in markdown
+ * @summary Defines the structure for image elements
+ * @typedef {Object} MdImageDefinition
+ * @property {string} [title] - Optional image title
+ * @property {string} source - Image source URL
+ * @property {string} [alt] - Optional alternative text
+ * @memberOf module:utils
+ */
+export type MdImageDefinition = {
+    title?: string;
+    source: string;
+    alt?: string;
+};
+/**
+ * @description Image element type in markdown
+ * @summary Represents an image element with its properties
+ * @typedef {Object} MdImage
+ * @property {MdImageDefinition} img - The image definition object
+ * @memberOf module:utils
+ */
+export type MdImage = {
+    img: MdImageDefinition;
+};
+/**
+ * @description List item element type in markdown
+ * @summary Represents ordered and unordered lists in markdown
+ * @typedef {Object} MdListItem
+ * @property {string[]} ul - Unordered list items
+ * @property {string[]} ol - Ordered list items
+ * @memberOf module:utils
+ */
+export type MdListItem = {
+    [k in MdListElement]: string[];
+};
+/**
+ * @description Table definition type in markdown
+ * @summary Defines the structure for table elements
+ * @typedef {Object} MdTableDefinition
+ * @property {string[]} headers - Array of table header names
+ * @property {Object[]} rows - Array of row objects containing column values
+ * @memberOf module:utils
+ */
+export type MdTableDefinition = {
+    headers: string[];
+    rows: {
+        [column: string]: string | string[];
+    }[];
+};
+/**
+ * @description Table element type in markdown
+ * @summary Represents a table structure with headers and rows
+ * @typedef {Object} MdTable
+ * @property {MdTableDefinition} table - The table definition object
+ * @memberOf module:utils
+ */
+export type MdTable = {
+    table: MdTableDefinition;
+};
+/**
+ * @description Code block definition type in markdown
+ * @summary Defines the structure for code blocks
+ * @typedef {Object} MdCodeDefinition
+ * @property {string} [language] - Optional programming language specification
+ * @property {string|string[]} content - The code content as string or array of strings
+ * @memberOf module:utils
+ */
+export type MdCodeDefinition = {
+    language?: string;
+    content: string | string[];
+};
+/**
+ * @description Code block element type in markdown
+ * @summary Represents a code block with optional language specification
+ * @typedef {Object} MdCode
+ * @property {MdCodeDefinition} code - The code block definition object
+ * @memberOf module:utils
+ */
+export type MdCode = {
+    code: MdCodeDefinition;
+};
+/**
+ * @description Horizontal rule element type in markdown
+ * @summary Represents a horizontal rule separator
+ * @typedef {Object} MdSeparator
+ * @property {string} hr - The horizontal rule representation
+ * @memberOf module:utils
+ */
+export type MdSeparator = {
+    hr: string;
+};
+/**
+ * @description Link element type in markdown
+ * @summary Represents a hyperlink with title and source
+ * @typedef {Object} MdLink
+ * @property {{title: string, source: string}} link - The link definition object
+ * @memberOf module:utils
+ */
+export type MdLink = {
+    link: {
+        title: string;
+        source: string;
+    };
+};
+/**
+ * @description Markdown element type definition
+ * @summary Represents all possible markdown elements that can be used in document generation.
+ * This type combines various markdown elements including headers, paragraphs, images, lists,
+ * tables, code blocks, separators, and links into a union type for flexible markdown content creation.
+ * @typedef {(MdSingleLine | MdMultiLine | MdImage | MdListItem | MdTable | MdCode | MdSeparator | MdLink)} MdElements
+ * @memberOf module:utils
+ */
+export type MdElements = MdSingleLine | MdMultiLine | MdImage | MdListItem | MdTable | MdCode | MdSeparator | MdLink;

package/lib/types/utils/md.d.mts

@@ -0,0 +1,156 @@
+/**
+ * @description Single line markdown element type
+ * @summary Represents the possible header levels in markdown
+ * @typedef {"h1"|"h2"|"h3"|"h4"|"h5"|"h6"} MdSingleLineElement
+ * @memberOf module:utils
+ */
+export type MdSingleLineElement = "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+/**
+ * @description Multi-line element types in markdown
+ * @summary Defines the available multi-line element types
+ * @typedef {"p"|"blockquote"} MdMultiLineElement
+ * @memberOf module:utils
+ */
+export type MdMultiLineElement = "p" | "blockquote";
+/**
+ * @description List element types in markdown
+ * @summary Defines the available list types
+ * @typedef {"ul"|"ol"} MdListElement
+ * @memberOf module:utils
+ */
+export type MdListElement = "ul" | "ol";
+/**
+ * @description List element types in markdown
+ * @summary Defines the available list types
+ * @typedef {Object} MdSingleLine
+ * @property {string} [ul] - unordered list
+ * @property {string} [ol] - ordered list
+ * @memberOf module:utils
+ */
+export type MdSingleLine = {
+    [k in MdSingleLineElement]?: string;
+};
+/**
+ * @description Multi-line markdown element type
+ * @summary Represents markdown elements that can contain multiple lines of text
+ * @typedef {Object} MdMultiLine
+ * @property {string|string[]} [p] - Paragraph content
+ * @property {string|string[]} [blockquote] - Blockquote content
+ * @memberOf module:utils
+ */
+export type MdMultiLine = {
+    [k in MdMultiLineElement]?: string | string[];
+};
+/**
+ * @description Image definition type in markdown
+ * @summary Defines the structure for image elements
+ * @typedef {Object} MdImageDefinition
+ * @property {string} [title] - Optional image title
+ * @property {string} source - Image source URL
+ * @property {string} [alt] - Optional alternative text
+ * @memberOf module:utils
+ */
+export type MdImageDefinition = {
+    title?: string;
+    source: string;
+    alt?: string;
+};
+/**
+ * @description Image element type in markdown
+ * @summary Represents an image element with its properties
+ * @typedef {Object} MdImage
+ * @property {MdImageDefinition} img - The image definition object
+ * @memberOf module:utils
+ */
+export type MdImage = {
+    img: MdImageDefinition;
+};
+/**
+ * @description List item element type in markdown
+ * @summary Represents ordered and unordered lists in markdown
+ * @typedef {Object} MdListItem
+ * @property {string[]} ul - Unordered list items
+ * @property {string[]} ol - Ordered list items
+ * @memberOf module:utils
+ */
+export type MdListItem = {
+    [k in MdListElement]: string[];
+};
+/**
+ * @description Table definition type in markdown
+ * @summary Defines the structure for table elements
+ * @typedef {Object} MdTableDefinition
+ * @property {string[]} headers - Array of table header names
+ * @property {Object[]} rows - Array of row objects containing column values
+ * @memberOf module:utils
+ */
+export type MdTableDefinition = {
+    headers: string[];
+    rows: {
+        [column: string]: string | string[];
+    }[];
+};
+/**
+ * @description Table element type in markdown
+ * @summary Represents a table structure with headers and rows
+ * @typedef {Object} MdTable
+ * @property {MdTableDefinition} table - The table definition object
+ * @memberOf module:utils
+ */
+export type MdTable = {
+    table: MdTableDefinition;
+};
+/**
+ * @description Code block definition type in markdown
+ * @summary Defines the structure for code blocks
+ * @typedef {Object} MdCodeDefinition
+ * @property {string} [language] - Optional programming language specification
+ * @property {string|string[]} content - The code content as string or array of strings
+ * @memberOf module:utils
+ */
+export type MdCodeDefinition = {
+    language?: string;
+    content: string | string[];
+};
+/**
+ * @description Code block element type in markdown
+ * @summary Represents a code block with optional language specification
+ * @typedef {Object} MdCode
+ * @property {MdCodeDefinition} code - The code block definition object
+ * @memberOf module:utils
+ */
+export type MdCode = {
+    code: MdCodeDefinition;
+};
+/**
+ * @description Horizontal rule element type in markdown
+ * @summary Represents a horizontal rule separator
+ * @typedef {Object} MdSeparator
+ * @property {string} hr - The horizontal rule representation
+ * @memberOf module:utils
+ */
+export type MdSeparator = {
+    hr: string;
+};
+/**
+ * @description Link element type in markdown
+ * @summary Represents a hyperlink with title and source
+ * @typedef {Object} MdLink
+ * @property {{title: string, source: string}} link - The link definition object
+ * @memberOf module:utils
+ */
+export type MdLink = {
+    link: {
+        title: string;
+        source: string;
+    };
+};
+/**
+ * @description Markdown element type definition
+ * @summary Represents all possible markdown elements that can be used in document generation.
+ * This type combines various markdown elements including headers, paragraphs, images, lists,
+ * tables, code blocks, separators, and links into a union type for flexible markdown content creation.
+ * @typedef {(MdSingleLine | MdMultiLine | MdImage | MdListItem | MdTable | MdCode | MdSeparator | MdLink)} MdElements
+ * @memberOf module:utils
+ */
+export type MdElements = MdSingleLine | MdMultiLine | MdImage | MdListItem | MdTable | MdCode | MdSeparator | MdLink;

package/lib/types/utils/performanceRunner.d.cts

@@ -0,0 +1,129 @@
+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;
+}

package/lib/types/utils/performanceRunner.d.mts

@@ -0,0 +1,129 @@
+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;
+}

package/lib/types/utils/timeout.d.cts

@@ -0,0 +1,12 @@
+/**
+ * @description Creates a promise that resolves after a specified time.
+ * @summary Utility function that pauses execution for a given number of milliseconds.
+ *
+ * @param {number} ms - The number of milliseconds to wait.
+ * @return {Promise<void>} A promise that resolves after the specified timeout.
+ *
+ * @function awaitTimeout
+ *
+ * @memberOf module:utils
+ */
+export declare function awaitTimeout(ms: number): Promise<void>;

package/lib/types/utils/timeout.d.mts

@@ -0,0 +1,12 @@
+/**
+ * @description Creates a promise that resolves after a specified time.
+ * @summary Utility function that pauses execution for a given number of milliseconds.
+ *
+ * @param {number} ms - The number of milliseconds to wait.
+ * @return {Promise<void>} A promise that resolves after the specified timeout.
+ *
+ * @function awaitTimeout
+ *
+ * @memberOf module:utils
+ */
+export declare function awaitTimeout(ms: number): Promise<void>;