@ix-xs/node-comfort 1.0.0

package/core/Logger.js

@@ -0,0 +1,321 @@
+const _x = "\x1B";
+const _style = {
+  normal: 0,
+  bold: 1,
+  italic: 3,
+  underline: 4,
+  overline: 9,
+};
+const _color = {
+  fg: {
+    black: 30,
+    red: 31,
+    green: 32,
+    yellow: 33,
+    blue: 34,
+    magenta: 35,
+    cyan: 36,
+    white: 37,
+    gray: 90,
+    redBright: 91,
+    greenBright: 92,
+    yellowBright: 93,
+    blueBright: 94,
+    magentaBright: 95,
+    cyanBright: 96,
+    whiteBright: 97,
+    rgb: 38,
+  },
+  bg: {
+    black: 40,
+    red: 41,
+    green: 42,
+    yellow: 43,
+    blue: 44,
+    magenta: 45,
+    cyan: 46,
+    white: 47,
+    gray: 100,
+    redBright: 101,
+    greenBright: 102,
+    yellowBright: 103,
+    blueBright: 104,
+    magentaBright: 105,
+    cyanBright: 106,
+    whiteBright: 107,
+    rgb: 48,
+  },
+};
+const _options = {
+  delimiters: {
+    start: "<%",
+    end: "%>",
+  },
+  timestamp: true,
+};
+const _groups = [];
+
+/**
+ * Gets ANSI escape code for style/color.
+ * @private
+ * @param {string} name - Style or color name.
+ * @returns {number|null} ANSI code or null.
+ */
+const _getCode = (name) => {
+  if (_style[name] !== undefined) return _style[name];
+  if (_color.fg[name] !== undefined) return _color.fg[name];
+  if (name.startsWith("bg")) {
+    const bg = name.charAt(2).toLowerCase() + name.slice(3);
+    if (_color.bg[bg] !== undefined) return _color.bg[bg];
+  }
+  return null;
+};
+
+/**
+ * Parses template tokens into styles and text.
+ * @private
+ * @param {string} input - Template string.
+ * @returns {{codes: number[], text: string}} Parsed result.
+ */
+const _parse = (input) => {
+  const tokens = input.trim().split(/\s+/);
+  const styles = [];
+  const fgs = [];
+  const bgs = [];
+  const txts = [];
+
+  for (const token of tokens) {
+    const code = _getCode(token);
+    if (code === null) {
+      txts.push(token);
+    } else {
+      if (_style[token] !== undefined) {
+        styles.push(code);
+      } else if (token.startsWith("bg")) {
+        bgs.push(code);
+      } else {
+        fgs.push(code);
+      }
+    }
+  }
+
+  const codes = [...styles, ...bgs, ...fgs];
+  const text = input
+		.replace(
+		  /^\s*((redBright|greenBright|yellowBright|blueBright|magentaBright|cyanBright|whiteBright|red|green|yellow|blue|magenta|cyan|white|gray|black|bold|italic|underline|overline|bg\w+|\s+)*)/gi,
+		  "",
+		)
+		.trimStart();
+  return { codes, text };
+};
+
+/**
+ * Builds ANSI escape sequence from codes.
+ * @private
+ * @param {number[]} codes - ANSI codes.
+ * @returns {string} Escape sequence.
+ */
+const _build = (codes) => {
+  if (codes.length === 0) return "";
+  return `${_x}[${codes.join(";")}m`;
+};
+
+const _apply = (str) => {
+  const esc_start = _options.delimiters.start.replace(
+    /[.*+?^${}()|[\]\\]/g,
+    "\\$&",
+  );
+  const esc_end = _options.delimiters.end.replace(
+    /[.*+?^${}()|[\]\\]/g,
+    "\\$&",
+  );
+
+  return str.replace(
+    new RegExp(`${esc_start}([\\s\\S]*?)${esc_end}`, "g"),
+    (match, content) => {
+      const { codes, text } = _parse(content);
+      if (codes.length === 0 || text === "") return text;
+
+      if (text.includes("\n")) {
+        return text
+					.split(/\\r?\\n/)
+					.filter((line) => line.trim())
+					.map((line) => `${_build(codes)}${line}${_x}[0m`)
+					.join("\\n");
+      }
+
+      return `${_build(codes)}${text}${_x}[0m`;
+    },
+  );
+};
+
+/**
+ * @private
+ * @returns {string}
+ */
+const _timestamp = () => {
+  if (!_options.timestamp) return "";
+  return _apply(
+    `<%gray [${new Date().toLocaleTimeString(undefined, { hour12: false })}]%>`,
+  );
+};
+
+/**
+ * Generates indentation based on group depth.
+ * @private
+ * @returns {string} Indentation spaces.
+ */
+const _indent = () => {
+  return "  ".repeat(0 + _groups.length);
+};
+
+/**
+ * @module logger
+ * @description
+ * Beautiful ANSI-colored console logger with grouping, timestamps, and template syntax.
+ *
+ * Supports 16+ colors, styles (bold, italic, underline), background colors,
+ * nested groups with indentation, and customizable delimiters.
+ *
+ * ## Syntax
+ * ```
+ * <%red bold This is red and bold%>
+ * <%bgBlue whiteBright ERROR%>
+ * <%yellowBright [WARN]%>
+ * ```
+ *
+ * Available styles: `normal`, `bold`, `italic`, `underline`, `overline`
+ * Colors: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `gray`
+ * Bright colors: `redBright`, `greenBright`, `yellowBright`, `blueBright`, `magentaBright`, `cyanBright`, `whiteBright`
+ * Backgrounds: `bgBlack`, `bgRed`, `bgGreen`, etc.
+ *
+ * @example
+ * const nodeComfort = require("@ix-xs/node-comfort");
+ *
+ * nodeComfort.log("<%greenBright ✓ Success%> Operation completed!");
+ * nodeComfort.group("<%blue Processing files%>").log("File 1").groupEnd();
+ * const log = nodeComfort.logify({ users: 42 }); // → ANSI string
+ */
+module.exports = {
+  /**
+	 * Logs content with colors, timestamp, and group indentation.
+	 * Supports strings, objects (pretty JSON), and chaining.
+	 *
+	 * @param {any} content - Content to log (string, object, or primitive).
+	 * @returns {this} Chainable instance.
+	 * @example
+	 * nodeComfort.log("<%greenBright ✓ Done%>");
+	 * nodeComfort.log({ users: 42, active: true });
+	 * nodeComfort.group("Files").log("Processing...").groupEnd();
+	 */
+  log(content) {
+    let str;
+    if (typeof content === "string") {
+      str = content;
+    } else if (typeof content === "object") {
+      str = JSON.stringify(content, null, 2);
+    } else {
+      str = String(content);
+    }
+
+    const prefix = `${_timestamp()}${_indent()}`;
+    const fullStr = prefix ? `${prefix} ${str}` : str;
+
+    const formatted = _apply(fullStr);
+
+    if (formatted.includes("\n")) {
+      const lines = formatted.split("\n");
+
+      if (lines[0].trim()) console.log(lines[0]);
+
+      const indentOnly = _indent();
+      for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim()) {
+          console.log(`${indentOnly}${lines[i]}`);
+        }
+      }
+    } else {
+      console.log(formatted);
+    }
+
+    return this;
+  },
+
+  /**
+	 * Formats content with colors, timestamp, and group indentation (no console output).
+	 *
+	 * @param {any} content - Content to format.
+	 * @returns {string} Formatted string.
+	 * @example
+	 * const msg = nodeComfort.logify("<%redBright ERROR%> Invalid input");
+	 * console.log(msg);
+	 */
+  logify(content) {
+    let str;
+    if (typeof content === "string") {
+      str = content;
+    } else if (typeof content === "object") {
+      str = JSON.stringify(content, null, 2);
+    } else {
+      str = String(content);
+    }
+
+    const prefix = `${_timestamp()}${_indent()}`;
+    return _apply(prefix ? `${prefix} ${str}` : str);
+  },
+
+  /**
+	 * Starts a new log group with ▼ indicator and increased indentation.
+	 *
+	 * @param {string} label - Group label (supports colors).
+	 * @returns {this} Chainable instance.
+	 * @example
+	 * nodeComfort.group("<%yellow Processing%>").log("Step 1").groupEnd();
+	 */
+  group(label) {
+    _groups.push(label);
+    const prefix = `${_timestamp()}${_indent()}`;
+    console.log(prefix ? `${prefix}▼ ${label}` : `▼ ${label}`);
+    return this;
+  },
+
+  /**
+	 * Ends current group and reduces indentation.
+	 *
+	 * @returns {this} Chainable instance.
+	 * @example
+	 * nodeComfort.group("Work").groupEnd();
+	 */
+  groupEnd() {
+    if (_groups.length > 0) _groups.pop();
+    return this;
+  },
+
+  /**
+	 * Configures logger options (delimiters and timestamp).
+	 *
+	 * @param {object} [options] - Logger options.
+	 * @param {object} [options.delimiters] - Template delimiters.
+	 * @param {string} [options.delimiters.start="<%="] - Start delimiter.
+	 * @param {string} [options.delimiters.end="%>"] - End delimiter.
+	 * @param {boolean} [options.timestamp=true] - Show timestamps.
+	 * @returns {this} Chainable instance.
+	 * @example
+	 * nodeComfort.setLogger({
+	 *   delimiters: { start: "{{", end: "}}" },
+	 *   timestamp: false
+	 * }).log("{{ bgGreen new delimiters }}");
+	 */
+  setLogger(options = _options) {
+    options = {
+      delimiters: {
+        start: options?.delimiters?.start ?? _options.delimiters.start,
+        end: options?.delimiters?.end ?? _options.delimiters.end,
+      },
+      timestamp: options?.timestamp ?? _options.timestamp,
+    };
+    _options.delimiters = options.delimiters;
+    _options.timestamp = options.timestamp;
+    return this;
+  },
+};

package/core/Stepper.js

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