New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide official .d.ts typings for Electron #4875

Closed
miniak opened this Issue Mar 21, 2016 · 43 comments

Comments

Projects
@miniak
Contributor

miniak commented Mar 21, 2016

There is github-electron.d.ts in the DefinitelyTyped repository, however it is quite out of date (I have several PRs with added/updated APIs pending). Wouldn't it make sense to somehow coordinate this effort? Or maybe even generate the documentation from a .d.ts file instead of writing it in Markdown. Keeping the typings in a separate repository makes it really hard to keep it up to date.

Ideas?

@kevinsawicki

This comment has been minimized.

Show comment
Hide comment
@kevinsawicki

kevinsawicki Mar 21, 2016

Contributor

Refs #3375 /cc @jlord @zeke

Contributor

kevinsawicki commented Mar 21, 2016

Refs #3375 /cc @jlord @zeke

@zcbenz

This comment has been minimized.

Show comment
Hide comment
Contributor

zcbenz commented Mar 27, 2016

@OlsonDev

This comment has been minimized.

Show comment
Hide comment
@OlsonDev

OlsonDev Mar 27, 2016

VS Code's electron.d.ts is much more out of date than the @miniak's aforementioned DefinitelyTyped typings.

OlsonDev commented Mar 27, 2016

VS Code's electron.d.ts is much more out of date than the @miniak's aforementioned DefinitelyTyped typings.

@bpasero

This comment has been minimized.

Show comment
Hide comment
@bpasero

bpasero Mar 28, 2016

Contributor

The one we use in VS Code is really just the one from DefinitelyTyped and might be a bit out dated as of today (I took it some months ago).

Contributor

bpasero commented Mar 28, 2016

The one we use in VS Code is really just the one from DefinitelyTyped and might be a bit out dated as of today (I took it some months ago).

@felixrieseberg

This comment has been minimized.

Show comment
Hide comment
@felixrieseberg

felixrieseberg Apr 6, 2016

Member

A decent solution is to use YUIDoc (or something else along the same lines) and use that to create typings. That way, it benefits everyone (TypeScript people, VSCode users, Flow users, etc.).

Member

felixrieseberg commented Apr 6, 2016

A decent solution is to use YUIDoc (or something else along the same lines) and use that to create typings. That way, it benefits everyone (TypeScript people, VSCode users, Flow users, etc.).

@zeke

This comment has been minimized.

Show comment
Hide comment
@zeke

zeke Jul 8, 2016

Member

Work in progress: #6408

Member

zeke commented Jul 8, 2016

Work in progress: #6408

@mmc41

This comment has been minimized.

Show comment
Hide comment
@mmc41

mmc41 Sep 2, 2016

Yes, please - would really, really like an official typescript definition file (if possible embedded in the npm like Angular2 does for typescript). Besides making typescipt users happy this would improve the code editor experience a lot in IDE's (also for javascript users). This is the most wanted feature for me.

mmc41 commented Sep 2, 2016

Yes, please - would really, really like an official typescript definition file (if possible embedded in the npm like Angular2 does for typescript). Besides making typescipt users happy this would improve the code editor experience a lot in IDE's (also for javascript users). This is the most wanted feature for me.

@mmc41

This comment has been minimized.

Show comment
Hide comment
@mmc41

mmc41 Sep 4, 2016

What is the status on this?

mmc41 commented Sep 4, 2016

What is the status on this?

@zeke

This comment has been minimized.

Show comment
Hide comment
@zeke

zeke Sep 6, 2016

Member

@mmc41 I'm working on generating a JSON object that describes the Electron APIs. Hoping to ship that soon. Hopefully we can use it as a starting point for generating a TypeScript definition file. I will post back here when the JSON doc is ready.

Member

zeke commented Sep 6, 2016

@mmc41 I'm working on generating a JSON object that describes the Electron APIs. Hoping to ship that soon. Hopefully we can use it as a starting point for generating a TypeScript definition file. I will post back here when the JSON doc is ready.

@mmc41

This comment has been minimized.

Show comment
Hide comment
@mmc41

mmc41 Sep 7, 2016

