@ix-xs/node-comfort 1.0.4 → 1.0.5

package/types/src/logger.d.ts

@@ -0,0 +1,132 @@
+/**
+* @param {*} content
+*/
+export function log(content: any): {
+    log(content: any): /*elided*/ any;
+    /**
+   * @param {any} content - Content to format.
+   * @returns {string} Formatted string.
+   */
+    logify(content: any): string;
+    /**
+   * @param {string} label
+   */
+    group(label: string): /*elided*/ any;
+    groupEnd(): /*elided*/ any;
+    /**
+   * @param {object} [options]
+   * @param {object} [options.delimiters]
+   * @param {string} [options.delimiters.start="<%="]
+   * @param {string} [options.delimiters.end="%>"]
+   * @param {boolean} [options.timestamp=true]
+   */
+    setLogger(options?: {
+        delimiters?: {
+            start?: string;
+            end?: string;
+        };
+        timestamp?: boolean;
+    }): /*elided*/ any;
+};
+/**
+* @param {any} content - Content to format.
+* @returns {string} Formatted string.
+*/
+export function logify(content: any): string;
+/**
+* @param {string} label
+*/
+export function group(label: string): {
+    /**
+   * @param {*} content
+   */
+    log(content: any): /*elided*/ any;
+    /**
+   * @param {any} content - Content to format.
+   * @returns {string} Formatted string.
+   */
+    logify(content: any): string;
+    group(label: string): /*elided*/ any;
+    groupEnd(): /*elided*/ any;
+    /**
+   * @param {object} [options]
+   * @param {object} [options.delimiters]
+   * @param {string} [options.delimiters.start="<%="]
+   * @param {string} [options.delimiters.end="%>"]
+   * @param {boolean} [options.timestamp=true]
+   */
+    setLogger(options?: {
+        delimiters?: {
+            start?: string;
+            end?: string;
+        };
+        timestamp?: boolean;
+    }): /*elided*/ any;
+};
+export function groupEnd(): {
+    /**
+   * @param {*} content
+   */
+    log(content: any): /*elided*/ any;
+    /**
+   * @param {any} content - Content to format.
+   * @returns {string} Formatted string.
+   */
+    logify(content: any): string;
+    /**
+   * @param {string} label
+   */
+    group(label: string): /*elided*/ any;
+    groupEnd(): /*elided*/ any;
+    /**
+   * @param {object} [options]
+   * @param {object} [options.delimiters]
+   * @param {string} [options.delimiters.start="<%="]
+   * @param {string} [options.delimiters.end="%>"]
+   * @param {boolean} [options.timestamp=true]
+   */
+    setLogger(options?: {
+        delimiters?: {
+            start?: string;
+            end?: string;
+        };
+        timestamp?: boolean;
+    }): /*elided*/ any;
+};
+/**
+* @param {object} [options]
+* @param {object} [options.delimiters]
+* @param {string} [options.delimiters.start="<%="]
+* @param {string} [options.delimiters.end="%>"]
+* @param {boolean} [options.timestamp=true]
+*/
+export function setLogger(options?: {
+    delimiters?: {
+        start?: string;
+        end?: string;
+    };
+    timestamp?: boolean;
+}): {
+    /**
+   * @param {*} content
+   */
+    log(content: any): /*elided*/ any;
+    /**
+   * @param {any} content - Content to format.
+   * @returns {string} Formatted string.
+   */
+    logify(content: any): string;
+    /**
+   * @param {string} label
+   */
+    group(label: string): /*elided*/ any;
+    groupEnd(): /*elided*/ any;
+    setLogger(options?: {
+        delimiters?: {
+            start?: string;
+            end?: string;
+        };
+        timestamp?: boolean;
+    }): /*elided*/ any;
+};
+//# sourceMappingURL=logger.d.ts.map

