# string-escape-map

> Escape a given map of special characters

Latest version **2.0.0** (published 2023-10-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install string-escape-map
pnpm add string-escape-map
yarn add string-escape-map
bun add string-escape-map
```

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2023-10-05 |
| First published | 2022-01-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 30.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Dmitry Ovsyanko |
| Maintainers | do- |
| Keywords | escape, string, special, characters |

## Links

- npm: https://www.npmjs.com/package/string-escape-map
- Repository: https://github.com/do-/node-string-escape-map
- Homepage: https://github.com/do-/node-string-escape-map#readme
- Issues: https://github.com/do-/node-string-escape-map/issues
- npm.io page: https://npm.io/package/string-escape-map

## Alternatives

- [@mce/gif](https://npm.io/package/@mce/gif.md) — 2.6K weekly downloads
- [cleanse](https://npm.io/package/cleanse.md) — 173 weekly downloads
- [str](https://npm.io/package/str.md) — 127 weekly downloads
- [naming](https://npm.io/package/naming.md) — 95 weekly downloads
- [tap-telco-api](https://npm.io/package/tap-telco-api.md) — 19 weekly downloads

## Recent versions

- 2.0.0 (latest) — 2023-10-05
- 1.0.3 — 2023-10-05
- 1.0.2 — 2023-02-01
- 1.0.1 — 2023-01-20
- 1.0.0 — 2022-01-03

## README

![workflow](https://github.com/do-/node-string-escape-map/actions/workflows/main.yml/badge.svg)
![Jest coverage](./badges/coverage-jest%20coverage.svg)

# node-string-escape-map
Escape a given map of special characters

# Installation
```sh
npm install string-escape-map
```

# Usage
```js
//const stringEscape = require ('string-escape-map') // v.1.x.x � CommonJS

import stringEscape from 'string-escape-map'         // v.2.x.x � ES6 module

// initialization
const MY_ESC = new stringEscape ([
  ['\t', '\\t'],
  ['\n', '\\n'],
  [ "'", "''"],
])

// possible later adjustment
MY_ESC.set ('\r', '')

// run time usage
const unsafeString = `Don't
you?`

const safeString = MY_ESC.escape (unsafeString)
```
# Details
## Constructor 

The class provided by `string-escape-map` is derived from [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) and shares its [constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/Map) argument format: if set, it must be an [iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) of key-value pairs.

Additional restrictions on input are same as for the `set` method (see below).

## Methods
### `set`

The standard [set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/set) method is overloaded to effectively store char codes to safe substring mapping. So:

* `key` and `value` must be (primitive) `string`s;
* `key` must be a single character string. 

Under the hood, the `key` parameter is subject to [charCodeAt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charCodeAt).

Other than registering a map entry, it sets `escape1` or `escapeN` as `this.escape` method.

## `escape`

This method executes the module's main task: replaces all the characters in question with their safe representations

```js
const safeString = MY_ESC.escape (unsafeString)
```

### Parameter

`unsafeString` must be a primitive [string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String). 

`null`, `undefined` etc. values cause errors.

Zero length strings are allowed.

### Return value

A primitive string with all occurrences of each character previously `set` replaced with corresponding substrings.

## `escapeN`

This method is used as `escape` in case when more than one entry is set in this map. It scans through `unsafeString`, detect unsafe chars with `charCodeAt` and concatenates the result from safe `slice`s glued with replacement strings from this Map.

## `escape1`

This method is used as `escape` when only one unsafe character is known, so this works as `replaceAll`. The `unsafeString` is scanned with `indexOf`, the result is assembled from the `slice`s detected.

# Implementation notes

No [replace](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replace) nor [replaceAll](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/replaceAll) method is used.

No [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) is constructed.

The given string is scanned with [charCodeAt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charCodeAt) (which is significantly faster and more memory efficient than [charAt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/charAt)).

If no unsafe character is ever found, the argument is passed through untouched, without creating any temporary object at all.

Otherwise, the resulting string is created by concatenating complete safe [slice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/slice)s with replacement substrings for unsafe chars.

---
_Source: https://npm.io/package/string-escape-map · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._