Class SyncLogger

Synchronous logger with blocking I/O for guaranteed delivery.

All operations complete before returning, ensuring logs are written immediately. Perfect for security auditing, debugging, and crash-resilient logging at the cost of blocking application execution.

SyncLogger

Example: Basic usage

const logger = new SyncLogger();
logger.info('Step 1');  // Blocks until written
logger.info('Step 2');  // Executes after Step 1 completes

Example: Audit logging

const audit = new SyncLogger({
  file: './audit.log',
  forceFlush: true,     // fsync after each write
  useConsole: false
});

audit.info('User login', { userId: 123 });
// Log guaranteed on disk before continuing

Index

Constructors

constructor

Accessors

Methods

box close colorParts count countReset custom debug error flush fmt getFilePath getWriteCount group groupEnd header info list log progressBar separator styled success table time timeEnd warn

Constructors

constructor

new SyncLogger(options?: LoggerOptions): SyncLogger
Creates a new synchronous logger instance.
Parameters
- Optionaloptions: LoggerOptions = {}
  Configuration options
  
  Configuration options for a MagicLogger instance. These settings control the logger's behavior, output format, identity, and destination.
  - Optionalcontext?: Record<string, unknown>
    Optional default context applied to all logs. Can include environment metadata, user data, etc. Individual log calls may override this.
    
    Example
    { env: 'staging', region: 'us-east-1' }
  - OptionalfallbackToSync?: boolean
    Fallback to synchronous logging when async buffers are full. Only applies when mode is 'async' or 'balanced'.
    
    Default
    true
  - Optionalfile?: string
    File path for log output (SyncLogger only). When provided, logs will be written to this file synchronously.
    
    Example
    './audit.log'
  - OptionalforceFlush?: boolean
    Force flush to disk after each write (SyncLogger only). Uses fsync to ensure data is written to disk.
    
    Default
    true
  - Optionalid?: string
    Unique identifier for the logger instance. Used for filtering logs across services or systems.
    
    Example
    'auth-service'
  - OptionalidGenerator?: () => string
    Custom ID generator function for log entries.
  - Optionallevel?: string
    Minimum log level to output. Messages below this level will be filtered out.
    
    Example
    'info' // Only info, warn, error, fatal will be logged
    
    Default
    'info'
  - OptionallogDir?: string
    Directory to store log files in (Node only).
    
    Default
    'logs'
  - OptionallogRetentionDays?: number
    Number of days to retain log files before pruning (Node only).
    
    Default
    30
  - OptionalmaxStoredLogs?: number
    Maximum number of log entries to keep in browser storage. Has no effect in Node.js environments.
    
    Default
    1000
  - Optionalmode?: "sync" | "async" | "auto" | "balanced"
    Logger performance mode configuration.
    
    'sync': Always synchronous (immediate output)
    
    'async': Always asynchronous (uses internal AsyncLogger)
    
    'auto': Smart detection based on environment
    
    'balanced': Micro-async buffer with sync fallback
    
    Default
    'sync'
  - Optionalperformance?: "features" | "balanced" | "speed"
    Performance target hint for auto mode detection.
    
    'features': Prioritize rich styling and features (sync)
    
    'speed': Prioritize throughput (async)
    
    'balanced': Balance between features and speed
    
    Default
    'balanced'
  - OptionalperformanceMode?: boolean
    Enable performance mode to disable styling for maximum throughput. When enabled, all styling is bypassed for 3x+ performance improvement.
    
    Default
    false
  - OptionalprettyPrint?: "json" | "inspect"
    Pretty-printing mode for non-string variadic args. 'inspect' uses util.inspect in Node (with colors when enabled); 'json' uses JSON.stringify; default is 'inspect'.
  - OptionalprintMetaInDebug?: boolean
    When true, and verbose mode is enabled, append a compact [meta] summary of selected keys after the printed message. Meta remains structured for transports. Default: false
  - OptionalqueueManager?: QueueManagerOptions | QueueManager
    Queue management configuration for handling backpressure. Can be a QueueManager instance or options to create one.
    
    Example
    // Using options queueManager: { maxSize: 10000, dropPolicy: 'tail', highWaterMark: 0.8 } // Using instance queueManager: new QueueManager({ maxSize: 5000, dropPolicy: 'priority' })
  - OptionalrateLimiter?: RateLimiterOptions | RateLimiter
    Rate limiting configuration for log throttling. Can be a RateLimiter instance or options to create one.
    
    Example
    // Using options rateLimiter: { max: 1000, window: 60000, strategy: 'sliding' } // Using instance rateLimiter: new RateLimiter({ max: 100, window: 10000 })
  - Optionalredactor?: RedactorOptions | Redactor
    PII and sensitive data redaction configuration. Can be a Redactor instance or options to create one.
    
    Example
    // Using preset redactor: { preset: 'strict' } // Using instance redactor: new Redactor({ preset: 'paranoid', auditTrail: true })
  - Optionalsampler?: SamplerOptions | Sampler
    Statistical sampling configuration for volume control. Can be a Sampler instance or options to create one.
    
    Example
    // Using options sampler: { rate: 0.1, strategy: 'adaptive', targetRate: 1000 } // Using instance sampler: createSamplerPreset('production')
  - OptionalstorageName?: string
    Name to use for browser storage (localStorage key or IndexedDB name). Has no effect in Node.js environments.
    
    Default
    'magiclogger-logs'
  - OptionalstoreInBrowser?: boolean
    Whether to store logs in browser storage when in browser environment. Has no effect in Node.js environments.
    
    Default
    false
  - OptionalstrictLevels?: boolean
    Enforces strict log level behavior. If true, unknown levels passed to .log() will throw. If false, unknown levels are treated as custom and passed to .custom().
    
    Default
    false
  - Optionaltags?: string[]
    Optional static tags applied to all logs from this logger. Helps group or filter logs by functional or organizational tag.
    
    Example
    ['api', 'auth']
  - Optionaltheme?: string | ThemeDefinition
    Theme used to style logger output. Can be a string (theme name from ThemeManager) or a full object.
    
    Example
    'dark'
    
    Example
    { * info: ['cyan', 'bold'], * error: ['brightRed', 'bold'], * header: ['brightWhite', 'bgBlue', 'bold'] * }
  - OptionalthemeByTag?: Record<string, string>
    Optional mapping of tags to theme names. When provided, if a logger has any tag present in this map and no explicit theme is set, the mapped theme will be auto-applied. This enables brand/company-specific themes via tags.
    
    Example
    { acme: 'acme', contoso: 'contoso-dark' }
  - Optionaltransports?: Transport[]
    Array of transports to use for logging.
    
    Default
    []
  - OptionaluseColors?: boolean
    Enables or disables terminal or console color output.
    
    Default
    true
  - OptionaluseConsole?: boolean
    Whether to use console transport by default. Set to false to disable automatic console output.
    
    Default
    true
  - OptionaluseDefaultTransports?: boolean
    Whether to automatically create default transports.
    
    Default
    false
  - OptionaluseLocalStorage?: boolean
    Whether to use localStorage (true) or IndexedDB (false) for browser storage. Has no effect in Node.js environments.
    
    Default
    true
  - Optionalverbose?: boolean
    If enabled, debug-level logs will be shown.
    
    Default
    false
  - OptionalwriteToDisk?: boolean
    Writes logs to disk in timestamped .log files (Node only). Ignored in browsers.
    
    Default
    false