package/types/src/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/logger.js"],"names":[],"mappings":"AA8JE;;EAEC;AACD,6BAFS,GAAC;iBAAD,GAAC;IAkCV;;;KAGC;oBAFQ,GAAG,GACD,MAAM;IAejB;;KAEC;iBADQ,MAAM;;IAYf;;;;;;KAMC;wBAJA;QAAyB,UAAU,GACnC;YAAoC,KAAK,GAAjC,MAAM;YACsB,GAAG,GAA/B,MAAM;SACd;QAA0B,SAAS,GAA3B,OAAO;KAA0B;EApCzC;AACD;;;EAGC;AACD,gCAHS,GAAG,GACD,MAAM,CAchB;AACD;;EAEC;AACD,6BAFS,MAAM;IArDf;;KAEC;iBADQ,GAAC;IAkCV;;;KAGC;oBAFQ,GAAG,GACD,MAAM;iBAgBR,MAAM;;IAYf;;;;;;KAMC;wBAJA;QAAyB,UAAU,GACnC;YAAoC,KAAK,GAAjC,MAAM;YACsB,GAAG,GAA/B,MAAM;SACd;QAA0B,SAAS,GAA3B,OAAO;KAA0B;EAVzC;AACD;IA7DA;;KAEC;iBADQ,GAAC;IAkCV;;;KAGC;oBAFQ,GAAG,GACD,MAAM;IAejB;;KAEC;iBADQ,MAAM;;IAYf;;;;;;KAMC;wBAJA;QAAyB,UAAU,GACnC;YAAoC,KAAK,GAAjC,MAAM;YACsB,GAAG,GAA/B,MAAM;SACd;QAA0B,SAAS,GAA3B,OAAO;KAA0B;EANzC;AACD;;;;;;EAMC;AACD,oCALC;IAAyB,UAAU,GACnC;QAAoC,KAAK,GAAjC,MAAM;QACsB,GAAG,GAA/B,MAAM;KACd;IAA0B,SAAS,GAA3B,OAAO;CAA0B;IAtE1C;;KAEC;iBADQ,GAAC;IAkCV;;;KAGC;oBAFQ,GAAG,GACD,MAAM;IAejB;;KAEC;iBADQ,MAAM;;wBAcd;QAAyB,UAAU,GACnC;YAAoC,KAAK,GAAjC,MAAM;YACsB,GAAG,GAA/B,MAAM;SACd;QAA0B,SAAS,GAA3B,OAAO;KAA0B;EAazC"}

package/types/src/utils.d.ts

