JSON Log Line Utility

Common errors

• TypeError: logLineFactory is not a function

  cause Incorrect module import syntax (e.g., using `require` for an ESM module), or module resolution issues.
  fix Ensure your Node.js project is configured for ES Modules (e.g., `"type": "module"` in `package.json`) and use `import { logLineFactory } from 'json-log-line';`.

• Error: Cannot find module 'json-log-line'

  cause Module not installed, incorrect path, or an ES Modules vs. CommonJS mismatch in a complex setup.
  fix Run `npm install json-log-line` to ensure the package is installed. Verify your module resolution settings if using a bundler or custom Node.js configuration.

• The 'engines' field is specified in the package.json and indicates that the package is not compatible with your current Node.js version.

  cause Your installed Node.js version is older than the required `>=22` for this package.
  fix Upgrade your Node.js installation to version 22 or newer to meet the package's minimum requirements.

• My log output shows arrays merged together, but I expected them to be separate items.

  cause Prior to v1.0.7, an internal deepmerge dependency might have merged arrays. A fix in v1.0.7 changed this behavior to prevent recursive array merging.
  fix This is the intended behavior since v1.0.7. If you require arrays to be merged, you must implement custom formatting logic within your `format` options.

• A field I explicitly excluded is still appearing in my log line.

  cause The `include` option takes precedence over `exclude`. If a field is present in both lists, it will be included.
  fix Review your `include` and `exclude` configuration options. Remove the problematic field from the `include` array if you intend for it to be excluded.

Warnings

• breaking The behavior of merging arrays within log objects changed in v1.0.7. Previously, arrays might have been deep-merged by an internal dependency. This version introduced a fix to prevent recursive merging of arrays, treating them as atomic values. If your application relied on arrays being merged, this is a breaking change.
  Fix: If recursive array merging is required, you must implement custom logic within your formatters. The package's default behavior now explicitly avoids deep merging arrays.
• gotcha The package explicitly declares a Node.js engine requirement of `>=22` in its `package.json`. Attempting to use this package with older Node.js versions may lead to runtime errors, including module resolution issues, even if installed successfully.
  Fix: Ensure your Node.js environment is updated to version 22 or higher to meet the package's engine requirements.
• gotcha The `include` option in `logLineFactory` configuration always overrides `exclude` options. If a field is specified in both `include` and `exclude` lists, it will ultimately be included in the formatted output. This behavior, while documented, can be a source of confusion.
  Fix: Carefully manage your `include` and `exclude` lists. If a field is intended to be excluded, ensure it is not also present in the `include` list.
• gotcha Multi-key formatting options (`|` for 'take one' and `,` for 'take all') have distinct behaviors. Misunderstanding the difference can lead to unexpected output where either not all intended fields are formatted (using `|` incorrectly) or fields are formatted multiple times (using `,` incorrectly).
  Fix: Review the documentation for multi-key formatting. Use `|` when you want to apply a formatter to the *first* matching key found, and `,` when you want the formatter applied to *all* matching keys.
• gotcha A fix in v1.1.2, `fix: types + efficient + skip string nums`, explicitly changes how 'string numbers' are handled. If your prior custom formatters implicitly processed string-represented numbers (e.g., '"123"'), this update might alter their behavior, potentially skipping or changing how these values are formatted.
  Fix: Test your existing formatters with string-number inputs after upgrading to ensure the output remains as expected. Adjust formatters to explicitly handle string numbers if necessary.

Install

• npm install json-log-line npm
• yarn add json-log-line yarn
• pnpm add json-log-line pnpm

Imports

• logLineFactory
  wrong:

  const { logLineFactory } = require('json-log-line');

  correct:

  import { logLineFactory } from 'json-log-line';

  The package primarily uses ESM. While CommonJS might work via transpilation or older Node.js versions, direct ESM imports are recommended for Node.js >=22. It ships with TypeScript types.
• Options

  import type { Options } from 'json-log-line';

  Import the `Options` type for type-safe configuration in TypeScript projects.

Quickstart

Demonstrates how to initialize `logLineFactory` with include/exclude/format options, including multi-key formatting, and process JSON strings into custom-formatted log lines.

import { logLineFactory } from "json-log-line";

const options = {
  include: ["nested.field"],
  exclude: ["nested"],
  format: {
    part1: (value) => `[${value}]`,
    part2: (value) => `[${value}]`,
    "nested.field": (value) => `:${value}:\n`,
    // Example of 'take one' multi-key formatter
    "foo|baz": (value) => `!${value}`,
    // Example of 'take all' multi-key formatter
    "nested.a,other.a": (value) => `:${value}:`,
  },
};

const lineFormatter = logLineFactory(options);

const log1 = JSON.stringify({
  nested: {
    other: "something",
    field: "FIELD",
    a: "x",
    b: "y"
  },
  part1: "hello",
  part2: "world",
  some: "extra",
  data: "here",
  foo: "bar",
  baz: "buz",
  other: { a: "z" }
});

console.log(lineFormatter(log1));
// Expected output (may vary slightly based on unformatted fields order):
// [hello] [world] :FIELD:
// !bar :x: :z:
// {"nested":{"b":"y"},"some":"extra","data":"here","baz":"buz","other":{}}

const log2 = JSON.stringify({
    message: "User logged in",
    level: "info",
    timestamp: new Date().toISOString(),
    userId: 123,
    ipAddress: "192.168.1.1",
});

const simpleFormatter = logLineFactory({
    format: {
        level: (value) => `[${value.toUpperCase()}]`,
        message: (value) => `${value}`,
        timestamp: (value) => `(${new Date(value).toLocaleTimeString()})`,
        extraFields: (value) => JSON.stringify(value)
    }
});

console.log(simpleFormatter(log2));
// Example Output: [INFO] User logged in (12:17:00 PM) {"userId":123,"ipAddress":"192.168.1.1"}