Skip to content

Conversation

@plbstl
Copy link
Contributor

@plbstl plbstl commented Aug 14, 2025

Improved type definitions when using this library.

  • Updated typedefs for the public API
  • Added exhaustive typedefs for all supported encodings.
  • Added a script to auto generate typings from source code: npm run typegen
  • Separated encoding Options to DecodeOptions and EncodeOptions

closes #299

@coveralls
Copy link

coveralls commented Aug 14, 2025

Pull Request Test Coverage Report for Build 17037641521

Details

  • 0 of 0 changed or added relevant lines in 0 files are covered.
  • No unchanged relevant lines lost coverage.
  • Overall coverage remained the same at 93.837%

Totals Coverage Status
Change from base Build 17015959667: 0.0%
Covered Lines: 944
Relevant Lines: 1006

💛 - Coveralls

@bjohansebas
Copy link
Member

Hey, I just modified your PR to add tests for the types. I’m still testing a few things to make sure I don’t break anything, but feel free to push changes if you see something missing.

Signed-off-by: Sebastian Beltran <[email protected]>
Signed-off-by: Sebastian Beltran <[email protected]>
@plbstl
Copy link
Contributor Author

plbstl commented Aug 18, 2025

Very valid. I've pushed the relevant changes.

Copy link
Member

@bjohansebas bjohansebas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Signed-off-by: Sebastian Beltran <[email protected]>
@bjohansebas bjohansebas linked an issue Nov 26, 2025 that may be closed by this pull request
@bjohansebas bjohansebas changed the title improve typescript typings types: improve typescript typings Nov 26, 2025
@bjohansebas bjohansebas changed the title types: improve typescript typings types: improve type definitions and add missing APIs Nov 26, 2025
Signed-off-by: Sebastian Beltran <[email protected]>
Copy link

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR significantly improves TypeScript support for iconv-lite by adding comprehensive type definitions, separating encode/decode options, and introducing an auto-generation script for encoding types. The changes enhance developer experience with better type safety and IntelliSense support.

Key changes:

  • Added exhaustive union type of 400+ supported encodings with auto-generation script
  • Split Options into separate DecodeOptions and EncodeOptions interfaces for better type specificity
  • Enhanced API type definitions with detailed JSDoc comments and proper type guards

Reviewed changes

Copilot reviewed 9 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
types/encodings.d.ts Auto-generated exhaustive union type of all 400+ supported encoding strings
lib/index.d.ts Complete rewrite of type definitions with separated encode/decode options, improved documentation, and better type safety
generation/gen-typings.js New script to auto-generate encoding types from source encoding files
test/types/import.ts Test file to verify all exported types can be imported
test/types/iconv.ts Comprehensive type tests using expect-type library
package.json Added TypeScript tooling dependencies and test scripts
tsconfig.json New TypeScript configuration for type checking
.npmignore Exclude tsconfig.json from npm package
eslint.config.js Enable TypeScript support in ESLint
Changelog.md Document the improvements
.github/workflows/ci.yml Add TypeScript test job and exclude Windows+Node 17 combination
.github/workflows/iojs.yml Remove TypeScript dev dependencies for older Node versions

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@bjohansebas bjohansebas merged commit 7de9789 into pillarjs:master Nov 26, 2025
65 checks passed
@bjohansebas bjohansebas mentioned this pull request Nov 26, 2025
@Phillip9587
Copy link

Hey @bjohansebas, can you port this to the v1 branch?

@prigaux
Copy link

prigaux commented Dec 14, 2025

Hi,
The new typings are not compatible with module: "node20". One gets :

Property 'decode' does not exist on type 'typeof iconv'.

@plbstl
Copy link
Contributor Author

plbstl commented Dec 14, 2025

I've been experimenting. I initially did not want to modify lib/index.js when creating this PR, but editing the file may be needed for importing iconv properly across different NodeJS and TypeScript versions, with ESM and CJS.

It's a straightforward change. Rather than setting properties/methods in the iconv variable, we set them in the exports object instead. For example:

-- iconv.encodings = null
-- iconv.encode = function encode (str, encoding, options) {...}
++ exports.encodings = null
++ exports.encode = function encode (str, encoding, options) {...}

iconv variable can still be used internally. For example, when creating a new Codec in iconv.getCodec.

codec = new codecDef(codecOptions, iconv)

I have a working branch (https://github.com/plbstl/iconv-lite/tree/more-typedefs-improvements) with the test and test:typescript tests passing.

@plbstl
Copy link
Contributor Author

plbstl commented Dec 14, 2025

Hi, The new typings are not compatible with module: "node20". One gets :

Property 'decode' does not exist on type 'typeof iconv'.

@prigaux Can you provide more information? How are you attempting to access decode?

@bjohansebas
Copy link
Member

Hey @prigaux , could you please create a new issue with a minimal reproducible example?

@prigaux
Copy link

prigaux commented Dec 14, 2025

(sorry for not giving enough information, i thought i was enough to reproduce)

To reproduce, you need "type": "module" in package.json and --module node20 param to tsc.

Reproduced with

  • the following package.json:
{
  "type": "module",
  "dependencies": {
    "iconv-lite": "^0.7.1",
    "typescript": "^5.9.3",
    "@types/node": "^25.0.2"
  }
}
  • a simple test.ts file containing:
import iconv from 'iconv-lite'
iconv.decode
  • and running cmd
npx tsc --module nodenext test.ts 

=>

test.ts:2:7 - error TS2339: Property 'decode' does not exist on type 'typeof iconv'.

@bjohansebas
Copy link
Member

@prigaux I can’t manage to reproduce it. Could you create a clean GitHub repo with that so we can debug it more easily?

@takayukioda
Copy link

Hi, @plbstl @bjohansebas

Property 'decode' does not exist on type 'typeof iconv'.

I faced with the same error message; I'm not sure if I'm with same condition though.
Here is the code for reproduction.
https://github.com/takayukioda/reproduce-lab/blob/main/iconv-lite-not-found/src/index.ts
If you change the version from 0.7.1 to 0.7.0, it'll succeed to build. Or, if you change the import declaration from * as iconv to iconv, it also succeed.

iconv-lite/lib/index.d.ts

Lines 128 to 129 in d85f5ab

export type { iconv as Iconv, Encoding }
export { iconv as default }

I guess this is because iconv instance is now exported as default property, you need to import using default import instead of namespace import.

@prigaux
Copy link

prigaux commented Dec 15, 2025

Here is a clean repo: https://github.com/prigaux/iconv-lite-typescript-modules-issue

git clone https://github.com/prigaux/iconv-lite-typescript-modules-issue
cd iconv-lite-typescript-modules-issue/
npm install
npm run test1
npm run test2

I have nodejs 24.11.1-1nodesource1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

miss getCodec in .d.ts

6 participants