Configuration Reference

WizConfig

All fields are optional. Pass a partial object to new Wiz(config) or logger.setConfig(partial).

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

const logger = new Wiz({
  level:                    "info",
  scope:                    "api",
  correlationId:            "worker-1",
  format:                   "pretty",
  maskedKeys:               ["nationalId"],
  replaceDefaultMaskedKeys: false,
  omitTimestamp:            false,
  file: {
    dir:             "./logs",
    maxFiles:        7,
    asyncBuffer:     true,
    bufferSize:      100,
    flushIntervalMs: 1000,
  },
});

`level`


Type	`'trace' \| 'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal' \| 'none'`
Default	`'info'`

Minimum severity to output. Entries below this level are silently dropped with zero overhead. Set to 'none' to silence all output (no-op mode).

new Wiz({ level: "debug" })  // shows debug and above
new Wiz({ level: "none"  })  // all calls return immediately

`scope`


Type	`string`
Default	`undefined`

A label attached to every entry from this instance. Appears in all output formats as [scope]. Ideal for multi-instance setups.

const db   = new Wiz({ scope: "database" });
const http = new Wiz({ scope: "http" });

`correlationId`


Type	`string`
Default	`undefined`

A static ID attached to every entry. Can be overridden per-call by passing correlationId in log options.

const worker = new Wiz({ correlationId: "job-42" });
worker.info("Processing");  // every entry carries correlationId: "job-42"

// Per-call override:
worker.info("Handling", { correlationId: req.id });

`format`


Type	`'pretty' \| 'json' \| 'browser'`
Default	auto-detected

Forces a specific output format. If omitted, format is auto-detected:

Condition	Auto-selected format
`typeof window !== 'undefined'`	`'browser'`
`NODE_ENV=production` or `CI=true`	`'json'`
Everything else	`'pretty'`

new Wiz({ format: "json" })    // always JSON, even in development
new Wiz({ format: "pretty" })  // always coloured, even in production

`maskedKeys`


Type	`readonly string[]`
Default	`[]`

Extra keys to mask, merged with the built-in defaults. Matching is case-insensitive and ignores -, _, and spaces.

new Wiz({ maskedKeys: ["nationalId", "driverLicense"] })

`replaceDefaultMaskedKeys`


Type	`boolean`
Default	`false`

When true, the built-in defaults are replaced by maskedKeys instead of extended. Only the keys you list will be masked.

new Wiz({
  maskedKeys: ["internalRef"],
  replaceDefaultMaskedKeys: true,
  // now ONLY "internalRef" is masked
})

`omitTimestamp`


Type	`boolean`
Default	`false`

When true, the timestamp field is set to an empty string. Useful for deterministic snapshot testing.

new Wiz({ omitTimestamp: true })

`file`


Type	`FileTransportOptions \| false`
Default	`{}` (enabled with defaults)

File transport configuration. Pass false to disable file output entirely.

new Wiz({ file: false })  // console only

`file.dir`


Type	`string`
Default	`'logs'`

Directory for log files. Created recursively if it does not exist.

`file.maxFiles`


Type	`number`
Default	`7`

Number of daily log files to retain. Oldest files are pruned during day rollover.

`file.asyncBuffer`


Type	`boolean`
Default	`true`

Batch writes in memory and flush in bulk. Dramatically reduces disk I/O for high-throughput apps.

`file.bufferSize`


Type	`number`
Default	`100`

Number of entries to buffer before an automatic flush. Only active when asyncBuffer: true.

`file.flushIntervalMs`


Type	`number`
Default	`1000`

Max milliseconds between flushes. Ensures entries reach disk even if bufferSize is never reached. Only active when asyncBuffer: true.

Runtime reconfiguration

const logger = new Wiz({ level: "info" });

// Merge updates — rebuilds transports if format or file changes
logger.setConfig({ level: "debug" });
logger.setConfig({ format: "json", file: false });