Typescript type definition file for desktop IDEs?

Scriptable
#2

There’s not currently a Typescript package for Visual Studio Code but it sounds like a fun idea. Would you then write the script in Typescript, compile it to JS and run that in Scriptable? Or can a Typescript package work in Visual Studio Code when writing plain JS and not actually Typescript?

I have a file containing all type information for the auto completion. It’s structured to be read by Tern code analysis engine but it might very well be easier to parse than the online documentation. I might be able to share it or parts of it.

On the other hand, if you make something that parses the online documentation, you can quickly update your package when new APIs are added :blush:

1 Like
#3

A typescript definition file is basically an interface or .h file. Visual Studio Code can read it to give suggestions, code completion, etc. A user could write their code in any form of JS (vanilla, ES6, typescript, coffee script, etc). It would obviously have to be compiled to a form Scriptable can then understand. This is the best explanation I’ve found for what it is and why it’s helpful.

EDIT: Looking at Tern it seems like it’s a very similar concept to what you already have.

Improving JavaScript code using ESLint, Prettier, and standardJS
#4

Thanks for the responses!

I’ve looked at Tern and it looks like that the type definition file for that one only contains the properties and methods, but no description of those. The Typescript type definition file can also contain a description of which property/function/argument does what. Therefore I will probably go the online documentation route.

#5

A Tern language specification can contain documentation and the one for Scriptable actually does.

I still think that parsing the online documentation would be a fine approach. Then you wouldn’t depend on me to deliver a new specification when new APIs are introduced or existing APIs are updated.

#6

Oh, didn’t see that they can also include documentation. I must have missed that on their website!

Yes, I wouldn’t depend on you, but I think, if you also could publish this type file on the Scriptable website together with the documentation updates, then it would be easier to parse than the documentation itself. Especially if you change the appearance of the documentation, the parser has to be adjusted. But the Tern file stays constant in its layout.

Of course, it is your decision if you want to make the Tern file public :wink:

1 Like
#7

I’ve now made the parser for the documentation. The last question that remains for me is how I should publish it? On npm as a separate package? On npm as a @types package? But then the end user needs to download it using npm and therefore needs a package.json file and node_modules folder in the iCloud Scriptable folder…

Does anyone have a better idea?

If you want to have a look, you can find it here:

1 Like
#8

@schl3ck I took a look at your script and it looks good! I only found two problems: 1) here and there you are erroneously generating interface declarations. This shouldn’t be happening at all since you need to declare variables present in the global scope. Interfaces define types. E.g. args is declared as declare interface args {...}, whereas it should be declare let args: {...}. 2) Some things in the docs are defined in an informal language that breaks some typings.

@simonbs I think maintaining a TypeScript type definition file would be very useful since this would enable people to get perfect autocompletion in VS Code very easily, using only two extra files in their directory. Generating a good type definition file from the docs is not currently possible since not all of it is in a formal, machine-readable format. Plus there’s the problem that any generator tool would depend on the structure of the html. This would be minimal work for you since it can be generated from the Tern JSON type definition which you already maintain.

3 Likes
#9

Thanks for reporting! I haven’t used it since I generated it, so I haven’t tested it much! I will look into it in the next few days.

The first file is of course my typings file, but what specifies the second one?

#10

The second file is a jsconfig.json file to disable the dom library that the typescript language service implies by default, so that you don’t end up getting autocomplete for browser only variables. This is not just nice but necessary because there are some name collisions like Request.

3 Likes
#11

Could you please describe how to set this up, because these are also my first steps in working with TypeScript? Or the best thing would be, if you could create this second file and make a pull request on GitHub with an installation description for people that never touched TypeScript before?

I’m currently working on the change from interface to variables as you described it earlier.

1 Like
#12

The jsconfig file is not in the scope of the generator tool I think, so I wouldn’t open a pull request, but it looks like this:

{
	"compilerOptions": {
		"lib": ["es6"]
	}
}

All it does is enable the es6 standard lib (because Scriptable runs in an es6 environment as per the docs) and omit everything else, notably the dom library. You can put the typings anywhere you want in your project, and they will be applied. I’d put it in typings/scriptable.d.ts. The biggest issue is that as I already said, scraping the docs is suboptimal to say the least so we should work on convincing @simonbs to give us an official type definition file. :wink::wink::wink:

2 Likes
#13

You are right. But I would also be happy, if he would release the Tern file with a direct link which is automatically updated with the documentation. Then I could adapt my scraper to use this as source. And if I’ve finished it, I could hand it over to him so he can run it by his own after each update.

@simonbs please release the Tern file :wink:

2 Likes
#14

Please let me know if this does the job. https://docs.scriptable.app/scriptable.json

2 Likes
#15

Thank you!

Yes it does the job. But I’ve noticed that it doesn’t include the whole description of each function/property, only the subtitle… Would it be possible for you to include the whole description? Otherwise I would have to parse the online documentation again or it would be missing some things in the popup description if you hover over a keyword.

#16

I can probably do that. I’ve added it to my todo. First thing I need to figure out if the Tern specification has a dedicated attribute for long descriptions.

1 Like
#17

Thank you!

I’ve already had a look, but haven’t found anything. Also the official doc isn’t that long at all^^
Maybe you could add it with the key !longdoc or something like that, but I’m not sure if Tern then interprets this as a property…

#18

I’ve updated the scriptable.json file at https://docs.scriptable.app/scriptable.json to include the long description. I couldn’t find descriptions like this mentioned in the Tern specification, so I went with the key !scriptable.description. If you build a tool that uses this, please make sure that it’s easy to change the name of the key in the future. I’ll change it if I stumble upon a better name in the Tern specification.

3 Likes
#19

Thank you!

I’ve had a look and I noticed that you maybe have missed some parts of the description especially these texts:

image
CA62807A-3525-47D6-8948-B18AE04B8DB3.jpeg750×732 171 KB

They’re not necessary, but it would be nice to have :wink:

I will start to work on it next week hopefully.

#20

It’s done! Thank you again @simonbs for providing the Tern definition file (and its improvements in the meantime).

I’ve noticed, that there are some backslashes too much in some descriptions. I think they are in Mail.subject, Mail.body, Message.body and Request.addFileToMultipart.

Also there is a !prop_fn at the beginning of the !doc values of Request.onRedirect, UITableCell.onSelect, WebView.shouldAllowRequest and XMLParser.didStartDocument|didEndDocument|didStartElement|didEndElement|foundCharacters|parseErrorOccurred. I don’t know what that does…
Wait. These properties are not functions, but properties which you should assign a function, if I’m correct? I’ve to change them to get the definition onRedirect: (Request) => Request. So it’s still not 100% done… But it’s not far anymore! :smile:

The global functions atob() and btoa() have no return type defined. I think this is a mistake.

You can find the current status at my repo I’ve linked to here.
If someone wants to have a look at the result and help me find more errors, please look through the diff on github:


To summarize the todos: Respect !prop_fn for the definitions; handle static and instance methods with the same name (e.g. WebView.loadFile).

#21

I can now finally say that it’s finished! :smile:

I’ve fixed the bugs mentioned in my previous post and some more. Also thanks to @simonbs for fixing all the misspellings I’ve found and again for providing the Tern file!

2 Likes