API Reference

Default singleton

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

A pre-built Wiz instance with auto-detected defaults. Use this for simple scripts and small apps.

`new Wiz(config?)`

Creates a new independent logger instance.

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

const logger = new Wiz(config?: WizConfig);

Parameters:

Parameter	Type	Required	Description
`config`	`WizConfig`	No	Instance configuration. See Configuration for all options.

Example:

const logger = new Wiz({
  scope: "api",
  level: "debug",
  file: { dir: "./logs", maxFiles: 7 },
});

Log methods

All six log methods share the same signature:

logger.trace(message: string, options?: LogCallOptions): void
logger.debug(message: string, options?: LogCallOptions): void
logger.info (message: string, options?: LogCallOptions): void
logger.warn (message: string, options?: LogCallOptions): void
logger.error(message: string, options?: LogCallOptions): void
logger.fatal(message: string, options?: LogCallOptions): void

Parameters

Parameter	Type	Required	Description
`message`	`string`	Yes	Primary human-readable log message
`options.meta`	`Record<string, unknown>`	No	Structured metadata. Deep-cloned and PII-masked before output.
`options.error`	`Error`	No	Error object. Stack trace is parsed into structured `StackFrame[]`.
`options.correlationId`	`string`	No	Overrides the instance-level `correlationId` for this call only.

Examples

// Message only
logger.info("Server started");

// With metadata
logger.info("Request completed", {
  meta: { method: "POST", path: "/users", statusCode: 201, durationMs: 14 },
});

// With error
logger.error("Database query failed", {
  error: new Error("ECONNREFUSED"),
  meta: { host: "db.internal", port: 5432 },
});

// With per-call correlationId
logger.info("Processing item", {
  correlationId: job.id,
  meta: { itemId: item.id, queue: "high-priority" },
});

// All options combined
logger.fatal("Critical failure", {
  correlationId: "req-abc-123",
  meta: { component: "payment-processor", retries: 3 },
  error: new TypeError("Cannot read properties of null"),
});

`logger.setConfig(partial)`

Merges a partial config update into the running instance at runtime.

logger.setConfig(updates: Partial<WizConfig>): void

Rebuilds transports automatically when format or file changes.

// Change level at runtime
logger.setConfig({ level: "debug" });

// Switch to JSON format
logger.setConfig({ format: "json" });

// Disable file output
logger.setConfig({ file: false });

// Add masked keys
logger.setConfig({ maskedKeys: ["sessionToken", "internalId"] });

`logger.flush()`

Synchronously flushes all buffered entries to their transports.

logger.flush(): void

Call this before a graceful shutdown to ensure no buffered file entries are lost.

process.on("SIGTERM", async () => {
  logger.flush();         // synchronous flush
  await logger.close();   // then async close
  process.exit(0);
});

`logger.close()`

Flushes all buffers and asynchronously releases all transport resources (file handles, timers, etc.).

logger.close(): Promise<void>

Always await this before process.exit() when using the file transport.

await logger.close();

`LogCallOptions`

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

`wiz.config()` — global singleton helper

The default wiz singleton can be reconfigured at any time:

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

wiz.setConfig({ level: "debug", format: "json" });

API Reference

Default singleton

new Wiz(config?)

Log methods

Parameters

Examples

logger.setConfig(partial)

logger.flush()

logger.close()

LogCallOptions

wiz.config() — global singleton helper