smartlog/API.md

@push.rocks/smartlog API Reference

This document provides a detailed reference for all exports and APIs available in the @push.rocks/smartlog package and its submodules.

Core Module (@push.rocks/smartlog)

The core module provides the main logging functionality.

Classes

Smartlog

Main logger class for creating, managing, and routing logs.

import { Smartlog } from '@push.rocks/smartlog';

const logger = new Smartlog({
  logContext: {
    company: 'MyCompany',
    environment: 'production',
    // ...other context properties
  },
  minimumLogLevel: 'info' // Optional, defaults to 'silly'
});

Constructor Options:

• logContext: Object containing context information about the environment
• minimumLogLevel: Optional minimum log level to process (defaults to 'silly')

Methods:

• log(logLevel, message, data?, correlation?): Log a message with optional data and correlation
• increment(logLevel, message, data?, correlation?): Log an increment counter
• addLogDestination(destination): Add a custom log destination
• enableConsole(options?): Enable console logging (with optional stdout/stderr capture)
• createLogGroup(transactionId?): Create a log group for related logs
• handleLog(logPackage): Handle a pre-formatted log package

Static Methods:

• createForCommitinfo(commitinfo): Create a logger with commit information

LogGroup

Groups related logs together for better traceability.

import { Smartlog } from '@push.rocks/smartlog';

const logger = new Smartlog({/*...*/});
const logGroup = logger.createLogGroup('transaction-123');

logGroup.log('info', 'Starting process');
// All logs in this group will share the same transaction ID

Methods:

• log(logLevel, message, data?): Log a message within this group
• increment(logLevel, message, data?): Log an increment within this group

ConsoleLog

Implementation of ILogDestination that logs to console.

Interfaces Module (@push.rocks/smartlog/interfaces)

This module provides all type definitions and interfaces used by Smartlog.

Types

• TLogType: Available log types

  • 'log' | 'increment' | 'gauge' | 'error' | 'success' | 'value' | 'finance' | 'compliance'

• TLogLevel: Available log levels

  • 'silly' | 'info' | 'debug' | 'note' | 'ok' | 'success' | 'warn' | 'error' | 'lifecycle'

• TEnvironment: Available environments

  • 'local' | 'test' | 'staging' | 'production'

• TRuntime: Available runtime environments

  • 'node' | 'chrome' | 'rust' | 'deno' | 'cloudflare_workers'

Interfaces

ILogContext

Metadata about the environment where logging occurs.

interface ILogContext {
  commitinfo?: ICommitInfo;
  company?: string;
  companyunit?: string;
  containerName?: string;
  environment?: TEnvironment;
  runtime?: TRuntime;
  zone?: string;
}

ILogCorrelation

Information for correlating related logs.

interface ILogCorrelation {
  id: string;
  type: 'none' | 'service' | 'build' | 'infrastructure' | 'cdn';
  instance?: string;
  group?: string;
  transaction?: string;
}

ILogPackage<T = unknown>

The standard log package format.

interface ILogPackage<T = unknown> {
  timestamp: number;
  type: TLogType;
  context: ILogContext;
  level: TLogLevel;
  correlation: ILogCorrelation;
  message: string;
  data?: T;
}

ILogDestination

Interface for implementing custom log destinations.

interface ILogDestination {
  handleLog: (logPackage: ILogPackage) => Promise<void>;
}

Interactive Console Module (@push.rocks/smartlog/source-interactive)

This module provides interactive console components like spinners and progress bars.

Classes

SmartlogSourceInteractive

Creates interactive spinners for CLI applications.

import { SmartlogSourceInteractive } from '@push.rocks/smartlog/source-interactive';

const spinner = new SmartlogSourceInteractive();
spinner.text('Loading data...');
// Later
spinner.finishSuccess('Data loaded successfully!');

Methods:

