@decaf-ts/utils 0.1.6

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

@@ -0,0 +1,133 @@
+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:fs-utils
+ */
+export declare function patchFile(path: string, values: Record<string, number | string>): 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 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;
+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:fs-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:fs-utils
+ */
+export declare function getDependencies(path?: string): Promise<DependencyMap>;
+export declare function updateDependencies(): Promise<void>;
+export declare function installIfNotAvailable(deps: string[] | string, dependencies?: SimpleDependencyMap): Promise<SimpleDependencyMap>;
+export declare function pushToGit(): Promise<void>;
+export declare function installDependencies(dependencies: {
+    prod?: string[];
+    dev?: string[];
+    peer?: string[];
+}): Promise<void>;
+export declare function normalizeImport<T>(importPromise: Promise<T>): Promise<T>;

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

@@ -0,0 +1,41 @@
+/**
+ * @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
+ */
+export declare class HttpClient {
+    protected static log: import("..").VerbosityLogger;
+    /**
+     * @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/dist/types/utils/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./constants";
+export * from "./environment";
+export * from "./fs";
+export * from "./http";
+export * from "./text";
+export * from "./types";
+export * from "./utils";

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

@@ -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 @decaf-ts/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 @decaf-ts/utils
+ */
+export type MdMultiLineElement = "p" | "blockquote";
+/**
+ * @description List element types in markdown
+ * @summary Defines the available list types
+ * @typedef {"ul"|"ol"} MdListElement
+ * @memberOf @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/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 @decaf-ts/utils
+ */
+export type MdElements = MdSingleLine | MdMultiLine | MdImage | MdListItem | MdTable | MdCode | MdSeparator | MdLink;

package/dist/types/utils/tests.d.ts

@@ -0,0 +1,170 @@
+import { MdTableDefinition } from "./md";
+/**
+ * @interface AddAttachParams
+ * @description Parameters for adding an attachment to a report
+ * @summary Interface for attachment parameters
+ * @memberOf module:@decaf-ts/utils
+ */
+export interface AddAttachParams {
+    attach: string | Buffer;
+    description: string | object;
+    context?: any;
+    bufferFormat?: string;
+}
+/**
+ * @interface AddMsgParams
+ * @description Parameters for adding a message to a report
+ * @summary Interface for message parameters
+ * @memberOf module:@decaf-ts/utils
+ */
+export interface AddMsgParams {
+    message: string | object;
+    context?: any;
+}
+/**
+ * @typedef {("json"|"image"|"text"|"md")} PayloadType
+ * @description Types of payloads that can be handled
+ * @summary Union type for payload types
+ * @memberOf module:@decaf-ts/utils
+ */
+export type PayloadType = "json" | "image" | "text" | "md";
+export declare const JestReportersTempPathEnvKey = "JEST_HTML_REPORTERS_TEMP_DIR_PATH";
+/**
+ * @description Test reporting utility class for managing test results and evidence
+ * @summary A comprehensive test reporter that handles various types of test artifacts including messages,
+ * attachments, data, images, tables, and graphs. It provides methods to report and store test evidence
+ * in different formats and manages dependencies for reporting functionality.
+ *
+ * @template T - Type of data being reported
+ * @param {string} [testCase="tests"] - Name of the test case
+ * @param {string} [basePath] - Base path for storing test reports
+ * @class
+ *
+ * @example
+ * ```typescript
+ * const reporter = new TestReporter('login-test');
+ *
+ * // Report test messages
+ * await reporter.reportMessage('Test Started', 'Login flow initiated');
+ *
+ * // Report test data
+ * await reporter.reportData('user-credentials', { username: 'test' }, 'json');
+ *
+ * // Report test results table
+ * await reporter.reportTable('test-results', {
+ *   headers: ['Step', 'Status'],
+ *   rows: [
+ *     { Step: 'Login', Status: 'Pass' },
+ *     { Step: 'Validation', Status: 'Pass' }
+ *   ]
+ * });
+ *
+ * // Report test evidence
+ * await reporter.reportAttachment('Screenshot', screenshotBuffer);
+ * ```
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Client
+ *   participant TestReporter
+ *   participant FileSystem
+ *   participant Dependencies
+ *
+ *   Client->>TestReporter: new TestReporter(testCase, basePath)
+ *   TestReporter->>FileSystem: Create report directory
+ *
+ *   alt Report Message
+ *     Client->>TestReporter: reportMessage(title, message)
+ *     TestReporter->>Dependencies: Import helpers
+ *     TestReporter->>FileSystem: Store message
+ *   else Report Data
+ *     Client->>TestReporter: reportData(reference, data, type)
+ *     TestReporter->>Dependencies: Process data
+ *     TestReporter->>FileSystem: Store formatted data
+ *   else Report Table
+ *     Client->>TestReporter: reportTable(reference, tableDef)
+ *     TestReporter->>Dependencies: Convert to MD format
+ *     TestReporter->>FileSystem: Store table
+ *   end
+ */
+export declare class TestReporter {
+    protected testCase: string;
+    protected basePath: string;
+    /**
+     * @description Function for adding messages to the test report
+     * @summary Static handler for processing and storing test messages
+     * @type {function(AddMsgParams): Promise<void>}
+     */
+    protected static addMsgFunction: (params: AddMsgParams) => Promise<void>;
+    /**
+     * @description Function for adding attachments to the test report
+     * @summary Static handler for processing and storing test attachments
+     * @type {function(AddAttachParams): Promise<void>}
+     */
+    protected static addAttachFunction: (params: AddAttachParams) => Promise<void>;
+    /**
+     * @description Map of dependencies required by the reporter
+     * @summary Stores the current state of dependencies
+     * @type {SimpleDependencyMap}
+     */
+    private deps?;
+    constructor(testCase?: string, basePath?: string);
+    /**
+     * @description Imports required helper functions
+     * @summary Ensures all necessary dependencies are available and imports helper functions
+     * @return {Promise<void>} Promise that resolves when helpers are imported
+     */
+    private importHelpers;
+    /**
+     * @description Reports a message to the test report
+     * @summary Adds a formatted message to the test report with an optional title
+     * @param {string} title - Title of the message
+     * @param {string | object} message - Content of the message
+     * @return {Promise<void>} Promise that resolves when the message is reported
+     */
+    reportMessage(title: string, message: string | object): Promise<void>;
+    /**
+     * @description Reports an attachment to the test report
+     * @summary Adds a formatted message to the test report with an optional title
+     * @param {string} title - Title of the message
+     * @param {string | Buffer} attachment - Content of the message
+     * @return {Promise<void>} Promise that resolves when the message is reported
+     */
+    reportAttachment(title: string, attachment: string | Buffer): Promise<void>;
+    /**
+     * @description Reports data with specified type
+     * @summary Processes and stores data in the test report with formatting
+     * @param {string} reference - Reference identifier for the data
+     * @param {string | number | object} data - Data to be reported
+     * @param {PayloadType} type - Type of the payload
+     * @param {boolean} [trim=false] - Whether to trim the data
+     * @return {Promise<void>} Promise that resolves when data is reported
+     */
+    protected report(reference: string, data: string | number | object | Buffer, type: PayloadType, trim?: boolean): Promise<void>;
+    reportData(reference: string, data: string | number | object, type?: PayloadType, trim?: boolean): Promise<void>;
+    reportObject(reference: string, json: object, trim?: boolean): Promise<void>;
+    /**
+     * @description Reports a table in markdown format
+     * @summary Converts and stores a table definition in markdown format
+     * @param {string} reference - Reference identifier for the table
+     * @param {MdTableDefinition} tableDef - Table definition object
+     * @return {Promise<void>} Promise that resolves when table is reported
+     */
+    reportTable(reference: string, tableDef: MdTableDefinition): Promise<void>;
+    /**
+     * @description Reports a graph using Chart.js
+     * @summary Generates and stores a graph visualization
+     * @param {string} reference - Reference identifier for the graph
+     * @param {any} config - Chart.js configuration object
+     * @return {Promise<void>} Promise that resolves when graph is reported
+     */
+    reportGraph(reference: string, config: any): Promise<void>;
+    /**
+     * @description Reports an image to the test report
+     * @summary Stores an image buffer in the test report
+     * @param {string} reference - Reference identifier for the image
+     * @param {Buffer} buffer - Image data buffer
+     * @return {Promise<void>} Promise that resolves when image is reported
+     */
+    reportImage(reference: string, buffer: Buffer): Promise<void>;
+}

package/dist/types/utils/text.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @description Pads the end of a string with a specified character.
+ * @summary Extends the input string to a specified length by adding a padding character to the end.
+ * If the input string is already longer than the specified length, it is returned unchanged.
+ *
+ * @param {string} str - The input string to be padded.
+ * @param {number} length - The desired total length of the resulting string.
+ * @param {string} [char=" "] - The character to use for padding. Defaults to a space.
+ * @return {string} The padded string.
+ * @throws {Error} If the padding character is not exactly one character long.
+ *
+ * @function padEnd
+ *
+ * @memberOf module:TextUtils
+ */
+export declare function padEnd(str: string, length: number, char?: string): string;
+/**
+ * @description Replaces placeholders in a string with provided values.
+ * @summary Interpolates a string by replacing placeholders of the form ${variableName}
+ * with corresponding values from the provided object. If a placeholder doesn't have
+ * a corresponding value, it is left unchanged in the string.
+ *
+ * @param {string} input - The input string containing placeholders to be replaced.
+ * @param {Record<string, number | string>} values - An object containing key-value pairs for replacement.
+ * @return {string} The interpolated string with placeholders replaced by their corresponding values.
+ *
+ * @function patchPlaceholders
+ *
+ * @mermaid
+ * sequenceDiagram
+ *   participant Caller
+ *   participant patchString
+ *   participant String.replace
+ *   Caller->>patchString: Call with input and values
+ *   patchString->>String.replace: Call with regex and replacement function
+ *   String.replace->>patchString: Return replaced string
+ *   patchString-->>Caller: Return patched string
+ *
+ * @memberOf module:TextUtils
+ */
+export declare function patchPlaceholders(input: string, values: Record<string, number | string>): string;
+export declare function patchString(input: string, values: Record<string, number | string>, flags?: string): string;
+/**
+ * @description Converts a string to camelCase.
+ * @summary Transforms the input string into camelCase format, where words are joined without spaces
+ * and each word after the first starts with a capital letter.
+ *
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to camelCase.
+ *
+ * @function toCamelCase
+ *
+ * @memberOf module:TextUtils
+ */
+export declare function toCamelCase(text: string): string;
+/**
+ * @description Converts a string to ENVIRONMENT_VARIABLE format.
+ * @summary Transforms the input string into uppercase with words separated by underscores,
+ * typically used for environment variable names.
+ *
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to ENVIRONMENT_VARIABLE format.
+ *
+ * @function toENVFormat
+ *
+ * @memberOf module:TextUtils
+ */
+export declare function toENVFormat(text: string): string;
+/**
+ * @description Converts a string to snake_case.
+ * @summary Transforms the input string into lowercase with words separated by underscores.
+ *
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to snake_case.
+ *
+ * @function toSnakeCase
+ *
+ * @memberOf module:TextUtils
+ */
+export declare function toSnakeCase(text: string): string;
+/**
+ * @description Converts a string to kebab-case.
+ * @summary Transforms the input string into lowercase with words separated by hyphens.
+ *
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to kebab-case.
+ *
+ * @function toKebabCase
+ *
+ * @memberOf module:TextUtils
+ */
+export declare function toKebabCase(text: string): string;
+/**
+ * @description Converts a string to PascalCase.
+ * @summary Transforms the input string into PascalCase format, where words are joined without spaces
+ * and each word starts with a capital letter.
+ *
+ * @param {string} text - The input string to be converted.
+ * @return {string} The input string converted to PascalCase.
+ *
+ * @function toPascalCase
+ *
+ * @memberOf module:TextUtils
+ */
+export declare function toPascalCase(text: string): string;
+export declare function escapeRegExp(string: string): string;

package/dist/types/utils/timeout.d.ts

@@ -0,0 +1 @@
+export declare function awaitTimeout(ms: number): Promise<void>;