# escape-regex

## Purpose

`escapeRegex` escapes every regular-expression metacharacter in a
string so the string can be embedded literally inside a `RegExp`
constructor. The {@link InterpolationEngine} uses it to compile
placeholder patterns from caller-supplied delimiters (`{{`,
`%{`, `<%`, …) into a working RegExp without inadvertently
treating delimiter characters as regex syntax. Exposing it as a
standalone export lets downstream consumers build their own
delimiter-aware patterns or sanitise raw search queries.

The helper lives in its own file (alongside `escape-html`) so
tree-shaking can strip the rest of the interpolation engine when
a consumer needs only the escape primitive — for example, a
documentation tooling pipeline that compiles user-typed search
patterns into a forgiving regex.

## Features

- Escapes the canonical 12 ECMAScript regex metacharacters
  (`. * + ? ^ $ { } ( ) | [ ] \`) plus the closing brace
- Pure function: no I/O, no state, deterministic per input
- Single-pass `String.prototype.replace` with a precompiled
  regex literal — no allocation beyond the output string
- Zero dependencies — drops cleanly into edge / worker bundles

## Usage: Basic Example

```typescript
import { escapeRegex } from "@suaveplan/i18n-icu-parser/interpolation";

const safe = escapeRegex("a.b*c");
// "a\\.b\\*c"
const re = new RegExp(safe);
re.test("a.b*c"); // true (literal match)
```

## Usage: Advanced Example

```typescript
import { escapeRegex } from "@suaveplan/i18n-icu-parser/interpolation";

// Build a placeholder pattern from caller-supplied delimiters.
function buildPlaceholderPattern(open: string, close: string): RegExp {
    const o = escapeRegex(open);
    const c = escapeRegex(close);
    return new RegExp(`${o}\\s*([^${c}]+)\\s*${c}`, "g");
}

const re = buildPlaceholderPattern("<%=", "%>");
const matches = "Hello <%= name %>".matchAll(re);
for (const m of matches) console.log(m[1]?.trim()); // "name"
```

## API Reference

### `escapeRegex(str: string): string`

Escape every regular-expression metacharacter in `str`. The
escaped output can be inserted unchanged into a `RegExp` source
string and will match the original character literally.

Escaped characters: `.`, `*`, `+`, `?`, `^`, `$`, `{`, `}`,
`(`, `)`, `|`, `[`, `]`, `\`.

**Returns:** the escaped string. Strings without metacharacters
return unchanged.

## Implementation Notes

- The replacement uses `\\$&` (backref to the whole match)
  rather than enumerating every escape sequence, which keeps the
  function bytes-small and easy to audit.
- The character class `[.*+?^${}()|[\\]\\\\]` is the canonical
  V8 / SpiderMonkey escape set for the standard `RegExp`
  grammar. Alternation operators inside character classes (`-`)
  do NOT need escaping at the outer level and are intentionally
  omitted.
- The function is `O(n)` in input length. Worst case is a string
  of only metacharacters which expands 2x in the output.
- This is the canonical regex escape across Suaveplan
  — every package that needs to embed user input in a RegExp
  consumes this helper or its inlined twin in the parser file.