@zeke Thanks for the update. I recommend another approach however. It would seem to be much more easier to create a (commented) typescript definition file and generate JSON and other documentation artifacts from that. An similar situation is if you want both digital and analog copies of a video. If you start with analog you are likely to have great difficulty in producing a high quality digital copy. The typescript definition file (possibly with some comments if needed) is the digital equivalent. Another benefit of starting with the typescript version is that you can use it internally even if you do not do typescript yourself to feed IDE's (you will be amazed by the help that various IDEs can give based on a typescript definition file). You can also beta-test the typescript definition file as people can use it even if it is not finished. A JSON is not really useful in itself for most people.

mmc41 commented Sep 7, 2016

@zeke Thanks for the update. I recommend another approach however. It would seem to be much more easier to create a (commented) typescript definition file and generate JSON and other documentation artifacts from that. An similar situation is if you want both digital and analog copies of a video. If you start with analog you are likely to have great difficulty in producing a high quality digital copy. The typescript definition file (possibly with some comments if needed) is the digital equivalent. Another benefit of starting with the typescript version is that you can use it internally even if you do not do typescript yourself to feed IDE's (you will be amazed by the help that various IDEs can give based on a typescript definition file). You can also beta-test the typescript definition file as people can use it even if it is not finished. A JSON is not really useful in itself for most people.

@mmc41

This comment has been minimized.

Show comment
Hide comment
@mmc41

mmc41 Sep 7, 2016

@zeke Note that someone else have create a draft typescript definition file that could be used as a starting point (properly easier to use this than to start from scratch - especially on the bumpy json road you mentioned): "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/6d4239b89e0452b66cb7850ef9842aff71e370be/github-electron"

mmc41 commented Sep 7, 2016

@zeke Note that someone else have create a draft typescript definition file that could be used as a starting point (properly easier to use this than to start from scratch - especially on the bumpy json road you mentioned): "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/6d4239b89e0452b66cb7850ef9842aff71e370be/github-electron"

@zeke

This comment has been minimized.

Show comment
Hide comment
@zeke

zeke Sep 7, 2016

Member

It would seem to be much more easier to create a (commented) typescript definition file and generate JSON and other documentation artifacts from that.

I agree that would be a good starting point if Electron was a new project, but the content in docs/api is currently our source of truth about how all the APIs work. Maybe we can eventually move toward using a schema as the canonical thing, but for now it's the docs.

Thanks for sharing that github-electron typing. I have seen it and would definitely consider using it as a starting point.

Member

zeke commented Sep 7, 2016

It would seem to be much more easier to create a (commented) typescript definition file and generate JSON and other documentation artifacts from that.

I agree that would be a good starting point if Electron was a new project, but the content in docs/api is currently our source of truth about how all the APIs work. Maybe we can eventually move toward using a schema as the canonical thing, but for now it's the docs.

Thanks for sharing that github-electron typing. I have seen it and would definitely consider using it as a starting point.

@mmc41

This comment has been minimized.

Show comment
Hide comment
@mmc41

mmc41 Sep 7, 2016

@zeke BTW: Interesting enough here is a tool for doing the reverse of what you are doing - generating json from typescript : http://lbovet.github.io/typson-demo/
:-)

mmc41 commented Sep 7, 2016

@zeke BTW: Interesting enough here is a tool for doing the reverse of what you are doing - generating json from typescript : http://lbovet.github.io/typson-demo/
:-)

@miniak

This comment has been minimized.

Show comment
Hide comment
@miniak

miniak Sep 7, 2016

Contributor

I am maintaining those typings, I am willing to help if possible. Btw this is the latest version: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/github-electron

Contributor

miniak commented Sep 7, 2016

I am maintaining those typings, I am willing to help if possible. Btw this is the latest version: https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/github-electron

@miniak

This comment has been minimized.

Show comment
Hide comment
@miniak

miniak Sep 7, 2016

Contributor

I also think the a TypeScript definition with proper documentation would be a better source of truth.

Contributor

miniak commented Sep 7, 2016

I also think the a TypeScript definition with proper documentation would be a better source of truth.

@MarshallOfSound

This comment has been minimized.

Show comment
Hide comment
@MarshallOfSound

