TypeScript Types

All types are exported from the package root:

import type {
  IWiz,
  WizConfig,
  LogLevel,
  LogEntry,
  LogCallOptions,
  Transport,
  FileTransportOptions,
  ParsedError,
  StackFrame,
} from "@gouranga_samrat/log-wiz";

---

LogLevel

type LogLevel =
  | "trace"
  | "debug"
  | "info"
  | "warn"
  | "error"
  | "fatal"
  | "none";

---

LOG_LEVEL_SEVERITY

Numeric severity values. Use for custom level comparisons.

const LOG_LEVEL_SEVERITY: Readonly<Record<LogLevel, number>> = {
  trace: 10,
  debug: 20,
  info:  30,
  warn:  40,
  error: 50,
  fatal: 60,
  none:  Infinity,
};

import { LOG_LEVEL_SEVERITY } from "@gouranga_samrat/log-wiz";

LOG_LEVEL_SEVERITY["error"] > LOG_LEVEL_SEVERITY["warn"]; // true

---

WizConfig

interface WizConfig {
  level?:                    LogLevel;
  scope?:                    string;
  correlationId?:            string;
  format?:                   "pretty" | "json" | "browser";
  maskedKeys?:               readonly string[];
  replaceDefaultMaskedKeys?: boolean;
  file?:                     FileTransportOptions | false;
  omitTimestamp?:            boolean;
}

---

FileTransportOptions

interface FileTransportOptions {
  dir?:             string;   // default: "logs"
  maxFiles?:        number;   // default: 7
  asyncBuffer?:     boolean;  // default: true
  bufferSize?:      number;   // default: 100
  flushIntervalMs?: number;   // default: 1000
}

---

LogEntry

The immutable object passed to every transport’s write() method.

interface LogEntry {
  readonly timestamp:      string;                       // ISO-8601 or ""
  readonly level:          Exclude<LogLevel, "none">;
  readonly env:            "node" | "browser";
  readonly message:        string;
  readonly scope?:         string;
  readonly correlationId?: string;
  readonly meta?:          Record<string, unknown>;      // already PII-masked
  readonly error?:         ParsedError;
}

---

ParsedError

Structured representation of a JavaScript Error object.

interface ParsedError {
  readonly name:    string;
  readonly message: string;
  readonly stack?:  StackFrame[];
}

---

StackFrame

A single frame in a parsed stack trace.

interface StackFrame {
  readonly raw:       string;    // original line from Error.stack
  readonly function?: string;    // function name
  readonly file?:     string;    // file path
  readonly line?:     number;    // line number
  readonly column?:   number;    // column number
}

---

Transport

The contract every transport must satisfy.

interface Transport {
  write(entry: LogEntry): void;
  flush?(): void;
  close?(): Promise<void>;
}

---

LogCallOptions

Per-call options accepted by all log methods.

interface LogCallOptions {
  readonly correlationId?: string;
  readonly meta?:          Record<string, unknown>;
  readonly error?:         Error;
}

---

IWiz

Public interface of every Wiz instance. Use this to type loggers in dependency injection.

interface IWiz {
  trace(message: string, options?: LogCallOptions): void;
  debug(message: string, options?: LogCallOptions): void;
  info (message: string, options?: LogCallOptions): void;
  warn (message: string, options?: LogCallOptions): void;
  error(message: string, options?: LogCallOptions): void;
  fatal(message: string, options?: LogCallOptions): void;
  setConfig(config: Partial<WizConfig>): void;
  flush(): void;
  close(): Promise<void>;
}

// Dependency injection example
class UserService {
  constructor(private readonly logger: IWiz) {}

  async findUser(id: string) {
    this.logger.debug("Finding user", { meta: { id } });
  }
}