{"id":11173,"library":"json-log-line","title":"JSON Log Line Utility","description":"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.","status":"active","version":"1.1.3","language":"javascript","source_language":"en","source_url":"https://github.com/spence-s/json-log-line","tags":["javascript","typescript"],"install":[{"cmd":"npm install json-log-line","lang":"bash","label":"npm"},{"cmd":"yarn add json-log-line","lang":"bash","label":"yarn"},{"cmd":"pnpm add json-log-line","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const { logLineFactory } = require('json-log-line');","symbol":"logLineFactory","correct":"import { logLineFactory } from 'json-log-line';"},{"note":"Import the `Options` type for type-safe configuration in TypeScript projects.","symbol":"Options","correct":"import type { Options } from 'json-log-line';"}],"quickstart":{"code":"import { logLineFactory } from \"json-log-line\";\n\nconst options = {\n  include: [\"nested.field\"],\n  exclude: [\"nested\"],\n  format: {\n    part1: (value) => `[${value}]`,\n    part2: (value) => `[${value}]`,\n    \"nested.field\": (value) => `:${value}:\\n`,\n    // Example of 'take one' multi-key formatter\n    \"foo|baz\": (value) => `!${value}`,\n    // Example of 'take all' multi-key formatter\n    \"nested.a,other.a\": (value) => `:${value}:`,\n  },\n};\n\nconst lineFormatter = logLineFactory(options);\n\nconst log1 = JSON.stringify({\n  nested: {\n    other: \"something\",\n    field: \"FIELD\",\n    a: \"x\",\n    b: \"y\"\n  },\n  part1: \"hello\",\n  part2: \"world\",\n  some: \"extra\",\n  data: \"here\",\n  foo: \"bar\",\n  baz: \"buz\",\n  other: { a: \"z\" }\n});\n\nconsole.log(lineFormatter(log1));\n// Expected output (may vary slightly based on unformatted fields order):\n// [hello] [world] :FIELD:\n// !bar :x: :z:\n// {\"nested\":{\"b\":\"y\"},\"some\":\"extra\",\"data\":\"here\",\"baz\":\"buz\",\"other\":{}}\n\nconst log2 = JSON.stringify({\n    message: \"User logged in\",\n    level: \"info\",\n    timestamp: new Date().toISOString(),\n    userId: 123,\n    ipAddress: \"192.168.1.1\",\n});\n\nconst simpleFormatter = logLineFactory({\n    format: {\n        level: (value) => `[${value.toUpperCase()}]`,\n        message: (value) => `${value}`,\n        timestamp: (value) => `(${new Date(value).toLocaleTimeString()})`,\n        extraFields: (value) => JSON.stringify(value)\n    }\n});\n\nconsole.log(simpleFormatter(log2));\n// Example Output: [INFO] User logged in (12:17:00 PM) {\"userId\":123,\"ipAddress\":\"192.168.1.1\"}\n","lang":"typescript","description":"Demonstrates how to initialize `logLineFactory` with include/exclude/format options, including multi-key formatting, and process JSON strings into custom-formatted log lines."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.0.7"},{"fix":"Ensure your Node.js environment is updated to version 22 or higher to meet the package's engine requirements.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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).","severity":"gotcha","affected_versions":">=1.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.1.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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';`.","cause":"Incorrect module import syntax (e.g., using `require` for an ESM module), or module resolution issues.","error":"TypeError: logLineFactory is not a function"},{"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.","cause":"Module not installed, incorrect path, or an ES Modules vs. CommonJS mismatch in a complex setup.","error":"Error: Cannot find module 'json-log-line'"},{"fix":"Upgrade your Node.js installation to version 22 or newer to meet the package's minimum requirements.","cause":"Your installed Node.js version is older than the required `>=22` for this package.","error":"The 'engines' field is specified in the package.json and indicates that the package is not compatible with your current Node.js version."},{"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.","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.","error":"My log output shows arrays merged together, but I expected them to be separate items."},{"fix":"Review your `include` and `exclude` configuration options. Remove the problematic field from the `include` array if you intend for it to be excluded.","cause":"The `include` option takes precedence over `exclude`. If a field is present in both lists, it will be included.","error":"A field I explicitly excluded is still appearing in my log line."}],"ecosystem":"npm"}