Add native support for twoslash comment queries

[orta]

Suggestion

const hi = "Hi"
const msg = `${hi} world` as const
//    ^?

Should add an inline recommendation to editors what the type is at msg.

I think there are a significant amount of new TypeScript users who are learning the language through video tools/tutorials. Probably much more than we expect. Lots of the folks teaching use this syntax via a vscode extension I wrote a few years back.

I initially punted on discussing internally about upstreaming it into TSServer, but I've slowly turned around on the idea as it feels like the teaching community is changing to be more video focused. So, I think it's worth the complexity, at least to bring it up.

🔍 Search Terms

inline comments show types messages print types twoslash

✅ Viability Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

TSServer already has inlay hint support for other features, so it would be expanding support, perhaps that means at parse/bind time checking comments for // ^? and caching their locations, then printing the results when an editor asks for hints in a particular range.

The current code simply uses the same kind of regex as the TSC tests

export function activate(context: vscode.ExtensionContext) {
  const provider: vscode.InlayHintsProvider = {
    provideInlayHints: async (model, iRange, cancel) => {
      const offset = model.offsetAt(iRange.start);
      const text = model.getText(iRange);
      const results: vscode.InlayHint[] = [];

      const m = text.matchAll(/^\s*\/\/\s*\^\?/gm);
      for (const match of m) {
        if (match.index === undefined) {
          return;
        }

        const end = match.index + match[0].length - 1;
        // Add the start range for the inlay hint
        const endPos = model.positionAt(end + offset);
        const inspectionPos = new vscode.Position(
          endPos.line - 1,
          endPos.character
        );

        if (cancel.isCancellationRequested) {
          return [];
        }

        const { scheme, fsPath, authority, path } = model.uri;
        const hint: any = await vscode.commands.executeCommand(
          "typescript.tsserverRequest",
          "quickinfo",
          {
            _: "%%%",
            file: scheme === 'file' ? fsPath : `^/${scheme}/${authority || 'ts-nul-authority'}/${path.replace(/^\//, '')}`,
            line: inspectionPos.line + 1,
            offset: inspectionPos.character,
          }
        );

        if (!hint || !hint.body) {
          continue;
        }

        // Make a one-liner
        let text = hint.body.displayString
          .replace(/\\n/g, " ")
          .replace(/\/n/g, " ")
          .replace(/  /g, " ")
          .replace(/[\u0000-\u001F\u007F-\u009F]/g, "");
        if (text.length > 120) {
          text = text.slice(0, 119) + "...";
        }

        const inlay: vscode.InlayHint = {
          kind: 0,
          position: new vscode.Position(endPos.line, endPos.character + 1),
          label: text,
          paddingLeft: true,
        };
        results.push(inlay);
      }
      return results;
    },
  };

📃 Motivating Example

I think there are 2 main uses for this, and I've framed the initial part of this issue as being about education because that's what changed my opinion. The other part is that it is genuinely useful to pull out types while you are working on a more complex type, in which case twoslash comments act like a way of seeing your work in progress on complex types.

For example when I built a "wordle" in the type system, each type I created I would create an example of it in use and print it in order to see how types flow through the system. You can see a few left in here: https://t.co/OmXoSdi1Y1

Downsides

There are a few interesting downsides to the syntax, which I think are fine but at east worth highlighting:

• Hard to copy them Add the ability to copy the query as text orta/vscode-twoslash-queries#21
• Can't highlight an identifier on the first 2 chars

Extensions

We could also add support for drilling into the types:

type Person = {
  name: string;
  address: {
    line1: string;
    country: string;
  }
}

const person = bob;
//     ^?['address']  { line1: string; country: string }

[Ciantic]

I just found out that VSCode TypeScript supports inline type hints, the gray types there are not written by user but elicited by the IDE

It doesn't work for const for some reason but it does for let... It of course works if you use only VSCode during your video lectures. Rust is a language that is unusable for me without inlay hints, TypeScript seems to benefit from those too, it might be hard to get used to it at first because they might add noise you don't want.

All TypeScript and Deno settings.json for inlay hints

{
  // For TypeScript
  "typescript.inlayHints.variableTypes.enabled": true,
  "typescript.inlayHints.parameterNames.enabled": "all",
  "typescript.inlayHints.functionLikeReturnTypes.enabled": true,
  "typescript.inlayHints.parameterTypes.enabled": true,
  "typescript.inlayHints.propertyDeclarationTypes.enabled": true,
  "typescript.inlayHints.enumMemberValues.enabled": true,
  "typescript.inlayHints.parameterNames.suppressWhenArgumentMatchesName": false,
  "typescript.inlayHints.variableTypes.suppressWhenTypeMatchesName": false,

  // Color settings
  "workbench.colorCustomizations": {
    "editorInlayHint.foreground": "#7e7e7e",
    "editorInlayHint.background": "#ff000000"
  },

  // For deno
  "deno.inlayHints.variableTypes.enabled": true,
  "deno.inlayHints.parameterNames.enabled": "all",
  "deno.inlayHints.functionLikeReturnTypes.enabled": true,
  "deno.inlayHints.parameterTypes.enabled": true,
  "deno.inlayHints.propertyDeclarationTypes.enabled": true,
  "deno.inlayHints.enumMemberValues.enabled": true,
  "deno.inlayHints.parameterNames.suppressWhenArgumentMatchesName": false,
  "deno.inlayHints.variableTypes.suppressWhenTypeMatchesName": false,
}

[fatcerberus]

It doesn't work for const for some reason

If you write e.g. const foo = "bar" then the type is "bar" so the inlay hint isn’t shown since it would be redundant. I think the same is true for new Class() because there again, the type is obvious. Outside of that you should still get inlay hints for const.

[fatcerberus]

the teaching community is changing to be more video focused

I’m probably in the minority on this but I always felt like video was the wrong medium for teaching programming, because there’s very little temporal component to it. Sure, it takes time to enter code, but that’s entirely mechanical; if I could beam all the code I need into the computer at once with just my thoughts, I would. Thus why AI tools like GitHub Copilot are successful.

Video coding tutorials make me think of those old boring YouTube “tutorials” where it’s just someone typing stuff into Notepad for 10 minutes - just give me the text file to read myself! 😅

Then again, I’ve always learned better from API references than coding tutorials (which tend to just make me impatient), so yeah.

[orta]

Yep, the inlay hints feature in editors is what this feature on the playground and the vscode extension linked use, the current support doesn't handle the types of sorts of introspection I was showcasing though (and for me are mostly noise).

Hah, everyone trying to drag my proposal off-topic! I also prefer text, but the availability + accessibility of youtube (and maybe tiktok? though I struggle to imagine it's a great learning tool for depth) have changed what its like at the beginning of expertise even if it's not really doing much for the intermediate to experts for a topic!

[fatcerberus]

Hah, everyone trying to drag my proposal off-topic!

Yep, sorry about that. 😅

[rauschma]

I just used the Playground and it’s neat that the ^? syntax already works there.

[Edit: slightly off-topic, apologies] For written content (printed books, blog posts, etc.), I’d love to additionally be able to state the inferred type and have a tool check that it’s correct – e.g.:

const str = "Hello" as const;
//     ^? const str: "Hello"

Alternative 1 – shorter:

const str = "Hello" as const;
//     ^? "Hello"

Alternative 2 – prefix:

// @inferred-type: "Hello"
const str = "Hello" as const;

[orta]

There is support for that as an eslint plugin, JoshuaKGoldberg/eslint-plugin-expect-type#47

[RyanCavanaugh]

This would be a VS Code or other editor thing, since there's (AFAIK) nothing TS Server could tell the editor to do here that would make this happen automatically.

[orta]

VS Code would need a minor change to always ask for inlay hints, but I'd expect the core of the support to live in provideInlayHints in TSServer which is what does all the heavy lifting for this in here

[DanielRosenwasser]

So we chatted about this in our editor sync. We all love and use query comments (// ^?) in the playground, and some of us have it installed in VS Code itself.

Here's some of what came out of the conversation - some of it just describing our own next steps, and some of it feedback that might or might not be interesting/useful

1. A user has to know to enable inlay hints in the first place to get this - and we likely wouldn't turn query comments on by default, even if inlay hints was turned on. Of course, going through settings to turn this on is a way to discover this feature, but we're not sure if it's the right gateway yet.

2. The extension is a good proofing ground for whether this should be part of TypeScript direclty - over time, if we really saw broader usage, we could reconsider this. This is often how VS Code's core feature set is developed, with extensions paving the way.

3. We think the discoverability of the extension could be improved if the name reflected its specific feature. If you know what twoslash is, then you might have an idea of what it does - but query comments are really their own thing! Ultimately it's your call, but I really think it would help if people could more-easily put a name to this feature.

4. One really cool idea we had is whether it could make sense for the extension to work on other languages. There's no reason query comments have to be specific to TypeScript and JavaScript. Is there a world where this extension could operate on multiple languages?

   VS Code already provides a command for requesting hover (see an example here). An extension could just leverage that instead of talking directly to TSServer.

   Unfortunately there's public no mechanism for asking for the current token scope
   to see whether a position falls in a comment. I'm pretty sure _workbench.captureSyntaxTokens is not meant to be public. But I believe the playground doesn't really care if something really falls in a comment anyway:

   

   The comment pattern could be special-cased on a per-language basis - but so many languages use // that they'd all benefit from just that.

So the TL;DR? No for now - but we're happy to revisit in the future.

We do think that there's a really cool opportunity for the extension to generalize to more languages if it's something you'd be interested in.