@decaf-ts/utils 1.2.3 → 1.3.1

package/lib/types/utils/fs.d.ts

@@ -1,259 +0,0 @@
-import fs from "fs";
-import { DependencyMap, SimpleDependencyMap } from "./types";
-/**
- * @description Patches a file with given values.
- * @summary Reads a file, applies patches using TextUtils, and writes the result back to the file.
- *
- * @param {string} path - The path to the file to be patched.
- * @param {Record<string, number | string>} values - The values to patch into the file.
- * @return {void}
- *
- * @function patchFile
- *
- * @mermaid
- * sequenceDiagram
- *   participant Caller
- *   participant patchFile
- *   participant fs
- *   participant readFile
- *   participant TextUtils
- *   participant writeFile
- *   Caller->>patchFile: Call with path and values
- *   patchFile->>fs: Check if file exists
- *   patchFile->>readFile: Read file content
- *   readFile->>fs: Read file
- *   fs-->>readFile: Return file content
- *   readFile-->>patchFile: Return file content
- *   patchFile->>TextUtils: Patch string
- *   TextUtils-->>patchFile: Return patched content
- *   patchFile->>writeFile: Write patched content
- *   writeFile->>fs: Write to file
- *   fs-->>writeFile: File written
- *   writeFile-->>patchFile: File written
- *   patchFile-->>Caller: Patching complete
- *
- * @memberOf module:utils
- */
-export declare function patchFile(path: string, values: Record<string, number | string>, filter?: (str: string) => boolean): void;
-/**
- * @description Reads a file and returns its content.
- * @summary Reads the content of a file at the specified path and returns it as a string.
- *
- * @param {string} path - The path to the file to be read.
- * @return {string} The content of the file.
- *
- * @function readFile
- *
- * @memberOf module:utils
- */
-export declare function readFile(path: string): string;
-/**
- * @description Writes data to a file.
- * @summary Writes the provided data to a file at the specified path.
- *
- * @param {string} path - The path to the file to be written.
- * @param {string | Buffer} data - The data to be written to the file.
- * @return {void}
- *
- * @function writeFile
- *
- * @memberOf module:utils
- */
-export declare function writeFile(path: string, data: string | Buffer): void;
-/**
- * @description Retrieves all files recursively from a directory.
- * @summary Traverses through directories and subdirectories to collect all file paths.
- *
- * @param {string} p - The path to start searching from.
- * @param {function} [filter] - Optional function to filter files by name or index.
- * @return {string[]} Array of file paths.
- *
- * @function getAllFiles
- *
- * @memberOf module:utils
- */
-export declare function getAllFiles(p: string, filter?: (f: string, i?: number) => boolean): string[];
-/**
- * @description Renames a file or directory.
- * @summary Moves a file or directory from the source path to the destination path.
- *
- * @param {string} source - The source path of the file or directory.
- * @param {string} dest - The destination path for the file or directory.
- * @return {Promise<void>} A promise that resolves when the rename operation is complete.
- *
- * @function renameFile
- *
- * @memberOf module:utils
- */
-export declare function renameFile(source: string, dest: string): Promise<void>;
-/**
- * @description Copies a file or directory.
- * @summary Creates a copy of a file or directory from the source path to the destination path.
- *
- * @param {string} source - The source path of the file or directory.
- * @param {string} dest - The destination path for the file or directory.
- * @return {void}
- *
- * @function copyFile
- *
- * @memberOf module:utils
- */
-export declare function copyFile(source: string, dest: string): void;
-/**
- * @description Deletes a file or directory.
- * @summary Removes a file or directory at the specified path, with recursive and force options enabled.
- *
- * @param {string} p - The path to the file or directory to delete.
- * @return {void}
- *
- * @function deletePath
- *
- * @memberOf module:utils
- */
-export declare function deletePath(p: string): void;
-/**
- * @description Retrieves package information from package.json.
- * @summary Loads and parses the package.json file from a specified directory or the current working directory. Can return the entire package object or a specific property.
- * @param {string} [p=process.cwd()] - The directory path where the package.json file is located.
- * @param {string} [property] - Optional. The specific property to retrieve from package.json.
- * @return {object | string} The parsed contents of package.json or the value of the specified property.
- * @function getPackage
- * @mermaid
- * sequenceDiagram
- *   participant Caller
- *   participant getPackage
- *   participant readFile
- *   participant JSON
- *   Caller->>getPackage: Call with path and optional property
- *   getPackage->>readFile: Read package.json
- *   readFile-->>getPackage: Return file content
- *   getPackage->>JSON: Parse file content
- *   JSON-->>getPackage: Return parsed object
- *   alt property specified
- *     getPackage->>getPackage: Check if property exists
- *     alt property exists
- *       getPackage-->>Caller: Return property value
- *     else property doesn't exist
- *       getPackage-->>Caller: Throw Error
- *     end
- *   else no property specified
- *     getPackage-->>Caller: Return entire package object
- *   end
- * @memberOf module:utils
- */
-export declare function getPackage(p?: string, property?: string): object | string;
-/**
- * @description Sets an attribute in the package.json file.
- * @summary Updates a specific attribute in the package.json file with the provided value.
- *
- * @param {string} attr - The attribute name to set in package.json.
- * @param {string | number | object} value - The value to set for the attribute.
- * @param {string} [p=process.cwd()] - The directory path where the package.json file is located.
- * @return {void}
- *
- * @function setPackageAttribute
- *
- * @memberOf module:utils
- */
-export declare function setPackageAttribute(attr: string, value: string, p?: string): void;
-/**
- * @description Retrieves the version from package.json.
- * @summary A convenience function that calls getPackage to retrieve the "version" property from package.json.
- * @param {string} [p=process.cwd()] - The directory path where the package.json file is located.
- * @return {string} The version string from package.json.
- * @function getPackageVersion
- * @memberOf module:utils
- */
-export declare function getPackageVersion(p?: string): string;
-/**
- * @description Retrieves all dependencies from the project.
- * @summary Executes 'npm ls --json' command to get a detailed list of all dependencies (production, development, and peer) and their versions.
- * @param {string} [path=process.cwd()] - The directory path of the project.
- * @return {Promise<{prod: Array<{name: string, version: string}>, dev: Array<{name: string, version: string}>, peer: Array<{name: string, version: string}>}>} An object containing arrays of production, development, and peer dependencies.
- * @function getDependencies
- * @mermaid
- * sequenceDiagram
- *   participant Caller
- *   participant getDependencies
- *   participant runCommand
- *   participant JSON
- *   Caller->>getDependencies: Call with optional path
- *   getDependencies->>runCommand: Execute 'npm ls --json'
- *   runCommand-->>getDependencies: Return command output
- *   getDependencies->>JSON: Parse command output
- *   JSON-->>getDependencies: Return parsed object
- *   getDependencies->>getDependencies: Process dependencies
- *   getDependencies-->>Caller: Return processed dependencies
- * @memberOf module:utils
- */
-export declare function getDependencies(p?: string): Promise<DependencyMap>;
-/**
- * @description Updates project dependencies to their latest versions.
- * @summary Runs npm-check-updates to update package.json and then installs the updated dependencies.
- *
- * @return {Promise<void>} A promise that resolves when dependencies are updated.
- *
- * @function updateDependencies
- *
- * @memberOf module:utils
- */
-export declare function updateDependencies(): Promise<void>;
-/**
- * @description Installs dependencies if they are not already available.
- * @summary Checks if specified dependencies are installed and installs any that are missing.
- *
- * @param {string[] | string} deps - The dependencies to check and potentially install.
- * @param {SimpleDependencyMap} [dependencies] - Optional map of existing dependencies.
- * @return {Promise<SimpleDependencyMap>} Updated map of dependencies.
- *
- * @function installIfNotAvailable
- *
- * @memberOf module:utils
- */
-export declare function installIfNotAvailable(deps: string[] | string, dependencies?: SimpleDependencyMap): Promise<SimpleDependencyMap>;
-/**
- * @description Pushes changes to Git repository.
- * @summary Temporarily changes Git user configuration, commits all changes, pushes to remote, and restores original user configuration.
- *
- * @return {Promise<void>} A promise that resolves when changes are pushed.
- *
- * @function pushToGit
- *
- * @memberOf module:utils
- */
-export declare function pushToGit(): Promise<void>;
-/**
- * @description Installs project dependencies.
- * @summary Installs production, development, and peer dependencies as specified.
- *
- * @param {object} dependencies - Object containing arrays of dependencies to install.
- * @param {string[]} [dependencies.prod] - Production dependencies to install.
- * @param {string[]} [dependencies.dev] - Development dependencies to install.
- * @param {string[]} [dependencies.peer] - Peer dependencies to install.
- * @return {Promise<void>} A promise that resolves when all dependencies are installed.
- *
- * @function installDependencies
- *
- * @memberOf module:utils
- */
-export declare function installDependencies(dependencies: {
-    prod?: string[];
-    dev?: string[];
-    peer?: string[];
-}): Promise<void>;
-/**
- * @description Normalizes imports to handle both CommonJS and ESModule formats.
- * @summary Utility function to handle module import differences between formats.
- *
- * @template T - Type of the imported module.
- * @param {Promise<T>} importPromise - Promise returned by dynamic import.
- * @return {Promise<T>} Normalized module.
- *
- * @function normalizeImport
- *
- * @memberOf module:utils
- */
-export declare function normalizeImport<T>(importPromise: Promise<T>): Promise<T>;
-export declare function getFileSizeZipped(dir: string): Promise<number>;
-export declare function listFolder(basePath?: string, filter?: (name: string, dirent: fs.Dirent) => boolean): string[];
-export declare function listNodeModulesPackages(basePath?: string): string[];

