Flatten nested objects | Data transformation functions |Preview of Tealium Docs

How it works

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`	The character used to combine parent and child property names. The default is `.`.
`prefix`	`String`	The string concatenated at the beginning of the new key name followed by the `delimiter`.
`ignoreKeys`	`String[]`	An array of keys to omit from the output.
`replaceKeys`	`Object{string:string}`	Specifies new names for keys, where the key is the existing key in the object and the value is the new key. Example: `{ "uid" : "user_id" }`

Parameters

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

Full example

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