title	Types
description	TypeScript type definitions exported by konsole-logger — KonsoleOptions, LogEntry, Transport, TimestampFormat, FormatterOptions.

Types

Type definitions exported by konsole-logger.

LogEntry

Represents a single log entry stored in the circular buffer.

type LogEntry = {
  msg: string;                       // primary message string
  messages?: unknown[];              // original arguments — only when keepMessages: true
  fields: Record<string, unknown>;   // structured key-value pairs (includes bindings)
  timestamp: Date;
  hrTime?: number;                   // high-res nanosecond offset (when highResolution: true)
  namespace: string;
  level: LogLevelName;               // 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
  levelValue: number;                // 10 | 20 | 30 | 40 | 50 | 60
  logtype?: string;                  // @deprecated — use level
};

Properties

Property	Type	Description
`msg`	`string`	The primary log message
`messages`	`unknown[] \| undefined`	Original arguments — populated only when the logger sets `keepMessages: true` (off by default to save per-entry footprint)
`fields`	`Record<string, unknown>`	Structured key-value pairs (child bindings merged with call-site fields)
`timestamp`	`Date`	When the log was created
`hrTime`	`number \| undefined`	High-resolution monotonic timestamp in nanoseconds (present when `highResolution: true`)
`namespace`	`string`	The logger namespace
`level`	`LogLevelName`	Severity: `'trace'` `'debug'` `'info'` `'warn'` `'error'` `'fatal'`
`levelValue`	`number`	Numeric severity: 10 / 20 / 30 / 40 / 50 / 60

Example

import { Konsole } from 'konsole-logger';

const logger = new Konsole({ namespace: 'App', format: 'silent' });
logger.error('Something failed', { code: 500, path: '/users' });

const [entry] = logger.getLogs();
// {
//   msg: 'Something failed',
//   fields: { code: 500, path: '/users' },
//   timestamp: Date,
//   namespace: 'App',
//   level: 'error',
//   levelValue: 50,
// }
//
// Pass `keepMessages: true` to additionally preserve the original args as
// `entry.messages: ['Something failed', { code: 500, path: '/users' }]`.

Transport (interface)

All transport implementations satisfy this interface.

interface Transport {
  readonly name: string;
  write(entry: LogEntry): void;
  flush?(): Promise<void>;
  destroy(): Promise<void>;
}

Implementing a custom transport

import type { Transport, LogEntry } from 'konsole-logger';

class MyTransport implements Transport {
  readonly name = 'my-transport';

  write(entry: LogEntry): void {
    // deliver the entry somewhere
    externalService.send({
      level: entry.level,
      msg: entry.msg,
      ...entry.fields,
    });
  }

  async destroy(): Promise<void> {
    // clean up resources
  }
}

const logger = new Konsole({
  namespace: 'App',
  transports: [new MyTransport()],
});

KonsoleOptions

Configuration for the Konsole constructor.

interface KonsoleOptions {
  namespace?: string;
  level?: LogLevelName;
  format?: KonsoleFormat;
  timestamp?: TimestampFormat | TimestampOptions;
  redact?: string[];
  transports?: (Transport | TransportConfig)[];
  maxLogs?: number;
  defaultBatchSize?: number;
  retentionPeriod?: number;
  cleanupInterval?: number;
  useWorker?: boolean;
  keepMessages?: boolean;
  criteria?: Criteria; // @deprecated
}

Properties

Property	Type	Default	Description
`namespace`	`string`	`'Global'`	Logger namespace
`level`	`LogLevelName`	`'trace'`	Minimum level — entries below are discarded
`format`	`KonsoleFormat`	`'auto'`	Output format (see below)
`timestamp`	`TimestampFormat \| TimestampOptions`	`'datetime'`	Timestamp format (see below)
`redact`	`string[]`	`[]`	Dot-notation field paths to mask with `'[REDACTED]'` — see Redaction
`transports`	`(Transport \| TransportConfig)[]`	`[]`	External log destinations
`maxLogs`	`number`	`10000`	Circular buffer capacity
`defaultBatchSize`	`number`	`100`	Entries per `viewLogs()` call
`retentionPeriod`	`number`	`172800000`	48 hours in ms
`cleanupInterval`	`number`	`3600000`	1 hour in ms
`useWorker`	`boolean`	`false`	Worker mode (Web Worker in browser, `worker_threads` in Node.js)
`keepMessages`	`boolean`	`false`	Preserve the original `args` array on each entry as `messages`. Off by default to save per-entry memory; turn on when reading `entry.messages` from `getLogs()` consumers, or to surface every object arg as expandable in `BrowserFormatter`
`criteria`	`Criteria`	`true`	Output filter (deprecated — use `level` and `format`)

