Package Exports

json-placeholder-replacer
json-placeholder-replacer/dist/library.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (json-placeholder-replacer) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

jsonPlaceholderReplacer

Lightweight yet really powerful typescript library/cli to replace placeholders in an javascript object/JSON. By default, all you have to do is to use double curly brackets {{placeholderKey}} or angle brackets <<**placeholderKey**>>, interchangeably, to identify the placeholder. Don't worry, if you don't like these default placeholders you can create your own.

CLI usage

json-placeholder-replacer annotetad-json.json [...variableMaps]

Example

$ json-placeholder-replacer annotated.json variable_map.json $ jpr variable_map.json < annotated.json $ cat annotated.json | jpr variable_map.json $ echo '{"curly": "{{key}}", "angle": "<>"}' | jpr variable_maps

Would result

cat replaceable.json
        # {
        #  "curly": "{{key}}",
        #  "angle": "<<key>>"
        # }
cat variable.map:
        # {
        #         "key": 10,
        #         "not-mapped": 20
        # }
json-placeholder-replacer replaceable.json variable.map
        # {
        #         "curly": 10,
        #         "angle": 10,
        #         "not-mapped": 20
        # }

Library usage

import { JsonPlaceholderReplacer } from "json-placeholder-replacer";
const placeHolderReplacer = new JsonPlaceholderReplacer();

placeHolderReplacer.addVariableMap({
  key: 100,
  otherKey: 200,
});
const afterReplace = placeHolderReplacer.replace({
  replaceable: "{{key}}",
  otherReplaceableWithSameKey: "<<key>>",
  otherReplaceable: "{{otherKey}}",
});

// afterReplace = {
//    replaceable: 100,
//    otherReplaceableWithSameKey: 100,
//    otherReplaceable: 200
// }

[!NOTE] An object passed to .replace() is mutated in-place:

const beforeReplace = { some: "{{placeholder}}" };
const afterReplace = placeHolderReplacer.replace(beforeReplace);
// beforeReplace === afterReplace

You can replace the default placeholders with some as cool as you want

const placeHolderReplacer = new JsonPlaceholderReplacer({
  delimiterTags: [{ begin: "@{{-", end: "-}}@" }],
});
placeHolderReplacer.addVariableMap({
  key: "nice",
});
const afterReplace = placeHolderReplacer.replace({
  replaceable: "@{{-key-}}@",
});

// afterReplace = {
//    replaceable: "nice",
// }

It's also possible to add more than one variables map

placeHolderReplacer.addVariableMap({
  firstMapKey: "1",
});
placeHolderReplacer.addVariableMap({
  secondMapKey: 2,
});
const afterReplace = placeHolderReplacer.replace({
  replaceable: "{{firstMapKey}}",
  otherReplaceable: "<<secondMapKey>>",
});

// afterReplace = {
//    replaceable: "1",
//    otherReplaceable: 2
// }

And the last added maps have higher priority (but non-nullish values will be preserved from previous map)

placeHolderReplacer.addVariableMap({
  id: "lowerPriority",
  name: "Name",
});
placeHolderReplacer.addVariableMap({
  id: "higherPriority",
  name: undefined,
});
const afterReplace = placeHolderReplacer.replace({
  id: "{{id}}",
  name: "{{name}}",
});

// afterReplace = {
//    id: "higherPriority"
//    name: "Name"
// }

It's possible to override global values map with `.setVariableMap()`

placeHolderReplacer.addVariableMap({
  id: "Id",
  name: "Name",
});
placeHolderReplacer.setVariableMap({
  // <- note setVariableMap() here
  id: "New Id",
  name: undefined,
});
const afterReplace = placeHolderReplacer.replace({
  id: "{{id}}",
  name: "{{name}}",
});

// afterReplace = {
//    id: "New Id"
//    name: "{{name}}"
// }

It's possible to override global maps with local by `.replaceWith()`

placeHolderReplacer.addVariableMap({
  id: "Id",
  name: "Name",
});
const afterReplace = placeHolderReplacer.replaceWith(
  {
    id: "{{id}}",
    name: "{{name}}",
  },
  { name: "New Name" },
);

// afterReplace = {
//    id: "{{id}}"
//    name: "New Name"
// }

It keeps original variable types

If a variable in the map is boolean/string/number/object, it remains as boolean/string/number/object when it's replaced

placeHolderReplacer.addVariableMap({
  booleanKey: true,
  stringKey: "string",
  numberKey: 10,
  objectKey: {
    inner: "inner",
  },
});
const afterReplace = placeHolderReplacer.replace({
  booleanReplaceable: "{{booleanKey}}",
  stringReplaceable: "{{stringKey}}",
  numberReplaceable: "{{numberKey}}",
  objectReplaceable: "{{objectKey}}",
});

// afterReplace = {
//    booleanReplaceable: true,
//    stringReplaceable: "string",
//    numberReplaceable: 10,
//    objectReplaceable: {
//      inner: "inner"
//    }
// }

Just to make it clearer, it does not replace the placeholder Key

placeHolderReplacer.addVariableMap({
  key: "someValue",
});
const afterReplace = placeHolderReplacer.replace({
  "{{key}}": "value",
});
// afterReplace = {
//    "{{key}}": "value"
// }

And, of course, it handles array substitution as well

placeHolderReplacer.addVariableMap({
  key: 987,
  objectReplaceable: {
    inner: "inner",
  },
});
const afterReplace = placeHolderReplacer.replace({
  array: ["string", "{{objectReplaceable}}", "{{key}}"],
});

// afterReplace = {
//    array: ["string", { inner: "inner" }, 987]
// }

Want to get nested elements? Go for it

placeHolderReplacer.addVariableMap({
  key: {
    nested: "value",
  },
});
const afterReplace: any = placeHolderReplacer.replace({
  replaceable: "<<key.nested>>",
});

// afterReplace = {
//    replaceable: "value"
// }

This feature allows you to have default values in case you don't have them mapped

placeHolderReplacer.addVariableMap({
  key: "value",
});
const afterReplace: any = placeHolderReplacer.replace({
  replaceable: "<<not-found-key:default-value>>",
});

// afterReplace = {
//    replaceable: "default-value"
// }

Of course, you can also change what is the default value separator (defaults to ':')

const placeHolderReplacer = new JsonPlaceholderReplacer({
  defaultValueSeparator: ":=:",
});

placeHolderReplacer.addVariableMap({
  key: "value",
});
const afterReplace: any = placeHolderReplacer.replace({
  replaceable: "<<not-found-key:=:default-value>>", // Note the ':=:'
});

// afterReplace = {
//    replaceable: "default-value"
// }

Lastly, cyclic objects are also accepted

const placeHolderReplacer = new JsonPlaceholderReplacer();

const cyclicObject: any = {
  key: "{{key1}}",
  deep: {
    nested: "{{key2}}",
  },
};
cyclicObject.deep.circular = cyclicObject;
placeHolderReplacer.addVariableMap({ key1: "value1", key2: "value2" });

const afterReplace: any = placeHolderReplacer.replace(cyclicObject);

// afterReplace = {
//    key: "value1",
//    deep: {
//      nested: "value2",
//      circular: {
//        key: "value1",
//        deep: {
//          nested: "value2",
//          circular: [CYCLE...]
//        }
//      }
//    }
// }