Returns SyncLogger
Remarks
All operations are synchronous and block until complete. File output uses sync I/O with optional fsync for durability. Perfect for audit logging and scenarios requiring guaranteed delivery.
Example
```
const logger = new SyncLogger({
  file: './audit.log',
  forceFlush: true,
  useColors: false  // Clean logs for parsing
});
```
- Defined in sync/SyncLogger.ts:109

Accessors

s

get s(): IStyleBuilder
Gets the chainable style builder for formatting text.

Returns IStyleBuilder
The style builder instance
Remarks
Provides fluent API for applying colors and styles to text. Styles are applied synchronously when the chain is executed.
Example
```
const styled = logger.s.red.bold('Error!');
logger.info(styled);
// Styled text guaranteed written before continuing
```
- Defined in sync/SyncLogger.ts:609

Methods

box

box(
    text: string,
    options?: {
        border?: "single" | "double" | "rounded" | "heavy";
        borderColor?: string[];
        color?: string[];
        padding?: number;
    },
): void
Prints text in a decorative box.
Parameters
- text: string
  Text to display in box
- options: {
      border?: "single" | "double" | "rounded" | "heavy";
      borderColor?: string[];
      color?: string[];
      padding?: number;
  } = {}
  Box formatting options
Returns void
Example
```
logger.box('Success!', {
  border: 'double',
  borderColor: ['green']
});
```
- Defined in sync/SyncLogger.ts:852