package/lib/types/utils/http.d.ts

@@ -1,41 +0,0 @@
-/**
- * @description A simple HTTP client for downloading files.
- * @summary This class provides functionality to download files from HTTPS URLs.
- * It uses Node.js built-in https module to make requests.
- *
- * @class HttpClient
- */
-export declare class HttpClient {
-    protected static log: import("@decaf-ts/logging").Logger;
-    /**
-     * @description Downloads a file from a given URL.
-     * @summary This method sends a GET request to the specified URL and returns the response body as a string.
-     * It handles different scenarios such as non-200 status codes and network errors.
-     *
-     * @param url - The URL of the file to download.
-     * @return A promise that resolves with the file content as a string.
-     *
-     * @mermaid
-     * sequenceDiagram
-     *   participant Client
-     *   participant HttpClient
-     *   participant HTTPS
-     *   participant Server
-     *   Client->>HttpClient: downloadFile(url)
-     *   HttpClient->>HTTPS: get(url)
-     *   HTTPS->>Server: GET request
-     *   Server-->>HTTPS: Response
-     *   HTTPS-->>HttpClient: Response object
-     *   alt Status code is 200
-     *     loop For each data chunk
-     *       HTTPS->>HttpClient: 'data' event
-     *       HttpClient->>HttpClient: Accumulate data
-     *     end
-     *     HTTPS->>HttpClient: 'end' event
-     *     HttpClient-->>Client: Resolve with data
-     *   else Status code is not 200
-     *     HttpClient-->>Client: Reject with error
-     *   end
-     */
-    static downloadFile(url: string): Promise<string>;
-}

package/lib/types/utils/index.d.ts

@@ -1,6 +0,0 @@
-export * from "./constants";
-export * from "./fs";
-export * from "./http";
-export * from "./types";
-export * from "./utils";
-export * from "./performanceRunner";

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

@@ -1,156 +0,0 @@
-/**
- * @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.ts

@@ -1,129 +0,0 @@
-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.ts

@@ -1,12 +0,0 @@
-/**
- * @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>;