@decaf-ts/utils 1.0.10 → 1.2.0

package/lib/types/assets/slogans.d.mts

@@ -0,0 +1,19 @@
+/**
+ * @description Definition of a slogan item.
+ * @summary Represents a single slogan entry with text and tags.
+ * @typedef {Object} SloganItem
+ * @property {string} Slogan - The slogan text.
+ * @property {string} Tags - Comma-separated tags describing the slogan.
+ * @memberOf module:utils
+ */
+/**
+ * @description List of available slogans for banners and messages.
+ * @summary Immutable array of slogan entries used by {@link getSlogan} and banner rendering.
+ * @type {SloganItem[]}
+ * @const slogans
+ * @memberOf module:utils
+ */
+export declare const slogans: {
+    Slogan: string;
+    Tags: string;
+}[];

package/lib/types/bin/build-scripts.d.cts

@@ -0,0 +1 @@
+export {};

package/lib/types/bin/build-scripts.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/types/bin/release-chain-dispatch.d.cts

@@ -0,0 +1 @@
+export {};

package/lib/types/bin/release-chain-dispatch.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/types/bin/release-chain.d.cts

@@ -0,0 +1 @@
+export {};

package/lib/types/bin/release-chain.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/types/bin/tag-release.d.cts

@@ -0,0 +1 @@
+export {};

package/lib/types/bin/tag-release.d.mts

@@ -0,0 +1 @@
+export {};

package/lib/types/cli/command.d.cts

@@ -0,0 +1,104 @@
+import { ParseArgsResult } from "../input/types.cjs";
+import { CommandOptions } from "./types.cjs";
+import { DefaultCommandValues } from "./constants.cjs";
+import { LoggedClass, Logger, LoggingConfig } from "@decaf-ts/logging";
+/**
+ * @class Command
+ * @abstract
+ * @template I - The type of input options for the command.
+ * @template R - The return type of the command execution.
+ * @memberOf module:utils
+ * @description Abstract base class for command implementation.
+ * @summary Provides a structure for creating command-line interface commands with input handling, logging, and execution flow.
+ *
+ * @param {string} name - The name of the command.
+ * @param {CommandOptions<I>} [inputs] - The input options for the command.
+ * @param {string[]} [requirements] - The list of required dependencies for the command.
+ */
+export declare abstract class Command<I, R> extends LoggedClass {
+    protected name: string;
+    protected inputs: CommandOptions<I>;
+    protected requirements: string[];
+    /**
+     * @static
+     * @description Static logger for the Command class.
+     * @type {Logger}
+     */
+    static log: Logger;
+    protected constructor(name: string, inputs?: CommandOptions<I>, requirements?: string[]);
+    /**
+     * @protected
+     * @async
+     * @description Checks if all required dependencies are present.
+     * @summary Retrieves the list of dependencies and compares it against the required dependencies for the command.
+     * @returns {Promise<void>} A promise that resolves when the check is complete.
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Command
+     *   participant getDependencies
+     *   participant Set
+     *   Command->>getDependencies: Call
+     *   getDependencies-->>Command: Return {prod, dev, peer}
+     *   Command->>Set: Create Set from prod, dev, peer
+     *   Set-->>Command: Return unique dependencies
+     *   Command->>Command: Compare against requirements
+     *   alt Missing dependencies
+     *     Command->>Command: Add to missing list
+     *   end
+     *   Note over Command: If missing.length > 0, handle missing dependencies
+     */
+    protected checkRequirements(): Promise<void>;
+    /**
+     * @protected
+     * @description Provides help information for the command.
+     * @summary This method should be overridden in derived classes to provide specific help information.
+     * @param {ParseArgsResult} args - The parsed command-line arguments.
+     * @returns {void}
+     */
+    protected help(args: ParseArgsResult): void;
+    /**
+     * @protected
+     * @abstract
+     * @description Runs the command with the provided arguments.
+     * @summary This method should be implemented in derived classes to define the command's behavior.
+     * @param {ParseArgsResult} answers - The parsed command-line arguments.
+     * @returns {Promise<R | string | void>} A promise that resolves with the command's result.
+     */
+    protected abstract run<R>(answers: LoggingConfig & typeof DefaultCommandValues & {
+        [k in keyof I]: unknown;
+    }): Promise<R | string | void>;
+    /**
+     * @async
+     * @description Executes the command.
+     * @summary This method handles the overall execution flow of the command, including parsing arguments,
+     * setting up logging, checking for version or help requests, and running the command.
+     * @returns {Promise<R | string | void>} A promise that resolves with the command's result.
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Command
+     *   participant UserInput
+     *   participant Logging
+     *   participant getPackageVersion
+     *   participant printBanner
+     *   Command->>UserInput: parseArgs(inputs)
+     *   UserInput-->>Command: Return ParseArgsResult
+     *   Command->>Command: Process options
+     *   Command->>Logging: setConfig(options)
+     *   alt version requested
+     *     Command->>getPackageVersion: Call
+     *     getPackageVersion-->>Command: Return version
+     *   else help requested
+     *     Command->>Command: help(args)
+     *   else banner requested
+     *     Command->>printBanner: Call
+     *   end
+     *   Command->>Command: run(args)
+     *   alt error occurs
+     *     Command->>Command: Log error
+     *   end
+     *   Command-->>Command: Return result
+     */
+    execute(): Promise<R | string | void>;
+}

