NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm, #42 most downloaded on npm
Convert character encodings in pure javascript.
Latest stable
0.7.3
Last release 14 days ago
08 Nov 2026
Ships unpredictably
gaps range from 9 days to 4.2 years
Rarely documented
notes for 4 of 52 stable releases
Nothing withdrawn
no release was ever pulled
15 years old
60 releases · first in 2011
Drag across the ruler to compare, or tap a release to open it.
Emit one replacement byte per unencodable Unicode code point in single-byte encoders. Fixes #368 .
Emit one replacement byte per unencodable Unicode code point in single-byte encoders. Fixes #368.
Supplementary characters such as 🙂 now encode as ? instead of ??, including with defaultCharByte or a handler that keeps the default replacement. Incremental encoders buffer a trailing high surrogate until the next nonempty write or end(), so pairs split between chunks also produce one replacement.
Remove the public iconv.defaultCharSingleByte and iconv.defaultCharUnicode properties.
Use the per-conversion defaultCharByte and defaultCharUnicode options instead.
Align KOI8-U, Macintosh and x-mac-cyrillic web labels with the WHATWG indexes.
koi8-u now uses the KOI8-RU mappings for AE / BE (ў / Ў). Macintosh labels decode BD as Greek omega (U+03A9), DB as €, and F0 as the Apple private-use character (U+F8FF). x-mac-cyrillic and x-mac-ukrainian map A2 / B6 to Ґ / ґ and FF to €. Encoding uses the same tables without Unicode normalization. Explicit KOI8-U code pages (21866, cp21866, ibm1168) and legacy macroman, maccyrillic, macukraine, 10000 and 10007 retain their original mappings.
Reject encoding labels containing non-ASCII characters instead of stripping them or folding them into ASCII (for example, the Kelvin sign in Koi8-r). Surrounding ASCII whitespace and case-insensitive ASCII matching remain supported.
Resolve legacy ASCII, Latin-1, Latin-5 and Thai labels to their WHATWG Windows encodings.
ascii and iso-8859-1 (including us-ascii and latin1) now use Windows-1252. iso-8859-9 and latin5 use Windows-1254; iso-8859-11 and tis-620 use Windows-874. This applies to encoding, decoding, handlers, fatal mode and streams. For example, byte 80 decodes to € with ascii or latin1, and encoding € produces 80. Explicit ISO code pages 28591, 28599 and 28601 (including their cp forms) retain their original tables; cp367 and ibm367 retain 7-bit ASCII. Use binary for byte-preserving Latin-1 conversion.
Add x-user-defined encoding and decoding following the WHATWG Encoding Standard.
ASCII is preserved and bytes 80–FF map to U+F780–U+F7FF. The codec supports incremental conversions, Node and Web Streams, configurable encoding replacements and handlers. Every byte is valid, including in fatal decoding mode.
Support { fatal: true } in table-based multibyte decoders, including Big5, Shift_JIS, EUC-JP, EUC-KR, GBK and GB18030.
Invalid and truncated sequences throw TypeError in one-shot decoding, incremental decoders and streams. After a fatal write, bytes restored by the WHATWG decoder algorithm and unread input remain available to subsequent writes; finalization resets the decoder even when it throws.
Add the ISO-2022-JP codec - by @cadelass in #425
iso-2022-jp (alias csiso2022jp) is now supported for decoding and encoding, following the WHATWG Encoding Standard. It reuses the EUC-JP tables without adding another mapping table.
Configure replacement text for SBCS, DBCS, CESU-8 and UTF-32 decoders with { defaultCharUnicode: "<invalid>" }.
Accept literal strings, including empty text, with U+FFFD as the default. Each decoder and stream captures its own replacement. Valid U+FFFD input is preserved, and fatal decoding still rejects invalid input where supported.
Configure the replacement byte for table-based single-byte and multibyte encoders with { defaultCharByte: 0x21 }.
Accept integers from 0 to 255, with 0x3F (?) as the default. Each encoder and stream captures its own replacement.
Throw TypeError consistently for invalid or truncated UTF-32 input in fatal mode, including incremental decoding and streams.
Preserve Big5 encoding order when an isolated UTF-16 surrogate follows a pending character sequence. Emit the pending character before its replacement and prevent combining marks from joining across the invalid input.
Stop treating U+FEFF replacement text as an input BOM when decoding CESU-8 and UTF-32.
Keep caller options unchanged in Node encoding and decoding streams, including frozen option objects.
Add Windows code page aliases 65000 / cp65000 for UTF-7 and 65001 / cp65001 for UTF-8. Addresses #109.
Add Windows code page aliases 1200 / 1201 for UTF-16LE/BE, 12000 / 12001 for UTF-32LE/BE and 20127 for 7-bit ASCII, including their cp forms. Unicode code pages preserve fixed byte order, BOM options and fatal decoding.
Respect changes to defaultCharSingleByte after a single-byte codec is cached - by @bjohansebas in #451
New encoders and streams validate and capture the current replacement byte, including after encodingExists() or decoding has initialized the codec. Existing encoders retain their original table and fallback, including during handler callbacks and finalization. The codec reuses its latest encoding table until the replacement changes.
Respect defaultCharUnicode when decoding table-based single-byte encodings - by @bjohansebas in #451
Undefined bytes in Windows-874, Windows-1253, Windows-1255, Windows-1257 and other SBCS encodings now use the configured replacement instead of always producing U+FFFD. Each decoder captures its instance's setting at creation, including when its table is already cached. Replacement text is inserted literally and in full; valid mappings and encoding are unaffected, and { fatal: true } still throws.
Preserve the WHATWG C1 control mappings in Windows-874 and Windows-125x - by @bjohansebas in #451
The 86 previously unassigned positions in the 0x80–0x9F range now decode to their corresponding control characters and encode back to the same bytes. For example, Windows-1252 byte 81 now decodes to U+0081 instead of U+FFFD, and U+0081 encodes as 81 instead of 3F. Encoding these controls no longer invokes invalidCharHandler, and they can be used in its replacements.
Support opt-in fatal decoding for table-based single-byte encodings - by @bjohansebas in #451
{ fatal: true } now throws TypeError for undefined bytes, including the 23 undefined positions in Windows-874, Windows-1253, Windows-1255 and Windows-1257. Valid C1 controls remain accepted, and the default remains replacement decoding. The option works with direct decoding, incremental decoders, Node streams and Web Streams, and is declared in DecodeOptions.
Decode the whole Shift_JIS EUDC block - by @b84330808 in #445
The 187 valid byte pairs from F941 to F9FC now decode to U+E69D to U+E757, as the Encoding Standard specifies. Previously, only F940 was mapped in that row; the remaining pairs produced a replacement character, with an ASCII trail byte decoded again. For example, F9 FC 41 now decodes to U+E757 A instead of U+FFFD A. EUDC characters remain decode-only: encoding uses the configured replacement byte or invokes invalidCharHandler.
Stop GBK from encoding U+E7C7 - by @b84330808 in #446
U+E7C7 only has the GB18030 four-byte code 81 35 F4 37, which the Encoding Standard's GBK encoder does not produce. The GBK encoder only reserves three bytes per character, so depending on the space left in its output buffer the code came out whole, cut to 81 35 F4, or as a RangeError from the Node backend. It now encodes as ?, like other characters that GBK cannot represent. Decoding 81 35 F4 37 is unchanged.
Apply the WHATWG GB18030 asymmetric encoder table - by @superbot-helper in #443
Encode the 18 private-use characters in the table to their specified two-byte forms, including when invalidCharHandler is enabled. These mappings intentionally decode to different characters under the GB18030-2022 index. U+E5E5 now uses the configured replacement byte or invokes invalidCharHandler.
Treat an invalid DBCS byte pair as one error - by @b84330808 in #442
Shift_JIS, EUC-KR, GBK, GB18030 and EUC-JP now handle an invalid two-byte sequence the way the Encoding Standard specifies, as Big5 already did: a non-ASCII second byte is consumed with the lead, and only an ASCII one is decoded again. CP936 and CP950 use the same error-recovery rule. Every lead byte that the standard defines is buffered, including rows with no assigned characters. Before, the second byte was read again as a new lead, so 81 E9 41 42 in Shift_JIS decoded to U+FFFD 顴 B and the A was lost.
Align additional GBK, GB18030 and EUC-JP decoding behavior with the Encoding Standard. GBK accepts GB18030 four-byte sequences while retaining its encoder. Incomplete GB18030 and EUC-JP sequences produce one replacement character at end-of-input. EUC-JP buffers every JIS X 0212 row and consumes invalid three-byte sequences as one error, reprocessing only an ASCII final byte.
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Remove Node-style streams from the Web entry point.
Remove Node-style streams from the Web entry point.
iconv-lite/web no longer exposes encodeStream(), decodeStream(), or supportsStreams. Use the native encodeWebStream() and decodeWebStream() methods and supportsWebStreams instead. The Node entry point continues to offer both stream APIs. enableStreamingAPI() has been removed from both entry points; Node streams initialize automatically.
Restrict public package entry points.
Only iconv-lite, iconv-lite/web, and iconv-lite/encodings/*.js are exported. Direct package imports of lib/*, backends/*, and package.json are no longer supported. Encoding label normalization is now an internal utility rather than the _canonicalizeEncoding instance method; public encoding operations continue to normalize labels internally.
Compress dense DBCS tables with VLQ-encoded runs.
Reduce compressed table size while preserving existing mappings and support for traditional table rows.
Register external encoding packages with addEncoding(definitions, options).
Support codec constructors, aliases, and configured variants on the Node and Web instances. Registration is atomic and idempotent; replacements require { replace: true } and invalidate dependent caches. Publish codec and backend contracts and types for external labels. Addresses #253.
Add native Web Streams support - by @bjohansebas, following #340
Add encodeWebStream() and decodeWebStream() in Node.js and browsers, using the global TransformStream without setup. The streams preserve codec options, buffered output, and invalid character handling, with native backpressure and error propagation. Node.js callers can choose these methods or the existing Node-style encodeStream() and decodeStream(). supportsWebStreams reports native or polyfilled availability.
Support invalidCharHandler across text encodings - by @DecimalTurn and @bjohansebas in #388
Add custom handling for unrepresentable characters in single-byte, multibyte, UTF-8, UTF-32, and binary encoding. Handlers can return replacement text, skip characters, keep default fallback bytes, cancel a write, or throw. Streaming preserves split surrogate pairs and original character positions. Supported by both Node and Web backends; hex and base64 reject the option.
Preserve configured codec variants when their base codec is cached.
Configured aliases use their own options and cache entries, with variant options taking precedence over base options. Cyclic aliases fail with an error instead of looping indefinitely.
Match root import types to the selected runtime entry point.
Browser and default resolution expose the Web API with Uint8Array results. Node resolution retains Buffer results and Node stream methods.
Decode binary, hex and Base64 streams incrementally.
Emit output during writes instead of retaining the entire input until close. Base64 keeps at most two pending bytes and adds padding only on final flush, allowing stream backpressure to bound queued output.
Preserve buffered UTF-16 and UTF-32 input during endianness detection.
Reusing or transferring input buffers after a streaming write no longer corrupts or discards bytes retained for autodetection.
Isolate the Node and Web entry points.
Importing iconv-lite/web alongside iconv-lite no longer changes the Node backend or enables Node streams on the Web instance. Each instance has its own codec cache and mutable settings; setBackend() affects only that instance.
Use import iconv from "iconv-lite" or dynamic import() from CommonJS. Direct require() is no longer supported. Node.js 22 remains the minimum version.
Migrate to native ES modules.
Use import iconv from "iconv-lite" or dynamic import() from CommonJS. Direct require() is no longer supported. Node.js 22 remains the minimum version. Browser consumers can use iconv-lite/web or lib/index-web.js. Encoding modules now load at import time; DBCS table data and codecs are still initialized on demand. Mutable settings remain on the default export.
Extend custom backend requirements for internal codecs - by @bjohansebas in #429
Custom backends must implement encodeString, decodeBytes and copyBytes. The built-in Node and Web backends provide these methods.
Refactor DBCS codecs for Node and browsers - by @bjohansebas
DBCS codecs, including GBK/GB18030, Big5, Shift_JIS, EUC-JP and EUC-KR, now use classes and backend allocations and conversions. Node encoders retain Buffer results, while Web encoders return Uint8Array without requiring a Buffer polyfill. Conversions reuse the Web UTF-16 decoder and DBCS pending-byte storage, and avoid redundant Node buffer views.
Refactor internal codecs for Node and browsers - by @bjohansebas in #429
UTF-8, CESU-8, binary, hex and Base64 now use classes and backend conversions. Node retains native Buffer conversions, while Web encoders return Uint8Array without requiring a Buffer polyfill. Binary, hex and Base64 decoding avoids input copies for complete inputs, and Web conversions use native hex/Base64 methods where available and beneficial.
Reject unassigned GB18030 four-byte pointers - by @binggao1230 and @bjohansebas in #417
Unassigned pointers now emit the configured replacement character instead of unrelated characters or unpaired surrogates. Supplementary characters decode directly without a range search. Exhaustive pointer and chunk-boundary tests run with both backends and in browsers.
Preserve DBCS output across chunk boundaries - by @bjohansebas
Streaming encoders and decoders reserve space for pending input as well as the new chunk. This prevents truncated output when completing surrogate pairs, Big5 combining sequences, or reprocessing malformed multibyte input.
Use the default byte when encoding U+FFFD in SBCS - by @mamicicekel in #424
Single-byte encoders now consistently encode U+FFFD using defaultCharSingleByte (? by default), instead of mapping it to an unassigned byte from the decoding table.
Preserve caller options in UTF-16 and UTF-32 auto encoders - by @KennyMcSimpson and @bjohansebas in #427
The automatic UTF-16 and UTF-32 encoders no longer modify the caller's options or throw when those options are frozen. Reusing the options for another encoding no longer adds an unexpected BOM. Explicit and inherited addBOM values, and UTF-32's defaultEncoding, remain respected.
Correct UTF-8 BOM handling - by @bjohansebas in #429
UTF-8 decoding strips only one leading BOM and calls stripBOM callbacks once.
Correct CESU-8 finalization - by @spokodev and @bjohansebas in #429
Incomplete CESU-8 sequences emit one replacement character on final flush, without a spurious 0 or repeated output on subsequent flushes.
Remove support for Node <22 - by @bjohansebas in #396
Remove support for Node <22 - by @bjohansebas in #396
Node.js versions prior to 22 are no longer supported. This allows us to migrate to ESM and rely on require(esm), which does not work correctly on earlier versions.
Make the UTF-16 decoder WHATWG-conformant by @bjohansebas in #402
UTF-16LE/BE (and the ucs2/ucs-2 aliases) now decode through the standard TextDecoder, matching the Encoding Standard's shared UTF-16 decoder. As a result, unpaired/invalid surrogates and a trailing odd byte are replaced with U+FFFD instead of being passed through, and the Node and Web backends now behave identically. The decoder also no longer depends on the backend.
The utf-16 label still auto-detects endianness (UTF-16LE vs UTF-16BE) from the BOM and a space-based heuristic, defaulting to UTF-16LE. This is kept as an iconv-lite extension even though it is not spec-compliant — the Encoding Standard maps the utf-16 label directly to UTF-16LE.
Reject encoding labels with forbidden characters, per WHATWG - by @bjohansebas in #403
Following the Encoding Standard's label-trimming rules, only ASCII whitespace (tab, LF, FF, CR, space) may surround an encoding label. Labels wrapped in other control or separator characters — NUL, vertical tab, NBSP, or the line/paragraph separators — are now rejected instead of being silently stripped and accepted. Punctuation such as dashes and underscores within an otherwise-valid label is still normalized.
Make the UTF-7 and UTF-7-IMAP codecs RFC 2152 conformant - by @bjohansebas in #406
When decoding, 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 now replaced with U+FFFD instead of being passed through (lone surrogates still pass through as raw 16-bit code units). When encoding UTF-7, the optional "Set O" punctuation is now left as direct ASCII, so the output differs byte-for-byte for those characters, though it still decodes to the same text.
Make the UTF-32 codecs strict and browser-native - by @bjohansebas in #407
UTF-32LE/BE and the auto-detecting utf-32 codec now decode strictly 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 U+FFFD instead of being passed through. Encoding likewise replaces a lone (unpaired) surrogate with U+FFFD. The opt-in { fatal: true } decoding option makes ill-formed input throw instead. The codecs no longer use the Node Buffer internally, so they also work on the Web backend (browsers), like UTF-16. The internal _utf32 codec name (a private, undocumented implementation detail of the old codec-options indirection) was removed.
Speed up the UTF-32 codecs - by @bjohansebas in #407
UTF-32 decoding and encoding are noticeably faster, and encoding no longer allocates a Node Buffer.
Recognize more WHATWG encoding labels - by @bjohansebas in #403
Added the WHATWG label aliases for encodings iconv-lite already implements: unicode/csunicode/iso-10646-ucs-2/unicodefeff (UTF-16LE) and unicodefffe (UTF-16BE); x-cp1250–x-cp1258 (windows-1250–1258); dos-874; koi/koi8 (KOI8-R); x-mac-cyrillic/x-mac-ukrainian/x-mac-roman; x-euc-jp/cseucpkdfmtjapanese (EUC-JP); the iso-8859-6/iso-8859-8 -e/-i and visual/logical variants; csisolatin9; sun_eu_greek; unicode-2.0-utf-8; and more. (Labels whose encoding iconv-lite does not implement, such as iso-2022-jp and x-user-defined, remain unsupported.)
Add an opt-in fatal decoding option - by @bjohansebas in #402
Passing { fatal: true } to iconv.decode(...) makes the TextDecoder-backed encodings (UTF-8, UTF-16LE/BE) throw on invalid input, per the WHATWG Encoding Standard, instead of replacing it with U+FFFD. The default stays lenient (replacement).
Full Changelog: v1.0.0-alpha.1...v1.0.0-alpha.2
Remove support for Node <18 and safe-buffer dependency - by @bjohansebas @Phillip9587 and @TheThing in #265 and #349
Remove support for Node <18 and safe-buffer dependency - by @bjohansebas @Phillip9587 and @TheThing in #265 and #349
Node.js versions prior to 18 are no longer supported. This allows us to remove the safe-buffer dependency and use native Buffer methods available in Node 18 and later.
Use native TextDecoder for decoding - by @JohnGu9 and @bjohansebas in #316
While this improves compatibility with web standards, some edge cases may behave differently because the implementation of TextDecoder in Node.js or other JavaScript runtimes has issues with the specification.
Introduce backend abstraction layer to support to Uint8Array buffer implementation - by @ashtuchkin
This paves the way for supporting environments without Node.js Buffer, such as browsers using Uint8Array.
This is a work in progress, so many parts still rely on Buffer internally, but the goal is to eventually have full support for a Uint8Array based implementation.
Update of the GBK encoding table according to changes in the specification - by @bjohansebas in #371
The GBK encoding table was updated to reflect the latest changes in the Encoding Standard:
Full Changelog: v0.7.2...v1.0.0-alpha.1
Add iso-8859-8-i and iso-8859-8-e charset aliases - by @baptistejamin in #394
iso-8859-8-i and iso-8859-8-e charset aliases - by @baptistejamin in #394Fix UTF-32 streaming across chunk boundaries - by @spokodev and @bjohansebas in #393
When decoding a UTF-32 stream, a 4-byte code unit split across a chunk boundary was decoded incorrectly, and a truncated trailing unit is now replaced with U+FFFD instead of being dropped. When encoding, a surrogate held over between chunks no longer throws. Whole-buffer decode/encode were unaffected.
Full Changelog: https://github.com/pillarjs/iconv-lite/compare/v0.7.2...v0.7.3
iso-8859-8-i and iso-8859-8-e charset aliases - by @baptistejamin in #394Fix UTF-32 streaming across chunk boundaries - by @spokodev and @bjohansebas in #393
When decoding a UTF-32 stream, a 4-byte code unit split across a chunk boundary was decoded incorrectly, and a truncated trailing unit is now replaced with U+FFFD instead of being dropped. When encoding, a surrogate held over between chunks no longer throws. Whole-buffer decode/encode were unaffected.
Full Changelog: v0.7.2...v0.7.3
Correction of CommonJS exports in TypeScript definitions - by @plbstl in #366
Correction of CommonJS exports in TypeScript definitions - by @plbstl in #366
Fixed the TypeScript definitions to correctly represent the CommonJS exports of the library.
This resolves issues where consumers using TypeScript would encounter errors due to incorrect
type definitions that did not align with the actual module exports.
Full Changelog: v0.7.1...v0.7.2
types: improve type definitions and add missing APIs - by @plbstl and @bjohansebas in #330
Full Changelog: v0.7.0...v0.7.1
Handle split surrogate pairs when encoding utf8 - by @yosion-p and @ashtuchkin in #282 :
Handle split surrogate pairs when encoding utf8 - by @yosion-p and @ashtuchkin in #282:
Handle a case where streaming utf8 encoder (converting js strings -> buffers) encounters
surrogate pairs split between chunks (last character of one chunk is high surrogate and first
character of the next chunk is a low surrogate).
Avoid false positives in encodingExists by using objects without a prototype - by @bjohansebas in #328
The encodingExists method could return incorrect results if the lookup matched properties inherited
from the prototype of the object that stores the encodings, such as constructor and others. This change
replaces that object with one that has no prototype, ensuring that only explicitly defined valid encodings
in the library are considered. In addition, the fix is applied to the internal cache system to avoid the same
kind of false positives
Full Changelog: v0.6.3...v0.7.0
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
One column per quarter.