close

close(): Promise<void>
Closes file handles and performs cleanup.

Returns Promise<void>
Remarks
Always call this when done logging to:
- Close file descriptors
- Flush any pending writes
- Free system resources
Example
```
const logger = new SyncLogger({ file: './app.log' });
try {
  logger.info('Processing');
} finally {
  logger.close();  // Always cleanup
}
```
- Defined in sync/SyncLogger.ts:523

colorParts

colorParts(message: string, colorMap: Record<string, ColorName[]>): string
Colors specific parts of a message based on a color map.
Parameters
- message: string
  The message to log
- colorMap: Record<string, ColorName[]>
  Map of text patterns to color arrays
Returns string
The styled message string
Example
```
logger.colorParts('User john_doe uploaded data.json', {
  'john_doe': ['cyan', 'bold'],
  'data.json': ['yellow']
});
```
- Defined in sync/SyncLogger.ts:780

count

count(label?: string): void
Counts occurrences with a label.
Parameters
- label: string = 'default'
  Counter label
Returns void
Example
```
logger.count('api-calls'); // "api-calls: 1"
logger.count('api-calls'); // "api-calls: 2"
```
- Defined in sync/SyncLogger.ts:942

countReset

countReset(label?: string): void
Resets a counter.
Parameters
- label: string = 'default'
  Counter label to reset
Returns void
- Defined in sync/SyncLogger.ts:955

custom

custom(msg: string, colors?: string[], prefix?: string): void
Logs a custom styled message with optional prefix. Supports arbitrary color combinations and custom prefixes.
Parameters
- msg: string
  Message to log
- colors: string[] = ...
  Array of color names to apply (default: ['white'])
- prefix: string = 'LOG'
  Custom prefix for the message (default: 'LOG')
Returns void
Example
```
logger.custom('Database connected', ['green', 'bold'], 'DB');
logger.custom('API rate limit warning', ['yellow', 'italic'], 'RATE');
```
- Defined in sync/SyncLogger.ts:739

debug

debug(message: string, meta?: LogEntryMeta): void
Logs a debug-level message synchronously.
Parameters
- message: string
  The debug message to log
- Optionalmeta: LogEntryMeta
  Optional metadata object
Returns void
Remarks
Only outputs when verbose mode is enabled. Blocks until written. Use for detailed diagnostic information during development.
Example
```
logger.debug('Processing item', {
  index: i,
  value: item,
  timestamp: Date.now()
});
// Debug info guaranteed written before next operation
```
- Defined in sync/SyncLogger.ts:448

error

error(message: string, error?: Error | LogEntryMeta, meta?: LogEntryMeta): void
Logs an error-level message synchronously with optional Error object.
Parameters
- message: string
  The error message
- Optionalerror: Error | LogEntryMeta
  Error object or metadata
- Optionalmeta: LogEntryMeta
  Additional metadata if error is an Error
