heco-log

A powerful and flexible logging utility for Node.js and TypeScript projects. Enhance your CLI and server logs with colors, banners, tables, blocks, and more.

Installation

Install via npm:

npm install heco-log

Usage

Import the library in your project:

import { heco } from "heco-log";

Basic Logging

heco.info("Checking environment configuration...");
heco.success("Environment loaded successfully!");
heco.error("NEXT_PUBLIC_API_URL is missing");
heco.warn("Using fallback token expiry time");
heco.debug("Raw env: this is debug testing");

Colored Messages

console.error(heco.red("❌ NEXT_PUBLIC_API_URL is not defined"));
console.error(heco.red("❌ Invalid environment config:"), "this is error testing");

Blocks

heco.block({
  title: "Success",
  message: "Build Success",
  color: "green",
});
heco.block({
  title: "Error",
  message: "Missing Environment Variable",
  color: "red",
  icon: "❌",
});
heco.block({
  title: "Warning",
  message: "Using default fallback",
  color: "yellow",
  icon: "⚠️",
});

Custom Colors

console.log(heco.customColor("Yellow!", "#FFFF00"));
console.log(heco.customColor("Red!", "rgb(255,0,0)"));

Tables

heco.table([
  { name: "Product A", price: "$10", stock: 23 },
  { name: "Product B", price: "$20", stock: 0 },
  { name: "Product C", price: "$15", stock: 5 },
], { color: "cyan" });

Banners

heco.banner("HecoLog", "1.4.2");

Traces

heco.trace("Build Process", [
  { label: "Initialize", status: "success" },
  { label: "Transpile code", status: "success", children: [
    { label: "Babel config loaded", status: "info" },
    { label: "TS compiled", status: "success" },
  ]},
  { label: "Run linters", status: "warn", children: [
    { label: "ESLint warnings found", status: "warn" },
  ]},
  { label: "Build failed", status: "fail" },
]);

Step Logs & Spinners (Async)

await heco.stepLog([
  {
    label: "Checking environment variables",
    run: async () => {
      if (!process.env.NEXT_PUBLIC_API_URL) throw new Error("Missing API URL");
    },
  },
  {
    label: "Building application",
    run: async () => { await new Promise(res => setTimeout(res, 500)); },
  },
  {
    label: "Uploading assets",
    run: async () => { await new Promise(res => setTimeout(res, 500)); return "warn"; },
  },
  {
    label: "Finalizing...",
    run: async () => { throw new Error("Unexpected failure in final step"); },
  },
]);

await heco.spinner("Fetching config", async () => {
  await new Promise(r => setTimeout(r, 2000));
});

Progress Bar

const progress = heco.progressBar({
  total: 10,
  label: "Building",
  color: "magenta",
});

for (let i = 0; i < 10; i++) {
  await new Promise(res => setTimeout(res, 200));
  progress.tick();
}

Prompts

const name = await heco.prompt("What's your name?");
console.log("Name:", name);

const proceed = await heco.confirm("Do you want to proceed?");
console.log("Proceed:", proceed);

const fruits = await heco.selectList(
    "Choose fruits",
    ["Apple", "Orange", "Banana"],
    {
      multiple: true,
    }
  );
console.log("Fruits:", fruits);

const country = await heco.selectList("Choose your country", [
    "Myanmar",
    "Thailand",
    "Japan",
    "Singapore",
  ]);
console.log("Chosen:", country);

// Close readline when done
heco.readlineClose();

Advanced Text

import { heco } from "heco-log";

// Rainbow Hello
const rainbow = heco
  .text("H", { color: "red", fontWeight: "bold" })
  .with("e", { color: "yellow", fontWeight: "bold" })
  .with("c", { color: "green", fontWeight: "bold" })
  .with("o", { color: "cyan", fontWeight: "bold" })
  .with("L", { color: "blue", fontWeight: "bold" })
  .with("o", { color: "magenta", fontWeight: "bold" })
  .with("g", { color: "white", fontWeight: "bold" })
  .with("!", { color: "gray", fontWeight: "bold" })
  .toString();

console.log(rainbow);

// Success Message
const success = heco
  .text("✔ Success!", {
    color: "green",
    backgroundColor: "black",
    fontWeight: "bold",
    textDecoration: "underline",
  })
  .toString();

console.log(success);

// Warning Message
const warning = heco
  .text("⚠ Warning:", {
    color: "yellow",
    backgroundColor: "black",
    fontWeight: "bold",
  })
  .with(" Disk space low!", {
    color: "yellow",
    backgroundColor: "black",
    fontStyle: "italic",
  })
  .toString();