package/lib/types/cli/command.d.mts

@@ -0,0 +1,104 @@
+import { ParseArgsResult } from "../input/types.js";
+import { CommandOptions } from "./types.js";
+import { DefaultCommandValues } from "./constants.js";
+import { LoggedClass, Logger, LoggingConfig } from "@decaf-ts/logging";
+/**
+ * @class Command
+ * @abstract
+ * @template I - The type of input options for the command.
+ * @template R - The return type of the command execution.
+ * @memberOf module:utils
+ * @description Abstract base class for command implementation.
+ * @summary Provides a structure for creating command-line interface commands with input handling, logging, and execution flow.
+ *
+ * @param {string} name - The name of the command.
+ * @param {CommandOptions<I>} [inputs] - The input options for the command.
+ * @param {string[]} [requirements] - The list of required dependencies for the command.
+ */
+export declare abstract class Command<I, R> extends LoggedClass {
+    protected name: string;
+    protected inputs: CommandOptions<I>;
+    protected requirements: string[];
+    /**
+     * @static
+     * @description Static logger for the Command class.
+     * @type {Logger}
+     */
+    static log: Logger;
+    protected constructor(name: string, inputs?: CommandOptions<I>, requirements?: string[]);
+    /**
+     * @protected
+     * @async
+     * @description Checks if all required dependencies are present.
+     * @summary Retrieves the list of dependencies and compares it against the required dependencies for the command.
+     * @returns {Promise<void>} A promise that resolves when the check is complete.
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Command
+     *   participant getDependencies
+     *   participant Set
+     *   Command->>getDependencies: Call
+     *   getDependencies-->>Command: Return {prod, dev, peer}
+     *   Command->>Set: Create Set from prod, dev, peer
+     *   Set-->>Command: Return unique dependencies
+     *   Command->>Command: Compare against requirements
+     *   alt Missing dependencies
+     *     Command->>Command: Add to missing list
+     *   end
+     *   Note over Command: If missing.length > 0, handle missing dependencies
+     */
+    protected checkRequirements(): Promise<void>;
+    /**
+     * @protected
+     * @description Provides help information for the command.
+     * @summary This method should be overridden in derived classes to provide specific help information.
+     * @param {ParseArgsResult} args - The parsed command-line arguments.
+     * @returns {void}
+     */
+    protected help(args: ParseArgsResult): void;
+    /**
+     * @protected
+     * @abstract
+     * @description Runs the command with the provided arguments.
+     * @summary This method should be implemented in derived classes to define the command's behavior.
+     * @param {ParseArgsResult} answers - The parsed command-line arguments.
+     * @returns {Promise<R | string | void>} A promise that resolves with the command's result.
+     */
+    protected abstract run<R>(answers: LoggingConfig & typeof DefaultCommandValues & {
+        [k in keyof I]: unknown;
+    }): Promise<R | string | void>;
+    /**
+     * @async
+     * @description Executes the command.
+     * @summary This method handles the overall execution flow of the command, including parsing arguments,
+     * setting up logging, checking for version or help requests, and running the command.
+     * @returns {Promise<R | string | void>} A promise that resolves with the command's result.
+     *
+     * @mermaid
+     * sequenceDiagram
+     *   participant Command
+     *   participant UserInput
+     *   participant Logging
+     *   participant getPackageVersion
+     *   participant printBanner
+     *   Command->>UserInput: parseArgs(inputs)
+     *   UserInput-->>Command: Return ParseArgsResult
+     *   Command->>Command: Process options
+     *   Command->>Logging: setConfig(options)
+     *   alt version requested
+     *     Command->>getPackageVersion: Call
+     *     getPackageVersion-->>Command: Return version
+     *   else help requested
+     *     Command->>Command: help(args)
+     *   else banner requested
+     *     Command->>printBanner: Call
+     *   end
+     *   Command->>Command: run(args)
+     *   alt error occurs
+     *     Command->>Command: Log error
+     *   end
+     *   Command-->>Command: Return result
+     */
+    execute(): Promise<R | string | void>;
+}