KonsoleFormat

type KonsoleFormat = 'auto' | 'pretty' | 'json' | 'text' | 'browser' | 'silent';

Value	Description
`'auto'`	Browser → `browser`, Node.js TTY → `pretty`, Node.js pipe → `json`
`'pretty'`	ANSI-colored human-readable output; respects `NO_COLOR` / `FORCE_COLOR`
`'json'`	Newline-delimited JSON — aggregator-friendly (Datadog, Loki, CloudWatch)
`'text'`	Plain text, no ANSI — for CI logs or plain log files
`'browser'`	`%c` CSS badge styling in browser DevTools
`'silent'`	No output; entries still stored in buffer and forwarded to transports

KonsoleChildOptions

Options accepted by logger.child().

interface KonsoleChildOptions {
  namespace?: string;
  level?: LogLevelName;
  timestamp?: TimestampFormat | TimestampOptions;
  redact?: string[];
}

Property	Type	Default	Description
`namespace`	`string`	Parent's	Override namespace for this child
`level`	`LogLevelName`	Parent's	Override minimum level (can only be more restrictive)
`timestamp`	`TimestampFormat \| TimestampOptions`	Parent's	Override timestamp format
`redact`	`string[]`	`[]`	Additional paths to redact (merged with parent's paths — child can never redact fewer)

RotationOptions

Configuration for file rotation on FileTransport.

interface RotationOptions {
  maxSize?: number;
  interval?: 'daily' | 'hourly' | number;
  maxFiles?: number;
  compress?: boolean;
}

Property	Type	Default	Description
`maxSize`	`number`	—	Rotate when file exceeds this size in bytes
`interval`	`'daily' \| 'hourly' \| number`	—	Rotate on a time schedule (`'daily'`, `'hourly'`, or ms)
`maxFiles`	`number`	`5`	Maximum rotated files to retain; oldest are deleted
`compress`	`boolean`	`false`	Gzip-compress rotated files (`.gz` suffix)

Rotated files use numeric suffixes: app.log.1 (newest) → app.log.2 → etc. The current log file always stays at the configured path. When both maxSize and interval are set, rotation triggers on whichever condition is met first.

TransportConfig

Configuration for an HTTP transport (auto-wrapped in HttpTransport).

interface TransportConfig {
  name: string;
  url: string;
  method?: 'POST' | 'PUT';
  headers?: Record<string, string>;
  batchSize?: number;
  flushInterval?: number;
  retryAttempts?: number;
  maxQueueSize?: number;
  overflowStrategy?: 'drop-oldest' | 'drop-newest';
  onError?: (err: Error, droppedEntries: LogEntry[]) => void;
  filter?: (entry: LogEntry) => boolean;
  transform?: (entry: LogEntry) => unknown;
  fetchImpl?: typeof fetch;
}

Properties

Property	Type	Default	Description
`name`	`string`	Required	Unique identifier
`url`	`string`	Required	Endpoint URL
`method`	`string`	`'POST'`	HTTP method
`headers`	`object`	`{}`	Additional request headers
`batchSize`	`number`	`50`	Entries per batch
`flushInterval`	`number`	`10000`	Auto-flush interval (ms)
`retryAttempts`	`number`	`3`	Retry attempts with exponential backoff
`maxQueueSize`	`number`	`Infinity`	Cap on pending batches awaiting send
`overflowStrategy`	`'drop-oldest' \| 'drop-newest'`	`'drop-oldest'`	What to drop when `maxQueueSize` is reached
`onError`	`function`	—	Called when a batch is permanently dropped (retries exhausted or evicted by `maxQueueSize`). Receives the underlying `Error` and the dropped entries.
`filter`	`function`	—	Only forward entries matching predicate
`transform`	`function`	—	Transform entry before sending
`fetchImpl`	`typeof fetch`	`globalThis.fetch`	Custom fetch (required on Node.js < 18)

TimestampFormat

type TimestampFormat =
  | 'iso'       // 2025-03-16T10:23:45.123Z
  | 'datetime'  // 2025-03-16 10:23:45.123
  | 'date'      // 2025-03-16
  | 'time'      // 10:23:45.123
  | 'unix'      // 1710583425 (epoch seconds)
  | 'unixMs'    // 1710583425123 (epoch milliseconds)
  | 'none'      // omit timestamp
  | ((date: Date, hrTime?: number) => string); // custom function

Preset	Output	Notes
`'datetime'`	`2025-03-16 10:23:45.123`	Default for pretty, text, and browser formatters
`'iso'`	`2025-03-16T10:23:45.123Z`	Default for JSON formatter; UTC
`'time'`	`10:23:45.123`	Time only, local timezone
`'date'`	`2025-03-16`	Date only, local timezone
`'unix'`	`1710583425`	Epoch seconds
`'unixMs'`	`1710583425123`	Epoch milliseconds
`'none'`	(empty)	Omit from output
`function`	Custom	Receives `Date` and optional `hrTime` (nanoseconds)

TimestampOptions

interface TimestampOptions {
  format?: TimestampFormat;     // default: 'datetime'
  highResolution?: boolean;     // default: false
}

Property	Type	Default	Description
`format`	`TimestampFormat`	`'datetime'`	Timestamp output format
`highResolution`	`boolean`	`false`	Capture nanosecond-precision timing via `process.hrtime.bigint()` (Node) or `performance.now()` (browser)

When highResolution is true, each LogEntry receives an hrTime field (nanoseconds, monotonic). The JSON formatter includes this in output as "hrTime": 123456789.

Criteria (deprecated)

type Criteria = boolean | ((logEntry: LogEntry) => boolean);

Controls whether the formatter outputs a log entry. Prefer level and format for new code.

LogLevelName

type LogLevelName = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';

ContextStore

type ContextStore = Record<string, unknown>;

The key/value bag propagated through async scope via Konsole.runWithContext. Merged into every log entry produced inside the scope — see the Async Context Propagation guide.

import { Konsole, type ContextStore } from 'konsole-logger';

const baseCtx: ContextStore = { service: 'payments', region: 'us-east-1' };

Konsole.runWithContext({ ...baseCtx, requestId: 'r_abc' }, () => {
  logger.info('charged');
});

FileFormat

type FileFormat = 'json' | 'text';

Used by FileTransport and StreamTransport to control the per-line serialization format.

KonsolePublic

Public interface surfaced by __Konsole.getLogger() in the browser.

// Per-logger interface (via __Konsole.getLogger())
{
  viewLogs(batchSize?: number): void;
  setTimestamp(opts: TimestampFormat | TimestampOptions): void;
  setLevel(level: LogLevelName): void;
}

// Global interface (via __Konsole)
{
  getLogger(namespace?: string): { viewLogs, setTimestamp, setLevel };
  listLoggers(): string[];
  enableAll(): void;
  disableAll(): void;
  setTimestamp(opts: TimestampFormat | TimestampOptions): void; // changes all loggers
  disableRedaction(disabled: boolean): void; // browser only — bypass redaction for debugging
}

FilesExpand file tree

types.md

Latest commit

History

types.md

File metadata and controls

Types

LogEntry

Properties

Example

Transport (interface)

Implementing a custom transport

KonsoleOptions

Properties

KonsoleFormat

KonsoleChildOptions

RotationOptions

TransportConfig

Properties

TimestampFormat

TimestampOptions

Criteria (deprecated)

LogLevelName

ContextStore

FileFormat

KonsolePublic