Flatten nested objects | Data transformation functions |Tealium Docs

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.

Examples

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"]
};

`delimiter`

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

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

`prefix`

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

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

`ignoreKeys`

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

{
  "user.id": 1
}

`replaceKeys`

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"]
}