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: As umd must contain only one default exported object the exported value is the replacer function.

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 two parameters: The first is what to be expected to be changed and the second called matcher will receive a key pair object where the key is a string of the value from the markup to be searched and the value is the text to replace with.

Note By default the matcher will transform its keys to from camelcase to kebab case to make the match i.e. "camelCase" will be searched in the string as "camel-case"

Replacer Options

It can be achieved some customized approach passing optionsto 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 }";

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 });

Example with string and object

import { replacer } from "dynason";

// The matcher object should look like this
const matcher = { foo: "A", bar: "B", camelCase: "kebab-case" };

// Replacing a single string
let string = "'<foo/>' and '<bar/>' as <camel-case>";
string = replacer(string, matcher); // `string` now is "A and B as kebab-case"

// 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" }

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, they need to be set in the DynasonSettings static class before calling the replacer method.

Serializer

These functions helps to transform objects to strings and viceversa when the passed value is not expected to be always a string.

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 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.

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.