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

Data Enhancement

Name: tessl/npm-logform
Author: tessl

Formats that add or organize metadata in log entries, including timestamps, labels, metadata organization, and timing information.

Capabilities

Timestamp Format

Adds timestamp information to log info objects.

/**
 * Creates a timestamp format that adds timestamp to info objects
 * @param {Object} opts - Timestamp options
 * @param {string|Function} opts.format - Date format string (fecha) or custom function
 * @param {string} opts.alias - Alternative property name for timestamp
 * @returns {Format} Timestamp format instance
 */
function timestamp(opts);

Usage Examples:

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

// Default ISO timestamp
const timestampFormat = format.timestamp();
const result1 = timestampFormat.transform({
  level: 'info',
  message: 'Hello world'
});
// Adds: timestamp: '2023-01-01T12:00:00.000Z'

// Custom format using fecha
const customTimestamp = format.timestamp({
  format: 'YYYY-MM-DD HH:mm:ss'
});
const result2 = customTimestamp.transform({
  level: 'info',
  message: 'Hello world'
});
// Adds: timestamp: '2023-01-01 12:00:00'

// Custom function
const functionTimestamp = format.timestamp({
  format: () => new Date().toLocaleString()
});

// With alias
const aliasTimestamp = format.timestamp({
  alias: 'time'
});
const result3 = aliasTimestamp.transform({
  level: 'info',
  message: 'Hello world'
});
// Adds both: timestamp: '2023-01-01T12:00:00.000Z' and time: '2023-01-01T12:00:00.000Z'

Label Format

Adds custom labels to log entries either as a separate property or inline with the message.

/**
 * Creates a label format that adds labels to info objects
 * @param {Object} opts - Label options
 * @param {string} opts.label - Label string to add
 * @param {boolean} opts.message - Add label to message text vs separate property
 * @returns {Format} Label format instance
 */
function label(opts);

Usage Examples:

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

// Label as separate property
const labelFormat = format.label({ label: 'my-service' });
const result1 = labelFormat.transform({
  level: 'info',
  message: 'Hello world'
});
// Result: { level: 'info', message: 'Hello world', label: 'my-service' }

// Label inline with message
const inlineLabelFormat = format.label({ 
  label: 'my-service',
  message: true 
});
const result2 = inlineLabelFormat.transform({
  level: 'info',
  message: 'Hello world'
});
// Result: { level: 'info', message: '[my-service] Hello world' }

Metadata Format

Organizes extraneous data into a metadata object, similar to winston 2.x behavior.

/**
 * Creates a metadata format that organizes extra properties
 * @param {Object} opts - Metadata options
 * @param {string} opts.key - Name of metadata property (default: 'metadata')
 * @param {string[]} opts.fillExcept - Keys to exclude from metadata
 * @param {string[]} opts.fillWith - Keys to include in metadata
 * @returns {Format} Metadata format instance
 */
function metadata(opts);

Usage Examples:

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

// Default behavior - exclude level and message
const metadataFormat = format.metadata();
const result1 = metadataFormat.transform({
  level: 'info',
  message: 'Hello world',
  userId: 123,
  ip: '192.168.1.1',
  userAgent: 'Mozilla/5.0...'
});
// Result: {
//   level: 'info',
//   message: 'Hello world',
//   metadata: {
//     userId: 123,
//     ip: '192.168.1.1',
//     userAgent: 'Mozilla/5.0...'
//   }
// }

// Custom metadata key
const customKeyFormat = format.metadata({ key: 'meta' });

// Exclude specific fields
const excludeFormat = format.metadata({
  fillExcept: ['level', 'message', 'timestamp']
});

// Include only specific fields
const includeFormat = format.metadata({
  fillWith: ['userId', 'sessionId']
});
const result2 = includeFormat.transform({
  level: 'info',
  message: 'User action',
  userId: 123,
  sessionId: 'abc-def',
  ip: '192.168.1.1' // This won't be included
});
// Result: {
//   level: 'info',
//   message: 'User action',
//   ip: '192.168.1.1',
//   metadata: {
//     userId: 123,
//     sessionId: 'abc-def'
//   }
// }

MS Format

Adds timing information showing milliseconds since the previous log message.

/**
 * Creates an ms format that adds timing information
 * @returns {Format} MS format instance
 */
function ms();

Usage Examples:

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

const msFormat = format.ms();

// First log
const result1 = msFormat.transform({
  level: 'info',
  message: 'Starting process'
});
// Adds: ms: '+0ms' (or similar initial value)

// Wait some time...
setTimeout(() => {
  const result2 = msFormat.transform({
    level: 'info',
    message: 'Process step completed'
  });
  // Adds: ms: '+250ms' (actual time difference)
}, 250);

// Combined with other formats
const combinedFormat = format.combine(
  format.timestamp(),
  format.ms(),
  format.simple()
);

Options Interfaces

Timestamp Options

interface TimestampOptions {
  /** Date format string (fecha) or custom function */
  format?: string | (() => string);
  
  /** Alternative property name for timestamp */
  alias?: string;
}

Label Options

interface LabelOptions {
  /** Label string to add */
  label?: string;
  
  /** Add label to message text vs separate property */
  message?: boolean;
}

Metadata Options

interface MetadataOptions {
  /** Name of metadata property (default: 'metadata') */
  key?: string;
  
  /** Keys to exclude from metadata */
  fillExcept?: string[];
  
  /** Keys to include in metadata */
  fillWith?: string[];
}