regexp.escape

regexp.escape is an ESnext spec-compliant shim/polyfill for the proposed RegExp.escape static method, maintained by the es-shims organization. It provides a standalone function that safely escapes RegExp special tokens in a string so the result can be embedded directly into a new RegExp(...) pattern without accidentally introducing metacharacter behavior — a common source of injection-style bugs when building dynamic regular expressions from user input.

Beyond the plain escape() function, the package exposes the full es-shims API surface: getPolyfill() to retrieve either the native RegExp.escape (if the runtime already implements the TC39 proposal) or the polyfill, shim() to install it onto the global RegExp object, and an /auto entry point that shims automatically on import. This makes it usable both as a direct utility and as a forward-compatible polyfill that steps out of the way once engines ship the real spec behavior.

What You Get

• A single escape(string) function that returns a regex-safe, escaped version of any input string
• getPolyfill() to prefer a native RegExp.escape implementation when the runtime already supports it, falling back to the polyfill otherwise
• shim() to install the polyfill onto the global RegExp object as RegExp.escape
• An /auto entry point (require('regexp.escape/auto')) that shims the global automatically on import
• A dependency-light, ES3-compatible implementation built on the es-abstract spec-operation library and es-shims conventions

Common Use Cases

• Safely interpolating untrusted or dynamic user input into a new RegExp(...) pattern without special characters altering the match logic
• Building search/filter features where a literal user-typed string needs to match itself exactly inside a regex
• Polyfilling RegExp.escape in environments/build targets that don’t yet implement the proposal so code can use the future-standard API today
• Constructing dynamic find-and-replace or highlighting logic from arbitrary substrings

Under The Hood

Architecture — The package layers cleanly: implementation.js holds the pure escape(S) algorithm (validates the input is a string, iterates its Unicode code points via StringToCodePoints, and either hex-escapes a leading decimal digit/ASCII letter or delegates to the EncodeForRegExpEscape abstract operation in aos/EncodeForRegExpEscape.js, which implements the TC39 spec’s step-by-step decision tree for syntax characters, punctuators, whitespace, line terminators, and lone/paired surrogates). polyfill.js wraps that in getPolyfill(), preferring a native RegExp.escape if present; shim.js installs the polyfill onto the global RegExp object via define-properties; index.js composes all of this into a single call-bind-bound export carrying getPolyfill/implementation/shim as properties; auto.js is a one-line side-effecting entry point that calls shim() on import.

Tech Stack — Pure JavaScript with zero build step, depending on the es-shims/ljharb ecosystem of spec-abstract-operation packages (es-abstract, es-errors, call-bind, define-properties, for-each, safe-regex-test) rather than reimplementing string/number spec algorithms inline, which is what gives it its ES3-down compatibility guarantees. Dev tooling is the standard es-shims toolkit: tape + nyc for tests, eslint with @ljharb/eslint-config, evalmd to lint README code blocks, and auto-changelog for release notes.

Code Quality — Tests in test/tests.js (410 lines) exercise both the round-trip property (escaping a string produces a regex that matches only itself) and explicit test262-derived cases for control characters, line terminators, and the ‘other punctuators’ set, run against both the raw implementation (test/index.js) and the shimmed global (test/shimmed.js). Code is heavily comment-annotated with the exact TC39 spec step numbers (e.g. // step 4.a.iii), which is unusual and valuable for auditability against the proposal text. No TypeScript types are shipped, consistent with the rest of the es-shims family.

API Design — The public surface is deliberately minimal: call the default export as a function, or reach for getPolyfill()/shim() when polyfill semantics are needed. This near-zero-configuration design, plus the /auto entry point, keeps the getting-started cost effectively zero, though the tradeoff is a single-purpose tool rather than a general regex-safety library — no options for allowlisting default characters or streaming input.