console.log(warning);

// Error Message
const error = heco
  .text("✖ Error:", {
    color: "red",
    backgroundColor: "black",
    fontWeight: "bold",
  })
  .with(" Something went wrong.", {
    color: "white",
    backgroundColor: "red",
    textDecoration: "underline",
  })
  .toString();

console.log(error);

// Info Message with inverse
const info = heco
  .text("ℹ Info:", {
    color: "cyan",
    fontWeight: "bold",
  })
  .with(" All systems operational.", {
    color: "green",
    inverse: true,
  })
  .toString();

console.log(info);

// You can mix and match both styles as you like!
const fun = heco
  .text("🎉 Fun:").color("magenta").fontWeight("bold")
  .with(" Try both styles!", { color: "cyan", fontStyle: "italic" })
  .toString();

console.log(fun);

heco.readlineClose();

Charts

Horizontal Bar Chart

console.log(
  heco.Charts.horizontalBar(
    [
      { label: "Jan", value: 30, color: "cyan" },
      { label: "Feb", value: 80, color: "green" },
      { label: "Mar", value: 60, color: "blue" },
      { label: "Apr", value: 45, color: "yellow" },
      { label: "May", value: 90, color: "magenta" },
      { label: "Jun", value: 55, color: "cyan" },
      { label: "Jul", value: 70, color: "green" },
      { label: "Aug", value: 65, color: "blue" },
      { label: "Sep", value: 75, color: "yellow" },
      { label: "Oct", value: 85, color: "magenta" },
      { label: "Nov", value: 50, color: "cyan" },
      { label: "Dec", value: 95, color: "red" },
    ],
    {
      width: 60,
      padding: 2,
      color: "green",
      labelColor: "magenta",
      valueColor: "gray",
      showAxis: true,
      labelAlign: "left",
    }
  )
);

Vertical Bar Chart

console.log(
  heco.Charts.verticalBar(
    [
      { label: "Jan", value: 30, color: "cyan" },
      { label: "Feb", value: 80, color: "green" },
      { label: "Mar", value: 60, color: "blue" },
      { label: "Apr", value: 45, color: "yellow" },
      { label: "May", value: 90, color: "magenta" },
      { label: "Jun", value: 55, color: "cyan" },
      { label: "Jul", value: 70, color: "green" },
      { label: "Aug", value: 65, color: "blue" },
      { label: "Sep", value: 75, color: "yellow" },
      { label: "Oct", value: 85, color: "magenta" },
      { label: "Nov", value: 50, color: "cyan" },
      { label: "Dec", value: 95, color: "red" },
    ],
    {
      width: 60,
      height: 12,
      color: "green",
      labelColor: "white",
      padding: 5,
      showAxis: true,
      labelAlign: "vertical",
    }
  )
);

Horizontal Pie Chart

console.log(
  heco.Charts.pieChartHorizontal(
    [
      { label: "🍎 Apples", value: 30, color: "red", symbol: "🟥" },
      { label: "🍊 Oranges", value: 20, color: "yellow", symbol: "🟧" },
      { label: "🍌 Bananas", value: 15, color: "green", symbol: "🟩" },
      { label: "🍇 Grapes", value: 35, color: "magenta", symbol: "🟪" },
    ],
    {
      barWidth: 30,
      showPercentage: true,
      labelColor: "magenta",
    }
  )
);

API Reference

• heco.info(message: string) – Info log
• heco.success(message: string) – Success log
• heco.error(message: string) – Error log
• heco.warn(message: string) – Warning log
• heco.debug(message: string) – Debug log
• heco.red(message: string) – Red colored message
• heco.customColor(message: string, color: string) – Custom color
• heco.block(options) – Block message
• heco.table(data, options?) – Table output
• heco.banner(title, version?) – Banner
• heco.trace(title, steps) – Trace steps
• heco.stepLog(steps) – Step-by-step async log
• heco.spinner(label, fn) – Spinner for async tasks
• heco.progressBar(options) – Progress bar for tracking tasks
• heco.prompt(message: string) – Prompt for user input
• heco.confirm(message: string) – Yes/no confirmation prompt
• heco.selectList(message: string, options: string[], options?: SelectListOptions) – Multi-select prompt
• heco.readlineClose() – Close the readline interface
• heco.Charts.horizontalBar(data, options?) – Horizontal bar chart
• heco.Charts.verticalBar(data, options?) – Vertical bar chart
• heco.Charts.pieChartHorizontal(data, options?) – Pie chart

License

MIT