tessl/npm-logform

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Format Composition

Name: tessl/npm-logform
Author: tessl

Utilities for combining and organizing multiple formats into powerful transformation pipelines.

Capabilities

Combine Format

Combines multiple formats into a single format that applies transformations in sequence.

/**
 * Combines multiple formats into a single format pipeline
 * @param {...Format} formats - Variable number of format instances to combine
 * @returns {Format} Combined format instance
 */
function combine(...formats);

The combine function creates a pipeline where each format's transform method is called in sequence. If any format returns a falsy value, the pipeline stops and the log entry is filtered out.

Usage Examples:

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

// Basic combination
const combinedFormat = format.combine(
  format.timestamp(),
  format.label({ label: 'my-app' }),
  format.colorize(),
  format.simple()
);

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

// Complex combination with filtering
const productionFormat = format.combine(
  format.timestamp({ format: 'YYYY-MM-DD HH:mm:ss' }),
  format.errors({ stack: true }),
  format.splat(),
  format.json()
);

// Development format with colors
const developmentFormat = format.combine(
  format.colorize(),
  format.timestamp(),
  format.align(),
  format.printf(info => `${info.timestamp} ${info.level}: ${info.message}`)
);

// Conditional formatting
const conditionalFormat = format.combine(
  format.timestamp(),
  format((info) => {
    if (info.level === 'debug' && process.env.NODE_ENV === 'production') {
      return false; // Filter out debug logs in production
    }
    return info;
  }),
  format.json()
);

Format Pipeline Behavior

The combine format implements a cascade pattern where:

Each format is applied in the order specified
The output of one format becomes the input to the next
If any format returns false or other falsy value, the pipeline stops
The final result is returned, or false if filtered

Pipeline Examples:

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

// Pipeline with filtering
const filteringPipeline = format.combine(
  format.timestamp(),
  format((info) => {
    // Filter out sensitive information
    if (info.message.includes('password')) {
      return false;
    }
    return info;
  }),
  format.json()
);

// Error handling pipeline
const errorPipeline = format.combine(
  format.errors({ stack: true }),
  format.timestamp(),
  format.printf(info => {
    if (info.stack) {
      return `${info.timestamp} ERROR: ${info.message}\n${info.stack}`;
    }
    return `${info.timestamp} ${info.level.toUpperCase()}: ${info.message}`;
  })
);

// Metadata organization pipeline
const metadataPipeline = format.combine(
  format.splat(),
  format.metadata({ fillExcept: ['level', 'message', 'timestamp'] }),
  format.timestamp(),
  format.json()
);

Cascade Function

The internal cascade function that implements the pipeline logic.

/**
 * Creates a cascade function that applies formats in sequence
 * @param {Format[]} formats - Array of format instances
 * @returns {Function} Cascade function that processes info objects
 */
function cascade(formats);

The cascade function validates that all provided formats have a transform method and creates a function that applies each transformation in sequence.

Internal Usage:

// Internal implementation example
function cascade(formats) {
  return (info) => {
    let obj = info;
    for (let i = 0; i < formats.length; i++) {
      obj = formats[i].transform(obj, formats[i].options);
      if (!obj) {
        return false; // Stop pipeline if format returns falsy
      }
    }
    return obj;
  };
}

Format Validation

The combine function includes validation to ensure all provided arguments are valid format instances.

/**
 * Validates that an object is a valid format instance
 * @param {any} format - Object to validate
 * @returns {boolean} True if valid format
 * @throws {Error} If format is invalid
 */
function isValidFormat(format);

Valid formats must have:

A transform method that is a function
Optional options property for configuration

Validation Examples:

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

// Valid format instances
const validFormats = [
  format.timestamp(),
  format.json(),
  format.colorize({ level: true })
];

// Invalid format examples that would throw errors
try {
  format.combine(
    format.timestamp(),
    { transform: 'not a function' }, // Invalid - transform is not a function
    format.json()
  );
} catch (error) {
  console.error('Invalid format detected:', error.message);
}

Advanced Composition Patterns

Conditional Formatting

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

const conditionalFormat = format.combine(
  format.timestamp(),
  format((info) => {
    // Apply different formatting based on log level
    if (info.level === 'error') {
      info.urgent = true;
    }
    return info;
  }),
  format.printf(info => {
    const prefix = info.urgent ? '🚨 ' : '';
    return `${prefix}${info.timestamp} [${info.level}]: ${info.message}`;
  })
);

Environment-Based Formatting

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

const environmentFormat = format.combine(
  format.timestamp(),
  process.env.NODE_ENV === 'development' 
    ? format.combine(
        format.colorize(),
        format.simple()
      )
    : format.combine(
        format.errors({ stack: true }),
        format.json()
      )
);

Multi-Transport Formatting

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

// Base format for all transports
const baseFormat = format.combine(
  format.timestamp(),
  format.errors({ stack: true }),
  format.splat()
);

// Console-specific format
const consoleFormat = format.combine(
  baseFormat,
  format.colorize(),
  format.printf(info => `${info.timestamp} ${info.level}: ${info.message}`)
);

// File-specific format
const fileFormat = format.combine(
  baseFormat,
  format.json()
);