LS API usability issues

[clausreinke]

It looks as if the LS API is written with a very limited set of use cases in mind (probably modeled after one of its clients;-). While that set of use cases is well supported, many desirable use cases beyond the target set are made unnecessarily difficult. In other words, the LS API is too tightly coupled to one set of use cases.

Examples:

1. getQuickInfoAtPosition tries to compute symbol at position (used to be called fullSymbolName in earlier iterations, I think) and type of symbol at position, but exposes neither (unless one is willing to extract those pieces of information from displayParts)

   (I tried to get the information from the underlying program and typechecker, but kept ending up with symbols that lacked some flags that seemed needed for further processing; but, really, I think these are reasonable bits of info to ask for at the LS API level - perhaps I should be using other methods?)

2. I often find myself wanting to explore the type of the thing under the cursor. When writing code, I can abuse completion for this, but when reading code, that feels unnatural.

   Now, I can jump to the definition of the thing under cursor, but that isn't what I want, and if the program relies on type inference, there may not be any explicit type info at the definition site, either.

   Next idea would be to infer the type the type by other means (which runs into 1 above) and then to jump to the definition site of that type - only that one cannot use the LS API to jump to the definition of anything that doesn't happen to be at the cursor position..

It seems the abstraction level is slightly wrong, and the LS is trying to do too much for the client: the LS should provide the info, the LS clients should process that info. Also, LS/client interactions are slightly too coarse-grained: some of the LS/client interactions could be more flexible by splitting them into smaller parts (such as A. finding the thing under the cursor and B. finding information about a given thing, where the thing might come from A or might be created in place).

[mhegazy]

I think what you are looking for here is a way to extend the language service implementation and add new features. if I understand correctly you are referring to something like gotoType that would take you to the definition location of the type of a symbol rather than the symbol itself.

The language service is meant for an editor to use. Hence the whole snapshots, AtPosition naming, formatting, breakpoints...etc.. If you want to build tools for other scenarios like global program analysis, I would just use the core compiler API (i.e. directly work with the program, sourceFile, checker ..etc).

The language service really is a very thin layer. All the language details and type inference is in the core compiler. for instance, getQuickInfoAtPosition, the main logic in two calls:
var symbol = typeInfoResolver.getSymbolAtLocation(node); and var type = typeInfoResolver.getTypeAtLocation(node);. the rest of the code in this method is serializing things to a LS API interfaces.
Similarlly getCompletionsAtPosition which is a bit more involved than quick info, most of the code is doing syntactic analysis to know if completion is "allowed" or not, and to know if you are after a dot or not.. again things that an editor or IDE would typically need. the main compiler/typesystem logic is in calls like: var symbol = typeInfoResolver.getSymbolAtLocation(node);, typeInfoResolver.isValidPropertyAccess(<PropertyAccessExpression>(node.parent), symbol.name), typeInfoResolver.getContextualType(containingObjectLiteral); and typeInfoResolver.getSymbolsInScope(node, symbolMeanings)

If you want to add additional analysis you should be able to just grab the program, get the typeChecker off it, and ask the same questions and process them differently.

And you are right, the LS features exposed have been originally modeled against exposed VS features as that was our first client, though not the only any longer :). Suggestions and/or PRs for interesting new LS features are always welcomed.

And for sure there are issues with the core compiler API, and we would love to work on making it easier to use, and your feedback would be appreciated.

(I tried to get the information from the underlying program and typechecker, but kept ending up with symbols that lacked some flags that seemed needed for further processing; but, really, I think these are reasonable bits of info to ask for at the LS API level - perhaps I should be using other methods?)

I will need some more details to be able to help out. my guess is that is a problem with the API that assumes a certain order of events, e.g. binding before accessing symbols.. etc.

Now, I can jump to the definition of the thing under cursor, but that isn't what I want, and if the program relies on type inference, there may not be any explicit type info at the definition site, either.

I think this is gotoType you are asking for, and i think it is a feature we need to add. Another feature would be to show type structure instead of simple type names in quickInfo.

It seems the abstraction level is slightly wrong, and the LS is trying to do too much for the client: the LS should provide the info, the LS clients should process that info. Also, LS/client interactions are slightly too coarse-grained: some of the LS/client interactions could be more flexible by splitting them into smaller parts (such as A. finding the thing under the cursor and B. finding information about a given thing, where the thing might come from A or might be created in place).

We have tried to isolate the client logic and push most of it in the LS interface. the main rational is that most clients need more or less the same behavior, e.g. completion. for additional features, i would use the compiler API directly by calling LS.getProgram().

[clausreinke]

(I tried to get the information from the underlying program and typechecker, but kept ending up with symbols that lacked some flags that seemed needed for further processing; but, really, I think these are reasonable bits of info to ask for at the LS API level - perhaps I should be using other methods?)

I will need some more details to be able to help out. my guess is that is a problem with the API that assumes a certain order of events, e.g. binding before accessing symbols.. etc.

Answering this separately:

I tried to copy the relevant calls from getQuickInfoAtPosition: var node = getTouchingPropertyName(sourceFile, position); (I'd never guessed this from its name, btw) and var symbol = typeInfoResolver.getSymbolAtLocation(node);. I even tried to call getQuickInfoAtPosition first, to avoid initialization issues with the lower-level methods, but no success: getQuickInfoAtPosition succeeds where getSymbolAtLocation(node) fails.

Apparently, there is a node.symbol property missing, which is passed as undefined into getTypeOfSymbol:

TypeError: Cannot read property 'flags' of undefined
    at getTypeOfSymbol (typescript.js:9608:23)
    at checkFunctionExpressionOrObjectLiteralMethod (typescript.js:13417:24)
    at checkExpressionWorker (typescript.js:13969:28)
    at checkExpressionOrQualifiedName (typescript.js:13911:42)
    at checkExpression (typescript.js:13903:20)
    at getTypeOfExpression (typescript.js:16073:20)
    at getTypeOfNode (typescript.js:16041:24)
    at typescript.js:11948:58
    at Object.forEach (typescript.js:613:30)
    at resolveLocation (typescript.js:11948:16)

[clausreinke]

Returning to the main line of argument:

Yes, extending the LS API would be one way to address this, and gotoType sounds like a useful addition. Nevertheless, I was trying to argue that there may be a better way forward, namely to

1. preserve/expose more of the information computed in the API results
2. factor complex API methods into simple building blocks
3. use method composition (instead of API extension) to improve API expressiveness

Concrete example again: getDefinitionAtPosition is position-based, and -after a couple of special cases- extracts a symbol from the source at position; if this method were to take an optional symbol parameter, that could be used instead (if provided). Then, if there was a separate method to obtain a symbol for an item of interest (even if that item is not explicit in the source code), all the rest of the getDefinitionAtPosition code/functionality could be reused, and no new gotoType method would be needed.

I agree that there is a balance here between keeping the higher-level API simple and re-exposing information that is easily obtained from the lower-level API but, even with this in mind, there seems to be room for improvement - by looking at the API methods as building blocks instead of monolithic endpoints.

[mhegazy]

We would be open to refactoring parts and exposing more functionality. let us know what you need and will work on it. alternatively you can send us a PR.