Dynason

A very small library to create a function to replace values in json objects or in string values.

To install the dynason library, run the following command in the console.

  npm install dynason --save-dev

Or use it from the unpkg cdn as a simple script tag via the browser to have it as a global object named replacer.

<script src="https://unpkg.com/[email protected]/umd/index.js"></script>
<script type="module">
  console.log(replacer); // Now can be used globally in the HTML app
</script>

Note: The umd object exports both the replacer and kebaby functions inside the umd object.

Note All of the examples in this document uses ECMA syntax to import or export code from the library, but this supports CommonJS syntax as well.

// ECMA Syntax
import { replacer } from "dynason";

// CommonJS Syntax
const { replacer } = require("dynason");

If you are using ESM with TypeScript consider reading the following information links:

• https://github.com/TypeStrong/ts-node#node-flags-and-other-tools
• https://www.typescriptlang.org/docs/handbook/esm-node.html
• https://nodejs.org/api/esm.html

Functionality

The function will receive three parameters:

• The first is the text containing the placeholders to be replaced.
• The second is called the matcher and it is a key pair object where the key is a string that will be used to match the placeholders and the value is the text to use when replacing.
• The third are the options to create custom behavior when matching. Check below for more information.

Replacer Options

It can be achieved some customized approach passing options to the replacer function.

Values

If the passed mode is surround, these are the start and final values to use for matching content inside a string. isCheck mode for modes information.

// These are the default values
const values = {
  start: "{",
  finish: "}",
};

Repeat

By default is 1 and is used to repeat the values that surrounds the string to be matched.

import { replacer } from "dynason";

const matcher = { foo: "A" };
// These will look for {{{foo}}} in the string

const string = replacer("Letter {{{foo}}}", matcher, { repeat: 3 }); // "Letter A"

Strict

If the strict mode is being used, when matching the surround values will ignore empty spaces between the content and these. (The default value is true).

// This will work
const strict = "{foo}";
// This not
const flex = "{ foo }";

Note:

To have more flexibility you can set the strict mode to false but is not recomended unless you are very certain what you are doing.

Modes

If you need a pure xml syntax like, on the replacer function you should set the mode parameter to xml. The same can be done for html also, the difference is with html it that it will expect a space between the slash and the content.

import { replacer } from "dynason";

const matcher = { foo: "A" };

// This way will search for xml syntax
let xml = "<foo/>";
xml = replacer(xml, matcher, { mode: "xml" }); // Will be replaced by A

// This way will search for html syntax
let html = "<foo/>";
xml = replacer(html, matcher, { mode: "html" }); // Will be replaced by A

Another values can be used to expect the surround symbol from the value to be match.

import { replacer } from "dynason";
const matcher = { foo: "A" };

// This would expect a value between brackets
let brackets = "{foo}";
brackets = replacer(brackets, matcher, , { mode: "surround", value: "curly-brackets" }); // Will be replaced by A

Also custom values can be used if needed.

import { replacer } from "dynason";
const matcher = { foo: "A" };

// When parsing by default `dynason` expects the markup to be surrounded by single quotes `\u0027`.
// This helps to not as much throw errors as it would do if you are planning to replace a template script file like a `JavaScript` one.
// This way the intellisense will think you are writing a simple string. Also this avoids collision issues when writing a real string like:
const value = { start: "'<", finish: "/>'" };

// This way is readable where the value will be replaced
const js = `
  const doubleQuote = "'<foo/>'";
  const literal = `'<foo/>'`;
`
replacer(js, matcher, { mode: "surround", value });

Serializer

These functions helps to transform text when a match occurs or to get custom names in the keys of the matcher.

import { replacer, kebaby } from "dynason";

// The matcher object should look like this
const matcher = { foo: "A", bar: "B", item1: "C" };

// Replacing a single string
let string = "{foo}, {bar}, {item-1}";
string = replacer(string, matcher, { serializers: { keys: kebaby } }); // `string` now is "A, B, C"

// Replacing an `object` (This may be an imported JSON file)
let json = { item1: "{foo}", item2: "{bar}" };
json = replacer(json, matcher); // `json` now is { item1: "A", item2: "B" }

keys

By default the exact same key from the matcher will be used to match values in the text, but some custom behavior can be applied if needed. As an example, replacing camelCase names to kebab-case.

stringify

When an object is passed as value will transform it to string to be used by the replacer function.

parse

When an object is passed as value, is transformed to string to be affected by the replacer then will be transformed back the to object using this function.

Note:

The value parameter can be either a string or an object. If it is an object will be transformed to a string using the stringify method from the JSON library then transformed back to an object using the parse method from the same library. To use a customized methods, these need to be passed in the options.

Flags

The regex flags are used on markup match. Plus a custom Sets whether to validate the keys from the matcher in the replacer to see if they follow a proper markup format. Plus a extra key that sets how to validate the keys from the matcher in the replacer to see if they follow a proper markup format.