improve typescript typings

.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
+          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

.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 }}

.npmignore

@@ -10,4 +10,5 @@ performance
 .nyc_output
 eslint.config.js
 *.tgz
-.git-blame-ignore-revs
+.git-blame-ignore-revs
+tsconfig.json

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: {

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");
 }
 

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

package.json

@@ -29,25 +29,29 @@
         "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"
     },
     "browser": {
         "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": {

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()

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"

tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": [ "es2015" ],
+    "module": "commonjs",
+    "noEmit": true,
+    "strict": true
+  },
+  "include": [
+    "./test/types/**/*.ts",
+    "./**/*.d.ts"
+  ]
+}

lib/encodings.d.ts → 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 & {})