Flatten nested objects

This article provides information on the flatten library, which is used to convert a nested object into an object that is not nested.

The flatten library is a standard library that is imported in the default code for a data transformation function. This library provides the flatten() utility, which converts a nested object into an object that is not nested. flatten() returns an object that contains strings and arrays of strings.

flatten() accepts two parameters, as follows:

flatten(target[, options])

  • target is the event object passed to the data transformation function.
  • options is an object that specifies how nested keys are handled during the conversion.

The options parameter contains the following properties:

Property Data Type Description
delimiter string, default is “.”. Specifies the character used to combine parent and child property names.
prefix string, default is “”. The prefix is concatenated at the beginning of the new key name followed by the delimiter.
ignoreKeys string[], default is []. Specifies keys that should be omitted from the output.
replaceKeys Object {string}, default is a period { }. Specifies new names for keys using key/value pairs, where the key is the existing key in the object and the value is the new key.


The following examples show how the options properties are used. These examples use the following nested object as the target to be flattened:

const object = {
  page: {
    id: 1
  user: {
    id: 1
  util: ["1", "2", "3"]


If delimiter is "_", the following object is returned:

  page_id: 1,
  util: ["1", "2", "3"]


If prefix is "fl", the following object is returned:

  "fl.user.id": 1,
  "fl.page.id": 1,
  "fl.util": ["1", "2", "3"]


If ignoreKeys is ["page", "util"], the following object is returned:

  "user.id": 1


If replaceKeys is defined as follows:

const replaceKeys = {
  "user": "",
  "page": "p"

The following object is returned:

  "id": 1,
  "p.id": 1,
  "util": ["1", "2", "3"]

Example of flattening a complex object

The following example shows a complex object to be flattened:

import flatten from 'tealium/util/flatten';
const options = {
  delimiter: "_",
  ignoreKeys: ["array_of_strings"],
  replaceKeys: {
    "number": "float",
    "array_of_objects": "modified_array_of_strings",
    "ordinal": ""
  prefix: "t"

const output = flatten({
  "boolean": true,
  "number": 12.34,
  "string": "value",
  "date": new Date(1631009413904),
  "array_of_strings": ["first", "second"],
  "array_of_arrays": [
    [1, 2],
    [3, 4]
  "array_of_objects": [{
    "ordinal": "first"
  }, {
    "ordinal": "second"
  "object": {
    "child_boolean": true,
    "child_number": 12.34,
    "child_string": "value",
    "child_array_of_strings": ["first", "second"],
    "child_array_of_arrays": [
      [1, 2],
      [3, 4]
    "child_object": {
      "gchild_boolean": true,
      "gchild_number": 12.34,
      "gchild_string": "value",
      "gchild_array_of_strings": ["first", "second"],
      "gchild_array_of_arrays": [
        [1, 2],
        [3, 4]
}, options);

The following object is returned by flatten():

  "t_boolean": "true",
  "t_float": "12.34",
  "t_string": "value",
  "t_date": "2021-09-07T10:10:13.904Z",
  "t_array_of_arrays": ["1","2","3","4"],
  "t_modified_array_of_strings": ["first","second"],
  "t_object_child_boolean": "true",
  "t_object_child_number": "12.34",
  "t_object_child_string": "value",
  "t_object_child_array_of_strings": ["first","second"],
  "t_object_child_array_of_arrays": ["1","2","3","4"],
  "t_object_child_object_gchild_boolean": "true",
  "t_object_child_object_gchild_number": "12.34",
  "t_object_child_object_gchild_string": "value",
  "t_object_child_object_gchild_array_of_strings": ["first","second"],
  "t_object_child_object_gchild_array_of_arrays": ["1","2","3","4"]

Was this page helpful?

This page was last updated: January 7, 2023