pillarjs/iconv-lite
Snapshot của pillarjs/iconv-lite: 3.2k★ · TypeScript · Frontend. Convert character encodings in pure javascript.
Tóm tắt dựng từ metadata GitHub của chính dự án — chưa có bài review TopGit. Trang sẽ tự động cập nhật khi bài review đầy đủ được xuất bản.
TopGit viết bài đầy đủ cho repo có nhiều sao nhất và được yêu cầu nhiều nhất. Trang này là snapshot trong thời gian chờ — xem README gốc ở tab READ ME.
Snapshot
Cộng tác viên hàng đầu
Xem cộng tác viên hàng đầu
iconv-lite: Pure JS character encoding conversion
- No need for native code compilation. Quick to install, works on Windows, Web, and in sandboxed environments.
- Used in popular projects like Express.js (body_parser), Grunt, Nodemailer, Yeoman and others.
- Faster than node-iconv (see below for performance comparison).
- Intuitive encode/decode API, including Streaming support.
- Native ES modules for Node.js and browsers, with automatic backend selection in compatible bundlers.
- Typescript type definition file included.
- React Native is supported (need to install
streammodule to enable Streaming API).
Usage
This package uses ES modules and requires Node.js 22 or later. CommonJS callers
can use const { default: iconv } = await import('iconv-lite') inside an async
function. Direct require('iconv-lite') is no longer a supported entry point.
Encoding and decoding remain synchronous once the module has loaded.
Use the default export for the conversion API and pass settings through options.
Functions are also available as named exports, for example
import { encode, decode } from 'iconv-lite'.
The public package entry points are iconv-lite, iconv-lite/web, and
iconv-lite/encodings/*.js.
Basic API
import iconv from 'iconv-lite';
// Convert from an encoded buffer to a js string.
const str = iconv.decode(Buffer.from([0x68, 0x65, 0x6c, 0x6c, 0x6f]), 'win1251');
// Convert from a js string to an encoded buffer.
const buf = iconv.encode("Sample input string", 'win1251');
// Replace unsupported characters with text in the target encoding.
const replacedBuf = iconv.encode("Hola 🙂", 'latin1', {
invalidCharHandler: () => ":)"
});
// Encodes "Hola :)"
// Customize handling in case some characters are not representable in the target encoding
try {
iconv.encode("Hello 世界", 'latin1', {
invalidCharHandler: function(char, index) {
throw new Error("Cannot encode character " + char + " at index " + index);
}
});
} catch (error) {
console.warn(error.message);
}
// Stop after first unsupported character (useful to avoid repeated warnings)
const checkedBuf = iconv.encode("Hello 世界", 'latin1', {
invalidCharHandler: function(char, index) {
console.warn("Unsupported character " + char + " at index " + index);
return true;
}
});
// checkedBuf === null
// Check if encoding is supported
iconv.encodingExists("us-ascii")
External encodings
Import an encoding package's definition map and register it on the entry point your application uses:
import iconv from 'iconv-lite'; // Or 'iconv-lite/web'.
import definitions from './custom-encodings.js';
iconv.addEncoding(definitions);
const bytes = iconv.encode('Hello', 'custom-encoding');
addEncoding(definitions, { replace: true }) explicitly allows replacing existing
codecs and aliases. Registration is atomic, normalizes labels, and rejects missing
alias targets and cycles. Repeating equivalent definitions is a no-op. Node and Web
instances keep their registrations separate.
See External encoding API for registration examples, codec and backend contracts, and TypeScript types.
Handling unrepresentable characters
For table-based single-byte and multibyte encodings, pass defaultCharByte to
select the fallback byte for that encoder. It must be an integer between 0x00
and 0xFF:
iconv.encode('Hello 世界', 'windows-1252', { defaultCharByte: 0x21 }); // "Hello !!"
The option also works with getEncoder(), encodeStream() and encodeWebStream().
Each encoder captures its setting at creation. The default is 0x3F (?).
ISO-2022-JP restricts the replacement to ASCII bytes other than ESC, SO and SI.
Replacement settings do not modify shared codec tables.
Single-byte encoders emit one replacement byte per unrepresentable Unicode code
point. For example, iconv.encode('🙂', 'windows-1252') returns one 0x3F byte.
Incremental encoders buffer a trailing high surrogate across empty writes until
the next nonempty write or end(). Consume the bytes returned by end() as well.
invalidCharHandler(char, index) runs when encoding would replace or truncate an
input character. Its result controls what happens:
| Handler result | Behavior |
|---|---|
| A string | Encode that replacement text; "" omits the character. |
false or undefined | Keep the encoding's default replacement bytes. |
true | Discard the current write and return null. |
| Throw an error | Propagate the error to the caller or encoding stream. |
Replacement text must be representable in the target encoding. An invalid
replacement or any other return value throws a TypeError, without calling the
handler recursively. Replacements use the same encoding context as surrounding
text, including multicharacter Big5 mappings. Indices refer to the original input,
not the replacement text.
The handler covers unmappable characters in single-byte and multibyte encodings,
unpaired surrogates in UTF-8 and UTF-32, and characters above U+00FF in binary.
UTF-16, CESU-8, and UTF-7 preserve UTF-16 code units, including unpaired surrogates,
so they do not invoke the handler. hex and base64 reject this option because
they convert byte representations rather than text. Omitting the handler keeps
the existing encoding behavior.
Rejecting invalid encoded input
Pass { fatal: true } to throw a TypeError when decoding invalid input.
This is supported by UTF-8, UTF-16, UTF-32, ISO-2022-JP and table-based single-byte and multibyte encodings,
including Windows-874, Windows-125x, Big5, Shift_JIS, EUC-JP, EUC-KR, GBK and GB18030.
The default remains replacement decoding.
iconv.decode(Uint8Array.of(0x81), 'windows-1252', { fatal: true }); // '\u0081'
iconv.decode(Uint8Array.of(0xAA), 'windows-1253'); // '\uFFFD'
iconv.decode(Uint8Array.of(0xAA), 'windows-1253', { fatal: true }); // Throws TypeError.
The option also applies to getDecoder(), decodeStream() and decodeWebStream().
A fatal single-byte decoder rejects the failing write and can process a later
valid write. Stream errors propagate through the stream's error mechanism.
Fatal table-based multibyte decoders reject invalid and truncated sequences. When an
incremental write throws, restored and unread bytes remain queued for a later write or end().
Finalization resets the decoder even when it throws.
For table-based single-byte and multibyte encodings, ISO-2022-JP, CESU-8 and UTF-32, pass
defaultCharUnicode to choose the text inserted for each decoding error:
iconv.decode(Uint8Array.of(0xAA), 'windows-1253', { defaultCharUnicode: '<invalid>' });
The value must be a string; "" omits invalid input. Text is inserted literally,
and valid input representing U+FFFD is preserved.
The option also works with getDecoder(), decodeStream() and decodeWebStream().
Each decoder captures its replacement at creation. The default is U+FFFD (�).
Where supported, { fatal: true } takes precedence and throws instead.
Browsers
Bundlers select the Web backend automatically. You can also select it explicitly:
import iconv from 'iconv-lite/web';
const bytes = iconv.encode('Hello', 'utf8'); // Uint8Array, without a Buffer polyfill.
For native browser modules, import dist/lib/index-web.js from a served copy of the
package. encodeWebStream() and decodeWebStream() use the native
TransformStream automatically. iconv.supportsWebStreams reports whether it is
available; older environments can supply a global TransformStream polyfill.
The Web entry point exposes only Web Streams. encodeStream(), decodeStream(),
and supportsStreams belong to the Node entry point.
DBCS table modules are imported with the library, but their arrays and codec lookup tables are initialized and cached only when the corresponding encoding is used.
Streaming API
In Node.js, encodeStream() and decodeStream() return Node streams.
encodeWebStream() and decodeWebStream() return Web Streams and are available
in both Node.js and browsers. Both APIs are initialized automatically.
// Decode stream (from binary data stream to js strings)
http.createServer(function(req, res) {
var converterStream = iconv.decodeStream('win1251');
req.pipe(converterStream);
converterStream.on('data', function(str) {
console.log(str); // Do something with decoded strings, chunk-by-chunk.
});
});
// Convert encoding streaming example
fs.createReadStream('file-in-win1251.txt')
.pipe(iconv.decodeStream('win1251'))
.pipe(iconv.encodeStream('ucs2'))
.pipe(fs.createWriteStream('file-in-ucs2.txt'));
// Sugar: Node encode/decode streams have .collect(cb) to accumulate data.
http.createServer(function(req, res) {
req.pipe(iconv.decodeStream('win1251')).collect(function(err, body) {
assert(typeof body == 'string');
console.log(body); // full request body string
});
});
Web Streams work with fetch(), pipeThrough(), and pipeTo():
import iconv from 'iconv-lite/web'; // Use 'iconv-lite' in Node.js.
const response = await fetch('/file-in-win1251.txt');
const utf8Bytes = response.body
.pipeThrough(iconv.decodeWebStream('win1251'))
.pipeThrough(iconv.encodeWebStream('utf8'));
// Consume the stream, or pipe it to a WritableStream destination.
const text = await new Response(utf8Bytes).text();
encodeWebStream(encoding, options) accepts strings and produces encoded bytes
(Buffer with the Node backend, Uint8Array with the Web backend).
decodeWebStream(encoding, options) accepts Uint8Array or Buffer chunks and
produces strings. Both accept the same codec options as encode() and decode().
Closing the writable side flushes buffered codec output; errors and cancellation
propagate through the native stream pipeline, with native backpressure.
Use a reader or pipeTo() to consume output while writing input. Web Streams
expose .readable and .writable; .collect() belongs to the Node stream API.
As with Node streams, hex input is parsed per chunk, so keep each pair of hex
digits in the same chunk.
Returning true from invalidCharHandler discards the entire
current write(), including its valid prefix, and returns null. Later writes
can still succeed. In encodeStream() and encodeWebStream(), this drops the
current chunk without ending the stream; throw from the handler to signal a
stream error instead.
With a handler, SBCS, DBCS, UTF-8, UTF-32, and binary encoders buffer a trailing
high surrogate until the next nonempty write or end(), so a split surrogate
pair is processed as one character. The
callback index counts Unicode code points within the input of the write where
the character starts. A buffered character retains its index from that write.
When using getEncoder(), consume the bytes returned by end() too; it can
return null if the handler cancels the buffered character. A cancellation
during either write() or end() makes the one-shot encode() return null.
Supported encodings
- Node.js-compatible encodings: utf8, ucs2 / utf16-le, binary, base64, hex.
- Additional unicode encodings: utf16, utf16-be, utf-7, utf-7-imap, utf32, utf32-le, and utf32-be.
- All widespread singlebyte encodings: Windows 125x family, ISO-8859 family, IBM/DOS codepages, Macintosh family, KOI8 family, all others supported by iconv library. Aliases like 'latin1', 'us-ascii' also supported.
- All widespread multibyte encodings: CP932, CP936, CP949, CP950, GB2312, GBK, GB18030, Big5, Shift_JIS, EUC-JP, ISO-2022-JP.
x-user-defined: preserves ASCII and maps bytes80–FFtoU+F780–U+F7FF, following WHATWG. Encoding reverses these mappings and uses the configured replacement or handler for other characters.
See all supported encodings on wiki.
The following legacy label families use the Windows mappings defined by the WHATWG Encoding Standard, for both encoding and decoding:
| Common labels | Encoding |
|---|---|
ascii, us-ascii, latin1, iso-8859-1 | Windows-1252 |
latin5, iso-8859-9 | Windows-1254 |
tis-620, iso-8859-11 | Windows-874 |
For example, iconv.decode(Uint8Array.of(0x80), 'ascii') now returns €, and
iconv.encode('€', 'latin1') produces byte 0x80. These labels differ from
Node.js Buffer's ascii and latin1 encodings. Use binary for byte-preserving
Latin-1 conversion between bytes and U+0000–U+00FF.
Numeric code page labels retain their explicit encodings, including in streams.
Both the number as a string and its cp-prefixed form are supported:
| Code page | Encoding |
|---|---|
1200, 1201 | UTF-16LE, UTF-16BE |
12000, 12001 | UTF-32LE, UTF-32BE |
65000, 65001 | UTF-7, UTF-8 |
20127 | 7-bit ASCII (also cp367 and ibm367) |
28591, 28599 | ISO-8859-1, ISO-8859-9 |
28601 | Existing iconv-lite alias for ISO-8859-11 |
Thus cp28591 still decodes 0x80 to U+0080, while the web label iso-8859-1
decodes it to €. Code pages 1200/1201 and 12000/12001 use fixed byte
order, without the autodetection of utf16 or utf32.
Encoding labels reject non-ASCII characters, including Unicode whitespace and
letters that Unicode lowercasing would turn into ASCII. Surrounding ASCII
whitespace and ASCII letter case are accepted. Numeric code pages and lenient
ASCII separator matching are iconv-lite extensions, not WHATWG TextDecoder labels.
Most singlebyte encodings are generated automatically from node-iconv. Thank you Ben Noordhuis and libiconv authors!
Multibyte encodings are generated from Unicode.org mappings and WHATWG Encoding Standard mappings. Thank you, respective authors!
Encoding/decoding speed
Comparison with node-iconv module (1000x256kb, on MacBook Pro, Core i5/2.6 GHz, Node v0.12.0). Note: your results may vary, so please always check on your hardware.
operation [email protected] [email protected]
----------------------------------------------------------
encode('win1251') ~96 Mb/s ~320 Mb/s
decode('win1251') ~95 Mb/s ~246 Mb/s
BOM handling
- Decoding: BOM is stripped by default, unless overridden by passing
stripBOM: falsein options (f.ex.iconv.decode(buf, enc, {stripBOM: false})). A callback might also be given as astripBOMparameter - it'll be called if BOM character was actually found. - If you want to detect UTF-8 BOM when decoding other encodings, use node-autodetect-decoder-stream module.
- Encoding: No BOM added, unless overridden by
addBOM: trueoption.
UTF-16 Encodings
This library supports UTF-16LE, UTF-16BE and UTF-16 encodings. First two are straightforward, but UTF-16 is trying to be smart about endianness in the following ways:
- Decoding: uses BOM and 'spaces heuristic' to determine input endianness. Default is UTF-16LE, but can be
overridden with
defaultEncoding: 'utf-16be'option. Strips BOM unlessstripBOM: false. - Encoding: uses UTF-16LE and writes BOM by default. Use
addBOM: falseto override.
UTF-32 Encodings
This library supports UTF-32LE, UTF-32BE and UTF-32 encodings. Like the UTF-16 encoding above, UTF-32 defaults to UTF-32LE, but uses BOM and 'spaces heuristics' to determine input endianness.
- The default of UTF-32LE can be overridden with the
defaultEncoding: 'utf-32be'option. Strips BOM unlessstripBOM: false. - Encoding: uses UTF-32LE and writes BOM by default. Use
addBOM: falseto override. (defaultEncoding: 'utf-32be'can also be used here to change encoding.) - Decoding is strict (per the Unicode Standard): a code unit that is a surrogate code point (U+D800–U+DFFF), is above U+10FFFF, or is a truncated trailing code unit is replaced with �. Pass
{ fatal: true }to throw on such input instead. - Encoding replaces a lone (unpaired) surrogate in the input with � so the output is always valid UTF-32.
UTF-7 Encodings
This library supports UTF-7 (RFC 2152) and UTF-7-IMAP / Modified UTF-7 (RFC 3501).
- Encoding: for UTF-7, the optional "Set O" punctuation is left as direct ASCII (per RFC 2152), so output stays compact.
- Decoding follows RFC 2152: ill-formed input — an incomplete code unit, non-zero Base64 padding bits, a shift-in not followed by Base64 or "-", or a non-ASCII byte outside a shifted run — is replaced with �. Lone surrogates pass through as their raw 16-bit code units.
- The
fataldecode option is not supported (RFC 2152 doesn't define it); decoding is always lenient (replacement with �).
UTF-7 is designed for short, 7-bit-safe strings (mail headers, IMAP mailbox names) and is best used that way.
It is not recommended for large or bulk text, where the native utf8/utf16 encodings are faster.
ISO-2022-JP
ISO-2022-JP is the stateful 7-bit Japanese encoding common in email. Encoding and decoding follow the WHATWG Encoding Standard.
- Decoding supports ASCII, JIS X 0201 Roman and Katakana, and JIS X 0208 (
ESC $ @andESC $ B). Escape sequences and characters may be split across stream chunks. Ill-formed input is replaced with �, including two escape sequences in a row with nothing between them (a WHATWG rule that prevents hiding content). - Encoding uses ASCII, JIS X 0201 Roman (for ¥ and ‾) and JIS X 0208, and always ends in ASCII. CR and LF preserve
Roman state; they switch JIS X 0208 back to ASCII. Halfwidth katakana are encoded as fullwidth, and characters
with no mapping become
?using the same state transitions as an ASCII input character. - Supports
fatal,defaultCharUnicode,defaultCharByteandinvalidCharHandler. The replacement byte must be ASCII and cannot be ESC (0x1B), SO (0x0E) or SI (0x0F), which would change or invalidate the encoding state. - Character mappings are the same as the
EUC-JPcodec (and browsers). They differ from the JIS mappings used by GNU iconv and Python for 6 characters: for example, 0x2141 decodes to U+FF5E (~), not U+301C (〜).
Other notes
When decoding, be sure to supply a Buffer to decode() method, otherwise bad things usually happen.
Untranslatable characters are set to � or ?. When encoding, invalidCharHandler can customize replacements, observe unsupported characters, cancel a write, or throw. Automatic transliteration is not supported.
Node versions 0.10.31 and 0.11.13 are buggy, don't use them (see #65, #77).
Repo liên quan
freeCodeCamp is a free, self-paced curriculum for learning to code, published as open source at freeCodeCamp/freeCodeCamp. It's a 501(c)(3) nonprofit funded by donor support, structured around six certifications in its Full-Stack Developer Curriculum, each gated by required projects instead of open-book quizzes. The repository also carries beta language certifications for developers, interview-prep resources, and the code that runs the live freecodecamp.org platform.
What GitHub issues dated 2014-10-10 to 2025-09-26 say about Vue 2, now at End of Life, plus where the repo stands today.
Bootstrap is an open-source front-end framework maintained at twbs/bootstrap. It ships compiled and minified CSS and JavaScript for building responsive, mobile-first sites, is licensed under MIT, and the release referenced throughout the README's install instructions is v5.3.8. The project was created by Mark Otto and Jacob Thornton, and its documentation is built with Astro and hosted at getbootstrap.com.
Airbnb JavaScript Style Guide is a public reference of JavaScript coding conventions maintained in the airbnb/javascript GitHub repository, covering rules for types, references, objects, arrays, destructuring, strings, and functions, among other topics. Most guidelines cite a matching ESLint rule and show bad-versus-good code side by side, and the project also links companion guides for React and CSS-in-JavaScript.
Trả lời nhanh
Cùng nhóm Frontend còn repo nào?
pillarjs/iconv-lite thuộc nhóm Frontend trên TopGit, cùng 4 topic GitHub. Trang Trending và Topics liệt kê các repo cùng số sao và cùng ngôn ngữ để so sánh.
Đọc thêm về pillarjs/iconv-lite ở đâu?
Trang TopGit này là một snapshot — tab "Readme" hiển thị nguyên văn README của repo (đã bỏ link, giữ ảnh). Repo GitHub ở github.com/pillarjs/iconv-lite là nguồn chính thức.
pillarjs/iconv-lite có phải mã nguồn mở không?
Có — pillarjs/iconv-lite phát hành theo license MIT, nghĩa là mã nguồn mở để đọc, fork và (tùy license) tái sử dụng. Mã: github.com/pillarjs/iconv-lite.
pillarjs/iconv-lite là gì?
pillarjs/iconv-lite (pillarjs/iconv-lite) là dự án TypeScript trên GitHub. Theo mô tả gốc: Convert character encodings in pure javascript.
pillarjs/iconv-lite so với các dự án Frontend khác thế nào?
pillarjs/iconv-lite được TopGit xếp vào nhóm Frontend, với 3.2k sao GitHub và viết bằng TypeScript. Xem trang chủ đề Frontend trên TopGit để so sánh với các dự án tương tự theo số sao và mức độ hoạt động.
Vì sao pillarjs/iconv-lite được xếp vào nhóm Frontend?
TopGit xếp pillarjs/iconv-lite vào nhóm Frontend dựa trên GitHub topics và mô tả của repo (gắn thẻ: "encoding", "encoding-convertors", "iconv"). Việc phân loại dựa trên metadata thật của repo, không phải đoán theo cảm tính biên tập.
Đọc đầy đủ README ở tab phía trên.
Muốn nghe thêm một ý kiến về iconv-lite?
Hỏi một AI đọc được trang này — một cú bấm là có ngay nhận định về iconv-lite.