MarshallOfSound Sep 7, 2016

Member

@miniak @mmc41 Personally (although after some research DefinitelyTyped looks very useful) I don't think that anyone should have to learn a new syntax / style of documentation purely to document methods inside Electron.

Markdown is a global language that most if not all devs know the basics of. I don't think we should be expecting devs to contribute to typescript definitions as our source of truth when an unknown proportion of them may have never come close to using typescript before.

You also have to take into account readability of the docs. A typescript definition is all very nice but it doesn't fit very well with the way electron.atom.io displays the docs.

Considering the current majority usage of the docs is to display easily readable content on either GitHub or the Jekyll Electron site. I think we should proceed with @zeke 's cool doc parser and then potentially write a converter to take that JSON file and turn it into a definitely typed declaration file.

The alternative (switching our source of truth to typescript files) would require writing even more converters to allow the current usage of the docs to continue (typescript -> JSON, typescript -> markdown / jekyll, Etc.)

Member

MarshallOfSound commented Sep 7, 2016

@miniak @mmc41 Personally (although after some research DefinitelyTyped looks very useful) I don't think that anyone should have to learn a new syntax / style of documentation purely to document methods inside Electron.

Markdown is a global language that most if not all devs know the basics of. I don't think we should be expecting devs to contribute to typescript definitions as our source of truth when an unknown proportion of them may have never come close to using typescript before.

You also have to take into account readability of the docs. A typescript definition is all very nice but it doesn't fit very well with the way electron.atom.io displays the docs.

Considering the current majority usage of the docs is to display easily readable content on either GitHub or the Jekyll Electron site. I think we should proceed with @zeke 's cool doc parser and then potentially write a converter to take that JSON file and turn it into a definitely typed declaration file.

The alternative (switching our source of truth to typescript files) would require writing even more converters to allow the current usage of the docs to continue (typescript -> JSON, typescript -> markdown / jekyll, Etc.)

@sedwards2009

This comment has been minimized.

Show comment
Hide comment
@sedwards2009

sedwards2009 Sep 7, 2016

If you want to create type declaration files then contributors are going to have to learn and use some kind of formal language to write the function/methods descriptions in. That can be TypeScript or some other ad hoc system which the doc parser reads. But either way, a formal style of documentation will be needed and contributors will have to know or learn it.

TypeScript has the advantage that lots of people know it already, and it is a formal language for specifying types as used in a JS program. It is also well documented etc.

sedwards2009 commented Sep 7, 2016

If you want to create type declaration files then contributors are going to have to learn and use some kind of formal language to write the function/methods descriptions in. That can be TypeScript or some other ad hoc system which the doc parser reads. But either way, a formal style of documentation will be needed and contributors will have to know or learn it.

TypeScript has the advantage that lots of people know it already, and it is a formal language for specifying types as used in a JS program. It is also well documented etc.

@mmc41

This comment has been minimized.

Show comment
Hide comment
@mmc41

mmc41 Sep 7, 2016

The problem with markdown (as any text) is that it is ambiguous and there is no way for a machine to check for errors. With markdown you essentially have to invent your own language, parsers and other technology in order to produce the needed typescript declarations.

mmc41 commented Sep 7, 2016

The problem with markdown (as any text) is that it is ambiguous and there is no way for a machine to check for errors. With markdown you essentially have to invent your own language, parsers and other technology in order to produce the needed typescript declarations.

@enlight

This comment has been minimized.

Show comment
Hide comment
@enlight

enlight Sep 9, 2016

Contributor

I haven't looked at the JSON file that @zeke has been working on in #7120 to see if it contains sufficient type information to generate type definitions, but assuming it will at some point contain all the requisite information it could be fed to https://github.com/RyanCavanaugh/dts-dom to generate the TypeScript type definitions.

Contributor

enlight commented Sep 9, 2016

I haven't looked at the JSON file that @zeke has been working on in #7120 to see if it contains sufficient type information to generate type definitions, but assuming it will at some point contain all the requisite information it could be fed to https://github.com/RyanCavanaugh/dts-dom to generate the TypeScript type definitions.

@felixrieseberg

This comment has been minimized.

