improve typescript typings

.npmignore

@@ -6,4 +6,5 @@ wiki
 coverage
 .github
 .idea
-performance
+performance
+lib/index-template.d.ts

generation/gen-typings.js

@@ -0,0 +1,83 @@
+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) => ("" + name).toLowerCase().replace(/:\d{4}$|[^0-9a-z]/g, "");
+
+  const processEncodingObject = (obj) => {
+    for (const key in obj) {
+      // Skip codecs
+      if (key.startsWith("_")) 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("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, no appended year) 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, "..", "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 outputPath = path.join(__dirname, "..", "lib", "index.d.ts");
+  fs.writeFileSync(outputPath, `${generatedHeader}${typedefs}`, "utf8");
+}
+
+// Run the script
+generateTypingsFile();

lib/index-template.d.ts

@@ -0,0 +1,125 @@
+/*---------------------------------------------------------------------------------------------
+ * REQUIREMENT: This definition is dependent on the @types/node definition.
+ *
+ * Install with `npm install @types/node --save-dev`
+ *
+ * This file provides detailed typings for all encodings supported by 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;