@remotex-labs/xbuild 1.1.1 → 1.3.0

package/README.md

@@ -1,91 +1,96 @@
-# @remotex-labs/xbuild
-
-`@remotex-labs/xbuild` is a versatile TypeScript toolchain build system
-
-## Installation
-
-Install `@remotex-labs/xbuild` globally using npm:
-
-```bash
-npm install -g @remotex-labs/xbuild
-```
-
-Or using Yarn:
-
-```bash
-yarn global add @remotex-labs/xbuild
-```
-
-## Usage
-
-Run the `xBuild -h` CLI tool with various options to build your typeScript projects.
-Command-Line Options
-
-```bash
-     ______       _ _     _
-     | ___ \     (_) |   | |
-__  _| |_/ /_   _ _| | __| |
-\ \/ / ___ \ | | | | |/ _` |
- >  <| |_/ / |_| | | | (_| |
-/_/\_\____/ \__,_|_|_|\__,_|
-
-Version: 0.0.2-beta.0
-
-index.js [file]
-
-A versatile JavaScript and TypeScript toolchain build system.
-
-Positionals:
-  entryPoints  The file entryPoints to build                            [string]
-
-Options:
-  -h, --help                  Show help                                [boolean]
-  -n, --node                  Build for node platform [boolean] [default: false]
-  -d, --dev                   Array entryPoints to run for development   [array]
-  -s, --serve                 Serve the build folder over HTTP
-                                                      [boolean] [default: false]
-  -o, --outdir                Output directory        [string] [default: "dist"]
-      --declaration, --de     Add TypeScript declarations
-                                                      [boolean] [default: false]
-  -w, --watch                 Watch for file changes  [boolean] [default: false]
-  -c, --config                Build configuration file (js/ts)
-                                          [string] [default: "xbuild.config.ts"]
-      --tsconfig, --tc        Set TypeScript configuration file to use
-                                             [string] [default: "tsconfig.json"]
-  -m, --minify                Minify the code         [boolean] [default: false]
-  -b, --bundle                Bundle the code         [boolean] [default: false]
-      --noTypeChecker, --ntc  Skip TypeScript type checking
-                                                      [boolean] [default: false]
-      --buildOnError, --boe   Continue building even if there are TypeScript
-                              type errors             [boolean] [default: false]
-  -v, --version               Show version number     [boolean] [default: false]
-
-```
-
-## Configuration
-
-The `xBuild` configuration file allows you to customize various settings for the build and development process. By default, xbuild uses `xbuild.config.ts` (`--config` change it). Here’s how you can configure it:
-
-### Example Configuration
-```typescript
-const config: ConfigurationInterface = {
-    declaration: true,
-    buildOnError: false,
-    noTypeChecker: false,
-    esbuild: {
-        entryPoints: ['./src/index.ts'],
-        bundle: true,
-        minify: true,
-        format: 'esm',
-    },
-    serve: {
-        active: true,
-        port: 8080,
-        host: 'localhost',
-        onRequest: (req, res, next) => {
-            console.log('Server request received');
-            next();
-        }
-    }
-};
-```
+# @remotex-labs/xbuild
+
+`@remotex-labs/xbuild` is a versatile TypeScript toolchain build system
+
+## Installation
+
+Install `@remotex-labs/xbuild` globally using npm:
+
+```bash
+npm install -g @remotex-labs/xbuild
+```
+
+Or using Yarn:
+
+```bash
+yarn global add @remotex-labs/xbuild
+```
+
+## Usage
+
+Run the `xBuild -h` CLI tool with various options to build your typeScript projects.
+Command-Line Options
+
+```bash
+
+
+     ______       _ _     _
+     | ___ \     (_) |   | |
+__  _| |_/ /_   _ _| | __| |
+\ \/ / ___ \ | | | | |/ _` |
+ >  <| |_/ / |_| | | | (_| |
+/_/\_\____/ \__,_|_|_|\__,_|
+
+Version: <xBuild version>
+
+index.js [file]
+
+A versatile JavaScript and TypeScript toolchain build system.
+
+Positionals:
+  entryPoints  The file entryPoints to build                            [string]
+
+Options:
+  -h, --help                  Show help                                [boolean]
+      --typeCheck, --tc       Perform type checking                    [boolean]
+  -n, --node                  Build for node platform                  [boolean]
+  -d, --dev                   Array entryPoints to run as development in Node.js
+                                                                         [array]
+      --debug, --db           Array entryPoints to run in Node.js with debug sta
+                              te                                         [array]
+  -s, --serve                 Serve the build folder over HTTP         [boolean]
+  -o, --outdir                Output directory                          [string]
+      --declaration, --de     Add TypeScript declarations              [boolean]
+  -w, --watch                 Watch for file changes                   [boolean]
+  -c, --config                Build configuration file (js/ts)
+                                          [string] [default: "xbuild.config.ts"]
+      --tsconfig, --tsc       Set TypeScript configuration file to use
+                                             [string] [default: "tsconfig.json"]
+  -m, --minify                Minify the code                          [boolean]
+  -b, --bundle                Bundle the code                          [boolean]
+      --noTypeChecker, --ntc  Skip TypeScript type checking            [boolean]
+      --buildOnError, --boe   Continue building even if there are TypeScript typ
+                              e errors                                 [boolean]
+  -f, --format                Defines the format for the build output ('cjs' | '
+                              esm' | 'iif').                            [string]
+  -v, --version               Show version number     [boolean] [default: false]
+
+```
+
+## Configuration
+
+The `xBuild` configuration file allows you to customize various settings for the build and development process. By default, xbuild uses `xbuild.config.ts` (`--config` change it). Here’s how you can configure it:
+
+### Example Configuration
+```typescript
+const config: ConfigurationInterface = {
+    declaration: true,
+    buildOnError: false,
+    noTypeChecker: false,
+    esbuild: {
+        entryPoints: ['./src/index.ts'],
+        bundle: true,
+        minify: true,
+        format: 'esm',
+    },
+    serve: {
+        active: true,
+        port: 8080,
+        host: 'localhost',
+        onRequest: (req, res, next) => {
+            console.log('Server request received');
+            next();
+        }
+    }
+};
+```

package/dist/components/package-type.component.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Import will remove at compile time
+ */
+import type { ConfigurationInterface } from "../configuration/interfaces/configuration.interface";
+/**
+ * Generates a `package.json` file with the appropriate `type` field
+ * based on the format specified in the configuration.
+ *
+ * - If the format is `esm`, the `type` will be set to `"module"`.
+ * - If the format is `cjs`, the `type` will be set to `"commonjs"`.
+ *
+ * The function will ensure that the output directory exists, and if it doesn't,
+ * it will create the necessary directories before writing the `package.json` file.
+ *
+ * @param {ConfigurationInterface} config - The build configuration object containing
+ * esbuild-related settings, such as the output directory (`outdir`) and format (`format`).
+ *
+ * - `config.esbuild.outdir`: The output directory where the `package.json` will be created.
+ * - `config.esbuild.format`: The module format, either `'esm'` or `'cjs'`, that determines the `type` field.
+ *
+ * @throws Will throw an error if there is a problem creating the directory or writing the file.
+ *
+ * Example usage:
+ *
+ * ```ts
+ * const config = {
+ *   esbuild: {
+ *     outdir: 'dist',
+ *     format: 'esm'
+ *   }
+ * };
+ * packageTypeComponent(config);
+ * // This will create 'dist/package.json' with the content: {"type": "module"}
+ * ```
+ */
+export declare function packageTypeComponent(config: ConfigurationInterface): void;

package/dist/configuration/interfaces/configuration.interface.d.ts

@@ -301,4 +301,51 @@ interface ExportedConfigurationInterface extends ConfigurationInterface {
  * objects where only a subset of properties need to be specified.
  */
 export type xBuildConfig = PartialDeep<ExportedConfigurationInterface>;
+/**
+ * Represents a partially deep configuration type based on the `ConfigurationInterface`.
+ *
+ * This type is used to define configurations that may have some properties
+ * missing or undefined. It leverages the `PartialDeep` utility type to allow
+ * for flexibility in configuration management.
+ */
+export type PartialDeepConfigurationsType = PartialDeep<ConfigurationInterface>;
+/**
+ * Defines the possible types for configurations.
+ *
+ * This type can either be a single instance of `PartialDeepConfigurationsType`
+ * or an array of such instances. This flexibility allows for configurations
+ * to be specified as a single object or as multiple objects, enabling
+ * support for various build setups.
+ *
+ * @example
+ * // A single configuration object
+ * const config: ConfigurationsType = {
+ *     esbuild: {
+ *         bundle: true,
+ *         outdir: 'dist'
+ *     }
+ * };
+ *
+ * @example
+ * ```ts
+ * // An array of configuration objects
+ * const configs: ConfigurationsType = [
+ *     {
+ *         esbuild: {
+ *             bundle: true,
+ *             outdir: 'dist/esm'
+ *         }
+ *     },
+ *     {
+ *         esbuild: {
+ *             bundle: false,
+ *             outdir: 'dist/cjs',
+ *             declaration: false,
+ *             noTypeChecker: true
+ *         }
+ *     }
+ * ];
+ * ```
+ */
+export type ConfigurationsType = PartialDeepConfigurationsType | Array<PartialDeepConfigurationsType>;
 export {};

package/dist/errors/base.error.d.ts

@@ -1,39 +1,21 @@
 /**
  * Import will remove at compile time
  */
-import type { StackEntryInterface } from '@remotex-labs/xmap';
-import { SourceService } from '@remotex-labs/xmap';
 /**
- * Constants
+ * Imports
  */
-export declare const dirname: string;
-export declare const sourceMapData: Buffer;
-export declare const defaultSourceService: SourceService;
+import type { SourceService } from '@remotex-labs/xmap';
+import type { ErrorType } from "./interfaces/stack.interface";
 /**
  * A base class for custom errors with enhanced stack trace formatting and source code information.
  *
  * The `BaseError` class extends the native `Error` class, adding functionality to format the error stack
  * trace and include details from a source map service. This is useful for debugging errors in compiled
  * or transpiled code by providing clearer information about the source of the error.
- *
- * @augments Error
  */
 export declare abstract class BaseError extends Error {
-    protected sourceMap: SourceService;
-    /**
-     * An array to hold the formatted lines of the stack trace.
-     *
-     * This property contains the enhanced stack trace of the error, formatted using source map information,
-     * if available.
-     */
-    stackArray: Array<string>;
-    /**
-     * The code block related to the error.
-     *
-     * This property holds a string representing the code snippet where the error occurred. It is formatted
-     * for better readability and is set based on the source map details.
-     */
-    blockCode: string | null;
+    readonly sourceMap?: SourceService | undefined;
+    callStacks: Array<NodeJS.CallSite>;
     /**
      * Creates a new instance of `BaseError`.
      *
@@ -46,16 +28,7 @@ export declare abstract class BaseError extends Error {
      * @param sourceMap - (Optional) The `SourceService` instance used to format and resolve the stack trace.
      *                    If not provided, the default source map service (`defaultSourceService`) is used.
      */
-    protected constructor(message: string, sourceMap?: SourceService);
-    /**
-     * Converts the error object to a formatted string.
-     *
-     * This method provides a string representation of the `BaseError` instance, including the error name,
-     * message, and an enhanced stack trace. It also includes the code block related to the error if available.
-     *
-     * @returns A string that represents the formatted error message and stack trace.
-     */
-    toString(): string;
+    protected constructor(message: string, sourceMap?: SourceService | undefined);
     /**
      * Reformats the error stack trace using source map information.
      *
@@ -63,39 +36,8 @@ export declare abstract class BaseError extends Error {
      * back to its original position in the source file using the provided source map service.
      * If the source map information is not available, it returns the original stack trace.
      *
-     * @param stack - The original stack trace of the error.
+     * @param error - The original error with stack trace of the error.
      * @returns The reformatted stack trace or the original stack trace if no mapping is available.
      */
-    protected reformatStack(stack: string | undefined): string | undefined;
-    /**
-     * Gets the formatted stack entries based on the provided source map service.
-     *
-     * This method processes each stack trace entry, resolves its original position using
-     * the source map service, and formats it accordingly. If the source position is available,
-     * the corresponding code block is also highlighted.
-     *
-     * @param stackEntries - An array of stack trace entries.
-     * @param sourceMap - The source map service used to resolve the stack trace to original source positions.
-     * @returns An array of formatted stack trace entries.
-     */
-    protected getFormattedStackEntries(stackEntries: StackEntryInterface[], sourceMap: SourceService): string[];
-    /**
-     * Updates the block code property if it has not been set yet.
-     *
-     * This method highlights the code snippet associated with the given position and formats it
-     * for better readability. The `blockCode` property is only updated once with the highlighted code.
-     *
-     * @param position - The position object containing the code snippet to be highlighted.
-     */
-    private updateBlockCodeIfNecessary;
-    /**
-     * Constructs the file path with the source root and line number information.
-     *
-     * This method ensures that the file path is correctly formatted with the source root (if available)
-     * and appends the line number for reference.
-     *
-     * @param position - The position object containing source file path and source root.
-     * @returns The formatted file path with line number.
-     */
-    private getFilePathWithSourceRoot;
+    protected reformatStack(error: ErrorType): string;
 }

package/dist/errors/interfaces/stack.interface.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A custom error type that extends the native `Error` object by adding a `callStacks` property.
+ * This property contains an array of `NodeJS.CallSite` objects, representing the call stack details.
+ */
+import type { BaseError } from "../base.error";
+/**
+ * Represents an enhanced error type that extends the built-in Error object.
+ * This type adds an optional property to store call stack information.
+ *
+ * @type ErrorType
+ *
+ * @extends {Error}
+ *
+ * @property callStacks - An optional array of call sites
+ *   captured when the error was created. This can provide additional context
+ *   regarding the call stack at the time of the error, useful for debugging.
+ *
+ * @example
+ * ```ts
+ * const myError: ErrorType = new Error("Something went wrong!");
+ * myError.callStacks = getCallStack(); // Assuming getCallStack captures call sites.
+ * console.error(myError);
+ * ```
+ */
+export type ErrorType = Error & {
+    callStacks?: Array<NodeJS.CallSite>;
+};
+/**
+ * Represents the state of a stack trace, containing information about the error, associated code, and formatted error message.
+ *
+ * @interface StackTraceStateInterface
+ * @property error - The error object with attached `callStacks`.
+ * @property blockCode - The block of code (if any) related to the error, or `null` if unavailable.
+ * @property formattedError - A formatted string representing the error details.
+ */
+export interface StackTraceStateInterface {
+    error: ErrorType & BaseError;
+    blockCode: null | string;
+    formattedError: string;
+}
+/**
+ * Represents detailed information about a specific frame in the call stack.
+ *
+ * @interface FrameDetailsInterface
+ * @property line - The line number where the frame occurred.
+ * @property column - The column number where the frame occurred.
+ * @property source - The source file path where the frame occurred.
+ * @property functionName - The name of the function being executed at this frame, or an empty string if not available.
+ */
+export interface FrameDetailsInterface {
+    line: number;
+    column: number;
+    source: string;
+    functionName: string;
+}

package/dist/errors/stack.error.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Import will remove at compile time
+ */
+import type { BaseError } from ".//base.error";
+import type { ErrorType } from "./interfaces/stack.interface";
+import { SourceService } from '@remotex-labs/xmap';
+export declare const xBuildLazy: {
+    readonly service: SourceService;
+};
+/**
+ * Prepares the error stack trace for display.
+ *
+ * This function overrides the default stack trace preparation to provide a custom format,
+ * including enhanced stack trace information and error details.
+ *
+ * @param error - The error object (Error or BaseError).
+ * @param stackEntries - The array of stack entries from the call stack.
+ * @returns The formatted stack trace as a string.
+ */
+export declare function formatStackTrace(error: ErrorType & BaseError, stackEntries: Array<NodeJS.CallSite>): string;

package/dist/errors/uncaught.error.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Handles uncaught exceptions in the Node.js process.
+ *
+ * This handler is triggered when an error is thrown that is not caught by any try-catch blocks.
+ * It captures such exceptions and logs them to the console. If the exception is an instance of `Error`,
+ * its string representation is logged. Otherwise, the raw error object is logged.
+ *
+ * This setup helps in debugging by ensuring that all uncaught exceptions are logged, providing visibility
+ * into errors that might otherwise go unnoticed.
+ *
+ * @example
+ * ```ts
+ * process.on('uncaughtException', (error) => {
+ *     if (error instanceof Error) {
+ *         console.error(error.toString());
+ *     } else {
+ *         console.error(error);
+ *     }
+ * });
+ * ```
+ *
+ * @throws Will log uncaught exceptions to the console.
+ * Custom handling logic should be added if additional error handling or logging is required.
+ */
+export {};

package/dist/errors/vm-runtime.error.d.ts

@@ -2,6 +2,7 @@
  * Import will remove at compile time
  */
 import type { SourceService } from '@remotex-labs/xmap';
+import type { ErrorType } from "./interfaces/stack.interface";
 /**
  * Imports
  */
@@ -31,6 +32,10 @@ export declare class VMRuntimeError extends BaseError {
      * The original error thrown during the VM execution.
      */
     originalError: Error;
+    /**
+     * Original error stack
+     */
+    originalErrorStack: string | undefined;
     /**
      * Creates a new VMRuntimeError instance.
      *
@@ -52,5 +57,5 @@ export declare class VMRuntimeError extends BaseError {
      * }
      * ```
      */
-    constructor(originalError: Error, sourceMap?: SourceService);
+    constructor(originalError: ErrorType, sourceMap?: SourceService);
 }

package/dist/errors/xbuild.error.d.ts

@@ -12,6 +12,10 @@ import { BaseError } from ".//base.error";
  * @augments BaseError
  */
 export declare class xBuildError extends BaseError {
+    /**
+     * Original error stack
+     */
+    originalErrorStack: string | undefined;
     /**
      * Creates an instance of `xBuildError`.
      *
@@ -21,8 +25,4 @@ export declare class xBuildError extends BaseError {
      *   that customize the error's behavior.
      */
     constructor(message: string, options?: ErrorOptions);
-    /**
-     * Set external stack
-     */
-    setStack(stack: string): void;
 }

package/dist/index.d.ts

@@ -4,3 +4,8 @@
  */
 export type * from "./configuration/interfaces/configuration.interface";
 export type { BuildResult, OnLoadArgs, OnLoadResult, OnResolveArgs, OnResolveResult, PluginBuild } from 'esbuild';
+/**
+ * Imports
+ */
+import "./errors/stack.error";
+import "./errors/uncaught.error";