@@ -0,0 +1,92 @@
+/**
+   * @param {number} ms
+   */
+export function wait(ms: number): Promise<any>;
+/**
+ * Polls a predicate at a given interval and emits events when it matches or times out.
+ *
+ * The predicate is evaluated every `options.interval` milliseconds (default: 50 ms).
+ * Be careful with the default interval: 50 ms is very frequent polling and can be
+ * unnecessarily CPU‑intensive if your predicate or trigger handlers are heavy.
+ * When `options.max` is `null`, the predicate can match indefinitely (infinite triggers),
+ * so you should choose an interval that makes sense for your use‑case.
+ *
+ * @param {boolean|Promise<boolean>|(() => boolean|Promise<boolean>)} predicate
+ *        Condition to evaluate at each tick, or a function returning it.
+ * @param {*} payload
+ *        Value passed to listeners when events are emitted (e.g. an object or message).
+ * @param {object} [options]
+ * @param {number} [options.interval=50]
+ *        Polling interval in milliseconds. Increase this value if your predicate is
+ *        expensive or you expect many triggers without a `max` limit.
+ * @param {number|null} [options.timeout=null]
+ *        Maximum time in milliseconds before emitting a "timeout" event and stopping.
+ *        If `null`, no timeout is applied.
+ * @param {number|null} [options.max=null]
+ *        Maximum number of successful predicate evaluations ("trigger" events) before
+ *        automatically stopping. If `null`, triggers are infinite until `stop()` is called.
+ *
+ * @example
+ * // Basic usage: infinite triggers every 50 ms (default interval) – use with caution.
+ * const task = when(() => true, { message: "Ok" });
+ *
+ * task.on("trigger", (payload) => {
+ *   console.log(payload.message);
+ *   // task.stop(); // stop when you’re done
+ * });
+ *
+ * task.start();
+ *
+ * @example
+ * // Safer usage: limit triggers and/or lower polling frequency.
+ * when(() => true, { message: "Ok" }, { max: 1, interval: 500 }) // one trigger max, every 500 ms
+ *   .on("trigger", (payload) => {
+ *     console.log(payload.message);
+ *   })
+ *   .start();
+ */
+export function when(predicate: boolean | Promise<boolean> | (() => boolean | Promise<boolean>), payload?: any, options?: {
+    interval?: number;
+    timeout?: number | null;
+    max?: number | null;
+}): {
+    start(): /*elided*/ any;
+    stop(): /*elided*/ any;
+    /**
+     * @typedef { "error" | "trigger" | "timeout" } EventNames
+     * @typedef {{
+     * error: (error) => void|Promise<void>,
+     * trigger: (payload) => void|Promise<void>,
+     * timeout: (payload) => void|Promise<void>,
+     * }} EventHandlers
+     */
+    /**
+     * @template {EventNames} E
+           * @param {E} event
+           * @param {EventHandlers[E]} handler
+           */
+    on<E extends "error" | "trigger" | "timeout">(event: E, handler: {
+        error: (error: any) => void | Promise<void>;
+        trigger: (payload: any) => void | Promise<void>;
+        timeout: (payload: any) => void | Promise<void>;
+    }[E]): /*elided*/ any;
+};
+export function dontCrash(): {
+    /**
+           * @template { "error" | "exit" | "sig" | "beforeExit" } E
+           * @param { E } event
+           * @param { { error: (error: Error | unknown) => void | Promise<void>, exit: (code: number) => void | Promise<void>, sig: (signal: "SIGINT" | "SIGTERM" | "SIGQUIT") => void | Promise<void>, beforeExit: (code: number) => void|Promise<void> }[E] } handler
+           */
+    on<E extends "error" | "exit" | "sig" | "beforeExit">(event: E, handler: {
+        error: (error: Error | unknown) => void | Promise<void>;
+        exit: (code: number) => void | Promise<void>;
+        sig: (signal: "SIGINT" | "SIGTERM" | "SIGQUIT") => void | Promise<void>;
+        beforeExit: (code: number) => void | Promise<void>;
+    }[E]): /*elided*/ any;
+};
+/**
+ * @param {*} value
+ */
+export function JSONString(value: any): string;
+export function JSONParse(value: any): any;
+//# sourceMappingURL=utils.d.ts.map

package/types/src/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/utils.js"],"names":[],"mappings":"AAGE;;KAEE;AACF,yBAFU,MAAM,gBAIf;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,gCAlCW,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,GAAC,CAAC,MAAM,OAAO,GAAC,OAAO,CAAC,OAAO,CAAC,CAAC,YAEzD,GAAC,YAGT;IAAyB,QAAQ,GAAzB,MAAM;IAGgB,OAAO,GAA7B,MAAM,GAAC,IAAI;IAGW,GAAG,GAAzB,MAAM,GAAC,IAAI;CAInB;;;IAiHC;;;;;;;OAOG;IACH;;;;aAIA;OAH0B,CAAC,SAAd,+BAAY,SACjB,CAAC;eAPC,CAAC,KAAK,KAAA,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC;iBAC3B,CAAC,OAAO,KAAA,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC;iBAC/B,CAAC,OAAO,KAAA,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC;;EAe9C;AACD;IAgBI;;;;aAIA;OAHsD,CAAC,SAA3C,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,YAAc,SAC5C,CAAC,WACD;QAAE,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,GAAG,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAAC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAC,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC,CAAC,CAAC;EA4BnP;AACD;;GAEG;AACH,kCAFW,GAAC,UAIX;AACD,2CAEC"}

package/core/CLI.js