Show comment
Hide comment
@felixrieseberg

felixrieseberg Sep 9, 2016

Member

No worries everyone, we'll get a definition file eventually - we discussed a few times amongst the maintainers what the best way here is, and we have to consider the time and effort of those working on electron above everything else. Nothing is more useless than an outdated definitions file 😉

As soon as Zeke is done with his JSON approach, I'll make sure that we have an official first-party d.ts.

Member

felixrieseberg commented Sep 9, 2016

No worries everyone, we'll get a definition file eventually - we discussed a few times amongst the maintainers what the best way here is, and we have to consider the time and effort of those working on electron above everything else. Nothing is more useless than an outdated definitions file 😉

As soon as Zeke is done with his JSON approach, I'll make sure that we have an official first-party d.ts.

@rootscript

This comment has been minimized.

Show comment
Hide comment
@rootscript

rootscript Sep 15, 2016

Just to add a little newbie overview. I use npm to install typings. Doing a typings search for electron returns these results, showing the source, maintainer, and when they were last updated.

Are you guys saying that github-electron is the correct source to use? and is the one that will be maintained/updated?

typings search electron        
Viewing 9 of 9

NAME                     SOURCE DESCRIPTION VERSIONS UPDATED                  HOMEPAGE                                              
electron                 env                2        2016-09-09T06:56:30.000Z                                                       
electron-builder         dt                 1        2016-03-16T15:55:26.000Z https://github.com/loopline-systems/electron-builder  
electron-json-storage    dt                 1        2016-03-24T00:02:15.000Z https://github.com/jviotti/electron-json-storage      
electron-notifications   dt                 1        2016-08-12T19:51:47.000Z https://github.com/blainesch/electron-notifications   
electron-notify          dt                 1        2016-08-16T15:10:39.000Z https://github.com/hankbao/electron-notify            
electron-packager        dt                 1        2016-03-16T15:55:26.000Z https://github.com/maxogden/electron-packager         
electron-window-state    dt                 1        2016-02-12T17:13:54.000Z https://github.com/mawie81/electron-window-state      
github-electron          dt                 1        2016-09-14T12:41:56.000Z http://electron.atom.io/                              
github-electron/electron dt                 1        2016-08-17T06:16:22.000Z https://github.com/electron-userland/electron-prebuilt

Also there is a note here in reference to electron-prebuilt:
Note As of version 1.3.1, this package is published to npm under two names: electron and electron-prebuilt. You can currently use either name, but electron is recommended, as the electron-prebuilt name is deprecated, and will only be published until the end of 2016.
https://www.npmjs.com/package/electron-prebuilt

rootscript commented Sep 15, 2016

Just to add a little newbie overview. I use npm to install typings. Doing a typings search for electron returns these results, showing the source, maintainer, and when they were last updated.

Are you guys saying that github-electron is the correct source to use? and is the one that will be maintained/updated?

typings search electron        
Viewing 9 of 9

NAME                     SOURCE DESCRIPTION VERSIONS UPDATED                  HOMEPAGE                                              
electron                 env                2        2016-09-09T06:56:30.000Z                                                       
electron-builder         dt                 1        2016-03-16T15:55:26.000Z https://github.com/loopline-systems/electron-builder  
electron-json-storage    dt                 1        2016-03-24T00:02:15.000Z https://github.com/jviotti/electron-json-storage      
electron-notifications   dt                 1        2016-08-12T19:51:47.000Z https://github.com/blainesch/electron-notifications   
electron-notify          dt                 1        2016-08-16T15:10:39.000Z https://github.com/hankbao/electron-notify            
electron-packager        dt                 1        2016-03-16T15:55:26.000Z https://github.com/maxogden/electron-packager         
electron-window-state    dt                 1        2016-02-12T17:13:54.000Z https://github.com/mawie81/electron-window-state      
github-electron          dt                 1        2016-09-14T12:41:56.000Z http://electron.atom.io/                              
github-electron/electron dt                 1        2016-08-17T06:16:22.000Z https://github.com/electron-userland/electron-prebuilt

