KotlinJS JS headers


#1

One of the biggest pain points of working with plain JavaScript is needing to page back and forth through documentation in order to know precisely how to use an API. KotlinJS has the potential to greatly alleviate this by providing statically typed definitions for standard javascript APIs and KDoc comments for what the APIs mean.

I would like to start contributing towards this goal by implementing some js specs.  Before I begin, however, there is some discussion around how to go about this.

  • Browser compatibility - Is there an official minimum target for KotlinJS? What are the guidelines for what signatures should be implemented and what should be ignored?
  • Organization - Are there guidelines for organization? JavaScript doesn't really have packages, so are we putting all standard library code in src/core?  
  • Reference - What should Kotlin use as the cannonical JS API reference?
  • Documentation - I think MDN has great documentation, I believe we can copy the Creative Commons documentation as long as we provide attribution.
  • Progress - It might be a good idea to create a list of standard js apis that need to be implemented and a way for people to claim a section to work on, things like TypedArrays, XMLHTTPRequest, Workers, etc.  

I'd like to discuss the strategy here, and come up with a way we can very quickly fill in critical missing JS APIs for KotlinJS.

There is a lot here, it may even be a good/hairbrained idea to write a spider to pull this information from a data source and write out a first pass.


#2

Firstly I should tell You that we going to convert TypeScript declarations from http://definitelytyped.org to Kotlin soon.

Browser compatibility - Is there an official minimum target for KotlinJS?

We don't have minimal target for browsers, but we have minimal target for JS, it's ES5. You can see compatable browsers here: http://kangax.github.io/compat-table/es5/. Mainly use the following ES5 features: * Property getter and setters (can not be implement by polyfills) * Object.create * Strict mode

What are the guidelines for what signatures should be implemented and what should be ignored?

We don't have any guidelines for choose and implement APIs. We just implements some things as needed(for users or for ourself). Of course we prefer fully implement API when it possible.

Organization - Are there guidelines for organization? JavaScript doesn't really have packages, so are we putting all standard library code in src/core?

We don't have any guidelines for this too. I don't think that "putting all standard library code in src/core" is good choice. I believe that ECMAScript things should be declared in `kotlin.js` package. And probably other things should be in separate packages.

Reference - What should Kotlin use as the cannonical JS API reference?

We prefer to be compatible with specifications(from ECMA, w3c, whatwg etc.).

Documentation - I think MDN has great documentation, I believe we can copy the Creative Commons documentation as long as we provide attribution.

I don't sure that we can. MDN use CC-BY-SA 2.5 which require apply same licence to derived documents. We should investigate it and discuss about it.

Progress - It might be a good idea to create a list of standard js apis that need to be implemented and a way for people to claim a section to work on, things like TypedArrays, XMLHTTPRequest, Workers, etc.

Feel free to propose such list :)

Useful links for that:
http://caniuse.com
https://developer.mozilla.org/en-US/docs/Web/Reference
https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5
http://chromestatus.com
https://status.modern.ie


#3

Thanks for the reply,

If Jetbrains is planning on converting the Definitely typed definitions, I’ll wait on that and only implement the things I need specifically.


#4

Is there an update on when the TypeScript declarations (.d.ts files) will be available in Kotlin?

Thanks


#5

Currently ETA is next milestone(~ in May). Please star the related issue to get updates.


#6

Thank you for the update, that is good news!

I added a link to Definitely Typed, a repository of 800+ such definitions, to the issue.