package/lib/types/cli/commands/build-scripts.d.cts

@@ -0,0 +1,148 @@
+import { Command } from "../command.cjs";
+import { CommandOptions } from "../types.cjs";
+import { DefaultCommandValues } from "../constants.cjs";
+import { LoggingConfig } from "@decaf-ts/logging";
+declare module "@rollup/plugin-terser";
+export declare function parseList(input?: string | string[]): string[];
+export declare function packageToGlobal(name: string): string;
+export declare function getPackageDependencies(): string[];
+declare enum Modes {
+    CJS = "commonjs",
+    ESM = "es2022"
+}
+declare enum BuildMode {
+    BUILD = "build",
+    BUNDLE = "bundle",
+    ALL = "all"
+}
+declare const options: {
+    prod: {
+        type: string;
+        default: boolean;
+    };
+    dev: {
+        type: string;
+        default: boolean;
+    };
+    buildMode: {
+        type: string;
+        default: BuildMode;
+    };
+    includes: {
+        type: string;
+        default: string;
+    };
+    externals: {
+        type: string;
+        default: string;
+    };
+    docs: {
+        type: string;
+        default: boolean;
+    };
+    commands: {
+        type: string;
+        default: boolean;
+    };
+    entry: {
+        type: string;
+        default: string;
+    };
+    banner: {
+        type: string;
+        default: boolean;
+    };
+    validateNodeNext: {
+        type: string;
+        default: boolean;
+    };
+};
+/**
+ * @description A command-line script for building and bundling TypeScript projects.
+ * @summary This class provides a comprehensive build script that handles TypeScript compilation,
+ * bundling with Rollup, and documentation generation. It supports different build modes
+ * (development, production), module formats (CJS, ESM), and can be extended with custom
+ * configurations.
+ * @class BuildScripts
+ */
+export declare class BuildScripts extends Command<CommandOptions<typeof options>, void> {
+    private replacements;
+    private readonly pkgVersion;
+    private readonly pkgName;
+    constructor();
+    /**
+     * @description Patches files with version and package name.
+     * @summary This method reads all files in a directory, finds placeholders for version
+     * and package name, and replaces them with the actual values from package.json.
+     * @param {string} p - The path to the directory containing the files to patch.
+     */
+    patchFiles(p: string): void;
+    private reportDiagnostics;
+    private formatDiagnostics;
+    private readConfigFile;
+    private evalDiagnostics;
+    private preCheckDiagnostics;
+    private checkTsDiagnostics;
+    private buildTs;
+    private build;
+    private rewriteRelativeJsSpecifiersToCjs;
+    private buildCjsFromEsm;
+    private applyTsConfigProfile;
+    private checkNodeNextCompatibility;
+    private buildTypes;
+    private rewriteRelativeDeclarationSpecifiers;
+    private emitDualDeclarationFiles;
+    private updatePackageJsonDualTypeExports;
+    /**
+     * @description Copies assets to the build output directory.
+     * @summary This method checks for the existence of an 'assets' directory in the source
+     * and copies it to the appropriate build output directory (lib or dist).
+     * @param {Modes} mode - The build mode (CJS or ESM).
+     */
+    copyAssets(mode: Modes): void;
+    /**
+     * @description Bundles the project using Rollup.
+     * @summary This method configures and runs Rollup to bundle the project. It handles
+     * different module formats, development and production builds, and external dependencies.
+     * @param {Modes} mode - The module format (CJS or ESM).
+     * @param {boolean} isDev - Whether it's a development build.
+     * @param {boolean} isLib - Whether it's a library build.
+     * @param {string} [entryFile="src/index.ts"] - The entry file for the bundle.
+     * @param {string} [nameOverride=this.pkgName] - The name of the output bundle.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @param {string|string[]} [includeArg] - A list of dependencies to include.
+     * @returns {Promise<void>}
+     */
+    bundle(mode: Modes, isDev: boolean, isLib: boolean, entryFile?: string, nameOverride?: string, externalsArg?: string | string[], includeArg?: string | string[]): Promise<void>;
+    private buildByEnv;
+    /**
+     * @description Builds the project for development.
+     * @summary This method runs the build process with development-specific configurations.
+     * @param {BuildMode} [mode=BuildMode.ALL] - The build mode (build, bundle, or all).
+     * @param {string|string[]} [includesArg] - A list of dependencies to include.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @returns {Promise<void>}
+     */
+    buildDev(entryFile?: string, mode?: BuildMode, validateNodeNext?: boolean, includesArg?: string | string[], externalsArg?: string | string[]): Promise<void>;
+    /**
+     * @description Builds the project for production.
+     * @summary This method runs the build process with production-specific configurations,
+     * including minification and other optimizations.
+     * @param {BuildMode} [mode=BuildMode.ALL] - The build mode (build, bundle, or all).
+     * @param {string|string[]} [includesArg] - A list of dependencies to include.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @returns {Promise<void>}
+     */
+    buildProd(entryFile?: string, mode?: BuildMode, validateNodeNext?: boolean, includesArg?: string | string[], externalsArg?: string | string[]): Promise<void>;
+    /**
+     * @description Generates the project documentation.
+     * @summary This method uses JSDoc and other tools to generate HTML documentation for the project.
+     * It also patches the README.md file with version and package size information.
+     * @returns {Promise<void>}
+     */
+    buildDocs(): Promise<void>;
+    protected run<R>(answers: LoggingConfig & typeof DefaultCommandValues & {
+        [k in keyof typeof options]: unknown;
+    }): Promise<string | void | R>;
+}
+export {};