Also there is a note here in reference to electron-prebuilt:
Note As of version 1.3.1, this package is published to npm under two names: electron and electron-prebuilt. You can currently use either name, but electron is recommended, as the electron-prebuilt name is deprecated, and will only be published until the end of 2016.
https://www.npmjs.com/package/electron-prebuilt

@zeke

This comment has been minimized.

Show comment
Hide comment
@zeke

zeke Oct 7, 2016

Member

@MarshallOfSound and I are actively working on this, and with each release we are inching toward an electron-api.json that will have all the necessary data to compile a TypeScript definition file. #7379 is an important piece of that, and with any luck it will land in the next release, 1.4.4

To track progress, watch MarshallOfSound/Electron-DefinitelyTyped

Member

zeke commented Oct 7, 2016

@MarshallOfSound and I are actively working on this, and with each release we are inching toward an electron-api.json that will have all the necessary data to compile a TypeScript definition file. #7379 is an important piece of that, and with any luck it will land in the next release, 1.4.4

To track progress, watch MarshallOfSound/Electron-DefinitelyTyped

@crocket

This comment has been minimized.

Show comment
Hide comment
@crocket

crocket Oct 23, 2016

I want to automatically generate a GHCJS binding to electron. Should I have a GHCJS binding automatically generated from electron-api.json or electron.d.ts?

It seems both are not ready for a GHCJS binding at this point.

A problem is that TypeScript has subtyping and haskell does not.

Refer to https://github.com/mgsloan/ghcjs-typescript for details.

crocket commented Oct 23, 2016

I want to automatically generate a GHCJS binding to electron. Should I have a GHCJS binding automatically generated from electron-api.json or electron.d.ts?

It seems both are not ready for a GHCJS binding at this point.

A problem is that TypeScript has subtyping and haskell does not.

Refer to https://github.com/mgsloan/ghcjs-typescript for details.

@MarshallOfSound

This comment has been minimized.

Show comment
Hide comment
@MarshallOfSound

MarshallOfSound Oct 23, 2016

Member

@crocket In order to use the maximum amount of information you should probably go from the JSON reference. Unless their is already a converter from .d.ts to GHCJS in which case just wait for .d.ts to be fully functioning and then run it through a converter 👍

Member

MarshallOfSound commented Oct 23, 2016

@crocket In order to use the maximum amount of information you should probably go from the JSON reference. Unless their is already a converter from .d.ts to GHCJS in which case just wait for .d.ts to be fully functioning and then run it through a converter 👍

@crocket

This comment has been minimized.

Show comment
Hide comment
@crocket

crocket Oct 23, 2016

@MarshallOfSound https://github.com/mgsloan/ghcjs-typescript is a stalled work, and it is supposed to convert .d.ts to haskell modules when it's completed.

Is electron-api.json ready for GHCJS binding?

As far as I know, optional object elements aren't unambiguously marked, yet.
I suspect I should wait until electron-api.json becomes stable.

Also, I'm looking for a way to automatically generate a GHCJS binding to NodeJS. However, NodeJS project doesn't have any typing information, yet.

crocket commented Oct 23, 2016

@MarshallOfSound https://github.com/mgsloan/ghcjs-typescript is a stalled work, and it is supposed to convert .d.ts to haskell modules when it's completed.

Is electron-api.json ready for GHCJS binding?

As far as I know, optional object elements aren't unambiguously marked, yet.
I suspect I should wait until electron-api.json becomes stable.

Also, I'm looking for a way to automatically generate a GHCJS binding to NodeJS. However, NodeJS project doesn't have any typing information, yet.

@MarshallOfSound

This comment has been minimized.

Show comment
Hide comment
@MarshallOfSound

MarshallOfSound Oct 23, 2016

Member

Is electron-api.json ready for GHCJS binding?

Lot's of the information you would need to generate bindings is already in the JSON output. The optional object element thing can be tracked #7370

Also, I'm looking for a way to automatically generate a GHCJS binding to NodeJS. However, NodeJS project doesn't have any typing information, yet.

Can't really help with that, you might be better off converting the existing node.d.ts file to GHCJS

Member

MarshallOfSound commented Oct 23, 2016

Is electron-api.json ready for GHCJS binding?