• text(message): Sets the spinner text and starts it if not running
• finishSuccess(message?): Completes the spinner with success message
• finishFail(message?): Completes the spinner with failure message
• successAndNext(message): Marks success and starts a new spinner
• failAndNext(message): Marks failure and starts a new spinner
• setSpinnerStyle(style): Sets spinner style ('dots', 'line', 'star', 'simple')
• setColor(color): Sets the spinner color
• setSpeed(ms): Sets the animation speed

SmartlogProgressBar

Creates progress bars for CLI applications.

import { SmartlogProgressBar } from '@push.rocks/smartlog/source-interactive';

const bar = new SmartlogProgressBar({
  total: 100,
  width: 40,
  showEta: true
});

bar.update(50); // Update to 50%
bar.increment(10); // Increment by 10 units
bar.complete(); // Complete the progress bar

Constructor Options:

• total: Total number of items/steps
• width: Width of the bar in characters
• complete: Character for completed section
• incomplete: Character for incomplete section
• renderThrottle: Minimum time between renders
• clear: Whether to clear the bar on completion
• showEta: Show estimated time remaining
• showPercent: Show percentage completed
• showCount: Show count of items

Methods:

• update(value): Update progress to a specific value
• increment(value?): Increment progress by a value (default: 1)
• complete(): Mark the progress bar as complete
• setColor(color): Set the color of the progress bar

File Destination Module (@push.rocks/smartlog/destination-file)

This module provides a log destination that writes logs to a file.

Classes

SmartlogDestinationFile

Writes logs to a file with timestamps.

import { Smartlog } from '@push.rocks/smartlog';
import { SmartlogDestinationFile } from '@push.rocks/smartlog/destination-file';

const logger = new Smartlog({/*...*/});
const fileDestination = new SmartlogDestinationFile('/absolute/path/to/logfile.log');
logger.addLogDestination(fileDestination);

Constructor Parameters:

• filePath: Absolute path to the log file

Local Destination Module (@push.rocks/smartlog/destination-local)

This module provides a log destination with colorful formatting for local development.

Classes

DestinationLocal

Formats logs with colors and prefixes for better readability in the console.

import { Smartlog } from '@push.rocks/smartlog';
import { DestinationLocal } from '@push.rocks/smartlog/destination-local';

const logger = new Smartlog({/*...*/});
const localDestination = new DestinationLocal();
logger.addLogDestination(localDestination);

Methods:

• handleLog(logPackage): Handles a log package
• newLine(lines?): Adds empty lines to the console
• logReduced(text, repeatEveryTimes?): Logs only when the message changes

DevTools Destination Module (@push.rocks/smartlog/destination-devtools)

This module provides a log destination that formats logs for browser developer tools.

Classes

SmartlogDestinationDevtools

Formats logs with colors for browser developer tools.

import { Smartlog } from '@push.rocks/smartlog';
import { SmartlogDestinationDevtools } from '@push.rocks/smartlog/destination-devtools';

const logger = new Smartlog({/*...*/});
const devtoolsDestination = new SmartlogDestinationDevtools();
logger.addLogDestination(devtoolsDestination);

ClickHouse Destination Module (@push.rocks/smartlog/destination-clickhouse)

This module provides a log destination that stores logs in a ClickHouse database.

Classes

SmartlogDestinationClickhouse

Stores logs in a ClickHouse database for analytics and querying.

import { Smartlog } from '@push.rocks/smartlog';
import { SmartlogDestinationClickhouse } from '@push.rocks/smartlog/destination-clickhouse';

const logger = new Smartlog({/*...*/});
const clickhouseDestination = await SmartlogDestinationClickhouse.createAndStart({
  host: 'clickhouse.example.com',
  port: 8123,
  user: 'username',
  password: 'password',
  database: 'logs_db'
});
logger.addLogDestination(clickhouseDestination);

Static Methods:

• createAndStart(options): Create and initialize a ClickHouse destination

Methods:

• start(): Initialize the connection to ClickHouse
• handleLog(logPackage): Store a log in ClickHouse