object-flatten-referencing^7.2.1

Installation

Quick Take

Examples

• Wrap an already wrapped value when prevention is disabled
• Insert a break even when the previous line already contains one
• Normalise a string setting to an array
• Avoid adding a break after a line that already ends with one
• Wrap flattened string values with custom markers
• Inspect the exported flattening defaults
• Disable wrapping across the complete input tree
• Skip wrapping for keys that match a glob
• Skip wrapping only at an exact nested path
• Flatten an array with line breaks between rows
• Flatten an object's keys and values to strings
• Use HTML rather than XHTML line-break syntax
• Leave an ignored key and its nested value unchanged
• Merge array rows without inserting line breaks
• Flatten input keys even when the reference has no matching key
• Leave an unmatched input key unchanged
• Throw when an input key is absent from the reference
• Set the separator used by flattenObject
• Keep values that already contain the wrapping markers
• Leave templating statements unwrapped

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:

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 — flattenObject()

The function flattenObject() is imported like this:

The first of the two building blocks described in The algorithm, exported so you can use it on its own. It flattens a plain object into an array of object-path notation strings:

import { flattenObject } from "object-flatten-referencing";

console.log(flattenObject({ a: "b", c: { d: "e" } }));
// => ["a.b", "c.d.e"]

console.log(flattenObject({ a: ["b", "c"] }));
// => ["a.b", "a.c"]

API — flattenArr()

The function flattenArr() is imported like this:

The second building block. It flattens an array into a string:

import { flattenArr } from "object-flatten-referencing";

console.log(flattenArr(["a", "b"], { wrapHeadsWith: "{{ ", wrapTailsWith: " }}" }, true));
// => "{{ a }} {{ b }}"

console.log(flattenArr(["a", "b"], {}, false, true));
// => "a<br />b"

API — arrayiffy()

This package re-exports arrayiffy from arrayiffy-if-string, so that consumers already importing from here don’t need a second dependency to normalise the string-or-array options:

import { arrayiffy } from "object-flatten-referencing";

console.log(arrayiffy("a"));
// => ["a"]

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:

API — types

This package is written in TypeScript and exports the type Opts, the Optional Options Object documented above:

import type { Opts } from "object-flatten-referencing";

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