{"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,"search_vec":"'1.1.3':14 'activ':138 'advanc':76 'allow':82 'applic':116 'condit':113 'configur':65 'continu':141 'control':48 'current':11 'custom':28,86 'custom-format':27 'defin':85 'delimit':42 'design':35 'develop':128 'dot':95 'ensur':125 'exclud':71 'experi':129 'explicit':68 'featur':145 'field':73 'flexibl':47 'focus':17 'format':29,77,80,103 'formatt':118 'function':53 'good':127 'includ':54,69,91 'indic':137 'integr':37 'javascript':24,62,146 'json':1,7,21,44,59 'json-log-lin':6 'key':52,90,102 'librari':120 'line':3,9,31 'log':2,8,30,50 'logger':45 'made':135 'mainten':139 'multi':101 'multi-key':100 'nd':43 'nest':92 'newlin':41 'newline-delimit':40 'notat':96 'object':25,63,89 'offer':46 'one':108 'option':78,81 'output':51 'packag':10 'period':136 'plain':23 'properti':93 'provid':15 'refin':142 'releas':133 'robust':55 'seamless':38 'sequenti':115 'ship':121 'sophist':99 'specif':72 'standard':61 'strategi':104 'string':32 'support':56,98 'system':66 'take':107,110 'transform':20,87 'type':124 'typescript':123,131,147 'user':83,132 'util':4,18 'version':13 'via':94","created_at":"2026-04-19T13:36:36.974309+00:00","updated_at":"2026-04-19T13:36:36.974309+00:00","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","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/spence-s/json-log-line","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/json-log-line","openapi_spec":null,"status_page":null,"smithery":null,"categories":["observability","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}