Loggical API Documentation v1.0.1

---

Loggical API Documentation / Logger

Class: Logger

Defined in: core/logger.ts:20

Logger class for structured logging with colors and levels

Constructors

Constructor

new Logger(options: LoggerOptions): Logger;

Defined in: core/logger.ts:82

Create a new logger with options

Parameters

Parameter	Type	Description
options	LoggerOptions	Logger configuration options

Returns

Logger

Examples

// Default logger
const logger = new Logger()

// Use preset with light customization
const apiLogger = new Logger({
  preset: 'compact',
  prefix: 'API',
  minLevel: LogLevel.WARN
})

// Full control over all options
const customLogger = new Logger({
  colorLevel: ColorLevel.ENHANCED,
  timestamped: true,
  compactObjects: false,
  maxValueLength: 200,
  transports: [new ConsoleTransport(), new FileTransport({ filename: 'app.log' })]
})

Methods

create()

static create(options?: LoggerOptions): Logger;

Defined in: core/logger.ts:111

Static factory method for creating a logger with default configuration

Parameters

Parameter	Type
options?	LoggerOptions

Returns

Logger

---

compact()

static compact(options?: Partial<LoggerOptions>): Logger;

Defined in: core/logger.ts:118

Static factory method for creating a compact logger

Parameters

Parameter	Type
options?	Partial<LoggerOptions>

Returns

Logger

---

readable()

static readable(options?: Partial<LoggerOptions>): Logger;

Defined in: core/logger.ts:125

Static factory method for creating a readable logger

Parameters

Parameter	Type
options?	Partial<LoggerOptions>

Returns

Logger

---

server()

static server(options?: Partial<LoggerOptions>): Logger;

Defined in: core/logger.ts:132

Static factory method for creating a server logger

Parameters

Parameter	Type
options?	Partial<LoggerOptions>

Returns

Logger

---

development()

static development(options?: Partial<LoggerOptions>): Logger;

Defined in: core/logger.ts:139

Static factory method for creating a development logger

Parameters

Parameter	Type
options?	Partial<LoggerOptions>

Returns

Logger

---

debug()

debug(...messages: unknown[]): void;

Defined in: core/logger.ts:205

Log debug messages - lowest priority, typically disabled in production

Parameters

Parameter	Type	Description
...messages	unknown[]	The message string and optional data objects to log

Returns

void

Example

logger.debug('Processing user data', { userId: '123', step: 'validation' })
logger.debug('Cache hit', { key: 'user:123', ttl: 300 })

---

info()

info(...messages: unknown[]): void;

Defined in: core/logger.ts:221

Log informational messages - general application flow and events

Parameters

Parameter	Type	Description
...messages	unknown[]	The message string and optional data objects to log

Returns

void

Example

logger.info('User login successful', { userId: '123', timestamp: new Date() })
logger.info('Request processed', { method: 'POST', url: '/api/users', duration: '150ms' })

---

warn()

warn(...messages: unknown[]): void;

Defined in: core/logger.ts:237

Log warning messages - potentially harmful situations that don't stop execution

Parameters

Parameter	Type	Description
...messages	unknown[]	The message string and optional data objects to log

Returns

void

Example

logger.warn('API rate limit approaching', { current: 95, limit: 100 })
logger.warn('Deprecated feature used', { feature: 'oldApi', alternative: 'newApi' })

---

error()

error(...messages: unknown[]): void;

Defined in: core/logger.ts:253

Log error messages - error conditions that don't require immediate termination

Parameters

Parameter	Type	Description
...messages	unknown[]	The message string and optional data objects to log

Returns

void

Example

logger.error('Database connection failed', { error: err.message, retryCount: 3 })
logger.error('Payment processing error', { orderId: '12345', gateway: 'stripe' })

---

highlight()

highlight(...messages: unknown[]): void;

Defined in: core/logger.ts:269

Log highlighted messages - important information that needs attention

Parameters

Parameter	Type	Description
...messages	unknown[]	The message string and optional data objects to log

Returns

void

Example

logger.highlight('System maintenance starting', { duration: '30min', affectedServices: ['api', 'db'] })
logger.highlight('New feature deployed', { version: '2.1.0', features: ['auth', 'payments'] })

---

fatal()

fatal(...messages: unknown[]): void;

Defined in: core/logger.ts:284

Log fatal error messages - unrecoverable errors

Parameters

Parameter	Type	Description
...messages	unknown[]	The message string and optional data objects to log

Returns

void

Example

logger.fatal('Database connection lost', { host: 'db.example.com', lastPing: '30s ago' })

---

getOptions()

getOptions(): LoggerOptions;

Defined in: core/logger.ts:290

Returns

LoggerOptions

---

withPrefix()

withPrefix(prefix: string): Logger;

