object-flatten-referencing npm package

Installation

Choose the installation type:

Quick Take

Idea

Sometimes you need to make one nested object to look like another, type-wise.

For example, you’ve got a key a, whose value is array of object(s):

{
  a: [
    {
      b: "c",
      d: "e",
    },
  ];
}

but, you need the key to have its value as string:

{
  a: "b.c<br />d.e";
}

This library does such object “flattening”.

API — `flattenReferencing()`

The main function flattenReferencing() is imported like this:

It’s a function which takes three input arguments:

The Optional Options Object has the following shape:

Key	Type	Obligatory	Default	Description
	`wrapHeadsWith` Type: String Obligatory: no Default: `%%_`
`wrapHeadsWith`	String	no	`%%_`	Prepend this to each value, each result of flattening or simply other encountered value.

	`wrapTailsWith` Type: String Obligatory: no Default: `_%%`
`wrapTailsWith`	String	no	`_%%`	Append this to each value, each result of flattening or simply other encountered value.

	`dontWrapKeys` Type: Array of strings or String Obligatory: no Default: empty array
`dontWrapKeys`	Array of strings or String	no	empty array	We won’t append or prepend anything to the keys that match value(s) given here (applies to child nodes as well). Also, we won’t flatten them (or their child nodes). This is used to prevent mangling of keys containing your data storage, for example. You can put wildcards (*) to match zero or more characters.

	`dontWrapPaths` Type: Array of strings or String Obligatory: no Default: empty array
`dontWrapPaths`	Array of strings or String	no	empty array	This is a more-precise cousin of `dontWrapKeys`. Put the exact path(s) to the key you want to ignore. Remember to append `[number]` after keys that have values as arrays. For example, here’s a path to ignore: `modules[0].part2[1].ccc[0].kkk` — key `modules` in root, equal to array. Take zero’th element from that array, it’s an object. Take that object’s key `part2`, it’s equal to an array. Take that array’s second element (index `1`)… and so on. This path would be ignored, for example.

	`xhtml` Type: Boolean Obligatory: no Default: `true`
`xhtml`	Boolean	no	`true`	When flattening, arrays or plain objects are converted into strings. Each value is separated by a line break, and this controls which type to use: HTML (`<br>`) or XHTML (`<br />`)

	`preventDoubleWrapping` Type: Boolean Obligatory: no Default: `true`
`preventDoubleWrapping`	Boolean	no	`true`	If the current value already contains a string from `wrapHeadsWith` or `wrapTailsWith`, don’t wrap to prevent double wrapping.

	`preventWrappingIfContains` Type: Array of strings or String Obligatory: no Default: empty array
`preventWrappingIfContains`	Array of strings or String	no	empty array	Sometimes variables you set in mapping can have various notations, for example in Nunjucks default `wrapHeadsWith` would be `{{` but also some variables are marked with `{%`. Obviously they would not get recognised and whole string containing them would get wrapped with let’s say `{{` and `}}`. But no more. State your system variable heads and tails here, put them as string array.

	`objectKeyAndValueJoinChar` Type: String Obligatory: no Default: `.`
`objectKeyAndValueJoinChar`	String	no	`.`	When an object is turned into a string, its key is joined with its value, with another string in-between. This controls what that in-between string is.

	`wrapGlobalFlipSwitch` Type: Boolean Obligatory: no Default: `true`
`wrapGlobalFlipSwitch`	Boolean	no	`true`	You can turn off the wrapping function completely using this.

	`ignore` Type: Array or String Obligatory: no Default: empty array
`ignore`	Array or String	no	empty array	Don’t apply any flattening to any of these keys. Naturally, don’t wrap them with anything either.

	`whatToDoWhenReferenceIsMissing` Type: Integer or Integer as String Obligatory: no Default: `0`
`whatToDoWhenReferenceIsMissing`	Integer or Integer as String	no	`0`	0 = skip, 1 = throw, 2 = flatten to string

	`mergeArraysWithLineBreaks` Type: Boolean Obligatory: no Default: `true`
`mergeArraysWithLineBreaks`	Boolean	no	`true`	Should we merge arrays using `<br />`’s? It’s handy to turn it off when mapping variables on email templates where values in data arrays are IF statements, and `<br />`’s are hardcoded inside of them.

	`mergeWithoutTrailingBrIfLineContainsBr` Type: Boolean Obligatory: no Default: `true`
`mergeWithoutTrailingBrIfLineContainsBr`	Boolean	no	`true`	When merging arrays to produce a string, each row’s contents will be checked do they contain `<br`, and if so, line break in front of it will not be added. Added in `v4`.

	`enforceStrictKeyset` Type: Boolean Obligatory: no Default: `true`
`enforceStrictKeyset`	Boolean	no	`true`	Are you allowed to pass in an unrecognised keys in the options object?

Here are all defaults in one place for copying:

The function will return a new plain object, flattened according to your supplied reference object.

API — `defaults`

You can import defaults:

It's a plain object:

The main function calculates the options to be used by merging the options you passed with these defaults.

API — `version`

You can import version:

The algorithm

In its core, this library uses two functions:

one which flattens objects
another which flattens arrays

Objects are flattened into arrays (yes, not strings) in the following fashion:

// from:
{
  a: 'b',
  c: 'd'
}
// to:
['%%_a.b_%%', '%%_c.d_%%']

Arrays are flattened into strings:

// from:
["a", "b", "c"];
// to:
("%%_a_%%<br />%%_b_%%<br />%%_c_%%");

This library recursively traverses both inputs, compares their types and if one type is lesser in the food chain (object vs. string), it uses the above functions to flatten all mismatching elements into strings.

In practice

In practice, this library is used to map the variables in email templates.

For example, your data content file in JSON (development version) that controls your template is:

// data file:
{
  "title": "Welcome",
  "name": "John"
}

but you need to turn it into the following when generating PROD version:

// you want your data file to look like this after processing:
{
  "title": "Welcome",
  "name": "${object.name}"
}

To achieve that, you use another JSON mapping file,

// mapping file:
{
  "name": {
    "object": "name"
  }
}

It’s easy to merge the mapping file onto the data file, but you get:

// intermediate data file after merging the mapping file over data file
{
  "title": "Welcome",
  "name": {
    "object": "name"
  }
}

Now you need to flatten the above object, so that the key called name has a value of string type, not object. This library helps to achieve that:

const mergedDataFile = {
  title: "Welcome",
  name: {
    object: "name",
  },
};
const reference = {
  title: "Welcome",
  name: "John",
};
mergedDataFile = flattenReferencing(mergedDataFile, reference, {
  wrapHeadsWith: "${",
  wrapTailsWith: "}",
});
console.log(JSON.stringify(mergedDataFile, null, 4));
// => {
//      "title": "Welcome",
//      "name": "${object.name}"
//    }

Voilà!

Changelog

Open Changelog

object-flatten-referencing7.0.3

Installation

Quick Take

Idea

API — flattenReferencing()

API — defaults

API — version