Returns void
Remarks
Blocks until written. Automatically extracts stack traces from Error objects. Critical for debugging as the error is guaranteed to be logged before continuing.
Example
```
try {
  dangerousOperation();
} catch (err) {
  logger.error('Operation failed', err);
  // Error is guaranteed logged before cleanup
}
```
- Defined in sync/SyncLogger.ts:385

flush

flush(): void
Forces an fsync to ensure all data is written to disk.

Returns void
Remarks
Usually not needed as SyncLogger flushes after each write by default. Use this if you disabled forceFlush in options but need to ensure a critical log is persisted.
Example
```
const logger = new SyncLogger({
  file: './app.log',
  forceFlush: false  // Disabled for performance
});

logger.info('Normal log');  // May be buffered by OS
logger.error('Critical error');
logger.flush();  // Force critical error to disk
```
- Defined in sync/SyncLogger.ts:573

fmt

fmt(strings: TemplateStringsArray, ...values: unknown[]): string
Formats text using template literal syntax with embedded styles.
Parameters
- strings: TemplateStringsArray
  Template literal strings
- ...values: unknown[]
  Interpolated values
Returns string
The formatted string with styles applied
Remarks
Supports @-style tags for styling within template literals. Processing is synchronous and returns formatted string immediately.
Example
```
const msg = logger.fmt`@red{Error:} ${errorMessage} at @blue{${line}}`;
logger.info(msg);
// Formatted message guaranteed written
```
- Defined in sync/SyncLogger.ts:632

getFilePath

getFilePath(): undefined | string
Gets the current log file path.

Returns undefined | string
The path to the log file, or undefined if not using file output
Example
```
const logger = new SyncLogger({ file: './app.log' });
console.log(logger.getFilePath()); // './app.log'
```
- Defined in sync/SyncLogger.ts:540

getWriteCount

getWriteCount(): number
Gets the number of writes to the file (for debugging).

Returns number
- Defined in sync/SyncLogger.ts:547

group

group(label: string): void
Creates a log group (for API compatibility).
Parameters
- label: string
  Group label
Returns void
- Defined in sync/SyncLogger.ts:965

groupEnd

groupEnd(): void
Ends a log group (for API compatibility).

Returns void
- Defined in sync/SyncLogger.ts:973

header(text: string, styles?: string[]): void
Prints a formatted header with separators.
Parameters
- text: string
  The header text to display
- Optionalstyles: string[]
  Optional array of color names to apply
Returns void
Remarks
Creates a visually distinct header with separator lines. Output is written synchronously before method returns.
Example
```
logger.header('Configuration', ['blue', 'bold']);
// Header guaranteed printed before next log
logger.info('Config loaded');
```
- Defined in sync/SyncLogger.ts:654

info

info(message: string, meta?: LogEntryMeta): void
Logs an info-level message synchronously.
Parameters
- message: string
  The message to log
- Optionalmeta: LogEntryMeta
  Optional metadata object
Returns void
Remarks
Blocks until the message is written to all outputs. Use for general informational messages.
Example
```
logger.info('Server started', { port: 3000 });
// Execution pauses here until log is written
```
- Defined in sync/SyncLogger.ts:359

list

list(
    items: string[],
    options?: {
        bullet?: string;
        bulletColor?: string[];
        indent?: number;
        itemColor?: string[];
    },
): void
Prints a formatted list with bullets.
Parameters
- items: string[]
  Array of items to display
- options: {
      bullet?: string;
      bulletColor?: string[];
      indent?: number;
      itemColor?: string[];
  } = {}
  List formatting options
Returns void
Example
```
logger.list(['Item 1', 'Item 2', 'Item 3']);
```
- Defined in sync/SyncLogger.ts:879

log

log(message: string, level?: string, meta?: LogEntryMeta): void
Generic synchronous logging method with custom level.
Parameters
- message: string
  The message to log
- Optionallevel: string = 'info'
  The severity level
- Optionalmeta: LogEntryMeta
  Optional metadata object
