Registry / observability / json-log-line

json-log-line

library1.1.3jsnpmunverified

The `json-log-line` package, currently at version 1.1.3, provides a focused utility for transforming JSON and plain JavaScript objects into custom-formatted log line strings. It is designed to integrate seamlessly with newline-delimited (nd) JSON loggers, offering flexible control over log output. Key functionalities include robust support for both JSON and standard JavaScript objects, a configurable system for explicitly including or excluding specific fields, and an advanced `format` option. This `format` option allows users to define custom transformations for object keys, including nested properties via dot notation, and supports sophisticated multi-key formatting strategies such as "take one" (`|`) or "take all" (`,`) for conditional or sequential application of formatters. The library ships with TypeScript types, ensuring a good development experience for TypeScript users. Releases are made periodically, indicating active maintenance and continuous refinement of its features.

observability serialization

npm install json-log-line

github ↗package ↗

INSTALL

IMPORT

SIG · JSON-LOG-LINE

json-log-line

observabilityjavascriptv1.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

logLineFactory

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

✗ const { logLineFactory } = require('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.

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"}

Debug

Known issues

breakingThe 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.

affects: >=1.0.7

gotchaThe 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

gotchaMulti-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.

affects: >=1.1.0

gotchaA 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.

affects: >=1.1.2

Errors

Common errors & fixes

TypeError: logLineFactory is not a function

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'

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.

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.

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.

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.

Upgrade

Version history

1.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/spence-s/json-log-line ↗

packagehttps://www.npmjs.com/package/json-log-line ↗