From 8cef8374413d66289a95223ac10816c6c505a9bb Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Thu, 14 Aug 2025 19:28:44 +0100
Subject: [PATCH 01/33] add jsDocs

---
 lib/index.d.ts | 28 +++++++++++++++++++++-------
 1 file changed, 21 insertions(+), 7 deletions(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index 6cdada8a..c991b15a 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -1,32 +1,46 @@
 /*---------------------------------------------------------------------------------------------
- *  Copyright (c) Microsoft Corporation. All rights reserved.
- *  Licensed under the MIT License.
- *  REQUIREMENT: This definition is dependent on the @types/node definition.
- *  Install with `npm install @types/node --save-dev`
+ * REQUIREMENT: This definition is dependent on the @types/node definition.
+ *
+ * This file provides detailed typings for all encodings supported by iconv-lite,
+ * based on the official wiki:
+ * https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings
  *--------------------------------------------------------------------------------------------*/
 
 declare module 'iconv-lite' {
-	// Basic API
+  //   --- Basic API ---
+
+  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
 	export function decode(buffer: Buffer | Uint8Array, encoding: string, options?: Options): string;
 
+  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
 	export function encode(content: string, encoding: string, options?: Options): Buffer;
 
+  /** Checks if a given encoding is supported by `iconv-lite`. */
 	export function encodingExists(encoding: string): boolean;
 
-	// Stream API
+  //   --- Stream API ---
+
+  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
 	export function decodeStream(encoding: string, options?: Options): NodeJS.ReadWriteStream;
 
+  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
 	export function encodeStream(encoding: string, options?: Options): NodeJS.ReadWriteStream;
 
-	// Low-level stream APIs
+  //   --- Low-level stream APIs ---
+
+  /** Creates and returns a low-level encoder stream. */
 	export function getEncoder(encoding: string, options?: Options): EncoderStream;
 
+  /** Creates and returns a low-level decoder stream. */
 	export function getDecoder(encoding: string, options?: Options): DecoderStream;
 }
 
 export interface Options {
+    /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
     stripBOM?: boolean;
+    /** Adds a byte order mark (BOM) to the output, when encoding. @default false */
     addBOM?: boolean;
+    /** Overrides the default endianness for `UTF-16` and `UTF-32` decodings or `UTF-32` encoding. */
     defaultEncoding?: string;
 }
 

From f74482d303c9ff461d3af0fc3c778c746e71925d Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Thu, 14 Aug 2025 19:31:30 +0100
Subject: [PATCH 02/33] separate encoding `Options` to `DecodeOptions` and
 `EncodeOptions`

---
 lib/index.d.ts | 31 ++++++++++++++++++-------------
 1 file changed, 18 insertions(+), 13 deletions(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index c991b15a..81c6b9b0 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -10,10 +10,10 @@ declare module 'iconv-lite' {
   //   --- Basic API ---
 
   /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-	export function decode(buffer: Buffer | Uint8Array, encoding: string, options?: Options): string;
+	export function decode(buffer: Buffer | Uint8Array, encoding: string, options?: DecodeOptions): string;
 
   /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-	export function encode(content: string, encoding: string, options?: Options): Buffer;
+	export function encode(content: string, encoding: string, options?: EncodeOptions): Buffer;
 
   /** Checks if a given encoding is supported by `iconv-lite`. */
 	export function encodingExists(encoding: string): boolean;
@@ -21,27 +21,32 @@ declare module 'iconv-lite' {
   //   --- Stream API ---
 
   /** Creates a stream that decodes binary data from a given `encoding` into strings. */
-	export function decodeStream(encoding: string, options?: Options): NodeJS.ReadWriteStream;
+	export function decodeStream(encoding: string, options?: DecodeOptions): NodeJS.ReadWriteStream;
 
   /** Creates a stream that encodes strings into binary data in a given `encoding`. */
-	export function encodeStream(encoding: string, options?: Options): NodeJS.ReadWriteStream;
+	export function encodeStream(encoding: string, options?: EncodeOptions): NodeJS.ReadWriteStream;
 
   //   --- Low-level stream APIs ---
 
   /** Creates and returns a low-level encoder stream. */
-	export function getEncoder(encoding: string, options?: Options): EncoderStream;
+	export function getEncoder(encoding: string, options?: EncodeOptions): EncoderStream;
 
   /** Creates and returns a low-level decoder stream. */
-	export function getDecoder(encoding: string, options?: Options): DecoderStream;
+	export function getDecoder(encoding: string, options?: DecodeOptions): DecoderStream;
 }
 
-export interface Options {
-    /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
-    stripBOM?: boolean;
-    /** Adds a byte order mark (BOM) to the output, when encoding. @default false */
-    addBOM?: boolean;
-    /** Overrides the default endianness for `UTF-16` and `UTF-32` decodings or `UTF-32` encoding. */
-    defaultEncoding?: string;
+export interface DecodeOptions {
+  /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
+  stripBOM?: boolean;
+  /** Overrides the default endianness for `UTF-16` and `UTF-32` decodings. */
+  defaultEncoding?: "utf16be" | "utf32be";
+}
+
+export interface EncodeOptions {
+  /** Adds a byte order mark (BOM) to the output, when encoding. @default false */
+  addBOM?: boolean;
+  /** Overrides the default endianness for `UTF-32` encoding. */
+  defaultEncoding?: "utf32be";
 }
 
 export interface EncoderStream {

From 2cc3a01e8746821e452fe29707caeafd9cde816d Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Thu, 14 Aug 2025 19:43:02 +0100
Subject: [PATCH 03/33] add typedefs for all supported encodings

---
 lib/index.d.ts | 171 +++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 158 insertions(+), 13 deletions(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index 81c6b9b0..3adcdedd 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -2,37 +2,182 @@
  * REQUIREMENT: This definition is dependent on the @types/node definition.
  *
  * This file provides detailed typings for all encodings supported by iconv-lite,
- * based on the official wiki:
+ * based on the official wiki and source code:
  * https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings
  *--------------------------------------------------------------------------------------------*/
 
-declare module 'iconv-lite' {
+// --- Unicode Encodings ---
+type UnicodeEncoding =
+  | "UTF7"
+  | "UTF7-IMAP"
+  | "UTF-16BE"
+  | "UTF-16" // With BOM
+  | "UCS-4"
+  | "UTF-32" // With BOM, alias for UCS-4
+  | "UTF-32LE"
+  | "UTF-32BE";
+
+// --- Single-byte Encodings ---
+
+// Helper type for Windows codepage numbers
+type WindowsCodepageNumber = "874" | "1250" | "1251" | "1252" | "1253" | "1254" | "1255" | "1256" | "1257" | "1258";
+
+// Windows codepages with aliases (winXXX, cpXXX, XXX)
+type WindowsCodepage =
+  | WindowsCodepageNumber
+  | `windows-${WindowsCodepageNumber}`
+  | `win${WindowsCodepageNumber}`
+  | `cp${WindowsCodepageNumber}`;
+
+// Helper type for ISO codepage numbers
+type ISOCodepageNumber = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "13" | "14" | "15" | "16";
+type ISOCodepageAliasNumber =
+  | "28591"
+  | "28592"
+  | "28593"
+  | "28594"
+  | "28595"
+  | "28596"
+  | "28597"
+  | "28598"
+  | "28599"
+  | "28600"
+  | "28601"
+  | "28603"
+  | "28604"
+  | "28605"
+  | "28606";
+
+// ISO codepages with aliases
+type ISOCodepage = `iso-8859-${ISOCodepageNumber}` | ISOCodepageAliasNumber | `cp${ISOCodepageAliasNumber}`;
+
+// Helper type for IBM codepage numbers
+type IBMCodepageNumber =
+  | "437"
+  | "737"
+  | "775"
+  | "850"
+  | "852"
+  | "855"
+  | "856"
+  | "857"
+  | "858"
+  | "860"
+  | "861"
+  | "862"
+  | "863"
+  | "864"
+  | "865"
+  | "866"
+  | "869"
+  | "922"
+  | "1046"
+  | "1124"
+  | "1125"
+  | "1129"
+  | "1133"
+  | "1161"
+  | "1162"
+  | "1163";
+
+// IBM codepages with aliases (ibmXXX, csibmXXX, XXX)
+type IBMCodepage =
+  | IBMCodepageNumber
+  | `CP${IBMCodepageNumber}`
+  | `ibm${IBMCodepageNumber}`
+  | `csibm${IBMCodepageNumber}`;
+
+// Mac codepages
+type MacCodepage =
+  | "macCroatian"
+  | "macCyrillic"
+  | "macGreek"
+  | "macIceland"
+  | "macRoman"
+  | "macRomania"
+  | "macThai"
+  | "macTurkish"
+  | "macUkraine"
+  | "macintosh"; // Alias for macRoman
+
+// KOI8 codepages
+type KOI8Codepage = "KOI8-R" | "KOI8-U" | "KOI8-RU" | "KOI8-T";
+
+// Miscellaneous single-byte encodings
+type MiscellaneousSingleByte =
+  | "ARMSCII-8"
+  | "RK1048"
+  | "TCVN"
+  | "GEORGIAN-ACADEMY"
+  | "GEORGIAN-PS"
+  | "PT154"
+  | "VISCII"
+  | "ISO646-CN"
+  | "ISO646-JP"
+  | "HP-ROMAN8"
+  | "TIS620";
+
+type SingleByteEncoding =
+  | WindowsCodepage
+  | ISOCodepage
+  | IBMCodepage
+  | MacCodepage
+  | KOI8Codepage
+  | MiscellaneousSingleByte;
+
+// --- Multi-byte Encodings ---
+
+// Japanese
+type JapaneseEncoding = "Shift_JIS" | "Windows-31j" | "Windows932" | "EUC-JP";
+
+// Chinese
+type ChineseEncoding = "GB2312" | "GBK" | "GB18030" | "Windows936" | "EUC-CN";
+
+// Korean
+type KoreanEncoding = "KS_C_5601" | "Windows949" | "EUC-KR";
+
+// Taiwan/Hong Kong
+type TaiwanHongKongEncoding = "Big5" | "Big5-HKSCS" | "Windows950";
+
+type MultiByteEncoding = JapaneseEncoding | ChineseEncoding | KoreanEncoding | TaiwanHongKongEncoding;
+
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+
+/** A union of all supported encoding strings in `iconv-lite`. */
+export type SupportedEncoding =
+  | NodeJS.BufferEncoding
+  | UnicodeEncoding
+  | SingleByteEncoding
+  | MultiByteEncoding
+  | (string & {});
+
+declare module "iconv-lite" {
   //   --- Basic API ---
 
   /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-	export function decode(buffer: Buffer | Uint8Array, encoding: string, options?: DecodeOptions): string;
+  export function decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
 
   /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-	export function encode(content: string, encoding: string, options?: EncodeOptions): Buffer;
+  export function encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
 
   /** Checks if a given encoding is supported by `iconv-lite`. */
-	export function encodingExists(encoding: string): boolean;
+  export function encodingExists(encoding: string): encoding is SupportedEncoding;
 
   //   --- Stream API ---
 
   /** Creates a stream that decodes binary data from a given `encoding` into strings. */
-	export function decodeStream(encoding: string, options?: DecodeOptions): NodeJS.ReadWriteStream;
+  export function decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
 
   /** Creates a stream that encodes strings into binary data in a given `encoding`. */
-	export function encodeStream(encoding: string, options?: EncodeOptions): NodeJS.ReadWriteStream;
+  export function encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
 
   //   --- Low-level stream APIs ---
 
   /** Creates and returns a low-level encoder stream. */
-	export function getEncoder(encoding: string, options?: EncodeOptions): EncoderStream;
+  export function getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
 
   /** Creates and returns a low-level decoder stream. */
-	export function getDecoder(encoding: string, options?: DecodeOptions): DecoderStream;
+  export function getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
 }
 
 export interface DecodeOptions {
@@ -50,11 +195,11 @@ export interface EncodeOptions {
 }
 
 export interface EncoderStream {
-	write(str: string): Buffer;
-	end(): Buffer | undefined;
+  write(str: string): Buffer;
+  end(): Buffer | undefined;
 }
 
 export interface DecoderStream {
-	write(buf: Buffer): string;
-	end(): string | undefined;
+  write(buf: Buffer): string;
+  end(): string | undefined;
 }

From 318acccf84ed3d7c2737b7ef8b14f0c7cba97941 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Thu, 14 Aug 2025 21:07:36 +0100
Subject: [PATCH 04/33] add more exhaustive lists of supported encodings

---
 lib/index.d.ts | 265 +++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 226 insertions(+), 39 deletions(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index 3adcdedd..dce4aef4 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -8,26 +8,35 @@
 
 // --- Unicode Encodings ---
 type UnicodeEncoding =
-  | "UTF7"
-  | "UTF7-IMAP"
-  | "UTF-16BE"
-  | "UTF-16" // With BOM
-  | "UCS-4"
-  | "UTF-32" // With BOM, alias for UCS-4
-  | "UTF-32LE"
-  | "UTF-32BE";
+  | "utf7"
+  | "utf7imap"
+  | "utf16be"
+  | "utf16" // With BOM
+  | "ucs4"
+  | "utf32" // With BOM, alias for UCS-4
+  | "utf32le"
+  | "utf32be";
 
 // --- Single-byte Encodings ---
 
 // Helper type for Windows codepage numbers
 type WindowsCodepageNumber = "874" | "1250" | "1251" | "1252" | "1253" | "1254" | "1255" | "1256" | "1257" | "1258";
 
-// Windows codepages with aliases (winXXX, cpXXX, XXX)
+// Windows codepages with aliases (windows-XXX, winXXX, cpXXX, XXX)
 type WindowsCodepage =
   | WindowsCodepageNumber
   | `windows-${WindowsCodepageNumber}`
+  | `windows${WindowsCodepageNumber}`
   | `win${WindowsCodepageNumber}`
-  | `cp${WindowsCodepageNumber}`;
+  | `cp${WindowsCodepageNumber}`
+  | "msee"
+  | "mscyrl"
+  | "msansi"
+  | "msgreek"
+  | "msturk"
+  | "mshebr"
+  | "msarab"
+  | "winbaltrim";
 
 // Helper type for ISO codepage numbers
 type ISOCodepageNumber = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "13" | "14" | "15" | "16";
@@ -49,13 +58,83 @@ type ISOCodepageAliasNumber =
   | "28606";
 
 // ISO codepages with aliases
-type ISOCodepage = `iso-8859-${ISOCodepageNumber}` | ISOCodepageAliasNumber | `cp${ISOCodepageAliasNumber}`;
+type ISOCodepage =
+  | `iso-8859-${ISOCodepageNumber}`
+  | `iso8859${ISOCodepageNumber}`
+  | ISOCodepageAliasNumber
+  | `cp${ISOCodepageAliasNumber}`
+  | "latin1"
+  | "latin2"
+  | "latin3"
+  | "latin4"
+  | "latin5"
+  | "latin6"
+  | "latin7"
+  | "latin8"
+  | "latin9"
+  | "latin10"
+  | "csisolatin1"
+  | "csisolatin2"
+  | "csisolatin3"
+  | "csisolatin4"
+  | "csisolatincyrillic"
+  | "csisolatinarabic"
+  | "csisolatingreek"
+  | "csisolatinhebrew"
+  | "csisolatin5"
+  | "csisolatin6"
+  | "l1"
+  | "l2"
+  | "l3"
+  | "l4"
+  | "l5"
+  | "l6"
+  | "l7"
+  | "l8"
+  | "l9"
+  | "l10"
+  | "isoir100"
+  | "isoir101"
+  | "isoir109"
+  | "isoir110"
+  | "isoir144"
+  | "isoir127"
+  | "isoir126"
+  | "isoir138"
+  | "isoir148"
+  | "isoir157"
+  | "isoir179"
+  | "isoir199"
+  | "isoir203"
+  | "isoir226"
+  | "cp819"
+  | "ibm819"
+  | "cyrillic"
+  | "arabic"
+  | "arabic8"
+  | "ecma114"
+  | "asmo708"
+  | "greek"
+  | "greek8"
+  | "ecma118"
+  | "elot928"
+  | "hebrew"
+  | "hebrew8"
+  | "turkish"
+  | "turkish8"
+  | "thai"
+  | "thai8"
+  | "celtic"
+  | "celtic8"
+  | "isoceltic";
 
 // Helper type for IBM codepage numbers
 type IBMCodepageNumber =
   | "437"
+  | "720"
   | "737"
   | "775"
+  | "808"
   | "850"
   | "852"
   | "855"
@@ -83,39 +162,99 @@ type IBMCodepageNumber =
 // IBM codepages with aliases (ibmXXX, csibmXXX, XXX)
 type IBMCodepage =
   | IBMCodepageNumber
-  | `CP${IBMCodepageNumber}`
+  | `cp${IBMCodepageNumber}`
   | `ibm${IBMCodepageNumber}`
-  | `csibm${IBMCodepageNumber}`;
+  | `csibm${IBMCodepageNumber}`
+  | "cspc8codepage437"
+  | "cspc775baltic"
+  | "cspc850multilingual"
+  | "cspcp852"
+  | "cspc862latinhebrew"
+  | "cpgr";
 
 // Mac codepages
 type MacCodepage =
-  | "macCroatian"
-  | "macCyrillic"
-  | "macGreek"
-  | "macIceland"
-  | "macRoman"
-  | "macRomania"
-  | "macThai"
-  | "macTurkish"
-  | "macUkraine"
-  | "macintosh"; // Alias for macRoman
+  | "maccroatian"
+  | "maccyrillic"
+  | "macgreek"
+  | "maciceland"
+  | "macroman"
+  | "macromania"
+  | "macthai"
+  | "macturkish"
+  | "macukraine"
+  | "maccenteuro"
+  | "10000"
+  | "10006"
+  | "10007"
+  | "10029"
+  | "10079"
+  | "10081";
 
 // KOI8 codepages
-type KOI8Codepage = "KOI8-R" | "KOI8-U" | "KOI8-RU" | "KOI8-T";
+type KOI8Codepage =
+  | "koi8r"
+  | "koi8u"
+  | "koi8ru"
+  | "koi8t"
+  | "cp20866"
+  | "20866"
+  | "ibm878"
+  | "cskoi8r"
+  | "cp21866"
+  | "21866"
+  | "ibm1168";
 
 // Miscellaneous single-byte encodings
 type MiscellaneousSingleByte =
-  | "ARMSCII-8"
-  | "RK1048"
-  | "TCVN"
-  | "GEORGIAN-ACADEMY"
-  | "GEORGIAN-PS"
-  | "PT154"
-  | "VISCII"
-  | "ISO646-CN"
-  | "ISO646-JP"
-  | "HP-ROMAN8"
-  | "TIS620";
+  | "armscii8"
+  | "rk1048"
+  | "strk10482002"
+  | "tcvn"
+  | "tcvn5712"
+  | "tcvn57121"
+  | "georgianacademy"
+  | "georgianps"
+  | "pt154"
+  | "viscii"
+  | "iso646cn"
+  | "gb198880"
+  | "cn"
+  | "isoir57"
+  | "iso646jp"
+  | "isoir14"
+  | "csiso14jisc6220ro"
+  | "jisc62201969ro"
+  | "jp"
+  | "hproman8"
+  | "cshproman8"
+  | "r8"
+  | "roman8"
+  | "xroman8"
+  | "ibm1051"
+  | "macintosh"
+  | "mac"
+  | "csmacintosh"
+  | "ascii"
+  | "ascii8bit"
+  | "usascii"
+  | "ansix34"
+  | "ansix341968"
+  | "ansix341986"
+  | "csascii"
+  | "cp367"
+  | "ibm367"
+  | "isoir6"
+  | "iso646us"
+  | "iso646irv"
+  | "us"
+  | "tis620"
+  | "isoir166"
+  | "tis6200"
+  | "tis62025291"
+  | "tis62025330"
+  | "cp720"
+  | "mik";
 
 type SingleByteEncoding =
   | WindowsCodepage
@@ -128,16 +267,64 @@ type SingleByteEncoding =
 // --- Multi-byte Encodings ---
 
 // Japanese
-type JapaneseEncoding = "Shift_JIS" | "Windows-31j" | "Windows932" | "EUC-JP";
+type JapaneseEncoding =
+  | "shiftjis"
+  | "csshiftjis"
+  | "mskanji"
+  | "sjis"
+  | "windows31j"
+  | "ms31j"
+  | "xsjis"
+  | "windows932"
+  | "ms932"
+  | "932"
+  | "cp932"
+  | "eucjp";
 
 // Chinese
-type ChineseEncoding = "GB2312" | "GBK" | "GB18030" | "Windows936" | "EUC-CN";
+type ChineseEncoding =
+  | "gb2312"
+  | "gb231280"
+  | "gb23121980"
+  | "csgb2312"
+  | "csiso58gb231280"
+  | "euccn"
+  | "windows936"
+  | "ms936"
+  | "936"
+  | "cp936"
+  | "gbk"
+  | "xgbk"
+  | "isoir58"
+  | "gb18030"
+  | "chinese";
 
 // Korean
-type KoreanEncoding = "KS_C_5601" | "Windows949" | "EUC-KR";
+type KoreanEncoding =
+  | "windows949"
+  | "ms949"
+  | "949"
+  | "cp949"
+  | "cseuckr"
+  | "csksc56011987"
+  | "euckr"
+  | "isoir149"
+  | "korean"
+  | "ksc56011987"
+  | "ksc56011989"
+  | "ksc5601";
 
 // Taiwan/Hong Kong
-type TaiwanHongKongEncoding = "Big5" | "Big5-HKSCS" | "Windows950";
+type TaiwanHongKongEncoding =
+  | "windows950"
+  | "ms950"
+  | "950"
+  | "cp950"
+  | "big5"
+  | "big5hkscs"
+  | "cnbig5"
+  | "csbig5"
+  | "xxbig5";
 
 type MultiByteEncoding = JapaneseEncoding | ChineseEncoding | KoreanEncoding | TaiwanHongKongEncoding;
 

From 55dd479c256c24034577e0f38a79bd1002356db4 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Thu, 14 Aug 2025 21:40:08 +0100
Subject: [PATCH 05/33] add script to auto-generate `iconv-lite` typedefs

---
 .npmignore                  |   3 +-
 lib/index.d.ts              | 615 ++++++++++++++++++++----------------
 scripts/generate-typings.js |  77 +++++
 scripts/template-index.d.ts |  63 ++++
 4 files changed, 486 insertions(+), 272 deletions(-)
 create mode 100644 scripts/generate-typings.js
 create mode 100644 scripts/template-index.d.ts

diff --git a/.npmignore b/.npmignore
index 12fca491..19164bf0 100644
--- a/.npmignore
+++ b/.npmignore
@@ -6,4 +6,5 @@ wiki
 coverage
 .github
 .idea
-performance
\ No newline at end of file
+performance
+scripts
diff --git a/lib/index.d.ts b/lib/index.d.ts
index dce4aef4..7796f1f3 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -6,41 +6,33 @@
  * https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings
  *--------------------------------------------------------------------------------------------*/
 
-// --- Unicode Encodings ---
-type UnicodeEncoding =
-  | "utf7"
-  | "utf7imap"
-  | "utf16be"
-  | "utf16" // With BOM
-  | "ucs4"
-  | "utf32" // With BOM, alias for UCS-4
-  | "utf32le"
-  | "utf32be";
-
-// --- Single-byte Encodings ---
-
-// Helper type for Windows codepage numbers
-type WindowsCodepageNumber = "874" | "1250" | "1251" | "1252" | "1253" | "1254" | "1255" | "1256" | "1257" | "1258";
-
-// Windows codepages with aliases (windows-XXX, winXXX, cpXXX, XXX)
-type WindowsCodepage =
-  | WindowsCodepageNumber
-  | `windows-${WindowsCodepageNumber}`
-  | `windows${WindowsCodepageNumber}`
-  | `win${WindowsCodepageNumber}`
-  | `cp${WindowsCodepageNumber}`
-  | "msee"
-  | "mscyrl"
-  | "msansi"
-  | "msgreek"
-  | "msturk"
-  | "mshebr"
-  | "msarab"
-  | "winbaltrim";
-
-// Helper type for ISO codepage numbers
-type ISOCodepageNumber = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "10" | "11" | "13" | "14" | "15" | "16";
-type ISOCodepageAliasNumber =
+/** A union of all supported encoding strings in `iconv-lite`. */
+export type SupportedEncoding =
+  | "10000"
+  | "10006"
+  | "10007"
+  | "10029"
+  | "10079"
+  | "10081"
+  | "1046"
+  | "1124"
+  | "1125"
+  | "1129"
+  | "1133"
+  | "1161"
+  | "1162"
+  | "1163"
+  | "1250"
+  | "1251"
+  | "1252"
+  | "1253"
+  | "1254"
+  | "1255"
+  | "1256"
+  | "1257"
+  | "1258"
+  | "20866"
+  | "21866"
   | "28591"
   | "28592"
   | "28593"
@@ -55,83 +47,8 @@ type ISOCodepageAliasNumber =
   | "28603"
   | "28604"
   | "28605"
-  | "28606";
-
-// ISO codepages with aliases
-type ISOCodepage =
-  | `iso-8859-${ISOCodepageNumber}`
-  | `iso8859${ISOCodepageNumber}`
-  | ISOCodepageAliasNumber
-  | `cp${ISOCodepageAliasNumber}`
-  | "latin1"
-  | "latin2"
-  | "latin3"
-  | "latin4"
-  | "latin5"
-  | "latin6"
-  | "latin7"
-  | "latin8"
-  | "latin9"
-  | "latin10"
-  | "csisolatin1"
-  | "csisolatin2"
-  | "csisolatin3"
-  | "csisolatin4"
-  | "csisolatincyrillic"
-  | "csisolatinarabic"
-  | "csisolatingreek"
-  | "csisolatinhebrew"
-  | "csisolatin5"
-  | "csisolatin6"
-  | "l1"
-  | "l2"
-  | "l3"
-  | "l4"
-  | "l5"
-  | "l6"
-  | "l7"
-  | "l8"
-  | "l9"
-  | "l10"
-  | "isoir100"
-  | "isoir101"
-  | "isoir109"
-  | "isoir110"
-  | "isoir144"
-  | "isoir127"
-  | "isoir126"
-  | "isoir138"
-  | "isoir148"
-  | "isoir157"
-  | "isoir179"
-  | "isoir199"
-  | "isoir203"
-  | "isoir226"
-  | "cp819"
-  | "ibm819"
-  | "cyrillic"
-  | "arabic"
-  | "arabic8"
-  | "ecma114"
-  | "asmo708"
-  | "greek"
-  | "greek8"
-  | "ecma118"
-  | "elot928"
-  | "hebrew"
-  | "hebrew8"
-  | "turkish"
-  | "turkish8"
-  | "thai"
-  | "thai8"
-  | "celtic"
-  | "celtic8"
-  | "isoceltic";
-
-// Helper type for IBM codepage numbers
-type IBMCodepageNumber =
+  | "28606"
   | "437"
-  | "720"
   | "737"
   | "775"
   | "808"
@@ -149,193 +66,349 @@ type IBMCodepageNumber =
   | "865"
   | "866"
   | "869"
+  | "874"
   | "922"
-  | "1046"
-  | "1124"
-  | "1125"
-  | "1129"
-  | "1133"
-  | "1161"
-  | "1162"
-  | "1163";
-
-// IBM codepages with aliases (ibmXXX, csibmXXX, XXX)
-type IBMCodepage =
-  | IBMCodepageNumber
-  | `cp${IBMCodepageNumber}`
-  | `ibm${IBMCodepageNumber}`
-  | `csibm${IBMCodepageNumber}`
-  | "cspc8codepage437"
+  | "932"
+  | "936"
+  | "949"
+  | "950"
+  | "ansix34"
+  | "ansix341968"
+  | "ansix341986"
+  | "arabic"
+  | "arabic8"
+  | "armscii8"
+  | "ascii"
+  | "ascii8bit"
+  | "asmo708"
+  | "base64"
+  | "big5"
+  | "big5hkscs"
+  | "binary"
+  | "celtic"
+  | "celtic8"
+  | "cesu8"
+  | "chinese"
+  | "cn"
+  | "cnbig5"
+  | "cp1046"
+  | "cp1124"
+  | "cp1125"
+  | "cp1129"
+  | "cp1133"
+  | "cp1161"
+  | "cp1162"
+  | "cp1163"
+  | "cp1250"
+  | "cp1251"
+  | "cp1252"
+  | "cp1253"
+  | "cp1254"
+  | "cp1255"
+  | "cp1256"
+  | "cp1257"
+  | "cp1258"
+  | "cp20866"
+  | "cp21866"
+  | "cp28591"
+  | "cp28592"
+  | "cp28593"
+  | "cp28594"
+  | "cp28595"
+  | "cp28596"
+  | "cp28597"
+  | "cp28598"
+  | "cp28599"
+  | "cp28600"
+  | "cp28601"
+  | "cp28603"
+  | "cp28604"
+  | "cp28605"
+  | "cp28606"
+  | "cp367"
+  | "cp437"
+  | "cp720"
+  | "cp737"
+  | "cp775"
+  | "cp808"
+  | "cp819"
+  | "cp850"
+  | "cp852"
+  | "cp855"
+  | "cp856"
+  | "cp857"
+  | "cp858"
+  | "cp860"
+  | "cp861"
+  | "cp862"
+  | "cp863"
+  | "cp864"
+  | "cp865"
+  | "cp866"
+  | "cp869"
+  | "cp874"
+  | "cp922"
+  | "cp932"
+  | "cp936"
+  | "cp949"
+  | "cp950"
+  | "cpgr"
+  | "csascii"
+  | "csbig5"
+  | "cseuckr"
+  | "csgb2312"
+  | "cshproman8"
+  | "csibm1046"
+  | "csibm1124"
+  | "csibm1125"
+  | "csibm1129"
+  | "csibm1133"
+  | "csibm1161"
+  | "csibm1162"
+  | "csibm1163"
+  | "csibm437"
+  | "csibm737"
+  | "csibm775"
+  | "csibm850"
+  | "csibm852"
+  | "csibm855"
+  | "csibm856"
+  | "csibm857"
+  | "csibm858"
+  | "csibm860"
+  | "csibm861"
+  | "csibm862"
+  | "csibm863"
+  | "csibm864"
+  | "csibm865"
+  | "csibm866"
+  | "csibm869"
+  | "csibm922"
+  | "csiso14jisc6220ro"
+  | "csiso58gb231280"
+  | "csisolatin1"
+  | "csisolatin2"
+  | "csisolatin3"
+  | "csisolatin4"
+  | "csisolatin5"
+  | "csisolatin6"
+  | "csisolatinarabic"
+  | "csisolatincyrillic"
+  | "csisolatingreek"
+  | "csisolatinhebrew"
+  | "cskoi8r"
+  | "csksc56011987"
+  | "csmacintosh"
   | "cspc775baltic"
   | "cspc850multilingual"
-  | "cspcp852"
   | "cspc862latinhebrew"
-  | "cpgr";
-
-// Mac codepages
-type MacCodepage =
+  | "cspc8codepage437"
+  | "cspcp852"
+  | "csshiftjis"
+  | "cyrillic"
+  | "ecma114"
+  | "ecma118"
+  | "elot928"
+  | "euccn"
+  | "eucjp"
+  | "euckr"
+  | "gb18030"
+  | "gb198880"
+  | "gb2312"
+  | "gb23121980"
+  | "gb231280"
+  | "gbk"
+  | "georgianacademy"
+  | "georgianps"
+  | "greek"
+  | "greek8"
+  | "hebrew"
+  | "hebrew8"
+  | "hex"
+  | "hproman8"
+  | "ibm1046"
+  | "ibm1051"
+  | "ibm1124"
+  | "ibm1125"
+  | "ibm1129"
+  | "ibm1133"
+  | "ibm1161"
+  | "ibm1162"
+  | "ibm1163"
+  | "ibm1168"
+  | "ibm367"
+  | "ibm437"
+  | "ibm737"
+  | "ibm775"
+  | "ibm808"
+  | "ibm819"
+  | "ibm850"
+  | "ibm852"
+  | "ibm855"
+  | "ibm856"
+  | "ibm857"
+  | "ibm858"
+  | "ibm860"
+  | "ibm861"
+  | "ibm862"
+  | "ibm863"
+  | "ibm864"
+  | "ibm865"
+  | "ibm866"
+  | "ibm869"
+  | "ibm878"
+  | "ibm922"
+  | "iso646cn"
+  | "iso646irv"
+  | "iso646jp"
+  | "iso646us"
+  | "iso88591"
+  | "iso885910"
+  | "iso885911"
+  | "iso885913"
+  | "iso885914"
+  | "iso885915"
+  | "iso885916"
+  | "iso88592"
+  | "iso88593"
+  | "iso88594"
+  | "iso88595"
+  | "iso88596"
+  | "iso88597"
+  | "iso88598"
+  | "iso88599"
+  | "isoceltic"
+  | "isoir100"
+  | "isoir101"
+  | "isoir109"
+  | "isoir110"
+  | "isoir126"
+  | "isoir127"
+  | "isoir138"
+  | "isoir14"
+  | "isoir144"
+  | "isoir148"
+  | "isoir149"
+  | "isoir157"
+  | "isoir166"
+  | "isoir179"
+  | "isoir199"
+  | "isoir203"
+  | "isoir226"
+  | "isoir57"
+  | "isoir58"
+  | "isoir6"
+  | "jisc62201969ro"
+  | "jp"
+  | "koi8r"
+  | "koi8ru"
+  | "koi8t"
+  | "koi8u"
+  | "korean"
+  | "ksc5601"
+  | "ksc56011987"
+  | "ksc56011989"
+  | "l1"
+  | "l10"
+  | "l2"
+  | "l3"
+  | "l4"
+  | "l5"
+  | "l6"
+  | "l7"
+  | "l8"
+  | "l9"
+  | "latin1"
+  | "latin10"
+  | "latin2"
+  | "latin3"
+  | "latin4"
+  | "latin5"
+  | "latin6"
+  | "latin7"
+  | "latin8"
+  | "latin9"
+  | "mac"
+  | "maccenteuro"
   | "maccroatian"
   | "maccyrillic"
   | "macgreek"
   | "maciceland"
+  | "macintosh"
   | "macroman"
   | "macromania"
   | "macthai"
   | "macturkish"
   | "macukraine"
-  | "maccenteuro"
-  | "10000"
-  | "10006"
-  | "10007"
-  | "10029"
-  | "10079"
-  | "10081";
-
-// KOI8 codepages
-type KOI8Codepage =
-  | "koi8r"
-  | "koi8u"
-  | "koi8ru"
-  | "koi8t"
-  | "cp20866"
-  | "20866"
-  | "ibm878"
-  | "cskoi8r"
-  | "cp21866"
-  | "21866"
-  | "ibm1168";
-
-// Miscellaneous single-byte encodings
-type MiscellaneousSingleByte =
-  | "armscii8"
+  | "mik"
+  | "ms31j"
+  | "ms932"
+  | "ms936"
+  | "ms949"
+  | "ms950"
+  | "msansi"
+  | "msarab"
+  | "mscyrl"
+  | "msee"
+  | "msgreek"
+  | "mshebr"
+  | "mskanji"
+  | "msturk"
+  | "pt154"
+  | "r8"
   | "rk1048"
+  | "roman8"
+  | "shiftjis"
+  | "sjis"
   | "strk10482002"
   | "tcvn"
   | "tcvn5712"
   | "tcvn57121"
-  | "georgianacademy"
-  | "georgianps"
-  | "pt154"
-  | "viscii"
-  | "iso646cn"
-  | "gb198880"
-  | "cn"
-  | "isoir57"
-  | "iso646jp"
-  | "isoir14"
-  | "csiso14jisc6220ro"
-  | "jisc62201969ro"
-  | "jp"
-  | "hproman8"
-  | "cshproman8"
-  | "r8"
-  | "roman8"
-  | "xroman8"
-  | "ibm1051"
-  | "macintosh"
-  | "mac"
-  | "csmacintosh"
-  | "ascii"
-  | "ascii8bit"
-  | "usascii"
-  | "ansix34"
-  | "ansix341968"
-  | "ansix341986"
-  | "csascii"
-  | "cp367"
-  | "ibm367"
-  | "isoir6"
-  | "iso646us"
-  | "iso646irv"
-  | "us"
+  | "thai"
+  | "thai8"
   | "tis620"
-  | "isoir166"
   | "tis6200"
   | "tis62025291"
   | "tis62025330"
-  | "cp720"
-  | "mik";
-
-type SingleByteEncoding =
-  | WindowsCodepage
-  | ISOCodepage
-  | IBMCodepage
-  | MacCodepage
-  | KOI8Codepage
-  | MiscellaneousSingleByte;
-
-// --- Multi-byte Encodings ---
-
-// Japanese
-type JapaneseEncoding =
-  | "shiftjis"
-  | "csshiftjis"
-  | "mskanji"
-  | "sjis"
+  | "turkish"
+  | "turkish8"
+  | "ucs2"
+  | "unicode11utf8"
+  | "us"
+  | "usascii"
+  | "utf16le"
+  | "utf8"
+  | "viscii"
+  | "win1250"
+  | "win1251"
+  | "win1252"
+  | "win1253"
+  | "win1254"
+  | "win1255"
+  | "win1256"
+  | "win1257"
+  | "win1258"
+  | "win874"
+  | "winbaltrim"
+  | "windows1250"
+  | "windows1251"
+  | "windows1252"
+  | "windows1253"
+  | "windows1254"
+  | "windows1255"
+  | "windows1256"
+  | "windows1257"
+  | "windows1258"
   | "windows31j"
-  | "ms31j"
-  | "xsjis"
+  | "windows874"
   | "windows932"
-  | "ms932"
-  | "932"
-  | "cp932"
-  | "eucjp";
-
-// Chinese
-type ChineseEncoding =
-  | "gb2312"
-  | "gb231280"
-  | "gb23121980"
-  | "csgb2312"
-  | "csiso58gb231280"
-  | "euccn"
   | "windows936"
-  | "ms936"
-  | "936"
-  | "cp936"
-  | "gbk"
-  | "xgbk"
-  | "isoir58"
-  | "gb18030"
-  | "chinese";
-
-// Korean
-type KoreanEncoding =
   | "windows949"
-  | "ms949"
-  | "949"
-  | "cp949"
-  | "cseuckr"
-  | "csksc56011987"
-  | "euckr"
-  | "isoir149"
-  | "korean"
-  | "ksc56011987"
-  | "ksc56011989"
-  | "ksc5601";
-
-// Taiwan/Hong Kong
-type TaiwanHongKongEncoding =
   | "windows950"
-  | "ms950"
-  | "950"
-  | "cp950"
-  | "big5"
-  | "big5hkscs"
-  | "cnbig5"
-  | "csbig5"
-  | "xxbig5";
-
-type MultiByteEncoding = JapaneseEncoding | ChineseEncoding | KoreanEncoding | TaiwanHongKongEncoding;
-
-// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-
-/** A union of all supported encoding strings in `iconv-lite`. */
-export type SupportedEncoding =
-  | NodeJS.BufferEncoding
-  | UnicodeEncoding
-  | SingleByteEncoding
-  | MultiByteEncoding
+  | "xgbk"
+  | "xroman8"
+  | "xsjis"
+  | "xxbig5"
   | (string & {});
 
 declare module "iconv-lite" {
diff --git a/scripts/generate-typings.js b/scripts/generate-typings.js
new file mode 100644
index 00000000..f372a86e
--- /dev/null
+++ b/scripts/generate-typings.js
@@ -0,0 +1,77 @@
+const fs = require("fs");
+const path = require("path");
+
+function getEncodingData(fileName) {
+  try {
+    const encodingsDir = path.join(__dirname, "..", "encodings");
+    return require(path.join(encodingsDir, fileName));
+  } catch (e) {
+    console.error(`Error reading ${fileName}:`, e);
+    return {};
+  }
+}
+
+function collectAllEncodings() {
+  const allNames = new Set();
+  const canonicalize = (name) =>
+    String(name)
+      .toLowerCase()
+      .replace(/[^0-9a-z]/g, "");
+
+  // Add a list of internal keys to ignore
+  const ignoredKeys = new Set(["_internal"]);
+
+  const processEncodingObject = (obj) => {
+    for (const key in obj) {
+      // Skip the internal keys
+      if (ignoredKeys.has(key)) {
+        continue;
+      }
+
+      const value = obj[key];
+      allNames.add(key); // Add the alias itself
+
+      if (typeof value === "string") {
+        allNames.add(value); // Add the canonical name it points to
+      } else if (typeof value === "object" && value.name) {
+        allNames.add(value.name); // Add the name from the object
+      }
+    }
+  };
+
+  // Process all relevant files
+  processEncodingObject(getEncodingData("internal.js"));
+  processEncodingObject(getEncodingData("sbcs-data.js"));
+  processEncodingObject(getEncodingData("sbcs-data-generated.js"));
+  processEncodingObject(getEncodingData("dbcs-data.js"));
+
+  // Add the canonicalized (lowercase, alphanumeric) versions
+  const finalNames = new Set();
+  allNames.forEach((name) => {
+    finalNames.add(name);
+    const canon = canonicalize(name);
+    if (canon) {
+      finalNames.add(canon);
+    }
+  });
+
+  return Array.from(finalNames).sort();
+}
+
+function generateTypingsFile() {
+  const allEncodings = collectAllEncodings();
+  const supportedEncodingType = allEncodings.map((name) => `  | "${name}"`).join("\n");
+
+  const templatePath = path.join(__dirname, "template-index.d.ts");
+  const iconvLiteTypedefsTemplate = fs.readFileSync(templatePath, "utf8");
+  const iconvLiteTypedefs = iconvLiteTypedefsTemplate.replace(
+    "// --SUPPORTED-ENCODINGS-PLACEHOLDER--",
+    `export type SupportedEncoding =\n${supportedEncodingType}\n  | (string & {});`
+  );
+
+  const outputPath = path.join(__dirname, "..", "lib", "index.d.ts");
+  fs.writeFileSync(outputPath, iconvLiteTypedefs, "utf8");
+}
+
+// Run the script
+generateTypingsFile();
diff --git a/scripts/template-index.d.ts b/scripts/template-index.d.ts
new file mode 100644
index 00000000..fe1a06fa
--- /dev/null
+++ b/scripts/template-index.d.ts
@@ -0,0 +1,63 @@
+/*---------------------------------------------------------------------------------------------
+ * REQUIREMENT: This definition is dependent on the @types/node definition.
+ *
+ * This file provides detailed typings for all encodings supported by iconv-lite,
+ * based on the official wiki and source code:
+ * https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings
+ *--------------------------------------------------------------------------------------------*/
+
+/** A union of all supported encoding strings in `iconv-lite`. */
+// --SUPPORTED-ENCODINGS-PLACEHOLDER--
+
+declare module "iconv-lite" {
+  //   --- Basic API ---
+
+  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+  export function decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+
+  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
+  export function encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
+
+  /** Checks if a given encoding is supported by `iconv-lite`. */
+  export function encodingExists(encoding: string): encoding is SupportedEncoding;
+
+  //   --- Stream API ---
+
+  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
+  export function decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
+
+  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
+  export function encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
+
+  //   --- Low-level stream APIs ---
+
+  /** Creates and returns a low-level encoder stream. */
+  export function getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
+
+  /** Creates and returns a low-level decoder stream. */
+  export function getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
+}
+
+export interface DecodeOptions {
+  /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
+  stripBOM?: boolean;
+  /** Overrides the default endianness for `UTF-16` and `UTF-32` decodings. */
+  defaultEncoding?: "utf16be" | "utf32be";
+}
+
+export interface EncodeOptions {
+  /** Adds a byte order mark (BOM) to the output, when encoding. @default false */
+  addBOM?: boolean;
+  /** Overrides the default endianness for `UTF-32` encoding. */
+  defaultEncoding?: "utf32be";
+}
+
+export interface EncoderStream {
+  write(str: string): Buffer;
+  end(): Buffer | undefined;
+}
+
+export interface DecoderStream {
+  write(buf: Buffer): string;
+  end(): string | undefined;
+}

From c8daf9347d2abf84b3ef0ec82b1e5a435909959f Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Thu, 14 Aug 2025 21:40:29 +0100
Subject: [PATCH 06/33] add `typegen` script to package.json

---
 package.json | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/package.json b/package.json
index b29b1136..0ddd9668 100644
--- a/package.json
+++ b/package.json
@@ -27,7 +27,8 @@
         "test:cov": "nyc --exclude test --reporter=html --reporter=text npm test",
         "test:performance": "node performance/index.js",
         "test:tap": "mocha --reporter tap --check-leaks --grep .",
-        "test:webpack": "npm pack && mv iconv-lite-*.tgz test/webpack/iconv-lite.tgz && cd test/webpack && npm install && npm run test && rm iconv-lite.tgz"
+        "test:webpack": "npm pack && mv iconv-lite-*.tgz test/webpack/iconv-lite.tgz && cd test/webpack && npm install && npm run test && rm iconv-lite.tgz",
+        "typegen": "node scripts/generate-typings.js"
     },
     "browser": {
         "stream": false

From d4df2ecabd7decbfc44a815e613946bd6780f2d9 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Thu, 14 Aug 2025 21:46:55 +0100
Subject: [PATCH 07/33] add manual edits warning to generated `index.d.ts`

---
 lib/index.d.ts              |  8 ++++++++
 scripts/generate-typings.js | 10 +++++++++-
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index 7796f1f3..944aaafd 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -1,3 +1,11 @@
+/*
+ * ---------------------------------------------------------------------------------------------
+ * DO NOT EDIT THIS FILE MANUALLY.
+ * THIS FILE IS AUTOMATICALLY GENERATED.
+ * TO UPDATE, RUN `npm run typegen` AND COMMIT THE CHANGES.
+ * ---------------------------------------------------------------------------------------------
+ */
+
 /*---------------------------------------------------------------------------------------------
  * REQUIREMENT: This definition is dependent on the @types/node definition.
  *
diff --git a/scripts/generate-typings.js b/scripts/generate-typings.js
index f372a86e..40eab73f 100644
--- a/scripts/generate-typings.js
+++ b/scripts/generate-typings.js
@@ -69,8 +69,16 @@ function generateTypingsFile() {
     `export type SupportedEncoding =\n${supportedEncodingType}\n  | (string & {});`
   );
 
+  const generatedHeader = `/*
+ * ---------------------------------------------------------------------------------------------
+ * DO NOT EDIT THIS FILE MANUALLY.
+ * THIS FILE IS AUTOMATICALLY GENERATED.
+ * TO UPDATE, RUN \`npm run typegen\` AND COMMIT THE CHANGES.
+ * ---------------------------------------------------------------------------------------------
+ */\n\n`;
+
   const outputPath = path.join(__dirname, "..", "lib", "index.d.ts");
-  fs.writeFileSync(outputPath, iconvLiteTypedefs, "utf8");
+  fs.writeFileSync(outputPath, `${generatedHeader}${iconvLiteTypedefs}`, "utf8");
 }
 
 // Run the script

From ed4d59c61822fedfbaf390390460e53f2baafd9c Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Thu, 14 Aug 2025 21:56:39 +0100
Subject: [PATCH 08/33] move `generate-typings` script to `generation` folder

Also renamed `scripts/template-index.d.ts` to `lib/index-template.d.ts`
---
 .npmignore                                               | 2 +-
 scripts/generate-typings.js => generation/gen-typings.js | 3 ++-
 scripts/template-index.d.ts => lib/index-template.d.ts   | 0
 package.json                                             | 2 +-
 4 files changed, 4 insertions(+), 3 deletions(-)
 rename scripts/generate-typings.js => generation/gen-typings.js (96%)
 rename scripts/template-index.d.ts => lib/index-template.d.ts (100%)

diff --git a/.npmignore b/.npmignore
index 19164bf0..d5a4b77f 100644
--- a/.npmignore
+++ b/.npmignore
@@ -7,4 +7,4 @@ coverage
 .github
 .idea
 performance
-scripts
+lib/index-template.d.ts
diff --git a/scripts/generate-typings.js b/generation/gen-typings.js
similarity index 96%
rename from scripts/generate-typings.js
rename to generation/gen-typings.js
index 40eab73f..d0a5c157 100644
--- a/scripts/generate-typings.js
+++ b/generation/gen-typings.js
@@ -62,8 +62,9 @@ function generateTypingsFile() {
   const allEncodings = collectAllEncodings();
   const supportedEncodingType = allEncodings.map((name) => `  | "${name}"`).join("\n");
 
-  const templatePath = path.join(__dirname, "template-index.d.ts");
+  const templatePath = path.join(__dirname, "..", "lib", "index-template.d.ts");
   const iconvLiteTypedefsTemplate = fs.readFileSync(templatePath, "utf8");
+
   const iconvLiteTypedefs = iconvLiteTypedefsTemplate.replace(
     "// --SUPPORTED-ENCODINGS-PLACEHOLDER--",
     `export type SupportedEncoding =\n${supportedEncodingType}\n  | (string & {});`
diff --git a/scripts/template-index.d.ts b/lib/index-template.d.ts
similarity index 100%
rename from scripts/template-index.d.ts
rename to lib/index-template.d.ts
diff --git a/package.json b/package.json
index 0ddd9668..7deab917 100644
--- a/package.json
+++ b/package.json
@@ -28,7 +28,7 @@
         "test:performance": "node performance/index.js",
         "test:tap": "mocha --reporter tap --check-leaks --grep .",
         "test:webpack": "npm pack && mv iconv-lite-*.tgz test/webpack/iconv-lite.tgz && cd test/webpack && npm install && npm run test && rm iconv-lite.tgz",
-        "typegen": "node scripts/generate-typings.js"
+        "typegen": "node generation/gen-typings.js"
     },
     "browser": {
         "stream": false

From b8fc5b6bf7efc08066ec1211fafdc937d353ee79 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 11:32:12 +0100
Subject: [PATCH 09/33] remove "declare module" from typings

---
 lib/index-template.d.ts | 38 +++++++++++++++++++-------------------
 lib/index.d.ts          | 38 +++++++++++++++++++-------------------
 2 files changed, 38 insertions(+), 38 deletions(-)

diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index fe1a06fa..25e138d7 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -1,6 +1,8 @@
 /*---------------------------------------------------------------------------------------------
  * REQUIREMENT: This definition is dependent on the @types/node definition.
  *
+ * `npm install --save-dev @types/node`
+ *
  * This file provides detailed typings for all encodings supported by iconv-lite,
  * based on the official wiki and source code:
  * https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings
@@ -9,34 +11,32 @@
 /** A union of all supported encoding strings in `iconv-lite`. */
 // --SUPPORTED-ENCODINGS-PLACEHOLDER--
 
-declare module "iconv-lite" {
-  //   --- Basic API ---
+//   --- Basic API ---
 
-  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-  export function decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+/** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+export function decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
 
-  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-  export function encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
+/** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
+export function encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
 
-  /** Checks if a given encoding is supported by `iconv-lite`. */
-  export function encodingExists(encoding: string): encoding is SupportedEncoding;
+/** Checks if a given encoding is supported by `iconv-lite`. */
+export function encodingExists(encoding: string): encoding is SupportedEncoding;
 
-  //   --- Stream API ---
+//   --- Stream API ---
 
-  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
-  export function decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
+/** Creates a stream that decodes binary data from a given `encoding` into strings. */
+export function decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
 
-  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
-  export function encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
+/** Creates a stream that encodes strings into binary data in a given `encoding`. */
+export function encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
 
-  //   --- Low-level stream APIs ---
+//   --- Low-level stream APIs ---
 
-  /** Creates and returns a low-level encoder stream. */
-  export function getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
+/** Creates and returns a low-level encoder stream. */
+export function getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
 
-  /** Creates and returns a low-level decoder stream. */
-  export function getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
-}
+/** Creates and returns a low-level decoder stream. */
+export function getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
 
 export interface DecodeOptions {
   /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 944aaafd..059ec1dc 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -9,6 +9,8 @@
 /*---------------------------------------------------------------------------------------------
  * REQUIREMENT: This definition is dependent on the @types/node definition.
  *
+ * `npm install --save-dev @types/node`
+ *
  * This file provides detailed typings for all encodings supported by iconv-lite,
  * based on the official wiki and source code:
  * https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings
@@ -419,34 +421,32 @@ export type SupportedEncoding =
   | "xxbig5"
   | (string & {});
 
-declare module "iconv-lite" {
-  //   --- Basic API ---
+//   --- Basic API ---
 
-  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-  export function decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+/** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+export function decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
 
-  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-  export function encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
+/** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
+export function encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
 
-  /** Checks if a given encoding is supported by `iconv-lite`. */
-  export function encodingExists(encoding: string): encoding is SupportedEncoding;
+/** Checks if a given encoding is supported by `iconv-lite`. */
+export function encodingExists(encoding: string): encoding is SupportedEncoding;
 
-  //   --- Stream API ---
+//   --- Stream API ---
 
-  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
-  export function decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
+/** Creates a stream that decodes binary data from a given `encoding` into strings. */
+export function decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
 
-  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
-  export function encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
+/** Creates a stream that encodes strings into binary data in a given `encoding`. */
+export function encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
 
-  //   --- Low-level stream APIs ---
+//   --- Low-level stream APIs ---
 
-  /** Creates and returns a low-level encoder stream. */
-  export function getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
+/** Creates and returns a low-level encoder stream. */
+export function getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
 
-  /** Creates and returns a low-level decoder stream. */
-  export function getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
-}
+/** Creates and returns a low-level decoder stream. */
+export function getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
 
 export interface DecodeOptions {
   /** Strips the byte order mark (BOM) from the input, when decoding. @default true */

From 429c8906b090763a026516f7da664541068d9239 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 13:27:40 +0100
Subject: [PATCH 10/33] make sure typings correctly describes usage in both cjs
 and esm

---
 lib/index-template.d.ts | 58 ++++++++++++++++++++++-------------------
 lib/index.d.ts          | 58 ++++++++++++++++++++++-------------------
 2 files changed, 62 insertions(+), 54 deletions(-)

diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index 25e138d7..c7a3eee9 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -11,33 +11,6 @@
 /** A union of all supported encoding strings in `iconv-lite`. */
 // --SUPPORTED-ENCODINGS-PLACEHOLDER--
 
-//   --- Basic API ---
-
-/** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-export function decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
-
-/** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-export function encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
-
-/** Checks if a given encoding is supported by `iconv-lite`. */
-export function encodingExists(encoding: string): encoding is SupportedEncoding;
-
-//   --- Stream API ---
-
-/** Creates a stream that decodes binary data from a given `encoding` into strings. */
-export function decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
-
-/** Creates a stream that encodes strings into binary data in a given `encoding`. */
-export function encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
-
-//   --- Low-level stream APIs ---
-
-/** Creates and returns a low-level encoder stream. */
-export function getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
-
-/** Creates and returns a low-level decoder stream. */
-export function getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
-
 export interface DecodeOptions {
   /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
   stripBOM?: boolean;
@@ -61,3 +34,34 @@ export interface DecoderStream {
   write(buf: Buffer): string;
   end(): string | undefined;
 }
+
+declare const iconv: {
+  //   --- Basic API ---
+
+  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+  decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+
+  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
+  encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
+
+  /** Checks if a given encoding is supported by `iconv-lite`. */
+  encodingExists(encoding: string): encoding is SupportedEncoding;
+
+  //   --- Stream API ---
+
+  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
+  decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
+
+  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
+  encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
+
+  //   --- Low-level stream APIs ---
+
+  /** Creates and returns a low-level encoder stream. */
+  getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
+
+  /** Creates and returns a low-level decoder stream. */
+  getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
+};
+
+export default iconv;
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 059ec1dc..95297551 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -421,33 +421,6 @@ export type SupportedEncoding =
   | "xxbig5"
   | (string & {});
 
-//   --- Basic API ---
-
-/** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-export function decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
-
-/** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-export function encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
-
-/** Checks if a given encoding is supported by `iconv-lite`. */
-export function encodingExists(encoding: string): encoding is SupportedEncoding;
-
-//   --- Stream API ---
-
-/** Creates a stream that decodes binary data from a given `encoding` into strings. */
-export function decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
-
-/** Creates a stream that encodes strings into binary data in a given `encoding`. */
-export function encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
-
-//   --- Low-level stream APIs ---
-
-/** Creates and returns a low-level encoder stream. */
-export function getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
-
-/** Creates and returns a low-level decoder stream. */
-export function getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
-
 export interface DecodeOptions {
   /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
   stripBOM?: boolean;
@@ -471,3 +444,34 @@ export interface DecoderStream {
   write(buf: Buffer): string;
   end(): string | undefined;
 }
+
+declare const iconv: {
+  //   --- Basic API ---
+
+  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+  decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+
+  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
+  encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
+
+  /** Checks if a given encoding is supported by `iconv-lite`. */
+  encodingExists(encoding: string): encoding is SupportedEncoding;
+
+  //   --- Stream API ---
+
+  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
+  decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
+
+  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
+  encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
+
+  //   --- Low-level stream APIs ---
+
+  /** Creates and returns a low-level encoder stream. */
+  getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
+
+  /** Creates and returns a low-level decoder stream. */
+  getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
+};
+
+export default iconv;

From 60d80dad8733fd529b2a53fb7f2d232a699d8a9e Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 13:36:11 +0100
Subject: [PATCH 11/33] process all encodings

---
 generation/gen-typings.js | 14 +++++++-------
 lib/index.d.ts            | 11 +++++++++++
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/generation/gen-typings.js b/generation/gen-typings.js
index d0a5c157..aea7e86c 100644
--- a/generation/gen-typings.js
+++ b/generation/gen-typings.js
@@ -18,15 +18,10 @@ function collectAllEncodings() {
       .toLowerCase()
       .replace(/[^0-9a-z]/g, "");
 
-  // Add a list of internal keys to ignore
-  const ignoredKeys = new Set(["_internal"]);
-
   const processEncodingObject = (obj) => {
     for (const key in obj) {
-      // Skip the internal keys
-      if (ignoredKeys.has(key)) {
-        continue;
-      }
+      // Skip internal keys
+      if (key.startsWith("_")) continue;
 
       const value = obj[key];
       allNames.add(key); // Add the alias itself
@@ -41,8 +36,13 @@ function collectAllEncodings() {
 
   // Process all relevant files
   processEncodingObject(getEncodingData("internal.js"));
+  processEncodingObject(getEncodingData("utf32.js"));
+  processEncodingObject(getEncodingData("utf16.js"));
+  processEncodingObject(getEncodingData("utf7.js"));
+  processEncodingObject(getEncodingData("sbcs-codec.js"));
   processEncodingObject(getEncodingData("sbcs-data.js"));
   processEncodingObject(getEncodingData("sbcs-data-generated.js"));
+  processEncodingObject(getEncodingData("dbcs-codec.js"));
   processEncodingObject(getEncodingData("dbcs-data.js"));
 
   // Add the canonicalized (lowercase, alphanumeric) versions
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 95297551..17d4cbbf 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -383,10 +383,21 @@ export type SupportedEncoding =
   | "turkish"
   | "turkish8"
   | "ucs2"
+  | "ucs4"
+  | "ucs4be"
+  | "ucs4le"
+  | "unicode11utf7"
   | "unicode11utf8"
   | "us"
   | "usascii"
+  | "utf16"
+  | "utf16be"
   | "utf16le"
+  | "utf32"
+  | "utf32be"
+  | "utf32le"
+  | "utf7"
+  | "utf7imap"
   | "utf8"
   | "viscii"
   | "win1250"

From aee31d5e964b5e1297a82b9a005efce50c00c5e1 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 13:42:41 +0100
Subject: [PATCH 12/33] typings: add legacy aliases (`toEncoding`,
 `fromEncoding`), `enableStreamingAPI`, `getCodec`, `_canonicalizeEncoding`,
 `encodings`, `_codecDataCache`, `defaultCharUnicode`, `defaultCharSingleByte`
 to the public API

---
 lib/index-template.d.ts | 66 +++++++++++++++++++++++++++++++++++++----
 lib/index.d.ts          | 66 +++++++++++++++++++++++++++++++++++++----
 2 files changed, 120 insertions(+), 12 deletions(-)

diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index c7a3eee9..21228a64 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -11,6 +11,8 @@
 /** A union of all supported encoding strings in `iconv-lite`. */
 // --SUPPORTED-ENCODINGS-PLACEHOLDER--
 
+// --- Options ---
+
 export interface DecodeOptions {
   /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
   stripBOM?: boolean;
@@ -25,6 +27,8 @@ export interface EncodeOptions {
   defaultEncoding?: "utf32be";
 }
 
+// --- Return values ---
+
 export interface EncoderStream {
   write(str: string): Buffer;
   end(): Buffer | undefined;
@@ -35,19 +39,30 @@ export interface DecoderStream {
   end(): string | undefined;
 }
 
-declare const iconv: {
-  //   --- Basic API ---
+export interface Codec {
+  encoder: new (options?: EncodeOptions, codec?: any) => EncoderStream;
+  decoder: new (options?: DecodeOptions, codec?: any) => DecoderStream;
+  [key: string]: any;
+}
 
-  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-  decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+declare const iconv: {
+  // --- Basic API ---
 
   /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
   encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
 
+  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+  decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+
   /** Checks if a given encoding is supported by `iconv-lite`. */
   encodingExists(encoding: string): encoding is SupportedEncoding;
 
-  //   --- Stream API ---
+  // --- Legacy aliases ---
+
+  toEncoding: typeof iconv.encode;
+  fromEncoding: typeof iconv.decode;
+
+  // --- Stream API ---
 
   /** Creates a stream that decodes binary data from a given `encoding` into strings. */
   decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
@@ -55,13 +70,52 @@ declare const iconv: {
   /** Creates a stream that encodes strings into binary data in a given `encoding`. */
   encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
 
-  //   --- Low-level stream APIs ---
+  /**
+   * Explicitly enable Streaming API in browser environments by passing in:
+   * ```js
+   * require('stream')
+   * ```
+   * @example iconv.enableStreamingAPI(require('stream'));
+   */
+  enableStreamingAPI(stream_module: any): void;
+
+  // --- Low-level stream APIs ---
 
   /** Creates and returns a low-level encoder stream. */
   getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
 
   /** Creates and returns a low-level decoder stream. */
   getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
+
+  /**
+   * Returns a codec object for the given `encoding`.
+   * @throws If the passed in encoding is not recognized.
+   */
+  getCodec(encoding: SupportedEncoding): Codec;
+
+  /** Strips all non-alphanumeric characters and appended year from `encoding`. */
+  _canonicalizeEncoding(encoding: SupportedEncoding): string;
+
+  // --- Properties ---
+
+  /** A cache of all loaded encoding definitions. */
+  encodings: Record<
+    SupportedEncoding,
+    | string
+    | {
+        type: string;
+        [key: string]: any;
+      }
+  > | null;
+
+  /** A cache of initialized codec objects. */
+  _codecDataCache: Record<string, Codec>;
+
+  /** The character used for untranslatable `Unicode` characters. @default "�" */
+  defaultCharUnicode: string;
+
+  /** The character used for untranslatable `single-byte` characters. @default "?" */
+  defaultCharSingleByte: string;
 };
 
 export default iconv;
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 17d4cbbf..53f486ca 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -432,6 +432,8 @@ export type SupportedEncoding =
   | "xxbig5"
   | (string & {});
 
+// --- Options ---
+
 export interface DecodeOptions {
   /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
   stripBOM?: boolean;
@@ -446,6 +448,8 @@ export interface EncodeOptions {
   defaultEncoding?: "utf32be";
 }
 
+// --- Return values ---
+
 export interface EncoderStream {
   write(str: string): Buffer;
   end(): Buffer | undefined;
@@ -456,19 +460,30 @@ export interface DecoderStream {
   end(): string | undefined;
 }
 
-declare const iconv: {
-  //   --- Basic API ---
+export interface Codec {
+  encoder: new (options?: EncodeOptions, codec?: any) => EncoderStream;
+  decoder: new (options?: DecodeOptions, codec?: any) => DecoderStream;
+  [key: string]: any;
+}
 
-  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-  decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+declare const iconv: {
+  // --- Basic API ---
 
   /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
   encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
 
+  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+  decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+
   /** Checks if a given encoding is supported by `iconv-lite`. */
   encodingExists(encoding: string): encoding is SupportedEncoding;
 
-  //   --- Stream API ---
+  // --- Legacy aliases ---
+
+  toEncoding: typeof iconv.encode;
+  fromEncoding: typeof iconv.decode;
+
+  // --- Stream API ---
 
   /** Creates a stream that decodes binary data from a given `encoding` into strings. */
   decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
@@ -476,13 +491,52 @@ declare const iconv: {
   /** Creates a stream that encodes strings into binary data in a given `encoding`. */
   encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
 
-  //   --- Low-level stream APIs ---
+  /**
+   * Explicitly enable Streaming API in browser environments by passing in:
+   * ```js
+   * require('stream')
+   * ```
+   * @example iconv.enableStreamingAPI(require('stream'));
+   */
+  enableStreamingAPI(stream_module: any): void;
+
+  // --- Low-level stream APIs ---
 
   /** Creates and returns a low-level encoder stream. */
   getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
 
   /** Creates and returns a low-level decoder stream. */
   getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
+
+  /**
+   * Returns a codec object for the given `encoding`.
+   * @throws If the passed in encoding is not recognized.
+   */
+  getCodec(encoding: SupportedEncoding): Codec;
+
+  /** Strips all non-alphanumeric characters and appended year from `encoding`. */
+  _canonicalizeEncoding(encoding: SupportedEncoding): string;
+
+  // --- Properties ---
+
+  /** A cache of all loaded encoding definitions. */
+  encodings: Record<
+    SupportedEncoding,
+    | string
+    | {
+        type: string;
+        [key: string]: any;
+      }
+  > | null;
+
+  /** A cache of initialized codec objects. */
+  _codecDataCache: Record<string, Codec>;
+
+  /** The character used for untranslatable `Unicode` characters. @default "�" */
+  defaultCharUnicode: string;
+
+  /** The character used for untranslatable `single-byte` characters. @default "?" */
+  defaultCharSingleByte: string;
 };
 
 export default iconv;

From f4e3513d42a4ba521c6b1ca067952982842a462e Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 14:03:48 +0100
Subject: [PATCH 13/33] typings: add `supportsStreams` property

---
 lib/index-template.d.ts | 3 +++
 lib/index.d.ts          | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index 21228a64..710d70c3 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -116,6 +116,9 @@ declare const iconv: {
 
   /** The character used for untranslatable `single-byte` characters. @default "?" */
   defaultCharSingleByte: string;
+
+  /** @readonly Whether or not, Streaming API is enabled. */
+  readonly supportsStreams: boolean;
 };
 
 export default iconv;
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 53f486ca..c99cccb2 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -537,6 +537,9 @@ declare const iconv: {
 
   /** The character used for untranslatable `single-byte` characters. @default "?" */
   defaultCharSingleByte: string;
+
+  /** @readonly Whether or not, Streaming API is enabled. */
+  readonly supportsStreams: boolean;
 };
 
 export default iconv;

From a9a5bdc91e822aaf657e0071efc993d8070f723d Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 14:04:23 +0100
Subject: [PATCH 14/33] add jsDocs to legacy aliases

---
 lib/index-template.d.ts | 3 +++
 lib/index.d.ts          | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index 710d70c3..30f44680 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -59,7 +59,10 @@ declare const iconv: {
 
   // --- Legacy aliases ---
 
+  /** Legacy alias for {@link iconv.encode}. */
   toEncoding: typeof iconv.encode;
+
+  /** Legacy alias for {@link iconv.decode}. */
   fromEncoding: typeof iconv.decode;
 
   // --- Stream API ---
diff --git a/lib/index.d.ts b/lib/index.d.ts
index c99cccb2..4bc03b46 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -480,7 +480,10 @@ declare const iconv: {
 
   // --- Legacy aliases ---
 
+  /** Legacy alias for {@link iconv.encode}. */
   toEncoding: typeof iconv.encode;
+
+  /** Legacy alias for {@link iconv.decode}. */
   fromEncoding: typeof iconv.decode;
 
   // --- Stream API ---

From 88e6647e4b6be87ca0a268fa7f8690fdbe6fa21d Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 14:14:44 +0100
Subject: [PATCH 15/33] small doc change

---
 lib/index-template.d.ts | 2 +-
 lib/index.d.ts          | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index 30f44680..6132ee4f 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -1,7 +1,7 @@
 /*---------------------------------------------------------------------------------------------
  * REQUIREMENT: This definition is dependent on the @types/node definition.
  *
- * `npm install --save-dev @types/node`
+ * Install with `npm install @types/node --save-dev`
  *
  * This file provides detailed typings for all encodings supported by iconv-lite,
  * based on the official wiki and source code:
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 4bc03b46..841f8ed9 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -9,7 +9,7 @@
 /*---------------------------------------------------------------------------------------------
  * REQUIREMENT: This definition is dependent on the @types/node definition.
  *
- * `npm install --save-dev @types/node`
+ * Install with `npm install @types/node --save-dev`
  *
  * This file provides detailed typings for all encodings supported by iconv-lite,
  * based on the official wiki and source code:

From 17d9b17ff682b544ec7041442384afacc34fd6b0 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 14:31:50 +0100
Subject: [PATCH 16/33] small js docs change

---
 lib/index-template.d.ts | 4 +---
 lib/index.d.ts          | 4 +---
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index 6132ee4f..c1d80064 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -3,9 +3,7 @@
  *
  * Install with `npm install @types/node --save-dev`
  *
- * This file provides detailed typings for all encodings supported by iconv-lite,
- * based on the official wiki and source code:
- * https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings
+ * This file provides detailed typings for all encodings supported by iconv-lite.
  *--------------------------------------------------------------------------------------------*/
 
 /** A union of all supported encoding strings in `iconv-lite`. */
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 841f8ed9..5b6c164c 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -11,9 +11,7 @@
  *
  * Install with `npm install @types/node --save-dev`
  *
- * This file provides detailed typings for all encodings supported by iconv-lite,
- * based on the official wiki and source code:
- * https://github.com/ashtuchkin/iconv-lite/wiki/Supported-Encodings
+ * This file provides detailed typings for all encodings supported by iconv-lite.
  *--------------------------------------------------------------------------------------------*/
 
 /** A union of all supported encoding strings in `iconv-lite`. */

From a2bf322a471c28272ad156e9a6b1374e05a595b4 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 14:55:52 +0100
Subject: [PATCH 17/33] improve var names and docs

---
 generation/gen-typings.js | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/generation/gen-typings.js b/generation/gen-typings.js
index aea7e86c..660ecfd9 100644
--- a/generation/gen-typings.js
+++ b/generation/gen-typings.js
@@ -20,7 +20,7 @@ function collectAllEncodings() {
 
   const processEncodingObject = (obj) => {
     for (const key in obj) {
-      // Skip internal keys
+      // Skip codecs
       if (key.startsWith("_")) continue;
 
       const value = obj[key];
@@ -63,9 +63,9 @@ function generateTypingsFile() {
   const supportedEncodingType = allEncodings.map((name) => `  | "${name}"`).join("\n");
 
   const templatePath = path.join(__dirname, "..", "lib", "index-template.d.ts");
-  const iconvLiteTypedefsTemplate = fs.readFileSync(templatePath, "utf8");
+  const typedefsTemplate = fs.readFileSync(templatePath, "utf8");
 
-  const iconvLiteTypedefs = iconvLiteTypedefsTemplate.replace(
+  const typedefs = typedefsTemplate.replace(
     "// --SUPPORTED-ENCODINGS-PLACEHOLDER--",
     `export type SupportedEncoding =\n${supportedEncodingType}\n  | (string & {});`
   );
@@ -79,7 +79,7 @@ function generateTypingsFile() {
  */\n\n`;
 
   const outputPath = path.join(__dirname, "..", "lib", "index.d.ts");
-  fs.writeFileSync(outputPath, `${generatedHeader}${iconvLiteTypedefs}`, "utf8");
+  fs.writeFileSync(outputPath, `${generatedHeader}${typedefs}`, "utf8");
 }
 
 // Run the script

From 72e0fa4ba3ef24b96601c084d649c56ab715da36 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 14:56:46 +0100
Subject: [PATCH 18/33] mirror the lib's `_canonicalizeEncoding` logic

---
 generation/gen-typings.js | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/generation/gen-typings.js b/generation/gen-typings.js
index 660ecfd9..6a5879d8 100644
--- a/generation/gen-typings.js
+++ b/generation/gen-typings.js
@@ -13,10 +13,7 @@ function getEncodingData(fileName) {
 
 function collectAllEncodings() {
   const allNames = new Set();
-  const canonicalize = (name) =>
-    String(name)
-      .toLowerCase()
-      .replace(/[^0-9a-z]/g, "");
+  const canonicalize = (name) => ("" + name).toLowerCase().replace(/:\d{4}$|[^0-9a-z]/g, "");
 
   const processEncodingObject = (obj) => {
     for (const key in obj) {

From ed46ed87b647b29c5b430e50d1a6845eea4f1fe7 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 14:59:18 +0100
Subject: [PATCH 19/33] change placeholder for `SupportedEncoding` type

---
 generation/gen-typings.js | 4 ++--
 lib/index-template.d.ts   | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/generation/gen-typings.js b/generation/gen-typings.js
index 6a5879d8..f9aaaab4 100644
--- a/generation/gen-typings.js
+++ b/generation/gen-typings.js
@@ -63,8 +63,8 @@ function generateTypingsFile() {
   const typedefsTemplate = fs.readFileSync(templatePath, "utf8");
 
   const typedefs = typedefsTemplate.replace(
-    "// --SUPPORTED-ENCODINGS-PLACEHOLDER--",
-    `export type SupportedEncoding =\n${supportedEncodingType}\n  | (string & {});`
+    "export type SupportedEncoding = string",
+    `export type SupportedEncoding =\n${supportedEncodingType}\n  | (string & {})`
   );
 
   const generatedHeader = `/*
diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index c1d80064..f4e9d18e 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -7,7 +7,7 @@
  *--------------------------------------------------------------------------------------------*/
 
 /** A union of all supported encoding strings in `iconv-lite`. */
-// --SUPPORTED-ENCODINGS-PLACEHOLDER--
+export type SupportedEncoding = string;
 
 // --- Options ---
 

From ed3f39eaf65e50542fcebd64ed1c3d69055ea880 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 15:07:00 +0100
Subject: [PATCH 20/33] improve docs

---
 generation/gen-typings.js |  2 +-
 lib/index-template.d.ts   | 10 +++++-----
 lib/index.d.ts            | 10 +++++-----
 3 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/generation/gen-typings.js b/generation/gen-typings.js
index f9aaaab4..176557d5 100644
--- a/generation/gen-typings.js
+++ b/generation/gen-typings.js
@@ -42,7 +42,7 @@ function collectAllEncodings() {
   processEncodingObject(getEncodingData("dbcs-codec.js"));
   processEncodingObject(getEncodingData("dbcs-data.js"));
 
-  // Add the canonicalized (lowercase, alphanumeric) versions
+  // Add the canonicalized (lowercase, alphanumeric, no appended year) versions
   const finalNames = new Set();
   allNames.forEach((name) => {
     finalNames.add(name);
diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index f4e9d18e..ece87785 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -12,16 +12,16 @@ export type SupportedEncoding = string;
 // --- Options ---
 
 export interface DecodeOptions {
-  /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
+  /** Strip the byte order mark (BOM) from the input, when decoding. @default true */
   stripBOM?: boolean;
-  /** Overrides the default endianness for `UTF-16` and `UTF-32` decodings. */
+  /** Override the default endianness for `UTF-16` and `UTF-32` decodings. */
   defaultEncoding?: "utf16be" | "utf32be";
 }
 
 export interface EncodeOptions {
-  /** Adds a byte order mark (BOM) to the output, when encoding. @default false */
+  /** Add a byte order mark (BOM) to the output, when encoding. @default false */
   addBOM?: boolean;
-  /** Overrides the default endianness for `UTF-32` encoding. */
+  /** Override the default endianness for `UTF-32` encoding. */
   defaultEncoding?: "utf32be";
 }
 
@@ -90,7 +90,7 @@ declare const iconv: {
 
   /**
    * Returns a codec object for the given `encoding`.
-   * @throws If the passed in encoding is not recognized.
+   * @throws If the `encoding` is not recognized.
    */
   getCodec(encoding: SupportedEncoding): Codec;
 
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 5b6c164c..52436259 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -433,16 +433,16 @@ export type SupportedEncoding =
 // --- Options ---
 
 export interface DecodeOptions {
-  /** Strips the byte order mark (BOM) from the input, when decoding. @default true */
+  /** Strip the byte order mark (BOM) from the input, when decoding. @default true */
   stripBOM?: boolean;
-  /** Overrides the default endianness for `UTF-16` and `UTF-32` decodings. */
+  /** Override the default endianness for `UTF-16` and `UTF-32` decodings. */
   defaultEncoding?: "utf16be" | "utf32be";
 }
 
 export interface EncodeOptions {
-  /** Adds a byte order mark (BOM) to the output, when encoding. @default false */
+  /** Add a byte order mark (BOM) to the output, when encoding. @default false */
   addBOM?: boolean;
-  /** Overrides the default endianness for `UTF-32` encoding. */
+  /** Override the default endianness for `UTF-32` encoding. */
   defaultEncoding?: "utf32be";
 }
 
@@ -511,7 +511,7 @@ declare const iconv: {
 
   /**
    * Returns a codec object for the given `encoding`.
-   * @throws If the passed in encoding is not recognized.
+   * @throws If the `encoding` is not recognized.
    */
   getCodec(encoding: SupportedEncoding): Codec;
 

From f66e8ec9b21b043c1ab1270ee71417a5488c689c Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 18:48:26 +0100
Subject: [PATCH 21/33] improve docs

---
 lib/index-template.d.ts | 2 +-
 lib/index.d.ts          | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
index ece87785..1f5ba386 100644
--- a/lib/index-template.d.ts
+++ b/lib/index-template.d.ts
@@ -3,7 +3,7 @@
  *
  * Install with `npm install @types/node --save-dev`
  *
- * This file provides detailed typings for all encodings supported by iconv-lite.
+ * This file provides detailed typings for the public API of iconv-lite
  *--------------------------------------------------------------------------------------------*/
 
 /** A union of all supported encoding strings in `iconv-lite`. */
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 52436259..6838bf9e 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -11,7 +11,7 @@
  *
  * Install with `npm install @types/node --save-dev`
  *
- * This file provides detailed typings for all encodings supported by iconv-lite.
+ * This file provides detailed typings for the public API of iconv-lite
  *--------------------------------------------------------------------------------------------*/
 
 /** A union of all supported encoding strings in `iconv-lite`. */

From a773a6f6f6b8a2f796824687746b27d67f5ecb4c Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 19:05:17 +0100
Subject: [PATCH 22/33] refactor: separate generated encodings into a dedicated
 file

---
 .npmignore                |   3 +-
 generation/gen-typings.js |  19 +-
 lib/encodings.d.ts        | 423 +++++++++++++++++++++++++++++++++++++
 lib/index.d.ts            | 424 +-------------------------------------
 4 files changed, 433 insertions(+), 436 deletions(-)
 create mode 100644 lib/encodings.d.ts

diff --git a/.npmignore b/.npmignore
index d5a4b77f..12fca491 100644
--- a/.npmignore
+++ b/.npmignore
@@ -6,5 +6,4 @@ wiki
 coverage
 .github
 .idea
-performance
-lib/index-template.d.ts
+performance
\ No newline at end of file
diff --git a/generation/gen-typings.js b/generation/gen-typings.js
index 176557d5..fdec2214 100644
--- a/generation/gen-typings.js
+++ b/generation/gen-typings.js
@@ -59,24 +59,21 @@ function generateTypingsFile() {
   const allEncodings = collectAllEncodings();
   const supportedEncodingType = allEncodings.map((name) => `  | "${name}"`).join("\n");
 
-  const templatePath = path.join(__dirname, "..", "lib", "index-template.d.ts");
-  const typedefsTemplate = fs.readFileSync(templatePath, "utf8");
-
-  const typedefs = typedefsTemplate.replace(
-    "export type SupportedEncoding = string",
-    `export type SupportedEncoding =\n${supportedEncodingType}\n  | (string & {})`
-  );
-
   const generatedHeader = `/*
  * ---------------------------------------------------------------------------------------------
  * DO NOT EDIT THIS FILE MANUALLY.
  * THIS FILE IS AUTOMATICALLY GENERATED.
  * TO UPDATE, RUN \`npm run typegen\` AND COMMIT THE CHANGES.
  * ---------------------------------------------------------------------------------------------
- */\n\n`;
+ */`;
+
+  const fileContent = `${generatedHeader}\n
+/** A union of all supported encoding strings in \`iconv-lite\`. */
+export type SupportedEncoding =\n${supportedEncodingType}\n  | (string & {});
+`;
 
-  const outputPath = path.join(__dirname, "..", "lib", "index.d.ts");
-  fs.writeFileSync(outputPath, `${generatedHeader}${typedefs}`, "utf8");
+  const outputPath = path.join(__dirname, "..", "lib", "encodings.d.ts");
+  fs.writeFileSync(outputPath, fileContent, "utf8");
 }
 
 // Run the script
diff --git a/lib/encodings.d.ts b/lib/encodings.d.ts
new file mode 100644
index 00000000..dc76893b
--- /dev/null
+++ b/lib/encodings.d.ts
@@ -0,0 +1,423 @@
+/*
+ * ---------------------------------------------------------------------------------------------
+ * DO NOT EDIT THIS FILE MANUALLY.
+ * THIS FILE IS AUTOMATICALLY GENERATED.
+ * TO UPDATE, RUN `npm run typegen` AND COMMIT THE CHANGES.
+ * ---------------------------------------------------------------------------------------------
+ */
+
+/** A union of all supported encoding strings in `iconv-lite`. */
+export type SupportedEncoding =
+  | "10000"
+  | "10006"
+  | "10007"
+  | "10029"
+  | "10079"
+  | "10081"
+  | "1046"
+  | "1124"
+  | "1125"
+  | "1129"
+  | "1133"
+  | "1161"
+  | "1162"
+  | "1163"
+  | "1250"
+  | "1251"
+  | "1252"
+  | "1253"
+  | "1254"
+  | "1255"
+  | "1256"
+  | "1257"
+  | "1258"
+  | "20866"
+  | "21866"
+  | "28591"
+  | "28592"
+  | "28593"
+  | "28594"
+  | "28595"
+  | "28596"
+  | "28597"
+  | "28598"
+  | "28599"
+  | "28600"
+  | "28601"
+  | "28603"
+  | "28604"
+  | "28605"
+  | "28606"
+  | "437"
+  | "737"
+  | "775"
+  | "808"
+  | "850"
+  | "852"
+  | "855"
+  | "856"
+  | "857"
+  | "858"
+  | "860"
+  | "861"
+  | "862"
+  | "863"
+  | "864"
+  | "865"
+  | "866"
+  | "869"
+  | "874"
+  | "922"
+  | "932"
+  | "936"
+  | "949"
+  | "950"
+  | "ansix34"
+  | "ansix341968"
+  | "ansix341986"
+  | "arabic"
+  | "arabic8"
+  | "armscii8"
+  | "ascii"
+  | "ascii8bit"
+  | "asmo708"
+  | "base64"
+  | "big5"
+  | "big5hkscs"
+  | "binary"
+  | "celtic"
+  | "celtic8"
+  | "cesu8"
+  | "chinese"
+  | "cn"
+  | "cnbig5"
+  | "cp1046"
+  | "cp1124"
+  | "cp1125"
+  | "cp1129"
+  | "cp1133"
+  | "cp1161"
+  | "cp1162"
+  | "cp1163"
+  | "cp1250"
+  | "cp1251"
+  | "cp1252"
+  | "cp1253"
+  | "cp1254"
+  | "cp1255"
+  | "cp1256"
+  | "cp1257"
+  | "cp1258"
+  | "cp20866"
+  | "cp21866"
+  | "cp28591"
+  | "cp28592"
+  | "cp28593"
+  | "cp28594"
+  | "cp28595"
+  | "cp28596"
+  | "cp28597"
+  | "cp28598"
+  | "cp28599"
+  | "cp28600"
+  | "cp28601"
+  | "cp28603"
+  | "cp28604"
+  | "cp28605"
+  | "cp28606"
+  | "cp367"
+  | "cp437"
+  | "cp720"
+  | "cp737"
+  | "cp775"
+  | "cp808"
+  | "cp819"
+  | "cp850"
+  | "cp852"
+  | "cp855"
+  | "cp856"
+  | "cp857"
+  | "cp858"
+  | "cp860"
+  | "cp861"
+  | "cp862"
+  | "cp863"
+  | "cp864"
+  | "cp865"
+  | "cp866"
+  | "cp869"
+  | "cp874"
+  | "cp922"
+  | "cp932"
+  | "cp936"
+  | "cp949"
+  | "cp950"
+  | "cpgr"
+  | "csascii"
+  | "csbig5"
+  | "cseuckr"
+  | "csgb2312"
+  | "cshproman8"
+  | "csibm1046"
+  | "csibm1124"
+  | "csibm1125"
+  | "csibm1129"
+  | "csibm1133"
+  | "csibm1161"
+  | "csibm1162"
+  | "csibm1163"
+  | "csibm437"
+  | "csibm737"
+  | "csibm775"
+  | "csibm850"
+  | "csibm852"
+  | "csibm855"
+  | "csibm856"
+  | "csibm857"
+  | "csibm858"
+  | "csibm860"
+  | "csibm861"
+  | "csibm862"
+  | "csibm863"
+  | "csibm864"
+  | "csibm865"
+  | "csibm866"
+  | "csibm869"
+  | "csibm922"
+  | "csiso14jisc6220ro"
+  | "csiso58gb231280"
+  | "csisolatin1"
+  | "csisolatin2"
+  | "csisolatin3"
+  | "csisolatin4"
+  | "csisolatin5"
+  | "csisolatin6"
+  | "csisolatinarabic"
+  | "csisolatincyrillic"
+  | "csisolatingreek"
+  | "csisolatinhebrew"
+  | "cskoi8r"
+  | "csksc56011987"
+  | "csmacintosh"
+  | "cspc775baltic"
+  | "cspc850multilingual"
+  | "cspc862latinhebrew"
+  | "cspc8codepage437"
+  | "cspcp852"
+  | "csshiftjis"
+  | "cyrillic"
+  | "ecma114"
+  | "ecma118"
+  | "elot928"
+  | "euccn"
+  | "eucjp"
+  | "euckr"
+  | "gb18030"
+  | "gb198880"
+  | "gb2312"
+  | "gb23121980"
+  | "gb231280"
+  | "gbk"
+  | "georgianacademy"
+  | "georgianps"
+  | "greek"
+  | "greek8"
+  | "hebrew"
+  | "hebrew8"
+  | "hex"
+  | "hproman8"
+  | "ibm1046"
+  | "ibm1051"
+  | "ibm1124"
+  | "ibm1125"
+  | "ibm1129"
+  | "ibm1133"
+  | "ibm1161"
+  | "ibm1162"
+  | "ibm1163"
+  | "ibm1168"
+  | "ibm367"
+  | "ibm437"
+  | "ibm737"
+  | "ibm775"
+  | "ibm808"
+  | "ibm819"
+  | "ibm850"
+  | "ibm852"
+  | "ibm855"
+  | "ibm856"
+  | "ibm857"
+  | "ibm858"
+  | "ibm860"
+  | "ibm861"
+  | "ibm862"
+  | "ibm863"
+  | "ibm864"
+  | "ibm865"
+  | "ibm866"
+  | "ibm869"
+  | "ibm878"
+  | "ibm922"
+  | "iso646cn"
+  | "iso646irv"
+  | "iso646jp"
+  | "iso646us"
+  | "iso88591"
+  | "iso885910"
+  | "iso885911"
+  | "iso885913"
+  | "iso885914"
+  | "iso885915"
+  | "iso885916"
+  | "iso88592"
+  | "iso88593"
+  | "iso88594"
+  | "iso88595"
+  | "iso88596"
+  | "iso88597"
+  | "iso88598"
+  | "iso88599"
+  | "isoceltic"
+  | "isoir100"
+  | "isoir101"
+  | "isoir109"
+  | "isoir110"
+  | "isoir126"
+  | "isoir127"
+  | "isoir138"
+  | "isoir14"
+  | "isoir144"
+  | "isoir148"
+  | "isoir149"
+  | "isoir157"
+  | "isoir166"
+  | "isoir179"
+  | "isoir199"
+  | "isoir203"
+  | "isoir226"
+  | "isoir57"
+  | "isoir58"
+  | "isoir6"
+  | "jisc62201969ro"
+  | "jp"
+  | "koi8r"
+  | "koi8ru"
+  | "koi8t"
+  | "koi8u"
+  | "korean"
+  | "ksc5601"
+  | "ksc56011987"
+  | "ksc56011989"
+  | "l1"
+  | "l10"
+  | "l2"
+  | "l3"
+  | "l4"
+  | "l5"
+  | "l6"
+  | "l7"
+  | "l8"
+  | "l9"
+  | "latin1"
+  | "latin10"
+  | "latin2"
+  | "latin3"
+  | "latin4"
+  | "latin5"
+  | "latin6"
+  | "latin7"
+  | "latin8"
+  | "latin9"
+  | "mac"
+  | "maccenteuro"
+  | "maccroatian"
+  | "maccyrillic"
+  | "macgreek"
+  | "maciceland"
+  | "macintosh"
+  | "macroman"
+  | "macromania"
+  | "macthai"
+  | "macturkish"
+  | "macukraine"
+  | "mik"
+  | "ms31j"
+  | "ms932"
+  | "ms936"
+  | "ms949"
+  | "ms950"
+  | "msansi"
+  | "msarab"
+  | "mscyrl"
+  | "msee"
+  | "msgreek"
+  | "mshebr"
+  | "mskanji"
+  | "msturk"
+  | "pt154"
+  | "r8"
+  | "rk1048"
+  | "roman8"
+  | "shiftjis"
+  | "sjis"
+  | "strk10482002"
+  | "tcvn"
+  | "tcvn5712"
+  | "tcvn57121"
+  | "thai"
+  | "thai8"
+  | "tis620"
+  | "tis6200"
+  | "tis62025291"
+  | "tis62025330"
+  | "turkish"
+  | "turkish8"
+  | "ucs2"
+  | "ucs4"
+  | "ucs4be"
+  | "ucs4le"
+  | "unicode11utf7"
+  | "unicode11utf8"
+  | "us"
+  | "usascii"
+  | "utf16"
+  | "utf16be"
+  | "utf16le"
+  | "utf32"
+  | "utf32be"
+  | "utf32le"
+  | "utf7"
+  | "utf7imap"
+  | "utf8"
+  | "viscii"
+  | "win1250"
+  | "win1251"
+  | "win1252"
+  | "win1253"
+  | "win1254"
+  | "win1255"
+  | "win1256"
+  | "win1257"
+  | "win1258"
+  | "win874"
+  | "winbaltrim"
+  | "windows1250"
+  | "windows1251"
+  | "windows1252"
+  | "windows1253"
+  | "windows1254"
+  | "windows1255"
+  | "windows1256"
+  | "windows1257"
+  | "windows1258"
+  | "windows31j"
+  | "windows874"
+  | "windows932"
+  | "windows936"
+  | "windows949"
+  | "windows950"
+  | "xgbk"
+  | "xroman8"
+  | "xsjis"
+  | "xxbig5"
+  | (string & {});
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 6838bf9e..6834e09e 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -1,11 +1,3 @@
-/*
- * ---------------------------------------------------------------------------------------------
- * DO NOT EDIT THIS FILE MANUALLY.
- * THIS FILE IS AUTOMATICALLY GENERATED.
- * TO UPDATE, RUN `npm run typegen` AND COMMIT THE CHANGES.
- * ---------------------------------------------------------------------------------------------
- */
-
 /*---------------------------------------------------------------------------------------------
  * REQUIREMENT: This definition is dependent on the @types/node definition.
  *
@@ -14,421 +6,7 @@
  * This file provides detailed typings for the public API of iconv-lite
  *--------------------------------------------------------------------------------------------*/
 
-/** A union of all supported encoding strings in `iconv-lite`. */
-export type SupportedEncoding =
-  | "10000"
-  | "10006"
-  | "10007"
-  | "10029"
-  | "10079"
-  | "10081"
-  | "1046"
-  | "1124"
-  | "1125"
-  | "1129"
-  | "1133"
-  | "1161"
-  | "1162"
-  | "1163"
-  | "1250"
-  | "1251"
-  | "1252"
-  | "1253"
-  | "1254"
-  | "1255"
-  | "1256"
-  | "1257"
-  | "1258"
-  | "20866"
-  | "21866"
-  | "28591"
-  | "28592"
-  | "28593"
-  | "28594"
-  | "28595"
-  | "28596"
-  | "28597"
-  | "28598"
-  | "28599"
-  | "28600"
-  | "28601"
-  | "28603"
-  | "28604"
-  | "28605"
-  | "28606"
-  | "437"
-  | "737"
-  | "775"
-  | "808"
-  | "850"
-  | "852"
-  | "855"
-  | "856"
-  | "857"
-  | "858"
-  | "860"
-  | "861"
-  | "862"
-  | "863"
-  | "864"
-  | "865"
-  | "866"
-  | "869"
-  | "874"
-  | "922"
-  | "932"
-  | "936"
-  | "949"
-  | "950"
-  | "ansix34"
-  | "ansix341968"
-  | "ansix341986"
-  | "arabic"
-  | "arabic8"
-  | "armscii8"
-  | "ascii"
-  | "ascii8bit"
-  | "asmo708"
-  | "base64"
-  | "big5"
-  | "big5hkscs"
-  | "binary"
-  | "celtic"
-  | "celtic8"
-  | "cesu8"
-  | "chinese"
-  | "cn"
-  | "cnbig5"
-  | "cp1046"
-  | "cp1124"
-  | "cp1125"
-  | "cp1129"
-  | "cp1133"
-  | "cp1161"
-  | "cp1162"
-  | "cp1163"
-  | "cp1250"
-  | "cp1251"
-  | "cp1252"
-  | "cp1253"
-  | "cp1254"
-  | "cp1255"
-  | "cp1256"
-  | "cp1257"
-  | "cp1258"
-  | "cp20866"
-  | "cp21866"
-  | "cp28591"
-  | "cp28592"
-  | "cp28593"
-  | "cp28594"
-  | "cp28595"
-  | "cp28596"
-  | "cp28597"
-  | "cp28598"
-  | "cp28599"
-  | "cp28600"
-  | "cp28601"
-  | "cp28603"
-  | "cp28604"
-  | "cp28605"
-  | "cp28606"
-  | "cp367"
-  | "cp437"
-  | "cp720"
-  | "cp737"
-  | "cp775"
-  | "cp808"
-  | "cp819"
-  | "cp850"
-  | "cp852"
-  | "cp855"
-  | "cp856"
-  | "cp857"
-  | "cp858"
-  | "cp860"
-  | "cp861"
-  | "cp862"
-  | "cp863"
-  | "cp864"
-  | "cp865"
-  | "cp866"
-  | "cp869"
-  | "cp874"
-  | "cp922"
-  | "cp932"
-  | "cp936"
-  | "cp949"
-  | "cp950"
-  | "cpgr"
-  | "csascii"
-  | "csbig5"
-  | "cseuckr"
-  | "csgb2312"
-  | "cshproman8"
-  | "csibm1046"
-  | "csibm1124"
-  | "csibm1125"
-  | "csibm1129"
-  | "csibm1133"
-  | "csibm1161"
-  | "csibm1162"
-  | "csibm1163"
-  | "csibm437"
-  | "csibm737"
-  | "csibm775"
-  | "csibm850"
-  | "csibm852"
-  | "csibm855"
-  | "csibm856"
-  | "csibm857"
-  | "csibm858"
-  | "csibm860"
-  | "csibm861"
-  | "csibm862"
-  | "csibm863"
-  | "csibm864"
-  | "csibm865"
-  | "csibm866"
-  | "csibm869"
-  | "csibm922"
-  | "csiso14jisc6220ro"
-  | "csiso58gb231280"
-  | "csisolatin1"
-  | "csisolatin2"
-  | "csisolatin3"
-  | "csisolatin4"
-  | "csisolatin5"
-  | "csisolatin6"
-  | "csisolatinarabic"
-  | "csisolatincyrillic"
-  | "csisolatingreek"
-  | "csisolatinhebrew"
-  | "cskoi8r"
-  | "csksc56011987"
-  | "csmacintosh"
-  | "cspc775baltic"
-  | "cspc850multilingual"
-  | "cspc862latinhebrew"
-  | "cspc8codepage437"
-  | "cspcp852"
-  | "csshiftjis"
-  | "cyrillic"
-  | "ecma114"
-  | "ecma118"
-  | "elot928"
-  | "euccn"
-  | "eucjp"
-  | "euckr"
-  | "gb18030"
-  | "gb198880"
-  | "gb2312"
-  | "gb23121980"
-  | "gb231280"
-  | "gbk"
-  | "georgianacademy"
-  | "georgianps"
-  | "greek"
-  | "greek8"
-  | "hebrew"
-  | "hebrew8"
-  | "hex"
-  | "hproman8"
-  | "ibm1046"
-  | "ibm1051"
-  | "ibm1124"
-  | "ibm1125"
-  | "ibm1129"
-  | "ibm1133"
-  | "ibm1161"
-  | "ibm1162"
-  | "ibm1163"
-  | "ibm1168"
-  | "ibm367"
-  | "ibm437"
-  | "ibm737"
-  | "ibm775"
-  | "ibm808"
-  | "ibm819"
-  | "ibm850"
-  | "ibm852"
-  | "ibm855"
-  | "ibm856"
-  | "ibm857"
-  | "ibm858"
-  | "ibm860"
-  | "ibm861"
-  | "ibm862"
-  | "ibm863"
-  | "ibm864"
-  | "ibm865"
-  | "ibm866"
-  | "ibm869"
-  | "ibm878"
-  | "ibm922"
-  | "iso646cn"
-  | "iso646irv"
-  | "iso646jp"
-  | "iso646us"
-  | "iso88591"
-  | "iso885910"
-  | "iso885911"
-  | "iso885913"
-  | "iso885914"
-  | "iso885915"
-  | "iso885916"
-  | "iso88592"
-  | "iso88593"
-  | "iso88594"
-  | "iso88595"
-  | "iso88596"
-  | "iso88597"
-  | "iso88598"
-  | "iso88599"
-  | "isoceltic"
-  | "isoir100"
-  | "isoir101"
-  | "isoir109"
-  | "isoir110"
-  | "isoir126"
-  | "isoir127"
-  | "isoir138"
-  | "isoir14"
-  | "isoir144"
-  | "isoir148"
-  | "isoir149"
-  | "isoir157"
-  | "isoir166"
-  | "isoir179"
-  | "isoir199"
-  | "isoir203"
-  | "isoir226"
-  | "isoir57"
-  | "isoir58"
-  | "isoir6"
-  | "jisc62201969ro"
-  | "jp"
-  | "koi8r"
-  | "koi8ru"
-  | "koi8t"
-  | "koi8u"
-  | "korean"
-  | "ksc5601"
-  | "ksc56011987"
-  | "ksc56011989"
-  | "l1"
-  | "l10"
-  | "l2"
-  | "l3"
-  | "l4"
-  | "l5"
-  | "l6"
-  | "l7"
-  | "l8"
-  | "l9"
-  | "latin1"
-  | "latin10"
-  | "latin2"
-  | "latin3"
-  | "latin4"
-  | "latin5"
-  | "latin6"
-  | "latin7"
-  | "latin8"
-  | "latin9"
-  | "mac"
-  | "maccenteuro"
-  | "maccroatian"
-  | "maccyrillic"
-  | "macgreek"
-  | "maciceland"
-  | "macintosh"
-  | "macroman"
-  | "macromania"
-  | "macthai"
-  | "macturkish"
-  | "macukraine"
-  | "mik"
-  | "ms31j"
-  | "ms932"
-  | "ms936"
-  | "ms949"
-  | "ms950"
-  | "msansi"
-  | "msarab"
-  | "mscyrl"
-  | "msee"
-  | "msgreek"
-  | "mshebr"
-  | "mskanji"
-  | "msturk"
-  | "pt154"
-  | "r8"
-  | "rk1048"
-  | "roman8"
-  | "shiftjis"
-  | "sjis"
-  | "strk10482002"
-  | "tcvn"
-  | "tcvn5712"
-  | "tcvn57121"
-  | "thai"
-  | "thai8"
-  | "tis620"
-  | "tis6200"
-  | "tis62025291"
-  | "tis62025330"
-  | "turkish"
-  | "turkish8"
-  | "ucs2"
-  | "ucs4"
-  | "ucs4be"
-  | "ucs4le"
-  | "unicode11utf7"
-  | "unicode11utf8"
-  | "us"
-  | "usascii"
-  | "utf16"
-  | "utf16be"
-  | "utf16le"
-  | "utf32"
-  | "utf32be"
-  | "utf32le"
-  | "utf7"
-  | "utf7imap"
-  | "utf8"
-  | "viscii"
-  | "win1250"
-  | "win1251"
-  | "win1252"
-  | "win1253"
-  | "win1254"
-  | "win1255"
-  | "win1256"
-  | "win1257"
-  | "win1258"
-  | "win874"
-  | "winbaltrim"
-  | "windows1250"
-  | "windows1251"
-  | "windows1252"
-  | "windows1253"
-  | "windows1254"
-  | "windows1255"
-  | "windows1256"
-  | "windows1257"
-  | "windows1258"
-  | "windows31j"
-  | "windows874"
-  | "windows932"
-  | "windows936"
-  | "windows949"
-  | "windows950"
-  | "xgbk"
-  | "xroman8"
-  | "xsjis"
-  | "xxbig5"
-  | (string & {});
+import type { SupportedEncoding } from "./encodings";
 
 // --- Options ---
 

From 088e997def33ee58e727ba66b205c1e2b7948cf3 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sat, 16 Aug 2025 19:06:03 +0100
Subject: [PATCH 23/33] remove unused `index-template.d.ts`

---
 lib/index-template.d.ts | 125 ----------------------------------------
 1 file changed, 125 deletions(-)
 delete mode 100644 lib/index-template.d.ts

diff --git a/lib/index-template.d.ts b/lib/index-template.d.ts
deleted file mode 100644
index 1f5ba386..00000000
--- a/lib/index-template.d.ts
+++ /dev/null
@@ -1,125 +0,0 @@
-/*---------------------------------------------------------------------------------------------
- * REQUIREMENT: This definition is dependent on the @types/node definition.
- *
- * Install with `npm install @types/node --save-dev`
- *
- * This file provides detailed typings for the public API of iconv-lite
- *--------------------------------------------------------------------------------------------*/
-
-/** A union of all supported encoding strings in `iconv-lite`. */
-export type SupportedEncoding = string;
-
-// --- Options ---
-
-export interface DecodeOptions {
-  /** Strip the byte order mark (BOM) from the input, when decoding. @default true */
-  stripBOM?: boolean;
-  /** Override the default endianness for `UTF-16` and `UTF-32` decodings. */
-  defaultEncoding?: "utf16be" | "utf32be";
-}
-
-export interface EncodeOptions {
-  /** Add a byte order mark (BOM) to the output, when encoding. @default false */
-  addBOM?: boolean;
-  /** Override the default endianness for `UTF-32` encoding. */
-  defaultEncoding?: "utf32be";
-}
-
-// --- Return values ---
-
-export interface EncoderStream {
-  write(str: string): Buffer;
-  end(): Buffer | undefined;
-}
-
-export interface DecoderStream {
-  write(buf: Buffer): string;
-  end(): string | undefined;
-}
-
-export interface Codec {
-  encoder: new (options?: EncodeOptions, codec?: any) => EncoderStream;
-  decoder: new (options?: DecodeOptions, codec?: any) => DecoderStream;
-  [key: string]: any;
-}
-
-declare const iconv: {
-  // --- Basic API ---
-
-  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-  encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
-
-  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-  decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
-
-  /** Checks if a given encoding is supported by `iconv-lite`. */
-  encodingExists(encoding: string): encoding is SupportedEncoding;
-
-  // --- Legacy aliases ---
-
-  /** Legacy alias for {@link iconv.encode}. */
-  toEncoding: typeof iconv.encode;
-
-  /** Legacy alias for {@link iconv.decode}. */
-  fromEncoding: typeof iconv.decode;
-
-  // --- Stream API ---
-
-  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
-  decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
-
-  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
-  encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
-
-  /**
-   * Explicitly enable Streaming API in browser environments by passing in:
-   * ```js
-   * require('stream')
-   * ```
-   * @example iconv.enableStreamingAPI(require('stream'));
-   */
-  enableStreamingAPI(stream_module: any): void;
-
-  // --- Low-level stream APIs ---
-
-  /** Creates and returns a low-level encoder stream. */
-  getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
-
-  /** Creates and returns a low-level decoder stream. */
-  getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
-
-  /**
-   * Returns a codec object for the given `encoding`.
-   * @throws If the `encoding` is not recognized.
-   */
-  getCodec(encoding: SupportedEncoding): Codec;
-
-  /** Strips all non-alphanumeric characters and appended year from `encoding`. */
-  _canonicalizeEncoding(encoding: SupportedEncoding): string;
-
-  // --- Properties ---
-
-  /** A cache of all loaded encoding definitions. */
-  encodings: Record<
-    SupportedEncoding,
-    | string
-    | {
-        type: string;
-        [key: string]: any;
-      }
-  > | null;
-
-  /** A cache of initialized codec objects. */
-  _codecDataCache: Record<string, Codec>;
-
-  /** The character used for untranslatable `Unicode` characters. @default "�" */
-  defaultCharUnicode: string;
-
-  /** The character used for untranslatable `single-byte` characters. @default "?" */
-  defaultCharSingleByte: string;
-
-  /** @readonly Whether or not, Streaming API is enabled. */
-  readonly supportsStreams: boolean;
-};
-
-export default iconv;

From c4d3a8010be2a9565d6f26e81f62150856e76fd2 Mon Sep 17 00:00:00 2001
From: Sebastian Beltran <bjohansebas@gmail.com>
Date: Sat, 16 Aug 2025 23:54:44 -0500
Subject: [PATCH 24/33] test: add typescript test

Signed-off-by: Sebastian Beltran <bjohansebas@gmail.com>
---
 .github/workflows/ci.yml      |  28 +++++-
 .github/workflows/iojs.yml    |   2 +-
 .npmignore                    |   3 +-
 eslint.config.js              |   3 +-
 generation/gen-typings.js     |   4 +-
 lib/index.d.ts                | 175 ++++++++++++++++++----------------
 package.json                  |   4 +
 test/types/iconv.ts           |   9 ++
 test/types/import.ts          |   2 +
 tsconfig.json                 |  13 +++
 {lib => types}/encodings.d.ts |   4 +-
 11 files changed, 153 insertions(+), 94 deletions(-)
 create mode 100644 test/types/iconv.ts
 create mode 100644 test/types/import.ts
 create mode 100644 tsconfig.json
 rename {lib => types}/encodings.d.ts (99%)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 4a9749ae..49833860 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -176,7 +176,7 @@ jobs:
         shell: bash
 
       - name: Remove npm module(s) ${{ matrix.npm-rm }}
-        run: npm rm --silent --save-dev ${{ matrix.npm-rm }} neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint
+        run: npm rm --silent --save-dev ${{ matrix.npm-rm }} neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint typescript @arethetypeswrong/cli expect-type
         if: matrix.npm-rm != ''
 
       - name: Install Node version specific dev deps
@@ -249,9 +249,31 @@ jobs:
           node-version: ${{ matrix.node-version }}
 
       - name: Remove npm module(s) iconv, eslint, neostandard, @stylistic/eslint-plugin-js, @stylistic/eslint-plugin
-        run: npm rm --silent --save-dev iconv neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint
+        run: npm rm --silent --save-dev iconv neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint typescript @arethetypeswrong/cli expect-type
 
       - name: Webpack test
         shell: bash
         run: |
-          npm run test:webpack
\ No newline at end of file
+          npm run test:webpack
+
+  test_typescript:
+    needs:
+      - lint
+      - coverage
+    runs-on: 'ubuntu-latest'
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install
+        run: |
+          npm install --ignore-scripts
+
+      - name: Run typescript tests
+        run: npm run test:typescript
\ No newline at end of file
diff --git a/.github/workflows/iojs.yml b/.github/workflows/iojs.yml
index 1c824288..4761c959 100644
--- a/.github/workflows/iojs.yml
+++ b/.github/workflows/iojs.yml
@@ -45,7 +45,7 @@ jobs:
         npm config set shrinkwrap false
 
     - name: Remove npm module(s) ${{ matrix.npm-rm }}
-      run: npm rm --silent --save-dev ${{ matrix.npm-rm }} neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint
+      run: npm rm --silent --save-dev ${{ matrix.npm-rm }} neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint typescript @arethetypeswrong/cli expect-type
       if: matrix.npm-rm != ''
 
     - name: Install npm module(s) ${{ matrix.npm-i }}
diff --git a/.npmignore b/.npmignore
index 943eee2a..2165a403 100644
--- a/.npmignore
+++ b/.npmignore
@@ -10,4 +10,5 @@ performance
 .nyc_output
 eslint.config.js
 *.tgz
-.git-blame-ignore-revs
\ No newline at end of file
+.git-blame-ignore-revs
+tsconfig.json
\ No newline at end of file
diff --git a/eslint.config.js b/eslint.config.js
index 34c0efd5..c81051d5 100644
--- a/eslint.config.js
+++ b/eslint.config.js
@@ -8,7 +8,8 @@ module.exports = [
       "encodings/sbcs-data-generated.js", // This a generate file
       // We need work on this
       "generation"
-    ]
+    ],
+    ts: true
   }),
   {
     rules: {
diff --git a/generation/gen-typings.js b/generation/gen-typings.js
index fdec2214..95dd27bb 100644
--- a/generation/gen-typings.js
+++ b/generation/gen-typings.js
@@ -69,10 +69,10 @@ function generateTypingsFile() {
 
   const fileContent = `${generatedHeader}\n
 /** A union of all supported encoding strings in \`iconv-lite\`. */
-export type SupportedEncoding =\n${supportedEncodingType}\n  | (string & {});
+export type Encodings =\n${supportedEncodingType}\n  | (string & {})
 `;
 
-  const outputPath = path.join(__dirname, "..", "lib", "encodings.d.ts");
+  const outputPath = path.join(__dirname, "..", "types", "encodings.d.ts");
   fs.writeFileSync(outputPath, fileContent, "utf8");
 }
 
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 6834e09e..4f2710dc 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -1,124 +1,131 @@
-/*---------------------------------------------------------------------------------------------
+/* ---------------------------------------------------------------------------------------------
  * REQUIREMENT: This definition is dependent on the @types/node definition.
  *
  * Install with `npm install @types/node --save-dev`
  *
  * This file provides detailed typings for the public API of iconv-lite
- *--------------------------------------------------------------------------------------------*/
+ *-------------------------------------------------------------------------------------------- */
 
-import type { SupportedEncoding } from "./encodings";
+import type { Encodings } from "../types/encodings"
 
 // --- Options ---
 
-export interface DecodeOptions {
-  /** Strip the byte order mark (BOM) from the input, when decoding. @default true */
-  stripBOM?: boolean;
-  /** Override the default endianness for `UTF-16` and `UTF-32` decodings. */
-  defaultEncoding?: "utf16be" | "utf32be";
-}
+declare namespace iconv {
+  export interface DecodeOptions {
+    /** Strip the byte order mark (BOM) from the input, when decoding. @default true */
+    stripBOM?: boolean;
+    /** Override the default endianness for `UTF-16` and `UTF-32` decodings. */
+    defaultEncoding?: "utf16be" | "utf32be";
+  }
 
-export interface EncodeOptions {
-  /** Add a byte order mark (BOM) to the output, when encoding. @default false */
-  addBOM?: boolean;
-  /** Override the default endianness for `UTF-32` encoding. */
-  defaultEncoding?: "utf32be";
-}
+  export interface EncodeOptions {
+    /** Add a byte order mark (BOM) to the output, when encoding. @default false */
+    addBOM?: boolean;
+    /** Override the default endianness for `UTF-32` encoding. */
+    defaultEncoding?: "utf32be";
+  }
 
-// --- Return values ---
+  // --- Return values ---
 
-export interface EncoderStream {
-  write(str: string): Buffer;
-  end(): Buffer | undefined;
-}
+  export interface EncoderStream {
+    write(str: string): Buffer;
+    end(): Buffer | undefined;
+  }
 
-export interface DecoderStream {
-  write(buf: Buffer): string;
-  end(): string | undefined;
-}
+  export interface DecoderStream {
+    write(buf: Buffer): string;
+    end(): string | undefined;
+  }
 
-export interface Codec {
-  encoder: new (options?: EncodeOptions, codec?: any) => EncoderStream;
-  decoder: new (options?: DecodeOptions, codec?: any) => DecoderStream;
-  [key: string]: any;
-}
+  export interface Codec {
+    encoder: new (options?: EncodeOptions, codec?: any) => EncoderStream;
+    decoder: new (options?: DecodeOptions, codec?: any) => DecoderStream;
+    [key: string]: any;
+  }
 
-declare const iconv: {
-  // --- Basic API ---
+  const iconv: {
+    // --- Basic API ---
 
-  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-  encode(content: string, encoding: SupportedEncoding, options?: EncodeOptions): Buffer;
+    /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
+    encode(content: string, encoding: Encodings, options?: EncodeOptions): Buffer;
 
-  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-  decode(buffer: Buffer | Uint8Array, encoding: SupportedEncoding, options?: DecodeOptions): string;
+    /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+    decode(buffer: Buffer | Uint8Array, encoding: Encodings, options?: DecodeOptions): string;
 
-  /** Checks if a given encoding is supported by `iconv-lite`. */
-  encodingExists(encoding: string): encoding is SupportedEncoding;
+    /** Checks if a given encoding is supported by `iconv-lite`. */
+    encodingExists(encoding: string): encoding is Encodings;
 
-  // --- Legacy aliases ---
+    // --- Legacy aliases ---
 
-  /** Legacy alias for {@link iconv.encode}. */
-  toEncoding: typeof iconv.encode;
+    /** Legacy alias for {@link iconv.encode}. */
+    toEncoding: typeof iconv.encode;
 
-  /** Legacy alias for {@link iconv.decode}. */
-  fromEncoding: typeof iconv.decode;
+    /** Legacy alias for {@link iconv.decode}. */
+    fromEncoding: typeof iconv.decode;
 
-  // --- Stream API ---
+    // --- Stream API ---
 
-  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
-  decodeStream(encoding: SupportedEncoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
+    /** Creates a stream that decodes binary data from a given `encoding` into strings. */
+    decodeStream(encoding: Encodings, options?: DecodeOptions): NodeJS.ReadWriteStream;
 
-  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
-  encodeStream(encoding: SupportedEncoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
+    /** Creates a stream that encodes strings into binary data in a given `encoding`. */
+    encodeStream(encoding: Encodings, options?: EncodeOptions): NodeJS.ReadWriteStream;
 
-  /**
-   * Explicitly enable Streaming API in browser environments by passing in:
-   * ```js
-   * require('stream')
-   * ```
-   * @example iconv.enableStreamingAPI(require('stream'));
-   */
-  enableStreamingAPI(stream_module: any): void;
+    /**
+     * Explicitly enable Streaming API in browser environments by passing in:
+     * ```js
+     * require('stream')
+     * ```
+     * @example iconv.enableStreamingAPI(require('stream'));
+     */
+    enableStreamingAPI(stream_module: any): void;
 
-  // --- Low-level stream APIs ---
+    // --- Low-level stream APIs ---
 
-  /** Creates and returns a low-level encoder stream. */
-  getEncoder(encoding: SupportedEncoding, options?: EncodeOptions): EncoderStream;
+    /** Creates and returns a low-level encoder stream. */
+    getEncoder(encoding: Encodings, options?: EncodeOptions): EncoderStream;
 
-  /** Creates and returns a low-level decoder stream. */
-  getDecoder(encoding: SupportedEncoding, options?: DecodeOptions): DecoderStream;
+    /** Creates and returns a low-level decoder stream. */
+    getDecoder(encoding: Encodings, options?: DecodeOptions): DecoderStream;
 
-  /**
-   * Returns a codec object for the given `encoding`.
-   * @throws If the `encoding` is not recognized.
-   */
-  getCodec(encoding: SupportedEncoding): Codec;
+    /**
+     * Returns a codec object for the given `encoding`.
+     * @throws If the `encoding` is not recognized.
+     */
+    getCodec(encoding: Encodings): Codec;
 
-  /** Strips all non-alphanumeric characters and appended year from `encoding`. */
-  _canonicalizeEncoding(encoding: SupportedEncoding): string;
+    /** Strips all non-alphanumeric characters and appended year from `encoding`. */
+    _canonicalizeEncoding(encoding: Encodings): string;
 
-  // --- Properties ---
+    // --- Properties ---
 
-  /** A cache of all loaded encoding definitions. */
-  encodings: Record<
-    SupportedEncoding,
-    | string
-    | {
+    /** A cache of all loaded encoding definitions. */
+    encodings: Record<
+      Encodings,
+      | string
+      | {
         type: string;
         [key: string]: any;
       }
-  > | null;
+    > | null;
 
-  /** A cache of initialized codec objects. */
-  _codecDataCache: Record<string, Codec>;
+    /** A cache of initialized codec objects. */
+    _codecDataCache: Record<string, Codec>;
 
-  /** The character used for untranslatable `Unicode` characters. @default "�" */
-  defaultCharUnicode: string;
+    /** The character used for untranslatable `Unicode` characters. @default "�" */
+    defaultCharUnicode: string;
 
-  /** The character used for untranslatable `single-byte` characters. @default "?" */
-  defaultCharSingleByte: string;
+    /** The character used for untranslatable `single-byte` characters. @default "?" */
+    defaultCharSingleByte: string;
 
-  /** @readonly Whether or not, Streaming API is enabled. */
-  readonly supportsStreams: boolean;
-};
+    /** @readonly Whether or not, Streaming API is enabled. */
+    readonly supportsStreams: boolean;
+  }
 
-export default iconv;
+  export type {
+    iconv,
+    Encodings
+  }
+  export { iconv as default }
+}
+export = iconv
diff --git a/package.json b/package.json
index b83f5e54..6e0fbd86 100644
--- a/package.json
+++ b/package.json
@@ -29,6 +29,7 @@
         "test:cov": "nyc --exclude test --reporter=html --reporter=text npm test",
         "test:performance": "node --allow-natives-syntax performance/index.js",
         "test:tap": "mocha --reporter tap --check-leaks --grep .",
+        "test:typescript": "tsc && attw --pack",
         "test:webpack": "npm pack && mv iconv-lite-*.tgz test/webpack/iconv-lite.tgz && cd test/webpack && npm install && npm run test && rm iconv-lite.tgz",
         "typegen": "node generation/gen-typings.js"
     },
@@ -36,18 +37,21 @@
         "stream": false
     },
     "devDependencies": {
+        "@arethetypeswrong/cli": "^0.17.4",
         "@stylistic/eslint-plugin": "^5.1.0",
         "@stylistic/eslint-plugin-js": "^4.1.0",
         "async": "^3.2.0",
         "bench-node": "^0.10.0",
         "eslint": "^9.0.0",
         "errto": "^0.2.1",
+        "expect-type": "^1.2.0",
         "iconv": "^2.3.5",
         "mocha": "^6.2.2",
         "neostandard": "^0.12.0",    
         "nyc": "^14.1.1",
         "request": "^2.88.2",
         "semver": "^6.3.0",
+        "typescript": "~5.9.2",
         "unorm": "^1.6.0"
     },
     "dependencies": {
diff --git a/test/types/iconv.ts b/test/types/iconv.ts
new file mode 100644
index 00000000..be2fff1c
--- /dev/null
+++ b/test/types/iconv.ts
@@ -0,0 +1,9 @@
+import iconv from "../../lib"
+import { expectTypeOf } from "expect-type"
+
+expectTypeOf(iconv._canonicalizeEncoding).toBeFunction()
+expectTypeOf(iconv.encode).toBeFunction()
+expectTypeOf(iconv.decode).toBeFunction()
+expectTypeOf(iconv.encodingExists).toBeFunction()
+expectTypeOf(iconv.toEncoding).toBeFunction()
+expectTypeOf(iconv.enableStreamingAPI).toBeFunction()
diff --git a/test/types/import.ts b/test/types/import.ts
new file mode 100644
index 00000000..a27bba76
--- /dev/null
+++ b/test/types/import.ts
@@ -0,0 +1,2 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import iconv, { iconv as iconvLite, Codec, DecodeOptions, DecoderStream, EncodeOptions, EncoderStream, Encodings } from "../../lib"
diff --git a/tsconfig.json b/tsconfig.json
new file mode 100644
index 00000000..24d7fb7f
--- /dev/null
+++ b/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": [ "es2015" ],
+    "module": "commonjs",
+    "noEmit": true,
+    "strict": true
+  },
+  "include": [
+    "./test/types/**/*.ts",
+    "./**/*.d.ts"
+  ]
+}
\ No newline at end of file
diff --git a/lib/encodings.d.ts b/types/encodings.d.ts
similarity index 99%
rename from lib/encodings.d.ts
rename to types/encodings.d.ts
index dc76893b..1a8c9f71 100644
--- a/lib/encodings.d.ts
+++ b/types/encodings.d.ts
@@ -7,7 +7,7 @@
  */
 
 /** A union of all supported encoding strings in `iconv-lite`. */
-export type SupportedEncoding =
+export type Encodings =
   | "10000"
   | "10006"
   | "10007"
@@ -420,4 +420,4 @@ export type SupportedEncoding =
   | "xroman8"
   | "xsjis"
   | "xxbig5"
-  | (string & {});
+  | (string & {})

From 37f734a6185cd8e6c47d4805729d8b04eeccd3e0 Mon Sep 17 00:00:00 2001
From: Sebastian Beltran <bjohansebas@gmail.com>
Date: Sat, 16 Aug 2025 23:59:49 -0500
Subject: [PATCH 25/33] fixup install node types

Signed-off-by: Sebastian Beltran <bjohansebas@gmail.com>
---
 package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/package.json b/package.json
index 6e0fbd86..297c8141 100644
--- a/package.json
+++ b/package.json
@@ -40,6 +40,7 @@
         "@arethetypeswrong/cli": "^0.17.4",
         "@stylistic/eslint-plugin": "^5.1.0",
         "@stylistic/eslint-plugin-js": "^4.1.0",
+        "@types/node": "^24.0.12",
         "async": "^3.2.0",
         "bench-node": "^0.10.0",
         "eslint": "^9.0.0",

From 4977980c9b82391f34ba375c5da89ed3a0dc050e Mon Sep 17 00:00:00 2001
From: Sebastian Beltran <bjohansebas@gmail.com>
Date: Sun, 17 Aug 2025 00:01:47 -0500
Subject: [PATCH 26/33] fixup ci

Signed-off-by: Sebastian Beltran <bjohansebas@gmail.com>
---
 .github/workflows/ci.yml   | 4 ++--
 .github/workflows/iojs.yml | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 49833860..153fd0da 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -176,7 +176,7 @@ jobs:
         shell: bash
 
       - name: Remove npm module(s) ${{ matrix.npm-rm }}
-        run: npm rm --silent --save-dev ${{ matrix.npm-rm }} neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint typescript @arethetypeswrong/cli expect-type
+        run: npm rm --silent --save-dev ${{ matrix.npm-rm }} neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint typescript @arethetypeswrong/cli expect-type @types/node
         if: matrix.npm-rm != ''
 
       - name: Install Node version specific dev deps
@@ -249,7 +249,7 @@ jobs:
           node-version: ${{ matrix.node-version }}
 
       - name: Remove npm module(s) iconv, eslint, neostandard, @stylistic/eslint-plugin-js, @stylistic/eslint-plugin
-        run: npm rm --silent --save-dev iconv neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint typescript @arethetypeswrong/cli expect-type
+        run: npm rm --silent --save-dev iconv neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint typescript @arethetypeswrong/cli expect-type @types/node
 
       - name: Webpack test
         shell: bash
diff --git a/.github/workflows/iojs.yml b/.github/workflows/iojs.yml
index 4761c959..5706e326 100644
--- a/.github/workflows/iojs.yml
+++ b/.github/workflows/iojs.yml
@@ -45,7 +45,7 @@ jobs:
         npm config set shrinkwrap false
 
     - name: Remove npm module(s) ${{ matrix.npm-rm }}
-      run: npm rm --silent --save-dev ${{ matrix.npm-rm }} neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint typescript @arethetypeswrong/cli expect-type
+      run: npm rm --silent --save-dev ${{ matrix.npm-rm }} neostandard @stylistic/eslint-plugin-js @stylistic/eslint-plugin eslint typescript @arethetypeswrong/cli expect-type @types/node
       if: matrix.npm-rm != ''
 
     - name: Install npm module(s) ${{ matrix.npm-i }}

From ea6d519593a05a1c324d297c67b04a8d79417607 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sun, 17 Aug 2025 16:12:51 +0100
Subject: [PATCH 27/33] fix imports and type name

---
 generation/gen-typings.js |   2 +-
 lib/index.d.ts            | 171 ++++++++++++++++++--------------------
 types/encodings.d.ts      |   2 +-
 3 files changed, 84 insertions(+), 91 deletions(-)

diff --git a/generation/gen-typings.js b/generation/gen-typings.js
index 95dd27bb..9d976110 100644
--- a/generation/gen-typings.js
+++ b/generation/gen-typings.js
@@ -69,7 +69,7 @@ function generateTypingsFile() {
 
   const fileContent = `${generatedHeader}\n
 /** A union of all supported encoding strings in \`iconv-lite\`. */
-export type Encodings =\n${supportedEncodingType}\n  | (string & {})
+export type Encoding =\n${supportedEncodingType}\n  | (string & {})
 `;
 
   const outputPath = path.join(__dirname, "..", "types", "encodings.d.ts");
diff --git a/lib/index.d.ts b/lib/index.d.ts
index 4f2710dc..ef74d8f2 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -6,126 +6,119 @@
  * This file provides detailed typings for the public API of iconv-lite
  *-------------------------------------------------------------------------------------------- */
 
-import type { Encodings } from "../types/encodings"
+import type { Encoding } from "../types/encodings";
 
 // --- Options ---
 
-declare namespace iconv {
-  export interface DecodeOptions {
-    /** Strip the byte order mark (BOM) from the input, when decoding. @default true */
-    stripBOM?: boolean;
-    /** Override the default endianness for `UTF-16` and `UTF-32` decodings. */
-    defaultEncoding?: "utf16be" | "utf32be";
-  }
+export interface DecodeOptions {
+  /** Strip the byte order mark (BOM) from the input, when decoding. @default true */
+  stripBOM?: boolean;
+  /** Override the default endianness for `UTF-16` and `UTF-32` decodings. */
+  defaultEncoding?: "utf16be" | "utf32be";
+}
 
-  export interface EncodeOptions {
-    /** Add a byte order mark (BOM) to the output, when encoding. @default false */
-    addBOM?: boolean;
-    /** Override the default endianness for `UTF-32` encoding. */
-    defaultEncoding?: "utf32be";
-  }
+export interface EncodeOptions {
+  /** Add a byte order mark (BOM) to the output, when encoding. @default false */
+  addBOM?: boolean;
+  /** Override the default endianness for `UTF-32` encoding. */
+  defaultEncoding?: "utf32be";
+}
 
-  // --- Return values ---
+// --- Return values ---
 
-  export interface EncoderStream {
-    write(str: string): Buffer;
-    end(): Buffer | undefined;
-  }
+export interface EncoderStream {
+  write(str: string): Buffer;
+  end(): Buffer | undefined;
+}
 
-  export interface DecoderStream {
-    write(buf: Buffer): string;
-    end(): string | undefined;
-  }
+export interface DecoderStream {
+  write(buf: Buffer): string;
+  end(): string | undefined;
+}
 
-  export interface Codec {
-    encoder: new (options?: EncodeOptions, codec?: any) => EncoderStream;
-    decoder: new (options?: DecodeOptions, codec?: any) => DecoderStream;
-    [key: string]: any;
-  }
+export interface Codec {
+  encoder: new (options?: EncodeOptions, codec?: any) => EncoderStream;
+  decoder: new (options?: DecodeOptions, codec?: any) => DecoderStream;
+  [key: string]: any;
+}
 
-  const iconv: {
-    // --- Basic API ---
+declare const iconv: {
+  // --- Basic API ---
 
-    /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-    encode(content: string, encoding: Encodings, options?: EncodeOptions): Buffer;
+  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
+  encode(content: string, encoding: Encoding, options?: EncodeOptions): Buffer;
 
-    /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-    decode(buffer: Buffer | Uint8Array, encoding: Encodings, options?: DecodeOptions): string;
+  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+  decode(buffer: Buffer | Uint8Array, encoding: Encoding, options?: DecodeOptions): string;
 
-    /** Checks if a given encoding is supported by `iconv-lite`. */
-    encodingExists(encoding: string): encoding is Encodings;
+  /** Checks if a given encoding is supported by `iconv-lite`. */
+  encodingExists(encoding: string): encoding is Encoding;
 
-    // --- Legacy aliases ---
+  // --- Legacy aliases ---
 
-    /** Legacy alias for {@link iconv.encode}. */
-    toEncoding: typeof iconv.encode;
+  /** Legacy alias for {@link iconv.encode}. */
+  toEncoding: typeof iconv.encode;
 
-    /** Legacy alias for {@link iconv.decode}. */
-    fromEncoding: typeof iconv.decode;
+  /** Legacy alias for {@link iconv.decode}. */
+  fromEncoding: typeof iconv.decode;
 
-    // --- Stream API ---
+  // --- Stream API ---
 
-    /** Creates a stream that decodes binary data from a given `encoding` into strings. */
-    decodeStream(encoding: Encodings, options?: DecodeOptions): NodeJS.ReadWriteStream;
+  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
+  decodeStream(encoding: Encoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
 
-    /** Creates a stream that encodes strings into binary data in a given `encoding`. */
-    encodeStream(encoding: Encodings, options?: EncodeOptions): NodeJS.ReadWriteStream;
+  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
+  encodeStream(encoding: Encoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
 
-    /**
-     * Explicitly enable Streaming API in browser environments by passing in:
-     * ```js
-     * require('stream')
-     * ```
-     * @example iconv.enableStreamingAPI(require('stream'));
-     */
-    enableStreamingAPI(stream_module: any): void;
+  /**
+   * Explicitly enable Streaming API in browser environments by passing in:
+   * ```js
+   * require('stream')
+   * ```
+   * @example iconv.enableStreamingAPI(require('stream'));
+   */
+  enableStreamingAPI(stream_module: any): void;
 
-    // --- Low-level stream APIs ---
+  // --- Low-level stream APIs ---
 
-    /** Creates and returns a low-level encoder stream. */
-    getEncoder(encoding: Encodings, options?: EncodeOptions): EncoderStream;
+  /** Creates and returns a low-level encoder stream. */
+  getEncoder(encoding: Encoding, options?: EncodeOptions): EncoderStream;
 
-    /** Creates and returns a low-level decoder stream. */
-    getDecoder(encoding: Encodings, options?: DecodeOptions): DecoderStream;
+  /** Creates and returns a low-level decoder stream. */
+  getDecoder(encoding: Encoding, options?: DecodeOptions): DecoderStream;
 
-    /**
-     * Returns a codec object for the given `encoding`.
-     * @throws If the `encoding` is not recognized.
-     */
-    getCodec(encoding: Encodings): Codec;
+  /**
+   * Returns a codec object for the given `encoding`.
+   * @throws If the `encoding` is not recognized.
+   */
+  getCodec(encoding: Encoding): Codec;
 
-    /** Strips all non-alphanumeric characters and appended year from `encoding`. */
-    _canonicalizeEncoding(encoding: Encodings): string;
+  /** Strips all non-alphanumeric characters and appended year from `encoding`. */
+  _canonicalizeEncoding(encoding: Encoding): string;
 
-    // --- Properties ---
+  // --- Properties ---
 
-    /** A cache of all loaded encoding definitions. */
-    encodings: Record<
-      Encodings,
-      | string
-      | {
+  /** A cache of all loaded encoding definitions. */
+  encodings: Record<
+    Encoding,
+    | string
+    | {
         type: string;
         [key: string]: any;
       }
-    > | null;
+  > | null;
 
-    /** A cache of initialized codec objects. */
-    _codecDataCache: Record<string, Codec>;
+  /** A cache of initialized codec objects. */
+  _codecDataCache: Record<string, Codec>;
 
-    /** The character used for untranslatable `Unicode` characters. @default "�" */
-    defaultCharUnicode: string;
+  /** The character used for untranslatable `Unicode` characters. @default "�" */
+  defaultCharUnicode: string;
 
-    /** The character used for untranslatable `single-byte` characters. @default "?" */
-    defaultCharSingleByte: string;
+  /** The character used for untranslatable `single-byte` characters. @default "?" */
+  defaultCharSingleByte: string;
 
-    /** @readonly Whether or not, Streaming API is enabled. */
-    readonly supportsStreams: boolean;
-  }
+  /** @readonly Whether or not, Streaming API is enabled. */
+  readonly supportsStreams: boolean;
+};
 
-  export type {
-    iconv,
-    Encodings
-  }
-  export { iconv as default }
-}
-export = iconv
+export default iconv;
diff --git a/types/encodings.d.ts b/types/encodings.d.ts
index 1a8c9f71..bedbe33f 100644
--- a/types/encodings.d.ts
+++ b/types/encodings.d.ts
@@ -7,7 +7,7 @@
  */
 
 /** A union of all supported encoding strings in `iconv-lite`. */
-export type Encodings =
+export type Encoding =
   | "10000"
   | "10006"
   | "10007"

From a68d5de5c8e35d77f2a56bc754209bd1b877f199 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sun, 17 Aug 2025 16:16:28 +0100
Subject: [PATCH 28/33] fix typescript tests

---
 lib/index.d.ts       | 1 +
 test/types/import.ts | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index ef74d8f2..6558f57b 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -7,6 +7,7 @@
  *-------------------------------------------------------------------------------------------- */
 
 import type { Encoding } from "../types/encodings";
+export type { Encoding } from "../types/encodings";
 
 // --- Options ---
 
diff --git a/test/types/import.ts b/test/types/import.ts
index a27bba76..32df8f6b 100644
--- a/test/types/import.ts
+++ b/test/types/import.ts
@@ -1,2 +1,2 @@
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-import iconv, { iconv as iconvLite, Codec, DecodeOptions, DecoderStream, EncodeOptions, EncoderStream, Encodings } from "../../lib"
+import iconv, { Codec, DecodeOptions, DecoderStream, EncodeOptions, EncoderStream, Encoding } from "../../lib";

From d578371e4ec63a3426d436198ac6dcaa8542ffe2 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sun, 17 Aug 2025 16:19:09 +0100
Subject: [PATCH 29/33] fix eslint issues

Removed semi-colons
---
 lib/index.d.ts       | 14 +++++++-------
 test/types/import.ts |  2 +-
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index 6558f57b..db989265 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -6,8 +6,8 @@
  * This file provides detailed typings for the public API of iconv-lite
  *-------------------------------------------------------------------------------------------- */
 
-import type { Encoding } from "../types/encodings";
-export type { Encoding } from "../types/encodings";
+import type { Encoding } from "../types/encodings"
+export type { Encoding } from "../types/encodings"
 
 // --- Options ---
 
@@ -104,9 +104,9 @@ declare const iconv: {
     Encoding,
     | string
     | {
-        type: string;
-        [key: string]: any;
-      }
+      type: string;
+      [key: string]: any;
+    }
   > | null;
 
   /** A cache of initialized codec objects. */
@@ -120,6 +120,6 @@ declare const iconv: {
 
   /** @readonly Whether or not, Streaming API is enabled. */
   readonly supportsStreams: boolean;
-};
+}
 
-export default iconv;
+export default iconv
diff --git a/test/types/import.ts b/test/types/import.ts
index 32df8f6b..724c4c14 100644
--- a/test/types/import.ts
+++ b/test/types/import.ts
@@ -1,2 +1,2 @@
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-import iconv, { Codec, DecodeOptions, DecoderStream, EncodeOptions, EncoderStream, Encoding } from "../../lib";
+import iconv, { Codec, DecodeOptions, DecoderStream, EncodeOptions, EncoderStream, Encoding } from "../../lib"

From 41a4833baae36778364203bb7f541802032e9349 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sun, 17 Aug 2025 16:56:49 +0100
Subject: [PATCH 30/33] allow CJS imports from node10

---
 lib/index.d.ts | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index db989265..b9bbf2b8 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -123,3 +123,6 @@ declare const iconv: {
 }
 
 export default iconv
+
+// @ts-expect-error Allow CJS imports from node10
+export = iconv

From 9234c9dde978514ed391055b9085ba4d0d2d4bab Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sun, 17 Aug 2025 17:02:24 +0100
Subject: [PATCH 31/33] improve `@ts-expect-error` comment

---
 lib/index.d.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index b9bbf2b8..d26db283 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -124,5 +124,5 @@ declare const iconv: {
 
 export default iconv
 
-// @ts-expect-error Allow CJS imports from node10
+// @ts-expect-error Correct CJS imports in node10
 export = iconv

From 3bc5c7672048a12035c3f474f73d83dd7ac7b003 Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Sun, 17 Aug 2025 17:03:16 +0100
Subject: [PATCH 32/33] correct `@ts-expect-error` comment

---
 lib/index.d.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index d26db283..f491516c 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -124,5 +124,5 @@ declare const iconv: {
 
 export default iconv
 
-// @ts-expect-error Correct CJS imports in node10
+// @ts-expect-error Correct CJS imports
 export = iconv

From 1d220417a9b34f4a04a0a77d7ee2c8ec5e11dabf Mon Sep 17 00:00:00 2001
From: Paul Ebose <paulebose@gmail.com>
Date: Mon, 18 Aug 2025 11:12:30 +0100
Subject: [PATCH 33/33] fix typedefs

---
 lib/index.d.ts | 185 +++++++++++++++++++++++++------------------------
 1 file changed, 94 insertions(+), 91 deletions(-)

diff --git a/lib/index.d.ts b/lib/index.d.ts
index f491516c..87217971 100644
--- a/lib/index.d.ts
+++ b/lib/index.d.ts
@@ -1,128 +1,131 @@
 /* ---------------------------------------------------------------------------------------------
- * REQUIREMENT: This definition is dependent on the @types/node definition.
- *
- * Install with `npm install @types/node --save-dev`
- *
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License.
+ *  REQUIREMENT: This definition is dependent on the @types/node definition.
+ *  Install with `npm install @types/node --save-dev`
+ *-------------------------------------------------------------------------------------------- */
+
+/* ---------------------------------------------------------------------------------------------
  * This file provides detailed typings for the public API of iconv-lite
  *-------------------------------------------------------------------------------------------- */
 
 import type { Encoding } from "../types/encodings"
-export type { Encoding } from "../types/encodings"
 
 // --- Options ---
 
-export interface DecodeOptions {
-  /** Strip the byte order mark (BOM) from the input, when decoding. @default true */
-  stripBOM?: boolean;
-  /** Override the default endianness for `UTF-16` and `UTF-32` decodings. */
-  defaultEncoding?: "utf16be" | "utf32be";
-}
+declare namespace iconv {
+  export interface DecodeOptions {
+    /** Strip the byte order mark (BOM) from the input, when decoding. @default true */
+    stripBOM?: boolean;
+    /** Override the default endianness for `UTF-16` and `UTF-32` decodings. */
+    defaultEncoding?: "utf16be" | "utf32be";
+  }
 
-export interface EncodeOptions {
-  /** Add a byte order mark (BOM) to the output, when encoding. @default false */
-  addBOM?: boolean;
-  /** Override the default endianness for `UTF-32` encoding. */
-  defaultEncoding?: "utf32be";
-}
+  export interface EncodeOptions {
+    /** Add a byte order mark (BOM) to the output, when encoding. @default false */
+    addBOM?: boolean;
+    /** Override the default endianness for `UTF-32` encoding. */
+    defaultEncoding?: "utf32be";
+  }
 
-// --- Return values ---
+  // --- Return values ---
 
-export interface EncoderStream {
-  write(str: string): Buffer;
-  end(): Buffer | undefined;
-}
+  export interface EncoderStream {
+    write(str: string): Buffer;
+    end(): Buffer | undefined;
+  }
 
-export interface DecoderStream {
-  write(buf: Buffer): string;
-  end(): string | undefined;
-}
+  export interface DecoderStream {
+    write(buf: Buffer): string;
+    end(): string | undefined;
+  }
 
-export interface Codec {
-  encoder: new (options?: EncodeOptions, codec?: any) => EncoderStream;
-  decoder: new (options?: DecodeOptions, codec?: any) => DecoderStream;
-  [key: string]: any;
-}
+  export interface Codec {
+    encoder: new (options?: EncodeOptions, codec?: any) => EncoderStream;
+    decoder: new (options?: DecodeOptions, codec?: any) => DecoderStream;
+    [key: string]: any;
+  }
 
-declare const iconv: {
-  // --- Basic API ---
+  const iconv: {
+    // --- Basic API ---
 
-  /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
-  encode(content: string, encoding: Encoding, options?: EncodeOptions): Buffer;
+    /** Encodes a `string` into a `Buffer`, using the provided `encoding`. */
+    encode(content: string, encoding: Encoding, options?: EncodeOptions): Buffer;
 
-  /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
-  decode(buffer: Buffer | Uint8Array, encoding: Encoding, options?: DecodeOptions): string;
+    /** Decodes a `Buffer` into a `string`, using the provided `encoding`. */
+    decode(buffer: Buffer | Uint8Array, encoding: Encoding, options?: DecodeOptions): string;
 
-  /** Checks if a given encoding is supported by `iconv-lite`. */
-  encodingExists(encoding: string): encoding is Encoding;
+    /** Checks if a given encoding is supported by `iconv-lite`. */
+    encodingExists(encoding: string): encoding is Encoding;
 
-  // --- Legacy aliases ---
+    // --- Legacy aliases ---
 
-  /** Legacy alias for {@link iconv.encode}. */
-  toEncoding: typeof iconv.encode;
+    /** Legacy alias for {@link iconv.encode}. */
+    toEncoding: typeof iconv.encode;
 
-  /** Legacy alias for {@link iconv.decode}. */
-  fromEncoding: typeof iconv.decode;
+    /** Legacy alias for {@link iconv.decode}. */
+    fromEncoding: typeof iconv.decode;
 
-  // --- Stream API ---
+    // --- Stream API ---
 
-  /** Creates a stream that decodes binary data from a given `encoding` into strings. */
-  decodeStream(encoding: Encoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
+    /** Creates a stream that decodes binary data from a given `encoding` into strings. */
+    decodeStream(encoding: Encoding, options?: DecodeOptions): NodeJS.ReadWriteStream;
 
-  /** Creates a stream that encodes strings into binary data in a given `encoding`. */
-  encodeStream(encoding: Encoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
+    /** Creates a stream that encodes strings into binary data in a given `encoding`. */
+    encodeStream(encoding: Encoding, options?: EncodeOptions): NodeJS.ReadWriteStream;
 
-  /**
-   * Explicitly enable Streaming API in browser environments by passing in:
-   * ```js
-   * require('stream')
-   * ```
-   * @example iconv.enableStreamingAPI(require('stream'));
-   */
-  enableStreamingAPI(stream_module: any): void;
+    /**
+     * Explicitly enable Streaming API in browser environments by passing in:
+     * ```js
+     * require('stream')
+     * ```
+     * @example iconv.enableStreamingAPI(require('stream'));
+     */
+    enableStreamingAPI(stream_module: any): void;
 
-  // --- Low-level stream APIs ---
+    // --- Low-level stream APIs ---
 
-  /** Creates and returns a low-level encoder stream. */
-  getEncoder(encoding: Encoding, options?: EncodeOptions): EncoderStream;
+    /** Creates and returns a low-level encoder stream. */
+    getEncoder(encoding: Encoding, options?: EncodeOptions): EncoderStream;
 
-  /** Creates and returns a low-level decoder stream. */
-  getDecoder(encoding: Encoding, options?: DecodeOptions): DecoderStream;
+    /** Creates and returns a low-level decoder stream. */
+    getDecoder(encoding: Encoding, options?: DecodeOptions): DecoderStream;
 
-  /**
-   * Returns a codec object for the given `encoding`.
-   * @throws If the `encoding` is not recognized.
-   */
-  getCodec(encoding: Encoding): Codec;
+    /**
+     * Returns a codec object for the given `encoding`.
+     * @throws If the `encoding` is not recognized.
+     */
+    getCodec(encoding: Encoding): Codec;
 
-  /** Strips all non-alphanumeric characters and appended year from `encoding`. */
-  _canonicalizeEncoding(encoding: Encoding): string;
+    /** Strips all non-alphanumeric characters and appended year from `encoding`. */
+    _canonicalizeEncoding(encoding: Encoding): string;
 
-  // --- Properties ---
+    // --- Properties ---
 
-  /** A cache of all loaded encoding definitions. */
-  encodings: Record<
-    Encoding,
-    | string
-    | {
-      type: string;
-      [key: string]: any;
-    }
-  > | null;
+    /** A cache of all loaded encoding definitions. */
+    encodings: Record<
+      Encoding,
+      | string
+      | {
+        type: string;
+        [key: string]: any;
+      }
+    > | null;
 
-  /** A cache of initialized codec objects. */
-  _codecDataCache: Record<string, Codec>;
+    /** A cache of initialized codec objects. */
+    _codecDataCache: Record<string, Codec>;
 
-  /** The character used for untranslatable `Unicode` characters. @default "�" */
-  defaultCharUnicode: string;
+    /** The character used for untranslatable `Unicode` characters. @default "�" */
+    defaultCharUnicode: string;
 
-  /** The character used for untranslatable `single-byte` characters. @default "?" */
-  defaultCharSingleByte: string;
+    /** The character used for untranslatable `single-byte` characters. @default "?" */
+    defaultCharSingleByte: string;
 
-  /** @readonly Whether or not, Streaming API is enabled. */
-  readonly supportsStreams: boolean;
-}
+    /** @readonly Whether or not, Streaming API is enabled. */
+    readonly supportsStreams: boolean;
+  }
 
-export default iconv
-
-// @ts-expect-error Correct CJS imports
+  export type { iconv as Iconv, Encoding }
+  export { iconv as default }
+}
 export = iconv