Returns void
Remarks
Blocks until written. Allows specifying any valid log level. Prefer using specific level methods (info, error, etc.) when possible.
Example
```
logger.log('Custom message', 'trace', {
  module: 'auth',
  action: 'validate'
});
// Custom level log guaranteed written
```
- Defined in sync/SyncLogger.ts:498

progressBar

progressBar(
    percentage: number,
    width?: number,
    fillChar?: string,
    emptyChar?: string,
): void
Displays a text-based progress bar.
Parameters
- percentage: number
  Progress percentage (0-100)
- Optionalwidth: number = 40
  Width of the progress bar in characters
- OptionalfillChar: string = '█'
  Character for filled portion
- OptionalemptyChar: string = '░'
  Character for empty portion
Returns void
Remarks
Renders a visual progress indicator synchronously. Useful for batch operations where each step must complete before continuing.
Example
```
for (let i = 0; i <= 100; i += 10) {
  logger.progressBar(i, 50);
  // Progress guaranteed displayed before next iteration
  processNextBatch();
}
```
- Defined in sync/SyncLogger.ts:716

separator

separator(char?: string, length?: number): void
Prints a separator line.
Parameters
- Optionalchar: string = '-'
  Character to repeat for the separator
- Optionallength: number = 60
  Length of the separator line
Returns void
Remarks
Creates visual separation between log sections. Output is written synchronously.
Example
```
logger.info('Phase 1 complete');
logger.separator('=', 80);
logger.info('Starting Phase 2');
// Separator guaranteed printed between phases
```
- Defined in sync/SyncLogger.ts:690

styled

styled(
    msg: string,
    preset:
        | "info"
        | "success"
        | "warning"
        | "error"
        | "debug"
        | "important"
        | "highlight"
        | "muted"
        | "special"
        | "code"
        | "header",
): void
Logs a message with a predefined style preset.
Parameters
- msg: string
  Message to log
- preset:
      | "info"
      | "success"
      | "warning"
      | "error"
      | "debug"
      | "important"
      | "highlight"
      | "muted"
      | "special"
      | "code"
      | "header"
  Style preset name
Returns void
Example
```
logger.styled('Critical system failure', 'error');
logger.styled('Operation completed', 'success');
```
- Defined in sync/SyncLogger.ts:758

success

success(message: string, meta?: LogEntryMeta): void
Logs a success-level message synchronously.
Parameters
- message: string
  The success message to log
- Optionalmeta: LogEntryMeta
  Optional metadata object
Returns void
Remarks
Blocks until written. Use to indicate successful completion of operations. Typically displayed in green when colors enabled.
Example
```
await database.connect();
logger.success('Database connected', {
  host: dbHost,
  port: dbPort
});
// Success guaranteed logged before proceeding
```
- Defined in sync/SyncLogger.ts:473

table

table(
    data: Record<string, unknown>[],
    options?: {
        alignment?: "left" | "right" | "center";
        alternateRowColors?: boolean;
        border?: "none" | "single" | "double" | "rounded" | "heavy";
        borderColor?: string[];
        headerColor?: string[];
    },
): void
Displays data in a formatted table.
Parameters
- data: Record<string, unknown>[]
  Array of objects to display
- options: {
      alignment?: "left" | "right" | "center";
      alternateRowColors?: boolean;
      border?: "none" | "single" | "double" | "rounded" | "heavy";
      borderColor?: string[];
      headerColor?: string[];
  } = {}
  Table formatting options
Returns void
Example
```
logger.table([
  { name: 'Alice', role: 'Admin' },
  { name: 'Bob', role: 'User' }
]);
```
- Defined in sync/SyncLogger.ts:805

time

time(label: string): void
Starts a timer with the given label.
Parameters
- label: string
  Timer label
Returns void
Example
```
logger.time('operation');
// ... do work ...
logger.timeEnd('operation');
```
- Defined in sync/SyncLogger.ts:909

timeEnd