Defined in: core/logger.ts:317

Create a new logger with an additional prefix

Prefixes are displayed before each log message to identify the source or component. They can be automatically abbreviated if abbreviatePrefixes is enabled.

Parameters

Parameter	Type	Description
prefix	string	The prefix to add (e.g., 'API', 'DATABASE', 'AUTH-SERVICE')

Returns

Logger

A new Logger instance with the additional prefix

Example

const logger = new Logger()
const apiLogger = logger.withPrefix('API-SERVER')
const authLogger = apiLogger.withPrefix('AUTH')

authLogger.info('User authenticated')
// Output: [timestamp] ℹ️ [API-SERVER] [AUTH] User authenticated

---

withContext()

withContext(context: string | Record<string, unknown>, value?: unknown): Logger;

Defined in: core/logger.ts:376

Add context that will appear in all subsequent log messages

Context is persistent data that automatically appears in every log message from this logger instance. This is particularly useful for request-scoped logging where you want to include request ID, user ID, etc.

Parameters

Parameter	Type	Description
context	string | Record<string, unknown>	Either a key string or an object with key-value pairs
value?	unknown	The value when using key-value syntax

Returns

Logger

A new Logger instance with the added context

Examples

// Key-value syntax
const userLogger = logger.withContext('userId', 'user-123')

// Object syntax
const requestLogger = logger.withContext({
  requestId: 'req-456',
  method: 'POST',
  ip: '192.168.1.1'
})

fullLogger.info('Processing request')
// Output: [...] Processing request { requestId: "req-456", method: "POST", ip: "192.168.1.1" }

View full context example

// User Session Tracking
const sessionLogger = logger.withContext({
  userId: 'user-12345',
  sessionId: 'sess-abc-123',
  role: 'admin'
})

sessionLogger.info('User session started')

// Request/Response Cycle
const requestLogger = sessionLogger.withContext({
  requestId: 'req-def-456',
  method: 'POST',
  endpoint: '/api/users'
})

requestLogger.info('Incoming request')
requestLogger.info('Request processed successfully')

---

withoutContext()

withoutContext(): Logger;

Defined in: core/logger.ts:396

Remove all context from the logger

Returns

Logger

A new Logger instance with no context

---

withoutContextKey()

withoutContextKey(key: string): Logger;

Defined in: core/logger.ts:410

Remove a specific context key

Parameters

Parameter	Type	Description
key	string	The context key to remove

Returns

Logger

A new Logger instance without the specified context key

---

getContext()

getContext(): Record<string, unknown>;

Defined in: core/logger.ts:426

Get current context as a plain object

Returns

Record<string, unknown>

Object with current context key-value pairs

---

addTransport()

addTransport(transport: Transport): this;

Defined in: core/logger.ts:436

Add a transport to this logger

Parameters

Parameter	Type	Description
transport	Transport	The transport to add

Returns

this

---

removeTransport()

removeTransport(transportName: string): this;

Defined in: core/logger.ts:445

Remove a transport by name

Parameters

Parameter	Type	Description
transportName	string	Name of the transport to remove

Returns

this

---

getTransport()

getTransport(transportName: string): undefined | Transport;

Defined in: core/logger.ts:454

Get transport by name

Parameters

Parameter	Type	Description
transportName	string	Name of the transport

Returns

undefined | Transport

---

getTransports()

getTransports(): Transport[];

Defined in: core/logger.ts:461

Get all transports

Returns

Transport[]

---

clearTransports()

clearTransports(): this;

Defined in: core/logger.ts:468

Clear all transports

Returns

this

---

getTransportStatus()

getTransportStatus(): Record<string, unknown>[];

Defined in: core/logger.ts:476

Get status of all transports

Returns

Record<string, unknown>[]

---

installPlugin()

installPlugin(plugin: Plugin): Promise<void>;

Defined in: core/logger.ts:486

Install a plugin

Parameters

Parameter	Type	Description
plugin	Plugin	The plugin to install

Returns

Promise<void>

---

uninstallPlugin()

uninstallPlugin(name: string): Promise<void>;

Defined in: core/logger.ts:494

Uninstall a plugin by name

Parameters

Parameter	Type	Description
name	string	The name of the plugin to uninstall

Returns

Promise<void>

---

getPlugins()

getPlugins(): Plugin[];

Defined in: core/logger.ts:502

Get all installed plugins

Returns

Plugin[]

Array of installed plugins

---

hasPlugin()

hasPlugin(name: string): boolean;

Defined in: core/logger.ts:511

Check if a plugin is installed

Parameters

Parameter	Type	Description
name	string	The name of the plugin to check

Returns

boolean

True if the plugin is installed

---

close()

close(): Promise<void>;

Defined in: core/logger.ts:532

Close all transports and cleanup

Returns

Promise<void>