HBH Hub - Modern Web Solutions & Digital Platform

🔄 convertObject

The convertObject function provides a flexible way to transform, filter, and traverse objects. It supports multiple output formats, deep flattening, filtering, mapping, and sorting.

Import

          
            1import { convertObject } from "hbh-nodes";

Function: convertObject(obj, options = {})

Converts or extracts data from an object according to specified rules.

Parameters:

obj – The object to transform.
options – Optional settings:

Option	Type	Default	Description
`outputFormat`	`'flat'	'tree'	'nestedKeys'`	`'flat'`	Output structure format.
`props`	`string \| string[] \| RegExp`	`null`	Filter keys to include.
`filterFn`	`(val, key, path) => boolean`	`null`	Custom filter function.
`mapFn`	`(val, key, path) => any`	`(v) => v`	Transform values.
`includeKeys`	`boolean`	`false`	If `true`, flat output returns `[key, value]`.
`includePaths`	`boolean`	`false`	Use full path as key in flat output.
`flatten`	`boolean`	`true`	Traverse nested objects.
`defaultValue`	`any`	`undefined`	Fallback value for missing entries.
`strict`	`boolean`	`false`	Throw error if key/value not found.
`maxDepth`	`number`	`Infinity`	Limit traversal depth.
`sort`	`boolean`	`false`	Sort keys alphabetically.
`prefix`	`string`	`''`	Start traversal at nested path.
`keyKey`	`string`	`'key'`	Key name in tree nodes.
`valueKey`	`string`	`'value'`	Value name in tree nodes.
`childrenKey`	`string`	`'children'`	Child array key for tree output.

Output Formats

flat – Returns a flat array of values (or [key, value] pairs).
tree – Returns a nested tree of nodes: { key, value, children }.
nestedKeys – Returns nested keys only.
simple – Returns direct keys or mapped values of the object.

Additional helper walkers are included for specialized tasks:

keysOnly – Extract only keys.
valuesOnly – Extract only values.
pathsOnly – Extract full paths.
groupByType – Group keys by value type.
countValues – Count occurrences of values/arrays.
filterAndMap – Apply filter and map recursively.

Examples

Flat output with mapping

          
            1import { convertObject } from "hbh-nodes";3const data = {4  user: { name: "Alice", age: 25 },5  settings: { theme: "dark" }6};8const result = convertObject(data, {9  outputFormat: 'flat',10  mapFn: (v, k) => String(v).toUpperCase()11});13console.log(result);14// ["ALICE", "25", "DARK"]

Tree output with filtering

          
            1const tree = convertObject(data, {2  outputFormat: 'tree',3  filterFn: (val, key) => typeof val === 'string'4});6console.log(tree);7// [8//   { key: 'user', children: [{ key: 'name', value: 'Alice' }] },9//   { key: 'settings', children: [{ key: 'theme', value: 'dark' }] }10// ]

Nested keys output

          
            1const keys = convertObject(data, { outputFormat: 'nestedKeys' });2console.log(keys);3// [["user", ["name", "age"]], ["settings", ["theme"]]]

Features

Supports deep traversal and flattening.
Custom filters via props or filterFn.
Value transformations using mapFn.
Flexible output formats (flat, tree, nestedKeys).
Optional key/value inclusion, sorting, and strict mode.
Traversal can start from a nested path using prefix.