stringify-keys

3.0.0 verified Sat Apr 25 auth: no javascript maintenance

Build an array of key paths from a nested object, with support for custom separators, escaping, and optional inclusion of values. Version 3.0.0 removes redundant parent keys (e.g., 'a' is omitted when 'a.b' exists) and adds array traversal support. Maintenance-mode library with low release cadence (last major update in 2018). Differentiated by lightweight size, simple API, and escape handling for keys containing dots.

Common errors

error TypeError: stringify is not a function ↓

cause Wrong import: using destructured import { stringify } instead of default import.

fix

Use 'import stringify from 'stringify-keys'' or 'const stringify = require('stringify-keys')'.

error Cannot find module 'stringify-keys' ↓

cause Package not installed or typo in package name.

fix

Run 'npm install stringify-keys' and ensure the import path is exactly 'stringify-keys'.

error Unexpected token in JSON at position X ↓

cause Passing a JSON string instead of a JavaScript object.

fix

Parse the JSON string first: 'stringify(JSON.parse(str))'.

Warnings

breaking In v3.0.0, redundant parent keys are no longer included. For example, stringify({a: {b: 'c'}}) returns ['a.b'] instead of ['a', 'a.b']. ↓

fix Update any code that expects parent keys to be present. Use { values: true } with paths including parents if needed.

gotcha Keys containing dots are automatically escaped with backslashes by default (e.g., 'a.b' becomes 'a\\.b'). This can break naive string splitting. ↓

fix Use the escape option or manually handle backslash-escaping when processing paths.

gotcha Array indices are included as numeric path parts (e.g., 'arr.0.x'). This may not be expected if you want to skip array traversal. ↓

fix Filter out array indices from results if needed, or avoid passing arrays directly.

deprecated The package is in maintenance mode with no recent updates. It may not receive fixes for future Node.js versions. ↓

fix Consider migrating to alternatives like dot-prop or object-path if active development is needed.

Install

npm install stringify-keys

yarn add stringify-keys

pnpm add stringify-keys

Imports

default (stringify)
wrong
```
const stringify = require('stringify-keys')
```
correct
```
import stringify from 'stringify-keys'
```
Default import is the function. CJS require also works but ESM is preferred.
type definitions
```
import type { Options } from 'stringify-keys'
```
TypeScript users can import Options interface for type safety. Not exported as a value.
CommonJS require
wrong
```
const { stringify } = require('stringify-keys')
```
correct
```
const stringify = require('stringify-keys')
```
The module exports a single function, not an object with a named export.

Quickstart

Demonstrates basic usage, values output, custom separator, and custom escape function.

import stringify from 'stringify-keys';

const obj = {
  a: 'a',
  b: {
    c: {
      d: { e: 'f' }
    }
  },
  'a.b.c': { d: 'e' },
  arr: [{ x: 1 }, { y: 2 }]
};

// Basic usage: get key paths as array
console.log(stringify(obj));
// Output: ['a', 'b.c.d.e', 'a\\.b\\.c.d', 'arr.0.x', 'arr.1.y']

// Include values in result object
console.log(stringify(obj, { values: true }));
// Output: { a: 'a', 'b.c.d.e': 'f', 'a\\.b\\.c.d': 'e', 'arr.0.x': 1, 'arr.1.y': 2 }

// Custom separator
console.log(stringify(obj, { separator: '/' }));
// Output: ['a', 'b/c/d/e', 'a.b.c/d', 'arr/0/x', 'arr/1/y']

// Custom escape function
const escapeFn = (str) => str.split('.').join('_');
console.log(stringify({ 'a.b': 'c' }, { escape: escapeFn }));
// Output: ['a_b']