@@ -1,95 +0,0 @@
-const { spawn, execSync } = require("node:child_process");
-const EventEmitter = require("node:events");
-
-class cli_stream {
-  #processus;
-  #events = new EventEmitter();
-
-  constructor(command, args) {
-    this.#processus = spawn(command, args, {
-      shell: true,
-      stdio: ["ignore", "pipe", "pipe"],
-    });
-
-    this.#processus.stdout.on("data", (data) => {
-      this.#events.emit("data", data.toString());
-    });
-    this.#processus.stderr.on("data", (data) => {
-      this.#events.emit("data", data.toString());
-    });
-    this.#processus.on("error", (error) => {
-      this.#events.emit("error", error);
-    });
-    this.#processus.on("exit", async (code, signal) => {
-      await this.stop();
-    });
-    this.#processus.on("close", (code, signal) => {
-      this.#events.emit("stopped", code, signal);
-    });
-  }
-
-  /**
-	 * @typedef {"error"|"data"|"stopped"} EventName
-	 * @typedef {{
-	 * error: (error: Error) => void|Promise<void>,
-	 * data: (message: string) => void|Promise<void>,
-	 * stopped: (code: number, signal: keyof import("node:child_process").ChildProcessEventMap) => void|Promise<void>,
-	 * }} EventHandler
-	 */
-  /**
-	 * @template {EventName} E
-	 * @param {E} event
-	 * @param {EventHandler[E]} handler
-	 */
-  on(event, handler) {
-    this.#events.on(event, handler);
-    return this;
-  }
-
-  async stop() {
-    return new Promise((resolve) => {
-      if (!this.#processus || this.#processus.killed) {
-        this.#processus = null;
-        return resolve();
-      }
-
-      let resolved = false;
-
-      const done = () => {
-        if (!resolved) {
-          resolved = true;
-          this.#processus = null;
-          resolve();
-        }
-      };
-
-      this.#processus.once("exit", done);
-
-      this.#processus.kill("SIGTERM");
-
-      setTimeout(() => {
-        if (this.#processus && !this.#processus.killed && !resolved) {
-          this.#processus.kill("SIGKILL");
-        }
-        done();
-      }, 5000);
-    });
-  }
-}
-
-/**
- * @module CLI
- * @description
- */
-module.exports = {
-  /**
-	 * @param {string} command
-	 */
-  cli_run: (command) => {
-    return execSync(command, {
-      shell: true,
-      stdio: "pipe",
-    });
-  },
-  cli_stream,
-};

package/core/Checker.js

@@ -1,127 +0,0 @@
-const { types } = require("node:util");
-
-/**
- * @module Checker
- * @description
- * Provides a collection of utility functions for checking JavaScript value types.
- *
- * These helpers wrap common JavaScript type checks and selected `node:util.types`
- * methods for specific built-in objects such as Map, Set, Date, and Error.
- *
- * @example
- * const nodeComfort = require("@ix-xs/node-comfort");
- *
- * console.log(nodeComfort.isArray([1, 2, 3])); // true
- * console.log(nodeComfort.isNumber(42)); // true
- * console.log(nodeComfort.isDate(new Date())); // true
- */
-
-module.exports = {
-  /**
-	 * Checks if the value is an array.
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is an array, otherwise `false`.
-	 */
-  isArray(value) {
-    return Array.isArray(value);
-  },
-
-  /**
-	 * Checks if the value is a valid number (not NaN).
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is a valid number, otherwise `false`.
-	 */
-  isNumber(value) {
-    return typeof value === "number" && !Number.isNaN(value);
-  },
-
-  /**
-	 * Checks if the value is a function.
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is a function, otherwise `false`.
-	 */
-  isFunction(value) {
-    return typeof value === "function";
-  },
-
-  /**
-	 * Checks if the value is an object (and not `null`).
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is a non-null object, otherwise `false`.
-	 */
-  isObject(value) {
-    return typeof value === "object" && value !== null;
-  },
-
-  /**
-	 * Checks if the value is a boolean.
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is a boolean, otherwise `false`.
-	 */
-  isBoolean(value) {
-    return typeof value === "boolean";
-  },
-
-  /**
-	 * Checks if the value is a string.
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is a string, otherwise `false`.
-	 */
-  isString(value) {
-    return typeof value === "string";
-  },
-
-  /**
-	 * Checks if the value is `undefined`.
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is `undefined`, otherwise `false`.
-	 */
-  isUndefined(value) {
-    return typeof value === "undefined";
-  },
-
-  /**
-	 * Checks if the value is `null`.
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is `null`, otherwise `false`.
-	 */
-  isNull(value) {
-    return value === null;
-  },
-
-  /**
-	 * Checks if the value is a valid `Date` object.
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is an instance of `Date`, otherwise `false`.
-	 */
-  isDate(value) {
-    return types.isDate(value);
-  },
-
-  /**
-	 * Checks if the value is a `Map` instance.
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is a Map, otherwise `false`.
-	 */
-  isMap(value) {
-    return types.isMap(value);
-  },
-
-  /**
-	 * Checks if the value is a `Set` instance.
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is a Set, otherwise `false`.
-	 */
-  isSet(value) {
-    return types.isSet(value);
-  },
-
-  /**
-	 * Checks if the value is a native JavaScript error (`Error`, `TypeError`, etc.).
-	 * @param {*} value - The value to check.
-	 * @returns {boolean} Returns `true` if the value is a native error, otherwise `false`.
-	 */
-  isError(value) {
-    return types.isNativeError(value);
-  },
-};