timeEnd(label: string): void
Stops a timer and logs elapsed time.
Parameters
- label: string
  Timer label to stop
Returns void
- Defined in sync/SyncLogger.ts:919

warn

warn(message: string, meta?: LogEntryMeta): void
Logs a warning-level message synchronously.
Parameters
- message: string
  The warning message
- Optionalmeta: LogEntryMeta
  Optional metadata
Returns void
Remarks
Blocks until written. Use for potentially problematic situations that don't prevent operation but should be addressed.
Example
```
if (cacheSize > threshold) {
  logger.warn('Cache size exceeding threshold', {
    size: cacheSize,
    threshold
  });
  // Warning guaranteed logged before continuing
}
```
- Defined in sync/SyncLogger.ts:423

Class SyncLogger

Example: Basic usage

Example: Audit logging

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Optionalcontext?: Record<string, unknown>

Example

OptionalfallbackToSync?: boolean

Default

Optionalfile?: string

Example

OptionalforceFlush?: boolean

Default

Optionalid?: string

Example

OptionalidGenerator?: () => string

Optionallevel?: string

Example

Default

OptionallogDir?: string

Default

OptionallogRetentionDays?: number

Default

OptionalmaxStoredLogs?: number

Default

Optionalmode?: "sync" | "async" | "auto" | "balanced"

Default

Optionalperformance?: "features" | "balanced" | "speed"

Default

OptionalperformanceMode?: boolean

Default

OptionalprettyPrint?: "json" | "inspect"

OptionalprintMetaInDebug?: boolean

OptionalqueueManager?: QueueManagerOptions | QueueManager

Example

OptionalrateLimiter?: RateLimiterOptions | RateLimiter

Example

Optionalredactor?: RedactorOptions | Redactor

Example

Optionalsampler?: SamplerOptions | Sampler

Example

OptionalstorageName?: string

Default

OptionalstoreInBrowser?: boolean

Default

OptionalstrictLevels?: boolean

Default

Optionaltags?: string[]

Example

Optionaltheme?: string | ThemeDefinition

Example

Example

OptionalthemeByTag?: Record<string, string>

Example

Optionaltransports?: Transport[]

Default

OptionaluseColors?: boolean

Default

OptionaluseConsole?: boolean

Default

OptionaluseDefaultTransports?: boolean

Default

OptionaluseLocalStorage?: boolean

Default

Optionalverbose?: boolean

Default

OptionalwriteToDisk?: boolean

Default

Returns SyncLogger

Remarks

Example

Accessors

s

Returns IStyleBuilder

Remarks

`Optional`context?: Record<string, unknown>

`Optional`fallbackToSync?: boolean

`Optional`file?: string

`Optional`forceFlush?: boolean

`Optional`id?: string

`Optional`idGenerator?: () => string

`Optional`level?: string

`Optional`logDir?: string

`Optional`logRetentionDays?: number

`Optional`maxStoredLogs?: number

`Optional`mode?: "sync" | "async" | "auto" | "balanced"

`Optional`performance?: "features" | "balanced" | "speed"

`Optional`performanceMode?: boolean

`Optional`prettyPrint?: "json" | "inspect"

`Optional`printMetaInDebug?: boolean

`Optional`queueManager?: QueueManagerOptions | QueueManager

`Optional`rateLimiter?: RateLimiterOptions | RateLimiter

`Optional`redactor?: RedactorOptions | Redactor

`Optional`sampler?: SamplerOptions | Sampler

`Optional`storageName?: string

`Optional`storeInBrowser?: boolean

`Optional`strictLevels?: boolean

`Optional`tags?: string[]

`Optional`theme?: string | ThemeDefinition

`Optional`themeByTag?: Record<string, string>

`Optional`transports?: Transport[]

`Optional`useColors?: boolean

`Optional`useConsole?: boolean

`Optional`useDefaultTransports?: boolean

`Optional`useLocalStorage?: boolean

`Optional`verbose?: boolean

`Optional`writeToDisk?: boolean