object-flatten-referencing^5.0.14

§ Quick Take

import { strict as assert } from "assert";
import { flattenReferencing } from "object-flatten-referencing";

assert.deepEqual(
  flattenReferencing(
    {
      key1: "val11.val12",
      key2: "val21.val22",
    },
    {
      key1: "Contact us",
      key2: "Tel. 0123456789",
    }
  ),
  {
    key1: "%%_val11.val12_%%",
    key2: "%%_val21.val22_%%",
  }
);

§ 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(
  plainObject, 
  referenceObject,
  [options]
)

Returns a new plain object, flattened according to your supplied reference object.

§ 1st argument - plainObject

Type: object (plain object) Obligatory: yes

First input argument — the object which you want to flatten.

§ 2nd argument - searchValue

Type: object (plain object) Obligatory: yes

A reference object — according to what you want to flatten the plainObject.

§ 3rd argument (optional) - options

Type: object (plain object) Obligatory: no

Third argument - an Optional Options Object.

Here are all the defaults, compiled in one place just in case you want to copy and tweak:

{
  wrapHeadsWith: '%%_',
  wrapTailsWith: '_%%',
  dontWrapKeys: [],
  xhtml: true,
  preventDoubleWrapping: true,
  preventWrappingIfContains: [],
  objectKeyAndValueJoinChar: '.',
  wrapGlobalFlipSwitch: true,
  ignore: [],
  whatToDoWhenReferenceIsMissing: 0,
  mergeArraysWithLineBreaks: true,
  mergeWithoutTrailingBrIfLineContainsBr: true,
  enforceStrictKeyset: true,
}

§ 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

See it in the monorepo , on GitHub.

§ Contributing

To report bugs or request features or assistance, raise an issue on GitHub .

Any code contributions welcome! All Pull Requests will be dealt promptly.

§ Licence

MIT 

Copyright © 2010–2021 Roy Revelt and other contributors