package/core/Stepper.js

@@ -1,115 +0,0 @@
-/**
- * @module Stepper
- * @description
- * Fluent step controller for sequential task execution with navigation, skipping, and indexing.
- *
- * Perfect for CLI wizards, build pipelines, tutorials, or any sequential workflow.
- * Supports forward/backward navigation, jumping to specific steps, ignoring steps, and reset.
- *
- * @example
- * const nodeComfort = require("@ix-xs/node-comfort");
- *
- * // Simple 3-step process
- * nodeComfort.step([
- *   () => console.log("Step 1: Validate config"),
- *   () => console.log("Step 2: Build assets"),
- *   () => console.log("Step 3: Deploy")
- * ])
- *   .next().next().next(); // Execute all steps
- *
- * // Interactive navigation
- * const wizard = nodeComfort.step([
- *   () => nodeComfort.log("<%yellow 1%> Enter name"),
- *   () => nodeComfort.log("<%yellow 2%> Enter email"),
- *   () => nodeComfort.log("<%green ✓%> Complete!")
- * ]);
- *
- * wizard.next().back().ignore().next(); // 1 → back to 0 → skip 1 → execute 2
- */
-module.exports = {
-  /**
-	 * Creates a step controller for sequential function execution.
-	 *
-	 * Returns fluent API with `next()`, `back()`, `at()`, `ignore()`, `reset()` methods.
-	 *
-	 * @param {Array<() => void>} steps - Array of step functions to execute.
-	 *
-	 * @example
-	 * const steps = nodeComfort.step([
-	 *   () => console.log("Install dependencies"),
-	 *   () => console.log("Compile TypeScript"),
-	 *   () => console.log("Run tests")
-	 * ]);
-	 *
-	 * steps.next().next(); // Execute steps 0, 1
-	 * steps.back();        // Go back to step 0
-	 * steps.at(2);         // Jump to step 2
-	 */
-  step(steps) {
-    let i = -1;
-
-    const _ = {
-      currentIndex: i,
-      currentStep: steps[i],
-      /**
-			 * Advances to next step and executes it (if exists).
-			 */
-      next() {
-        if (i < steps.length - 1) {
-          i++;
-          if (typeof steps[i] === "function") steps[i]();
-        }
-        return _;
-      },
-      /**
-			 * Goes back to previous step and re-executes it (if exists).
-			 */
-      back() {
-        if (i > 0) {
-          i--;
-          if (typeof steps[i] === "function") steps[i]();
-        }
-        return _;
-      },
-      /**
-			 * Jumps to specific step index and executes it.
-			 * @param {number} index - Step index (0 to steps.length-1).
-			 * @example
-			 * steps.at(2); // Jump to 3rd step
-			 */
-      at(index) {
-        if (index >= 0 && index < steps.length) {
-          i = index;
-          if (typeof steps[i] === "function") steps[i]();
-        }
-        return _;
-      },
-      /**
-			 * Advances index without executing current step.
-			 * @example
-			 * steps.next().ignore().next(); // Execute 0, skip 1, execute 2
-			 */
-      ignore() {
-        if (i < steps.length - 1) {
-          i++;
-        }
-        return _;
-      },
-      /**
-			 * Resets to initial state (index: -1).
-			 */
-      reset() {
-        i = -1;
-        return _;
-      },
-      all() {
-        while (i < steps.length - 1) {
-          this.next();
-        }
-        return _;
-      },
-    };
-
-    return _;
-  },
-};