TypeScript Support

[jlarmstrongiv]

Benefits of native TypeScript include:

• Strong autocomplete
• Easier refactoring
• Code documentation

The underlying library warcio.js was also recently ported to TypeScript.

[matteocargnelutti]

Appreciate the suggestion :).

I believe we have pretty good support for the three elements you listed with JSDoc, with the added benefits of not having a build step and being able to copy/paste code in the REPL.

[jlarmstrongiv]

Ahh, I was involved with porting warcio.js to TypeScript, and was looking into doing the same here :)

not having a build step

Unfortunately, if you are looking to target browsers in #14, you will still need a build step with babel for backwards compatibility

being able to copy/paste code in the REPL

ts-node features a TypeScript REPL environment

---

While JSDoc can be used for type information, you will likely need // @ts-check at the top of your files and additional linter rules (such as eslint-plugin-jsdoc) to receive the benefits of static typing. That way, you will have errors if your code is missing JSDoc types or if the JSDoc types don’t actually match your code.

In addition, I find that TypeScript syntax less verbose and more readable than JSDoc, and more developers are familiar with TypeScript than JSDoc.

[matteocargnelutti]

I understand :).
Since there is no blocker on documentation, auto-complete or - as you noted - type checking, I think the library would benefit most from time investment elsewhere at the moment.

An additional factor is that we are developing and maintaining multiple JavaScript + JSDoc codebases at the moment, so this is where we are focusing our efforts on.

It is therefore unlikely we'll port to TypeScript anytime soon, but I'm happy to revisit further down the road if either of those things change.

---

PS: Also happy to consider adding @ts-check flags to enforce type checking via JSDoc if its helpful for folks whose editor doesn't support that feature without it. Let me know 😄 .

[jlarmstrongiv]

Also happy to consider adding @ts-check flags to enforce type checking via JSDoc if its helpful for folks whose editor doesn't support that feature without it

I bring up the // @ts-check and additional eslint rules mainly because the current JSDoc comments, while helpful, are not fully type safe. Attempting to generate corresponding type declaration files *.d.ts fails.

To reproduce, try these steps from the TypeScript documentation:

• install typescript as a dev dependency
• run npx typesync or manually add dependency types
• create a tsconfig.json file (see below)
• run npx tsc
• observe generating types fails with many type errors

tsconfig.json

{
  // Change this to match your project
  "include": ["./**/*"],
  "exclude": ["./dist"],
  "compilerOptions": {
    // Tells TypeScript to read JS files, as
    // normally they are ignored as source files
    "allowJs": true,
    // Generate d.ts files
    "declaration": true,
    // This compiler run should
    // only output d.ts files
    "emitDeclarationOnly": true,
    // Types should go into this directory.
    // Removing this would place the .d.ts files
    // next to the .js files
    "outDir": "dist",
    // go to js file when using IDE functions like
    // "Go to Definition" in VSCode
    "declarationMap": true
  }
}

If you are open to it, I am expecting to have time in the upcoming months to convert this library to TypeScript 😄