or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

colorization.mdcore-formats.mddata-enhancement.mdformat-composition.mdindex.mdjson-formats.mdstring-processing.mdtext-formatting.md
tile.json

tessl/npm-logform

An mutable object-based log format designed for chaining & objectMode streams.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/logform@2.7.x

To install, run

npx @tessl/cli install tessl/npm-logform@2.7.0

index.mddocs/

Logform

Logform is a mutable object-based log format library designed for chaining and objectMode streams. It serves as the core formatting engine for the winston logging library, providing a comprehensive set of composable formatting functions that transform log info objects through customizable pipelines.

Package Information

  • Package Name: logform
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install logform

Core Imports

const { format } = require('logform');

For ES modules:

import { format } from 'logform';

Individual formats can be imported directly:

const { format: { combine, timestamp, json } } = require('logform');

Basic Usage

const { format } = require('logform');

// Simple format usage
const timestampFormat = format.timestamp();
const info = timestampFormat.transform({
  level: 'info',
  message: 'Hello world'
});

// Combining multiple formats
const combinedFormat = format.combine(
  format.timestamp(),
  format.colorize(),
  format.simple()
);

const formattedInfo = combinedFormat.transform({
  level: 'info',
  message: 'Hello world'
});

Architecture

Logform is built around several key concepts:

  • Info Objects: Mutable objects containing level, message, and optional metadata
  • Format Functions: Transformation functions that accept (info, opts) and return modified info or falsy values
  • Format Instances: Created by calling format functions with options, contain a transform method
  • Format Combining: Multiple formats can be chained together using format.combine()
  • Symbol Properties: Internal state maintained using symbols from the triple-beam package

The library follows a functional approach where formats are composable transformation functions that can be combined to create sophisticated logging pipelines.

Capabilities

Core Format Creation

The main entry point for creating custom formats and accessing built-in formats.

/**
 * Creates a new format from a transformation function
 * @param {Function} transformFn - Function that takes (info, opts) and returns modified info
 * @returns {Function} Format constructor function
 */
function format(transformFn);

/**
 * Registers color configurations for log levels
 * @param {Object} config - Configuration object with colors property
 * @returns {Object} The configuration object
 */
function levels(config);

Core Format System

Text Formatting

Basic text formatting operations for messages and levels.

// Simple text formatting
function align();
function simple();
function printf(templateFn);

Text Formatting

JSON and Structured Output

Formats for structured data output including JSON and Logstash formats.

function json(opts);
function logstash();
function prettyPrint(opts);

JSON and Structured Formats

Colorization and Visual Enhancement

Color-related formatting for terminal and CLI output.

function colorize(opts);
function uncolorize(opts);
function cli(opts);

Colorization

Data Enhancement and Metadata

Formats that add or organize metadata in log entries.

function timestamp(opts);
function label(opts);
function metadata(opts);
function ms();

Data Enhancement

String Processing and Error Handling

Advanced text processing and error handling capabilities.

function splat();
function errors(opts);
function padLevels(opts);

String Processing

Format Composition

Utilities for combining and organizing multiple formats.

function combine(...formats);

Format Composition

Core Types

// Info object structure (from TypeScript definitions)
interface TransformableInfo {
  level: string;
  message: unknown;
  [LEVEL]?: string;
  [MESSAGE]?: unknown;
  [SPLAT]?: unknown;
  [key: string | symbol]: unknown;
}

// Transform function signature
type TransformFunction = (info: TransformableInfo, opts?: unknown) => TransformableInfo | boolean;

// Format constructor function
type FormatWrap = (opts?: unknown) => Format;

// Base format class
class Format {
  constructor(opts?: object);
  options?: object;
  transform: TransformFunction;
}

Symbols and Constants

Logform uses symbols from the triple-beam package for internal state:

const { LEVEL, MESSAGE, SPLAT } = require('triple-beam');

// Symbol.for('level') - Read-only level property
// Symbol.for('message') - Complete formatted message string
// Symbol.for('splat') - String interpolation arguments