Lot's of the information you would need to generate bindings is already in the JSON output. The optional object element thing can be tracked #7370

Also, I'm looking for a way to automatically generate a GHCJS binding to NodeJS. However, NodeJS project doesn't have any typing information, yet.

Can't really help with that, you might be better off converting the existing node.d.ts file to GHCJS

@crocket

This comment has been minimized.

Show comment
Hide comment
@crocket

crocket Oct 23, 2016

Will electron-api.json become stable after #7370 is closed?
The closure of #7370 will introduce a breaking change in electron-api.json, and I don't know if other issues will break electron-api.json, too in the near future.

When do you think electron-api.json will become stable as a parser input?

crocket commented Oct 23, 2016

Will electron-api.json become stable after #7370 is closed?
The closure of #7370 will introduce a breaking change in electron-api.json, and I don't know if other issues will break electron-api.json, too in the near future.

When do you think electron-api.json will become stable as a parser input?

@MarshallOfSound

This comment has been minimized.

Show comment
Hide comment
@MarshallOfSound

MarshallOfSound Oct 23, 2016

Member

The closure of #7370 introduces a breaking change

I disagree, that wouldn't be breaking. Currently there is no way to determine if a parameter is optional, that issue will add a way. Not a breaking change rather a new feature.

When do you think electron-api.json will become stable as a parser input?

I already use it in my electron-definitelytyped parser that is still a WIP. Updates haven't broken the parser yet 👍

Member

MarshallOfSound commented Oct 23, 2016

The closure of #7370 introduces a breaking change

I disagree, that wouldn't be breaking. Currently there is no way to determine if a parameter is optional, that issue will add a way. Not a breaking change rather a new feature.

When do you think electron-api.json will become stable as a parser input?

I already use it in my electron-definitelytyped parser that is still a WIP. Updates haven't broken the parser yet 👍

@crocket

This comment has been minimized.

Show comment
Hide comment
@crocket

crocket Oct 23, 2016

I see. Will electron.d.ts be able to express optional parameters or optional object elements? How much information do you lose during conversion of electron-api.json to electron.d.ts?

By the way, https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/electron/github-electron.d.ts was updated to electron 1.4.3 already.

crocket commented Oct 23, 2016

I see. Will electron.d.ts be able to express optional parameters or optional object elements? How much information do you lose during conversion of electron-api.json to electron.d.ts?

By the way, https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/electron/github-electron.d.ts was updated to electron 1.4.3 already.

@MarshallOfSound

This comment has been minimized.

Show comment
Hide comment
@MarshallOfSound

MarshallOfSound Oct 23, 2016

Member

I see. Will electron.d.ts be able to express optional parameters or optional object elements? How much information do you lose during conversion of electron-api.json to electron.d.ts?

You don't lose any information currently, as more things get added to the JSON output I can add more things to my .d.ts output

By the way, https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/electron/github-electron.d.ts was updated to electron 1.4.3 already.

Yeah, that typing file is the entire point of this issue. It is out of date, inaccurate in lots of places and is missing documentation that is fixed / updated / added over time. The entire purpose of the JSON api is to export the docs for an Electron version in a standard way. Then the point of my .d.ts converter is to take the standard JSON file and convert to a definitely typed file.

Then on release day we can generate a .d.ts file with no manual interaction that we can guarantee is correct as it is parsed directly from the documentation.

Member

MarshallOfSound commented Oct 23, 2016

I see. Will electron.d.ts be able to express optional parameters or optional object elements? How much information do you lose during conversion of electron-api.json to electron.d.ts?

You don't lose any information currently, as more things get added to the JSON output I can add more things to my .d.ts output

By the way, https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/electron/github-electron.d.ts was updated to electron 1.4.3 already.

Yeah, that typing file is the entire point of this issue. It is out of date, inaccurate in lots of places and is missing documentation that is fixed / updated / added over time. The entire purpose of the JSON api is to export the docs for an Electron version in a standard way. Then the point of my .d.ts converter is to take the standard JSON file and convert to a definitely typed file.

Then on release day we can generate a .d.ts file with no manual interaction that we can guarantee is correct as it is parsed directly from the documentation.

@zeke

This comment has been minimized.

