JavaScript Reference ยท String
String.prototype.toWellFormed()
Reference for JavaScript String.prototype.toWellFormed(): replace lone UTF-16 surrogates with U+FFFD so a string is safe for encoders such as encodeURIComponent().
JavaScript strings are sequences of UTF-16 code units, and nothing stops a string from containing a lone surrogate: half of a surrogate pair without its partner. Such a string is not valid Unicode text, and some APIs refuse it. The toWellFormed() method returns a copy in which each lone surrogate is replaced by the replacement character U+FFFD (๏ฟฝ).
Use it before handing text to an API that needs valid Unicode, such as encodeURIComponent() or a protocol that requires valid UTF-8. To only test a string, use isWellFormed().
"ab\uD800".toWellFormed(); // "ab๏ฟฝ"
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
string.toWellFormed()
This method takes no parameters.
Return value: a new string in which every lone surrogate (a code unit from \uD800 to \uDFFF that is not part of a correct high-then-low pair) is replaced by U+FFFD. A string that is already well formed is returned with identical contents.
Exceptions: none for strings.
Usage notes
- A valid pair is kept. Emoji and other characters outside the Basic Multilingual Plane are stored as a high surrogate followed by a low surrogate; those are left alone.
- The length does not change. Each lone surrogate is one code unit and U+FFFD is one code unit, so indexes stay the same.
- Lossy: the original lone code unit is gone. If you need to preserve arbitrary binary data, do not store it in a string this way; use typed arrays.
- Where lone surrogates come from: slicing through an emoji with
slice(),substring()orsplit(""), truncating text at a fixed length, or reading corrupted data. encodeURIComponent()throws aURIErroron a lone surrogate, which is a common production crash when truncated user input is encoded.toWellFormed()prevents that.TextEncoderis already forgiving: it replaces lone surrogates with U+FFFD in its output bytes, as the second example shows.- Check first, if you like:
isWellFormed()avoids creating a copy when you only need to know. - Only surrogates are repaired. Other problems, such as unusual normalization forms, are not touched.
Browser support
This is a recent addition (ECMAScript 2024). It works in current browsers, but check a compatibility table before relying on it for older ones.