logfmt: Key-Value Logger and Parser

Common errors

• TypeError: logfmt.stringify is not a function

  cause Attempting to call `stringify` or other methods on an undefined `logfmt` object, or if the `logfmt` variable was reassigned.
  fix Ensure `const logfmt = require('logfmt');` is correctly placed and executed before calling any methods on `logfmt`. Verify no other code is inadvertently overwriting the `logfmt` variable.

• TypeError: Cannot read properties of undefined (reading 'pipe')

  cause This typically occurs when attempting to `pipe` to a `logfmt.streamParser()` or `logfmt.streamStringify()` instance, but the stream object itself is undefined or not a valid stream.
  fix Check that the stream being piped from (e.g., `process.stdin`, `req`, a `Readable` stream) is properly initialized and available. Ensure `logfmt.streamParser()` or `logfmt.streamStringify()` are correctly called without errors.

• SyntaxError: Unexpected token 'o' at JSON.parse (<anonymous>)

  cause This error happens when a logfmt string is accidentally passed to `JSON.parse()`. Logfmt is a key-value format, not JSON.
  fix Use `logfmt.parse(yourLogfmtString)` to correctly parse logfmt strings into JavaScript objects. Reserve `JSON.parse()` for actual JSON strings.

• ReferenceError: logfmt is not defined

  cause The `logfmt` variable was used without being declared or initialized, usually by omitting the `require` statement.
  fix Add `const logfmt = require('logfmt');` at the top of your file to properly import the module.

Warnings

• breaking The `logfmt` package appears to be abandoned. The last commit on GitHub was in June 2018, and the last release was in February 2018. This means there will be no further bug fixes, security patches, or feature development. Using this library in new projects is strongly discouraged.
  Fix: Consider alternatives for structured logging like `pino`, `winston`, or `bunyan` which offer active maintenance and modern features. If logfmt format is strictly required, fork the repository or use a more actively maintained logfmt parser/stringifier if one exists.
• gotcha The `logfmt.parse()` method does not automatically convert all numeric strings to numbers. It only converts `true` and `false` strings to booleans. Numbers are parsed as strings to avoid precision loss issues with 32-bit representations.
  Fix: Manually cast values to numbers after parsing if numeric operations are required: `const parsed = logfmt.parse('count=123'); const count = parseInt(parsed.count, 10);`
• gotcha The `logfmt` module is a singleton when imported via `require('logfmt')`. Any modifications to its properties (e.g., `logfmt.stringify = JSON.stringify`) will affect all parts of your application that use this global instance.
  Fix: To create an independent, configurable instance, use `const customLogfmt = new logfmt();`. This will allow you to modify `customLogfmt` without affecting the main singleton instance.
• gotcha The library primarily targets CommonJS environments and does not officially support ES Modules (ESM). While bundlers might transpile it, direct ESM `import` statements may behave unexpectedly or require specific configuration.
  Fix: For Node.js projects, use `const logfmt = require('logfmt');`. If an ESM-only project needs this, consider a wrapper or transpilation, but be aware of potential issues due to its age and CJS-centric design.

Install

• npm install logfmt npm
• yarn add logfmt yarn
• pnpm add logfmt pnpm

Imports

• logfmt
  wrong:

  import logfmt from 'logfmt';

  correct:

  const logfmt = require('logfmt');

  The library is primarily CommonJS. While some bundlers may shim `import logfmt from 'logfmt'`, `require()` is the intended and most reliable way to import the module.
• logfmt.stringify
  wrong:

  import { stringify } from 'logfmt';

  correct:

  const logfmt = require('logfmt');
  logfmt.stringify({ key: 'value' });

  Functions like `stringify` are properties of the main `logfmt` module object, not named exports for direct destructuring in CommonJS or ESM without specific configuration.
• logfmt.parse
  wrong:

  const parse = require('logfmt').parse;

  correct:

  const logfmt = require('logfmt');
  logfmt.parse('key=value');

  While `require('logfmt').parse` works, the module is designed as a singleton object, so accessing methods directly from the main `logfmt` constant is idiomatic.
• logfmt.streamParser

  const logfmt = require('logfmt');
  process.stdin.pipe(logfmt.streamParser());

  Used for creating a readable stream that parses incoming logfmt lines into JavaScript objects. Requires piping from another stream.

Quickstart

Demonstrates basic `stringify` and `parse` operations, then shows how to use `streamParser` to process logfmt data from a simulated stream.

const logfmt = require('logfmt');
const through = require('through'); // often used for stream manipulation

// --- Non-streaming usage ---
const data = { status: 200, method: 'GET', path: '/api/items', duration_ms: 50 };
const logString = logfmt.stringify(data);
console.log('Stringified:', logString);
// Expected: Stringified: status=200 method=GET path=/api/items duration_ms=50

const parsedObject = logfmt.parse('status=200 method=GET path=/api/items duration_ms=50');
console.log('Parsed:', parsedObject);
// Expected: Parsed: { status: '200', method: 'GET', path: '/api/items', duration_ms: '50' }

// --- Streaming usage (parsing logfmt from a simulated input) ---
const { Readable } = require('stream');
const simulatedInput = new Readable({
  read() {
    this.push('metric=cpu_usage value=0.5 host=web-01\n');
    this.push('metric=memory_free value=1024 host=db-01\n');
    this.push(null); // No more data
  }
});

console.log('\n--- Streaming Parse Output ---');
simulatedInput
  .pipe(logfmt.streamParser())
  .pipe(through(function(obj) {
    console.log('Streamed Object:', obj);
  }));
// Expected: Streamed Object: { metric: 'cpu_usage', value: '0.5', host: 'web-01' }
// Expected: Streamed Object: { metric: 'memory_free', value: '1024', host: 'db-01' }