Typescript Codegen Support

[mattpocock]

Opening this issue to spawn a discussion about type-safety. Lucy offers a nice opportunity to increase TS type safety by statically analysing the machine. This is similar to, but much more reliable than, xstate-codegen. xstate-codegen pulls out machines from JS/TS, which is fraught with issues. Lucy could statically analyse files, free of side effects, and create 100% perfect types every time.

What do perfect types look like?

1. All actions/guards/services know what events caused them to fire.
2. state.matches can be made type safe.

Because Lucy compiles to out.js files, an accompanying .d.ts file would be appropriate. Users could also pass it generics, such as TEvent and TContext, similar to xstate-codegen.

Interested to hear your thoughts.

[mattpocock]

@matthewp More thoughts on this:

https://www.loom.com/share/24611881ff44467ca021f63e33f18599

[matthewp]

Hey @mattpocock I really like your ideas here! I agree about moving inline actions/guards into the named section. I'm on board with that. A JSON version seems interesting and relatively simple too. Would love to hear more about how that might be used (easier to integrate with a visualizer maybe?)

I've been on vacation so haven't been diving deeply into TS yet but should be able to respond more in the next few days. One thing I have a question about is what is the user experience of types in a non-JS language? Does the user need to first compile to .d.ts and import the JS file (as you would using the CLI)? Or can they import the .lucy file using one of the build tool plugins and still get types? If so how would TS know about the types in .lucy files? Is there some kind of protocol for this?

More thoughts to come later. Thanks so much for your interest in moving this forward!

[mattpocock]

@matthewp

Does the user need to first compile to .d.ts and import the JS file?

No! You can actually strongly type the .lucy file directly. You can declare a specific module with an arbitrary file extension.

Would love to hear more about how [a JSON version] might be used

Some of this is still TBD, but the possibilities are interesting. The visual builder will most likely use JSON as its 'source code' - i.e. editing an in-place JSON definition of a machine. Giving Lucy the ability to print that JSON into 'lucy' would be pretty cool - but one for the future.

[matthewp]

This part is still unclear to me: https://twitter.com/matthewcp/status/1390276561392308224

I want to make sure we figure this out as part of adding good TS support. I think most people are going to be using bundler plugins and importing .lucy files, so it doesn't help if the generated JS has good type definitions if the editor doesn't know about them.

---

I'm kind of guessing that VSCode has an API as part of the language server that asks the extension for types. If we can just hand it the JS then we should prioritize adding types to the generated JS. If we have to tell it the specific types then we should prioritize getting the AST available to the extension.

[mattpocock]

This part is still unclear to me

Could the bundler plugin print Typescript declaration files? Similar to css-modules-typescript-loader

[mattpocock]

@matthewp I've been wanting to learn VSCode Language Server stuff for a while - would this be a part of lucy-vscode?

[matthewp]

To get support for types coming from bundler usage like: import createTodoMachine from './todo.lucy' I think that yeah, that likely is something that has to be done in a language server. Currently there isn't a language server at all for Lucy, it's just syntax highlighting. It would go in that project though.

The Svelte language server has to do something similar: https://github.com/sveltejs/language-tools

---

I really don't know what the requirements are here. If you just need to compile to JS and it then "figures it out" from there that would be great, you can use liblucy for that. If you need an AST or something, I'll have to add that.

[mattpocock]

@matthewp Got any other good resources around this? I'll dive into Svelte/Vue to see how they manage.

[matthewp]

No, I'm pretty new to it myself. I did find a few YouTube videos when I was learning about this, so there is some resources out there.

[matthewp]

Just an update here, with 0.3.0 out and the module signature in a better place, this will likely be the major thing done for 0.4.0.

I'm approaching it from VSCode first perspective, so depending what is needed there will determine what the initial approach will be here.

[matthewp]

I've been building machines for the REPL and I now see strongly the need to produce .d.ts files as I've been doing so manually! Still looking to target the VSCode extension first to see if it can take virtual .d.ts files or if we need a mode to output to TypeScript.

[matthewp]

Status here is that I've been investigating this issue more and did a spike on a language service for VSCode. At this point I think the best course of action is a TypeScript Language Service plugin (https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin). This will allow you to get Lucy support through the existing TypeScript language service in your editor.

My plan is to do a quick spike on that, and then the next step will likely be declaration file generation from the CLI compiler.

[matthewp]

The TypeScript plugin will be here: https://github.com/lucydsl/typescript-plugin

[matthewp]

I've gotten far enough on the typescript plugin to conclude that compiling to .d.ts will work for vscode integration. 🎉. lucydsl/typescript-plugin#1

So the next step is putting a pause on the development of that to add .d.ts output to the compiler/cli. As I work on this piece I'll likely ping people here to see if they like the output that I come up with.