typescript-plugins-text-based-user-interaction
Helpers for TypeScript Language Service Plugins that wants to interact with the user via the source file itself
- If you are developing TypeScript plugins that require to interact with the user - but want to be portable, editor/IDE agnostic you can use this library to interact with the user via expressions in the source file itself.
- default implementation for my plugins when need to inquire the user - not good looking but very powerful, portable, and cammon, here we are inquiring DEVELOPERS trying to refactor their source code, not Mickey Mouse!
- almost automatic implementation of a plugin from a config object
- this way I can focus on implementing the plugin / refactor itself and have a working / flexible solution and leave the nice UI work to someone else or when I have time for that - now the real need is ts refactors!
- just defining a config object it practically generates a working plugin that will suggest autocomplete "templates" and prompt user with function calls that he can modify and call refactors upon "to enter the data" (see demos and examples below)
- right now very dependant on TypeScript Language Service API
Demo
Moving and renaming a file in Visual studio Code Editor:
Editor agnostic!. See the same demo but in Atom editor:
-
Another demo, this time inquiring two arguments:
Ideas
- we have many ideas on how the interaction could be right now is like that, with a free-signature function call - so user can model it at piaccere. But this could be improved - for example, instead of a function call, user could be promopted like in a form and we could json-schema validate / hint/autocomplete/etc.
- Probably the best idea would be maintaining the protocol visual-metaphor-agnostic (perhaps json-schema is a good idea) and then implement different metaphor that user can choose to use by config and others contribute with new ones.
TODO:
- documentation, examples
- Big TODO: Language server protocol instead just TLS. implement this 100% there and you have plugins that will work on any ed.
- also related to previous - could we be language (ts) agnostic and provide the same capability to any LSP enable language not only to TS ?
Example
The following example are fragments of reorder signature parameters plugin. This plugin objective is to change the order of parameters on a given function signature or call. We need to know from the user, interactively, what's the function he want's to change its signature and how the parameters will be re-ordered in the signature. See the gif (TODO) for how the experience is. Basically the user can create a "snippet" of an special function call, modify the call (entering the data) and then applying a refactor to let us know the input.
// here we import the text-based-ui tool;;;;; // here we create the tool providing a configuration object that define "actions". In this case a simple one // we delegate all the work in interactionTool.getApplicableRefactors - will take care of displaying refactor suggestions if the user is standing in a speciall comment marked with the special preffix // we delegate most of the work to info.languageService.getEditsForRefactor. At this point user input is available in // selectedAction.args.name and selectedAction.args.reorder which we use to implement the actual refactor (implementation not relevant) // autocompletions! notice how I delegate the work on the tool interactionTool.getCompletionsAtPosition() // our plugin definition and registration (using typescript-plugin-util)
Example (old one)
The following is a fragment of typescript-plugin-move-file typescript plugin which uses this library to ask the user where to move current file or current directory:
The functions getApplicableRefactors
, getEditsForRefactor
, getCompletionsAtPosition
are the ones to be added in the TypeScript Language Service Plugin proxy object. See https://github.com/Microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin for more info about
typescript plugins.
; // tool creation. : ts.ApplicableRefactorInfo // We also ask the tool for completions at position so when user starts writing "refactor" it will be offered with snippets defined in the config for each type of action;
TODO / Roadmap
Changelog
0.0.5
- support for multi-line action declarations.
- support for dinamic autocomplete suggestions