Skip to content
JavaScript: Preserve dollar signs in literal replacement text

JavaScript: Preserve dollar signs in literal replacement text

November 16, 2026

A text template can corrupt a supplied value containing dollar substitution tokens. Use a replacement callback when the value must be inserted unchanged, even when the search token is a plain string.

Set up

Tested on Debian 13 Linux with Node.js v24.22.1. Use Bash, Node.js on your PATH, a text editor, and the mktemp, rm and rmdir utilities. No packages or network access are needed. Keep the same terminal through cleanup. Stop if setup fails before saving the source.

start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1

Run the example

Save as javascript-literal-replacement-dollars.mjs:

import assert from 'node:assert/strict';

function replaceLiteral(source, token, value) {
  if (![source, token, value].every((item) => typeof item === 'string')) {
    throw new TypeError('Expected strings');
  }
  if (token === '') throw new RangeError('Token must not be empty');
  return source.replaceAll(token, () => value);
}

const source = 'first={{value}}; second={{value}}';
const value = '$& / $$';
const interpreted = source.replaceAll('{{value}}', value);
const literal = replaceLiteral(source, '{{value}}', value);
assert.equal(interpreted, 'first={{value}} / $; second={{value}} / $');
assert.equal(literal, 'first=$& / $$; second=$& / $$');
assert.equal(replaceLiteral('a.b', '.', '$1'), 'a$1b');
assert.equal(replaceLiteral('unchanged', 'missing', value), 'unchanged');
assert.throws(() => replaceLiteral('text', '', value), RangeError);
assert.throws(() => replaceLiteral('text', 'text', null), TypeError);
console.log(`string replacement: ${interpreted}`);
console.log(`callback replacement: ${literal}`);
console.log(`literal dot: ${replaceLiteral('a.b', '.', '$1')}`);

Run:

node javascript-literal-replacement-dollars.mjs

Observed output:

string replacement: first={{value}} / $; second={{value}} / $
callback replacement: first=$& / $$; second=$& / $$
literal dot: a$1b

Read the result

The string replacement interprets the match token and collapses the doubled dollar sign. Returning the value from a callback preserves both sequences. The dot test also uses a string search token, so the dot matches literally without building a regular expression.

Apply it carefully

The helper accepts strings only and deliberately rejects an empty token. A missing token leaves the source unchanged. Replacement happens across the original matches; the returned text is not searched again in this call. This is plain-text substitution, not HTML escaping, shell quoting or SQL parameterization. Apply the destination format’s own encoding rules before using the result there.

The ECMAScript replaceAll algorithm treats callback results separately from string substitution tokens.

Clean up

Remove the saved file and empty scratch directory. If the directory is not empty, inspect its contents before removing anything else.

rm -- javascript-literal-replacement-dollars.mjs
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dir

Acknowledgements

This post was created with assistance from AI.

Last updated on