API Reference

ZTracer Class

import ZTracer from "z-tracer-kit";
const logger = new ZTracer(config);

All logging functionality is accessed through an instance of ZTracer.

Configuration

interface ZTracerConfig<T extends string> {
  global: {
    debug: boolean;
    callBack?: ZTracerCallBack<T>;
  };
  groups?: ZTracerGroups<T>;
}

• global.debug — enables/disables console output. Callbacks always run regardless.
• global.callBack — runs for every log.
• groups — map of group names to ZTracerGroup (background, color, callBack).

See Core Concepts for usage examples.

Methods

log(data: unknown, options?: ZTracerOptions<T>): Promise<void>

Logs arbitrary data.

await logger.log("Hello", { group: "api" });

fromJson(data: object | unknown[], options?: ZTracerOptions<T>): Promise<void>

Logs structured data. Arrays → tables; objects → expandable dirs.

await logger.fromJson([{ id: 1 }], { group: "db" });

time(callback: () => Promise<void> | void, options?: ZTracerOptions<T>): Promise<void>

Measures execution time of a callback.

await logger.time(async () => { await fetch(url); }, { group: "api" });

All methods return Promise<void> and should be awaited.

Options

interface ZTracerOptions<T extends string> {
  group?: T;          // Group name
  suffix?: string;     // Appended to group label
  callBack?: ZTracerCallBack<T>;  // Per-log callback
}

• group — if undefined, no group is rendered.
• suffix — optional disambiguation label.
• callBack — runs only for this log.

Types

type ZTracerCallBack<T> = (
  data: unknown,
  group?: T
) => void | Promise<void>;

interface ZTracerGroup<T> {
  background?: string;
  color?: string;
  callBack?: ZTracerCallBack<T>;
}

Full type definitions are available in the TypeScript guide.

Import / Require

ZTracer supports both ES Modules and CommonJS. The package exports default and named exports.

ES Module (import)

import ZTracer from "z-tracer-kit";
// or
import { ZTracer } from "z-tracer-kit";

CommonJS (require)

const { ZTracer } = require("z-tracer-kit");
// or
const ZTracer = require("z-tracer-kit").default;

The CommonJS output uses .cjs files and is automatically detected by Node.js when your project uses "type": "commonjs".

Errors & Edge Cases

• Callback errors — caught and logged; app never crashes.
• Invalid group — falls back to default gray style (#6c757d).
• No group/suffix — no group header rendered.
• Timer labels — unique per call (timer-{timestamp}-{random}).

For more details, see Log Lifecycle: Error Handling.