Show your JS-projects that use JSDoc types rather than TypeScript

[voxpelli]

Good examples are a great resource to learn from, hence it's useful to share our projects where we use this setup.

I'll start out with a couple of mine:

• async-htm-to-string – validates JSDoc types strictly, generates .d.ts from JSDoc types, ensures 100% type coverage using type-coverage + it even generates a ESM variant of the code when it publishes itself to npm
• bunyan-adaptor – validates JSDoc strictly + generates .d.ts
• installed-check-core – validates JSDoc strictly + generates .d.ts
• list-installed – validates JSDoc strictly + generates .d.ts
• micropub-express – validates JSDoc strictly + generates .d.ts

[Raynos]

I'll share some of mine that are using JSDoc

• https://github.com/Raynos/tapzero (16.1.0) (ported from TS => JSDoc)
• https://github.com/Raynos/sync-wait-group (16.1.0) (ported from TS => JSDoc)
• https://github.com/Raynos/fake-ses (15.4.2) (ported from TS => JSDoc)
• https://github.com/Raynos/fake-kms (15.4.2) (ported from TS => JSDoc)
• https://github.com/Raynos/error (15.2.2) (ported from JS => JSDoc)
• https://github.com/optoolco/fake-aws (15.7.1) (written in JSDoc)

I have a very small but recent project that is using JSDoc from scratch

• https://github.com/Raynos/lean.js , it has a seperate commit which contains the package.json / jsconfig.json boilerplate for a new project.

[jorenbroekema]

https://github.com/ing-bank/lion ported from JS with no types to JS with JSDoc type annotations and using TSC as linter / d.ts builder.

"compilerOptions": {
  "target": "esnext",
  "module": "esnext",
  "moduleResolution": "node",
  "lib": ["es2017", "dom"],
  "allowJs": true,
  "checkJs": true,
  "noEmit": true,
  "strict": true,
  "noImplicitThis": true,
  "alwaysStrict": true,
  "types": ["node", "mocha", "sinon"],
  "esModuleInterop": true,
  "suppressImplicitAnyIndexErrors": true
}

A cool trick for when JSDoc annotations aren't giving you the flexibility that you need e.g. for more complex interfaces, you can handwrite your own .d.ts or .ts files and import them in a JS file:

fooTypes.d.ts / .ts

export declare interface Foo {
  foo: string;
}

/**
 * @typedef {import('./fooTypes').Foo} Foo
 */

 /** @type {Foo} */
 const foo = { foo: 'bar' };

This works the same for importing types from dependencies in node_modules.

So you really can use TypeScript and JSDocs hand in hand and lean more towards one or the other based on preference. Our preference has been to make sure our source code is in JS so we don't have to commit to a bundle/compile step for local development.

[Gozala]

Had been working on typed algebraic effects library https://twitter.com/gozala/status/1402543329594675204?s=20

However I got stuck unable to work around TS-es inference limitations and inability to parametrize generic function type (see microsoft/TypeScript#44521).

But even without generics I could not work out good interface for abort handlers and lost steam. If anyone feels like cheering or interested in helping getting this lib to a publishable state, please let me know.

[Raynos]

I've become disullisioned with generics and typescript / jsdoc. It's simpler to just write boring go-style verbose code ...

[voxpelli]

@wooorm shared a project on Twitter that uses the JSDoc approach: https://github.com/syntax-tree/hast-util-to-jsx-runtime

Also mentioning that the @unifiedjs org has +500k lines of code with this approach.