package/lib/types/cli/commands/build-scripts.d.mts

@@ -0,0 +1,148 @@
+import { Command } from "../command.js";
+import { CommandOptions } from "../types.js";
+import { DefaultCommandValues } from "../constants.js";
+import { LoggingConfig } from "@decaf-ts/logging";
+declare module "@rollup/plugin-terser";
+export declare function parseList(input?: string | string[]): string[];
+export declare function packageToGlobal(name: string): string;
+export declare function getPackageDependencies(): string[];
+declare enum Modes {
+    CJS = "commonjs",
+    ESM = "es2022"
+}
+declare enum BuildMode {
+    BUILD = "build",
+    BUNDLE = "bundle",
+    ALL = "all"
+}
+declare const options: {
+    prod: {
+        type: string;
+        default: boolean;
+    };
+    dev: {
+        type: string;
+        default: boolean;
+    };
+    buildMode: {
+        type: string;
+        default: BuildMode;
+    };
+    includes: {
+        type: string;
+        default: string;
+    };
+    externals: {
+        type: string;
+        default: string;
+    };
+    docs: {
+        type: string;
+        default: boolean;
+    };
+    commands: {
+        type: string;
+        default: boolean;
+    };
+    entry: {
+        type: string;
+        default: string;
+    };
+    banner: {
+        type: string;
+        default: boolean;
+    };
+    validateNodeNext: {
+        type: string;
+        default: boolean;
+    };
+};
+/**
+ * @description A command-line script for building and bundling TypeScript projects.
+ * @summary This class provides a comprehensive build script that handles TypeScript compilation,
+ * bundling with Rollup, and documentation generation. It supports different build modes
+ * (development, production), module formats (CJS, ESM), and can be extended with custom
+ * configurations.
+ * @class BuildScripts
+ */
+export declare class BuildScripts extends Command<CommandOptions<typeof options>, void> {
+    private replacements;
+    private readonly pkgVersion;
+    private readonly pkgName;
+    constructor();
+    /**
+     * @description Patches files with version and package name.
+     * @summary This method reads all files in a directory, finds placeholders for version
+     * and package name, and replaces them with the actual values from package.json.
+     * @param {string} p - The path to the directory containing the files to patch.
+     */
+    patchFiles(p: string): void;
+    private reportDiagnostics;
+    private formatDiagnostics;
+    private readConfigFile;
+    private evalDiagnostics;
+    private preCheckDiagnostics;
+    private checkTsDiagnostics;
+    private buildTs;
+    private build;
+    private rewriteRelativeJsSpecifiersToCjs;
+    private buildCjsFromEsm;
+    private applyTsConfigProfile;
+    private checkNodeNextCompatibility;
+    private buildTypes;
+    private rewriteRelativeDeclarationSpecifiers;
+    private emitDualDeclarationFiles;
+    private updatePackageJsonDualTypeExports;
+    /**
+     * @description Copies assets to the build output directory.
+     * @summary This method checks for the existence of an 'assets' directory in the source
+     * and copies it to the appropriate build output directory (lib or dist).
+     * @param {Modes} mode - The build mode (CJS or ESM).
+     */
+    copyAssets(mode: Modes): void;
+    /**
+     * @description Bundles the project using Rollup.
+     * @summary This method configures and runs Rollup to bundle the project. It handles
+     * different module formats, development and production builds, and external dependencies.
+     * @param {Modes} mode - The module format (CJS or ESM).
+     * @param {boolean} isDev - Whether it's a development build.
+     * @param {boolean} isLib - Whether it's a library build.
+     * @param {string} [entryFile="src/index.ts"] - The entry file for the bundle.
+     * @param {string} [nameOverride=this.pkgName] - The name of the output bundle.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @param {string|string[]} [includeArg] - A list of dependencies to include.
+     * @returns {Promise<void>}
+     */
+    bundle(mode: Modes, isDev: boolean, isLib: boolean, entryFile?: string, nameOverride?: string, externalsArg?: string | string[], includeArg?: string | string[]): Promise<void>;
+    private buildByEnv;
+    /**
+     * @description Builds the project for development.
+     * @summary This method runs the build process with development-specific configurations.
+     * @param {BuildMode} [mode=BuildMode.ALL] - The build mode (build, bundle, or all).
+     * @param {string|string[]} [includesArg] - A list of dependencies to include.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @returns {Promise<void>}
+     */
+    buildDev(entryFile?: string, mode?: BuildMode, validateNodeNext?: boolean, includesArg?: string | string[], externalsArg?: string | string[]): Promise<void>;
+    /**
+     * @description Builds the project for production.
+     * @summary This method runs the build process with production-specific configurations,
+     * including minification and other optimizations.
+     * @param {BuildMode} [mode=BuildMode.ALL] - The build mode (build, bundle, or all).
+     * @param {string|string[]} [includesArg] - A list of dependencies to include.
+     * @param {string|string[]} [externalsArg] - A list of external dependencies.
+     * @returns {Promise<void>}
+     */
+    buildProd(entryFile?: string, mode?: BuildMode, validateNodeNext?: boolean, includesArg?: string | string[], externalsArg?: string | string[]): Promise<void>;
+    /**
+     * @description Generates the project documentation.
+     * @summary This method uses JSDoc and other tools to generate HTML documentation for the project.
+     * It also patches the README.md file with version and package size information.
+     * @returns {Promise<void>}
+     */
+    buildDocs(): Promise<void>;
+    protected run<R>(answers: LoggingConfig & typeof DefaultCommandValues & {
+        [k in keyof typeof options]: unknown;
+    }): Promise<string | void | R>;
+}
+export {};