Show comment
Hide comment
@zeke

zeke Nov 4, 2016

Member

Getting closer! #7857

Member

zeke commented Nov 4, 2016

Getting closer! #7857

@pjhenning

This comment has been minimized.

Show comment
Hide comment
@pjhenning

pjhenning Dec 29, 2016

Hello, any updates on the status of this? I'd love to get going on a project using TS with Electron but I'm hesitant to start without official typings.

pjhenning commented Dec 29, 2016

Hello, any updates on the status of this? I'd love to get going on a project using TS with Electron but I'm hesitant to start without official typings.

@HitomiTenshi

This comment has been minimized.

Show comment
Hide comment
@HitomiTenshi

HitomiTenshi commented Dec 30, 2016

Same here!

@zeke

This comment has been minimized.

Show comment
Hide comment
@zeke

zeke Dec 30, 2016

Member

The latest is this: before we officially bundle an electron.d.ts file within the electron npm package, we need to teach the docs linter to parse the docs for Electron's webview tag. I belive this is the last blocker.

If you want to take the current WIP file for a spin, see electron-userland/electron-prebuilt#209

See also DefinitelyTyped/DefinitelyTyped#12888 for progress on deprecating/replacing the third-party definitions.

Member

zeke commented Dec 30, 2016

The latest is this: before we officially bundle an electron.d.ts file within the electron npm package, we need to teach the docs linter to parse the docs for Electron's webview tag. I belive this is the last blocker.

If you want to take the current WIP file for a spin, see electron-userland/electron-prebuilt#209

See also DefinitelyTyped/DefinitelyTyped#12888 for progress on deprecating/replacing the third-party definitions.

@pjhenning

This comment has been minimized.

Show comment
Hide comment
@pjhenning

pjhenning Dec 31, 2016

Thanks for the reply! The WIP file should be good enough for now :)

pjhenning commented Dec 31, 2016

Thanks for the reply! The WIP file should be good enough for now :)

@MarshallOfSound

This comment has been minimized.

Show comment
Hide comment
@MarshallOfSound

MarshallOfSound Dec 31, 2016

Member

@aculeat The most up to date file can be found in this gist

https://gist.github.com/MarshallOfSound/8b1b1aa0773fab1a9178cc2d1025dadd

Member

MarshallOfSound commented Dec 31, 2016

@aculeat The most up to date file can be found in this gist

https://gist.github.com/MarshallOfSound/8b1b1aa0773fab1a9178cc2d1025dadd

@pjhenning

This comment has been minimized.

Show comment
Hide comment
@pjhenning

pjhenning Dec 31, 2016

pjhenning commented Dec 31, 2016

@chrilith

This comment has been minimized.

Show comment
Hide comment
@chrilith

chrilith Jan 22, 2017

Don't npm install -D @types/electrondo the trick?

chrilith commented Jan 22, 2017

Don't npm install -D @types/electrondo the trick?

@MarshallOfSound

This comment has been minimized.

Show comment
Hide comment
@MarshallOfSound

MarshallOfSound Jan 22, 2017

Member

@chrilith They are third-party provided typings written by hand. This issue is about generating first-party typings and shipping them with the "electron" npm module.

Member

MarshallOfSound commented Jan 22, 2017

@chrilith They are third-party provided typings written by hand. This issue is about generating first-party typings and shipping them with the "electron" npm module.

@unional

This comment has been minimized.

Show comment
Hide comment
@unional

unional Apr 4, 2017

As I do more work in TS, I start to realize that JSON -> type definition is not as good as type definition -> JSON (I think the same hold true for JSON schema, but need to verify).

The reason is that there are information cannot be represented in JSON compare to a formal type specification language such as TypeScript or Flow.

For example. consider the following:

export function foo(options: Options) { ... }

export interface Options {
  a: string,
  b: {
    c: string
    d?: int
  }
}

While this can be used, it is actually better to be written as:

export function foo(option: foo.Options) { ... }

export namespace foo {
  export interface Options {
    a: string,
    b: Options.B
  }

  // this is advance
  export namespace Options {
    export interface B {
      c: string,
      d?: int
    }
  }
}

