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

JSON and Structured Formats

Name: tessl/npm-logform
Author: tessl

Formats for structured data output including JSON serialization, Logstash compatibility, and pretty-printed object inspection.

Capabilities

JSON Format

Serializes log info objects to JSON using safe-stable-stringify for reliable output.

/**
 * Creates a JSON format with configurable serialization options
 * @param {Object} opts - JSON formatting options
 * @param {Function} opts.replacer - Function that influences how info is stringified
 * @param {number} opts.space - Number of white spaces for formatting
 * @param {boolean} opts.bigint - Handle bigint values (default: true)
 * @param {string|null|Function} opts.circularValue - Value for circular references (default: "[Circular]")
 * @param {boolean} opts.deterministic - Guarantee deterministic key order (default: true)
 * @param {number} opts.maximumBreadth - Max properties per object (default: Infinity)
 * @param {number} opts.maximumDepth - Max nesting levels (default: Infinity)
 * @returns {Format} JSON format instance
 */
function json(opts);

Usage Examples:

const { format } = require('logform');
const { MESSAGE } = require('triple-beam');

// Basic JSON format
const jsonFormat = format.json();
const result = jsonFormat.transform({
  level: 'info',
  message: 'Hello world',
  meta: { userId: 123 }
});
console.log(result[MESSAGE]); 
// '{"level":"info","message":"Hello world","meta":{"userId":123}}'

// Pretty printed JSON
const prettyJson = format.json({ space: 2 });
const prettyResult = prettyJson.transform({
  level: 'info',
  message: 'Hello world'
});

// With custom replacer
const customJson = format.json({
  replacer: (key, value) => {
    if (key === 'password') return '[REDACTED]';
    return value;
  }
});

// With safe-stable-stringify options
const safeJson = format.json({
  maximumDepth: 5,
  circularValue: '[Circular Reference]',
  deterministic: true
});

Logstash Format

Transforms log info objects into Logstash-compatible JSON format.

/**
 * Creates a Logstash-compatible format
 * @returns {Format} Logstash format instance
 */
function logstash();

The Logstash format restructures the info object into Logstash's expected schema:

@message: The original message
@timestamp: The timestamp (if present)
@fields: All other properties from the info object

Usage Examples:

const { format } = require('logform');
const { MESSAGE } = require('triple-beam');

const logstashFormat = format.combine(
  format.timestamp(),
  format.logstash()
);

const result = logstashFormat.transform({
  level: 'info',
  message: 'User logged in',
  userId: 123,
  ip: '192.168.1.1'
});

console.log(result[MESSAGE]);
// '{"@message":"User logged in","@timestamp":"2023-01-01T00:00:00.000Z","@fields":{"level":"info","userId":123,"ip":"192.168.1.1"}}'

Pretty Print Format

Pretty-prints log info objects using Node.js util.inspect for development and debugging.

/**
 * Creates a pretty-print format using util.inspect
 * @param {Object} opts - Pretty print options
 * @param {number} opts.depth - Maximum depth for object inspection (default: 2)
 * @param {boolean} opts.colorize - Enable colorization (default: false)
 * @returns {Format} Pretty print format instance
 */
function prettyPrint(opts);

Note: The pretty print format should not be used in production as it may impact performance and block the event loop.

Usage Examples:

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

// Basic pretty print
const prettyFormat = format.prettyPrint();
const result = prettyFormat.transform({
  [LEVEL]: 'info',
  level: 'info',
  message: 'Complex object',
  data: {
    users: [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }],
    settings: { theme: 'dark', language: 'en' }
  }
});

// With custom depth and colors
const coloredPretty = format.prettyPrint({
  depth: 3,
  colorize: true
});

// Symbols are automatically stripped from output
const complexResult = prettyFormat.transform({
  [LEVEL]: 'info',
  [MESSAGE]: 'This will be stripped',
  [SPLAT]: ['This too'],
  level: 'info',
  message: 'Visible message',
  metadata: { key: 'value' }
});
console.log(complexResult[MESSAGE]);
// "{ level: 'info', message: 'Visible message', metadata: { key: 'value' } }"

JSON Format Options

Safe-Stable-Stringify Options

The JSON format uses safe-stable-stringify internally, providing these additional options:

interface JsonOptions {
  /** Function that influences stringification */
  replacer?: (key: string, value: any) => any;
  
  /** Number of white spaces for formatting */
  space?: number;
  
  /** Convert bigint to number (default: true) */
  bigint?: boolean;
  
  /** Value for circular references (default: "[Circular]") */
  circularValue?: string | null | ErrorConstructor;
  
  /** Guarantee deterministic key order (default: true) */
  deterministic?: boolean;
  
  /** Maximum properties per object (default: Infinity) */
  maximumBreadth?: number;
  
  /** Maximum nesting levels (default: Infinity) */
  maximumDepth?: number;
}