package/lib/types/cli/commands/build-scripts.d.ts

@@ -85,9 +85,14 @@ export declare class BuildScripts extends Command<CommandOptions<typeof options>
     private checkTsDiagnostics;
     private buildTs;
     private build;
+    private rewriteRelativeJsSpecifiersToCjs;
+    private buildCjsFromEsm;
     private applyTsConfigProfile;
     private checkNodeNextCompatibility;
     private buildTypes;
+    private rewriteRelativeDeclarationSpecifiers;
+    private emitDualDeclarationFiles;
+    private updatePackageJsonDualTypeExports;
     /**
      * @description Copies assets to the build output directory.
      * @summary This method checks for the existence of an 'assets' directory in the source

package/lib/types/cli/commands/index.d.cts

@@ -0,0 +1,3 @@
+export * from "./build-scripts.cjs";
+export * from "./tag-release.cjs";
+export * from "./release-chain.cjs";

package/lib/types/cli/commands/index.d.mts

@@ -0,0 +1,3 @@
+export * from "./build-scripts.js";
+export * from "./tag-release.js";
+export * from "./release-chain.js";

package/lib/types/cli/commands/release-chain.d.cts

@@ -0,0 +1,62 @@
+import { Command } from "../command.cjs";
+import { CommandOptions } from "../types.cjs";
+import { DefaultCommandValues } from "../constants.cjs";
+import { LoggingConfig } from "@decaf-ts/logging";
+declare const releaseChainArgs: {
+    meta: {
+        type: string;
+        default: string;
+    };
+    branch: {
+        type: string;
+        default: string;
+    };
+    current: {
+        type: string;
+        default: string;
+    };
+    package: {
+        type: string;
+        default: string;
+    };
+    token: {
+        type: string;
+        default: string;
+    };
+    submoduleFile: {
+        type: string;
+        default: string;
+    };
+    submodulePath: {
+        type: string;
+        default: string;
+    };
+    workflow: {
+        type: string;
+        default: string;
+    };
+    repo: {
+        type: string;
+        default: string;
+    };
+    ref: {
+        type: string;
+        default: string;
+    };
+    targetBase: {
+        type: string;
+        default: string;
+    };
+};
+type ReleaseChainAnswerMap = {
+    [K in keyof typeof releaseChainArgs]: unknown;
+};
+export declare class ReleaseChainCommand extends Command<CommandOptions<typeof releaseChainArgs>, void> {
+    constructor();
+    protected run(options: LoggingConfig & typeof DefaultCommandValues & ReleaseChainAnswerMap): Promise<void>;
+}
+export declare class ReleaseChainDispatchCommand extends Command<CommandOptions<typeof releaseChainArgs>, void> {
+    constructor();
+    protected run(options: LoggingConfig & typeof DefaultCommandValues & ReleaseChainAnswerMap): Promise<void>;
+}
+export {};