TypeScript Without Transpilation (2021)

Sorry for being that guy, but this should probably be called "typechecking without transpilation".

What ends up being written is not TypeScript syntax (which does require transpilation to run).

JSDoc is awesome for incremental adoption though, I've migrated a few codebases this way without too much pain.

JSDoc can get you pretty far, but it can be clumsy sometimes. There’s a [TC39 proposal](https://github.com/tc39/proposal-type-annotations) to allow types to live in JS code and be treated as comments (similar with Python types today)

JSDoc comments are definitely not the “best of both worlds,” they are a limited and verbose subset of typing. I would only use them for specific reasons, like I’m in a hostile ecosystem that dogmatically doesn’t want any build steps (like WebGL/WebGPU engines).

I've found a happy medium to be annotating functions etc with JSDoc style comments but keeping interfaces etc. in a .d.ts file. The Typescript compiler is able to import it from a .js file just fine.

Some of the limitations listed are wrong:

> The main limitation is that you don't have access to some TypeScript-specific syntax.

> * as, also known as type assertions (or casts)

You generally shouldn’t (as the article notes), but you can:

  const foo = /** @type {Bar} */ ({
    something: {
      satisfying: 'Bar',
    },
  });

This also works for `as const`, which is often better when you can use readonly types:

  const foo = /** @type {const} */ ({
    something: 'else',
  });
  // { readonly something: 'else' }

  /** @satisfies {Bar} */
  const foo = …;

> * is, also known as type predicates

This definitely works:

  /**
   * @param {unknown} value
   * @return {value is Foo}
   */
  const isFoo = (value) => …

  /**
   * @callback IsFoo
   * @param {unknown} value
   * @return {value is Foo}
   */

Also useful, if needed, the @template tag which is roughly equivalent to TS type parameters (generics) which you can use, for example, to assign generic type guards:

  /**
   * @template T
   * @callback IsT
   * @param {unknown} value
   * @return {value is T}
   */

  /** @type {IsT<Foo>} */
  const isFoo = (value) => …

I'm using this setup at the moment, mostly because I work on legacy code base that has no good types yet.

Typically you would do jsconfig.json though, which is same as tsconfig.json but allowJs is already set. Mostly stylistic change, but some tooling might benefit for having jsconfig instead of tsconfig.

// @ts-check works until you need to do an assertion, a cast, a predicate, pass an explicit type to a generic method, etc., then it gets very annoying. I only ever use it if I’m writing a single self-contained and relatively short script and can’t be bothered with a build step.

Does anyone know if I have a TypeScript project, is there an automated process to turn it into this format this article describes? Eject for TS, I guess.

This is exactly how I use typescript, as a linter and static type analyzer for javascript. Unfortunately, typescript support for JSdoc is quite basic. So that method has its limit. But I'm not committing any typescript code.

Someone here just suggested to import type definition files with JS doc annotations, and that's actually a good idea.

Right on time as I've been trying to add some type safety onto my OSS project. Does anyone have some extra info on how to best leverage JSDoc to write safe(r) JS code?

I thought this was going to be a project like ts-node [1]

[1] https://github.com/TypeStrong/ts-node

Confused about the mentions of Elm. What does this have to do with Elm?