iconv-lite

iconv-lite is a pure JavaScript character encoding conversion library that enables developers to convert text between different character encodings without requiring native code compilation. It offers both synchronous encode/decode APIs and streaming support for handling large data efficiently, supports a comprehensive range of encodings, and is designed for maximum portability and performance across Node.js, browsers, React Native, and sandboxed environments.

Package Information

• Package Name: iconv-lite
• Package Type: npm
• Language: JavaScript with TypeScript definitions
• Installation: npm install iconv-lite

Core Imports

const iconv = require('iconv-lite');

For ES modules:

import * as iconv from 'iconv-lite';

Basic Usage

const iconv = require('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');

// Check if encoding is supported
const isSupported = iconv.encodingExists("us-ascii");

Architecture

iconv-lite is built around several key components:

• Core API: Synchronous encode() and decode() functions for simple conversions
• Streaming API: Transform streams for handling large data with encodeStream() and decodeStream()
• Codec System: Pluggable encoding system with lazy-loaded codecs for different character sets
• BOM Handling: Automatic Byte Order Mark detection and manipulation for UTF encodings
• Encoding Support: Comprehensive support for UTF, ISO, Windows, ASCII, and multibyte encodings

Capabilities

Core Encoding/Decoding

Synchronous character encoding conversion between strings and buffers. Essential for processing text data in different character encodings.

function encode(content, encoding, options);

function decode(buffer, encoding, options);

function encodingExists(encoding);

Core Encoding API

Streaming API

Transform streams for encoding and decoding large amounts of data efficiently. Perfect for processing files or network streams.

function encodeStream(encoding, options);

function decodeStream(encoding, options);

function enableStreamingAPI(streamModule);

Streaming API

Low-level API

Direct access to encoder and decoder instances for advanced use cases and custom stream implementations.

function getEncoder(encoding, options);

function getDecoder(encoding, options);

function getCodec(encoding);

Low-level API

Types

/**
 * Options interface for encode/decode functions
 */
const Options = {
  /** Strip BOM (Byte Order Mark) from decoded output (default: true for decode) */
  stripBOM,
  /** Add BOM to encoded output (default: false) */
  addBOM,
  /** Default encoding fallback */
  defaultEncoding
};

/**
 * Encoder stream interface
 */
const EncoderStream = {
  write(str),
  end()
};

/**
 * Decoder stream interface
 */
const DecoderStream = {
  write(buf),
  end()
};

Properties and Constants

/** Registry of all available encodings and aliases (lazy-loaded, initially null) */
const encodings;

/** Default character for Unicode encoding errors */
const defaultCharUnicode; // "�"

/** Default character for single-byte encoding errors */
const defaultCharSingleByte; // "?"

/** Boolean indicating if streaming API is currently enabled */
const supportsStreams;

/** Flag to suppress deprecation warnings for decode() with strings */
const skipDecodeWarning;

/** Internal cache of loaded codec instances */
const _codecDataCache;

/** BOM (Byte Order Mark) character constant */
const BOMChar; // "\uFEFF"

Supported Encodings

iconv-lite supports a comprehensive range of character encodings:

• UTF Encodings: UTF-8, UTF-16, UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7
• ISO Encodings: ISO-8859 family (1-16)
• Windows Encodings: Windows-125x family (1250-1258)
• ASCII Encodings: US-ASCII and variants
• Multibyte Encodings: CP932, GB2312, GBK, Big5, Shift_JIS, EUC-JP, EUC-KR
• Special Encodings: CESU-8, UCS-2, Binary, Base64, Hex