This way, you can do the following when consuming this library:

import { foo } from 'some-foo'

function myFoo(option: MyOption) { ... }

interface MyOption {
  a?: string // make `a` optional because myFoo will fill in a default value
  b: foo.Options.B // while keep and reuse type of B
}

I think you will have a hard time to generate type definitions like this from JSON (because you need to selectively create reusable sub-complex type).

My two cents. 🌷

Of course, for the first version, the easy way is the best way. 😄

unional commented Apr 4, 2017

As I do more work in TS, I start to realize that JSON -> type definition is not as good as type definition -> JSON (I think the same hold true for JSON schema, but need to verify).

The reason is that there are information cannot be represented in JSON compare to a formal type specification language such as TypeScript or Flow.

For example. consider the following:

export function foo(options: Options) { ... }

export interface Options {
  a: string,
  b: {
    c: string
    d?: int
  }
}

While this can be used, it is actually better to be written as:

export function foo(option: foo.Options) { ... }

export namespace foo {
  export interface Options {
    a: string,
    b: Options.B
  }

  // this is advance
  export namespace Options {
    export interface B {
      c: string,
      d?: int
    }
  }
}

This way, you can do the following when consuming this library:

import { foo } from 'some-foo'

function myFoo(option: MyOption) { ... }

interface MyOption {
  a?: string // make `a` optional because myFoo will fill in a default value
  b: foo.Options.B // while keep and reuse type of B
}

I think you will have a hard time to generate type definitions like this from JSON (because you need to selectively create reusable sub-complex type).

My two cents. 🌷

Of course, for the first version, the easy way is the best way. 😄

@zeke

This comment has been minimized.

Show comment
Hide comment
@zeke

zeke Apr 4, 2017

Member

I think you will have a hard time to generate type definitions like this from JSON

Hard indeed, but it is happening: https://github.com/electron/electron-typescript-definitions

Member

zeke commented Apr 4, 2017

I think you will have a hard time to generate type definitions like this from JSON

Hard indeed, but it is happening: https://github.com/electron/electron-typescript-definitions

@sohail85

This comment has been minimized.

Show comment
Hide comment
@sohail85

sohail85 Apr 10, 2017

Hi @zeke : This question might not sound right question to be asked in this thread, but being starter on typescript and following this thread made me a bit confused.
In this thread we started to talk about JSON(#6408) and then electron doc linter and then typedefination,
what I understood you will use JSON to make typedefination for electron and I am not sure about linter if we need that since typedefination will be used as a helper and provide intellisense, correct me if I am wrong.
I need to use Electron's type definition in my project and it seems to me there are 3 versions of it available one which maintain by VS code, one by definatly typed and one which you guys are working on, which type definition is safe to work with?
usually by running npm install we get typing folder but its not the case with following command, am I missing something? npm install electron-typescript-definitions --save
Thanks for you hard work and again sorry to ask this question here.

sohail85 commented Apr 10, 2017

Hi @zeke : This question might not sound right question to be asked in this thread, but being starter on typescript and following this thread made me a bit confused.
In this thread we started to talk about JSON(#6408) and then electron doc linter and then typedefination,
what I understood you will use JSON to make typedefination for electron and I am not sure about linter if we need that since typedefination will be used as a helper and provide intellisense, correct me if I am wrong.
I need to use Electron's type definition in my project and it seems to me there are 3 versions of it available one which maintain by VS code, one by definatly typed and one which you guys are working on, which type definition is safe to work with?
usually by running npm install we get typing folder but its not the case with following command, am I missing something? npm install electron-typescript-definitions --save
Thanks for you hard work and again sorry to ask this question here.

@kevinsawicki

This comment has been minimized.

Show comment
Hide comment
@kevinsawicki

kevinsawicki May 31, 2017

Contributor

The electron.d.ts file is now released with the electron npm module and published with each release on https://github.com/electron/electron/releases

Closing this out, please open new issues for specific issues with the current file.

Contributor

kevinsawicki commented May 31, 2017

The electron.d.ts file is now released with the electron npm module and published with each release on https://github.com/electron/electron/releases

Closing this out, please open new issues for specific issues with the current file.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment