TypeScript Definition for Cytoscape.js - It is being worked on now!

[Cyberider]

For any of you that use or are thinking of using TypeScript to strengthen your JS coding there is s TS definition file project in the works.

Fabian-Schmidt (not me) is working on it at: https://github.com/Fabian-Schmidt/DefinitelyTyped/tree/master/cytoscape

I use TypeScript so I'm excited to be able to use cytoscape.js with TypeScript.

Rick

[Killbot5000]

I'm in the process of completing the work of Fabian-Schmidt.

I'll try to get everything upstream by the end of August, but the process of branching and merging is still new to me, so a delay is possible.

In the meantime, feel free to bug me for the latest version.

Regards, KB5000

[Cyberider]

If it helps:

In the discussion at: https://github.com/borisyankov/DefinitelyTyped/issues/4763 @maxkfranz offers a JSON spec of the API.

Between that and this project: https://github.com/horiuchi/dtsgenerator (TypeScript d.ts file generate from JSON Schema file)

Can you get the JSON spec to generate the d.ts definition file?

[phreed]

Would you mind it I made this a typed-typings? https://github.com/typed-typings The advantages are described here... https://github.com/typings/typings/issues/322

[Cyberider]

What is your typed-typings? A curated list of typed definitions?

Date: Thu, 23 Jun 2016 11:18:21 -0700 From: notifications@github.com To: cytoscape.js@noreply.github.com CC: rickgodwin@hotmail.com; author@noreply.github.com Subject: Re: [cytoscape/cytoscape.js] TypeScript Definition for Cytoscape.js - It is being worked on now! (#1012)

Would you mind it I made this a typed-typings?

https://github.com/typed-typings

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[maxkfranz]

Whatever way Typescript definitions are published, it would be great if it could be automated on the Cytoscape.js side so that they're automatically kept up to date.

The docmaker.js file generates the HTML version of the docs from docmaker.json. It would be great if a tsdefmaker.js file could be made to output a .d.ts file. That way, everything could be automated with each release.

I'm not an expert an TS or TS defs, so it would be great if someone wanted to make a PR to do this.

Thanks

[phreed]

Typed-Typings is similar to DefinitelyTyped except rather than having all the typing definition files in a single git repository they can be placed in a number of places. This also allows for a registry for different versions of the typings.

[Cyberider]

okay, great. Sure, do what you got to do regarding cytoscape.js

Date: Fri, 24 Jun 2016 10:51:49 -0700 From: notifications@github.com To: cytoscape.js@noreply.github.com CC: rickgodwin@hotmail.com; author@noreply.github.com Subject: Re: [cytoscape/cytoscape.js] TypeScript Definition for Cytoscape.js - It is being worked on now! (#1012)

Typed-Typings is similar to DefinitelyTyped except rather than having all the typing definition files in a single git repository they can be placed in a number of places.

This also allows for a registry for different versions of the typings.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[Cyberider]

Okay sounds great but I have nothing to do with the cytoscape.js project! I have just expressed a desire to have TS defs for it. Rick

Date: Fri, 24 Jun 2016 08:10:20 -0700 From: notifications@github.com To: cytoscape.js@noreply.github.com CC: rickgodwin@hotmail.com; author@noreply.github.com Subject: Re: [cytoscape/cytoscape.js] TypeScript Definition for Cytoscape.js - It is being worked on now! (#1012)

Whatever way Typescript definitions are published, it would be great if it could be automated on the Cytoscape.js side so that they're automatically kept up to date.

The docmaker.js file generates the HTML version of the docs from docmaker.json. It would be great if docmaker.js could be refashioned into a tsdefmaker.js file to output a .d.ts file. That way, everything could be automated with each release.

I'm not an expert an TS or TS defs, so it would be great if someone wanted to make a PR to do this.

Thanks

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[aindlq]

@phreed Are you still going to publish the typings?

fyi I'm successfully using them in my project, so far so good. Also I've made some significant improvements to them in the Styles/CSS part.

[phreed]

Pretty soon. I do not need them quite yet for my project.

[ktong]

@phreed Would you mind to share me your typed-typings? I am using cytoscape in an angular2 based projects.

Thanks

[calebeaires]

Is there some news about cytoscape typing?

[phreed]

I am continuing to work on them. You can use them in there current state from my github project. I add the following to my package.json file

"devDependencies": {
...
"@types/cytoscape": "github:phreed/ts-typings#cytoscape",
...
}

and then npm install @types/cytoscape or npm install --save-dev github:phreed/ts-typings#cytoscape

[calebeaires]

@phreed very thanks for it!

[Cyberider]

Wow, nice work @phreed!

Why not PR your work-in-progress to the Typescript Definitions repository DefinitelyTyped so others can help you polish it up?

[felixfbecker]

After https://github.com/cytoscape/cytoscape.js/issues/1012#issuecomment-228372289, why not do PR to this repo and publish them with npm? That would be even better than DefinitelyTyped

[maxkfranz]

Unless the process of creating ts defs can be completely automated through the existing docs build, then they won't be maintained in the official repo.

It would be great if someone would create a community npm package. Maybe @phreed would like to publish https://github.com/phreed/ts-typings/tree/cytoscape to npm, or maybe someone could create a new Github repo based on @phreed's work that could centralise community ts defs for Cytoscape.

[felixfbecker]

The .d.ts file would have to get updated on interface changes. The alternative would be to actually use TypeScript in this library, which would provide a variety of benefits (type safety => less bugs). In that case .d.ts files would get generated automatically.

The official distribution channel for community typings is through DefinitelyTyped (which gets published to @types on npm).

[maxkfranz]

@phreed's defs are for Typed-Typings rather than DefinitelyTyped.

I don't think it's likely that Cytoscape will be rewritten in TS. If the community wants to maintain a separate defs package to support TS users, that's great and we'd be glad to link to it!

[Lambik]

Afaik there are no typings yet for version 3.0.0? :(

[phreed]

My plan in May is to update to @types and v3. Alternatively I am considering a Typescript wrapper.

On Thu, Apr 27, 2017, 04:04 Tom Muylle notifications@github.com wrote:

Afaik there are no typings yet for version 3.0.0? :(

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/cytoscape/cytoscape.js/issues/1012#issuecomment-297657057, or mute the thread https://github.com/notifications/unsubscribe-auth/AAM6vB0CbRCGo0KSF0D6n3camv2qAMhPks5r0FougaJpZM4FZKD3 .

[felixfbecker]

@phreed how's it going? Any update?

[phreed]

This is where things are now https://github.com/phreed/ts-typings/tree/cytoscape I am working through the v3 api and should have something in @types within the next couple of days.

[phreed]

I have a draft version for the v3 api. https://github.com/phreed/ts-typings/tree/cytoscape3

[phreed]

I believe what you mention was a change from v2.x to v3.x I have been working on the typings for v3.x here... https://github.com/phreed/ts-typings/blob/cytoscape3/index.d.ts

I have completed a pass through the latest documentation... http://js.cytoscape.org/ ...but there are probably (certainly) errors. I am working though the tests based on the examples in that document now and would welcome any help. My plan is to release this work as part of DefinitelyTyped... https://github.com/phreed/DefinitelyTyped

Thanks

On Wed, May 17, 2017 at 11:15 AM WaynePlummer notifications@github.com wrote:

Should this:

interface Stylesheet {
    selector: string;
    css: Css.Node | Css.Edge;
}

actually read:

interface Stylesheet {
    selector: string;
    style: Css.Node | Css.Edge;
}

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/cytoscape/cytoscape.js/issues/1012#issuecomment-302141723, or mute the thread https://github.com/notifications/unsubscribe-auth/AAM6vASI5uXqxd9UEy1I8ay2VImpxUanks5r6x0ugaJpZM4FZKD3 .

[maxkfranz]

Should this:

 interface Stylesheet {
     selector: string;
     css: Css.Node | Css.Edge;
 }

actually read:

 interface Stylesheet {
     selector: string;
     style: Css.Node | Css.Edge;
 }

Either works in 2.x or 3.2, but style is preferred and css is now undocumented/deprecated.

[WaynePlummer]

Yes, I deleted my original post once I realised that this must be what was going on... but thanks, @phreed and @maxkfranz both for confirming :)

[maxkfranz]

I've been looking into automation a bit more and it seems both TS and Flow have some options that might work to more directly integrate type definitions into Cytoscape:

• Flow
  • JSDoc support in JavaScript
  • Flow comments
  • flow-jsdoc
  • flow-typed
• TS
  • Typescript type annotations as comments
  • Support 'Promote JSDoc comment to type annotation'
  • Support 'Promote JSDoc comment to type annotation'

I would lean towards using Flow, because it supports using JSDoc comments to generate the type definition files. It looks like JSDoc (now v3) is much better than it was when this lib was started, so maybe we could use it to generate the docs page as well.

[felixfbecker]

TypeScript is way more popular than Flow. Just look at questions asked on StackOverflow:

Flow definitions won't help TypeScript users of course, and TypeScript definitions don't help Flow users. At least in this thread, people asked for TypeScript definitions, not for Flow definitions ;)

[maxkfranz]

TS may be more popular than Flow, but JS is more popular than TS by a wide margin. Flow can be used without making semantic changes to the source, whereas it seems TS must make semantic changes to the source. This lib will not use TS or Flow to directly generate definition files unless the source is still just plain JS. It's important that anyone who knows JS can pick up the source in any editor, modify it easily, and run/test it natively on Node without any compilation step. 3.2/unstable uses Babel/ESNext for compatibility with old browsers, for example, but the source can be run directly in Node 6+.

This looks to be possible in Flow, but I don't see any official support notes in the TS docs or the TS issue tracker. If the goal of this ticket is to have productive autocomplete/intellisense in your tooling, it shouldn't matter whether it uses Flow or TS: Your editor can use plugins for both.

I don't have any inherent preference for either tool, but I think if the lib ever supports typings in the source it would have to use JSDoc comments. It's ubiquitous and non-intrusive. Ideally we could support both Flow and TS output via JSDoc comments.

If TS supports JSDoc, then that's great. But I'd like to see docs for it; I didn't find any. If TS doesn't support JSDoc, I think it would be worthwhile for you guys to advocate for it in the TS issue tracker. I think that's the only way there'd be direct support for TS in this lib.

[opavader]

@maxkfranz I think for now TS users will be very much happy with simple inclusion of typedef files created by @phreed . typedef files are fairly easy to maintain as they are limited mostly to api only and there are rarely major breaking changes in any libraries api. For development of library, I guess JSDoc comments will be suffice for most contributors.

[phreed]

Have any of you had a chance to give it a try? https://github.com/phreed/ts-typings/tree/cytoscape3 Should I go ahead a push it out to DefinitelyTyped? The typings are working for my current project. I am planning on using cytoscape.js from ClojureScript for my next project. I won't be able to spend much time on maintenance, so somebody else should probably pick this up.

[phreed]

@maxkfranz I am not sure what you mean by TS requiring semantic changes to the underlying JS. From my perspective there are no changes necessary to the underlying JS or semantically or otherwise. The typings simply provide some of the missing description of an otherwise obscure semantic.

[maxkfranz]

I am not sure what you mean by TS requiring semantic changes to the underlying JS.

@phreed (1) (a : int, b : int) => a + b is different from (1) (a : String, b : String) => a + b even though the compiled result is the same. But my original point was that either of the two previous lines is different than (3) (a, b) => a + b: (1) and (2) have additional semantics not present in (3) and no browser is able to interpret (1) or (2). Using comments to annotate (3) with types doesn't break anything, whereas (1) or (2) are broken unless you buy into the TS ecosystem and require any contributor or user (who modifies the source) to do the same. That's my real concern. Anybody familiar with JS should be able to just edit the source, not just TS experts.

@opavader Yes, @phreed's definition for the lib is great! My points mainly concern the future. Say a year from now, is that definition file up-to-date? Longterm, it's probably best if generation of the definition can be automated from the lib source so it's always up-to-date.

[felixfbecker]

@maxkfranz you don't need to add TS types to the source. It's possible to add the .d.ts files alongside the .js files, which means the JS will run fine in any browser.

[maxkfranz]

@felixfbecker That's correct, but it seems you do need to add TS types to the source if you want to generate the definition automatically from the source. The Cytoscape Consortium has limited resources and TS support, in the grand scheme of things, is a relatively low priority. If TS support can't be automated and very easily maintained (like with JSDoc comments), then there probably won't be first-party TS support.

If the goal of everyone in the thread is to have a high quality, up-to-date definition in the longterm, then I think we should try to aim for automated, easily-maintained JSDoc comments as I've mentioned. I found this on the wiki, but the docs don't say anything about support.

[felixfbecker]

Understood. I think we can live fine with external typings.

[opavader]

@phreed I used your typedefs and so far have worked well and I will be happy to continue with the maintenance.

@maxkfranz There is such a tool tsd-jsdoc, though this too will require lot of additions & cleanup of current jsdoc comments.

[phreed]

@opavader We should move forward with pushing the typings from my ts-typings repo, as they are, into DefinitelyTyped. The DefinitelyTyped location will then be the primary source.

I believe the typings to be complete as far as covering the API. What remains is testing which includes adding all of the samples into the test file and people like you all kicking it around.

[opavader]

@phreed shouldn't it be bundled with this package itself. PRs to DefinitelyTyped often take multiple days to get merged. Updates & versioning will be eased as well.

[phreed]

@maxkfranz Is the following the substance of your point?

The primary question regarding providing data and function type specifications is... What would the cytoscape.js people be willing to do?

• keep a set of informal / formal specifications in the jsdocs (current approach)
• keep a set of formal specifications in the jsdocs
• keep a set of type specifications separate from the main javascript but in the cytoscape repository @opavader
• notify a collaborator (us) that the api has changed

A secondary question... What should the form of these specifications?

• flow, typescript, jsdoc,

[felixfbecker]

The existing tools to convert JSDoc to TypeScript definitions are all oriented to serve as a starting point for writing definitions, not continuously automating their generation. That is because the TypeScript type system is way more expressive to describe JavaScript APIs than JSDoc.

[maxkfranz]

@phreed

keep a set of informal / formal specifications in the jsdocs (current approach)

We don't even have this yet in the lib. There's a hand-rolled docs generator script from a json spec.

keep a set of formal specifications in the jsdocs

Ideally we could use formal jsdoc comments throughout (at least) the public-facing api to generate the docs, ts defs, and flow defs. This would be a good, longterm option. The source doesn't have any jsdoc comments yet, so this would all be todo.

keep a set of type specifications separate from the main javascript but in the cytoscape repository @opavader

This is the best option in the shortterm.

notify a collaborator (us) that the api has changed

That should be easy/automatic, because all api changes are documented in each version's milestone.

@felixfbecker Do you have an example of jsdoc not being enough? My understanding is that detailed-enough jsdoc comments should suffice for features like intellisense/autocomplete. Tern seems able to do it with just jsdoc comments, so I think ts should be able to do the same.

[wy193777]

@phreed Do you want to push your definition to DefinitelyTyped now? Usually other users need to use it in typescript could take care of it.

[wy193777]

I created a pull request after fix lint and other small errors. Push it to DefinitelyTyped could let other users use it and fix problems when they are using it. Ideally this could be maintained by users automatically without cytoscape developer. https://github.com/DefinitelyTyped/DefinitelyTyped/pull/20511

[wy193777]

Today the type definition has been merged to DefinitelyTyped, but it has some problems.

When I import the module: import * as cytoscape from "cytoscape";, and call cytoscape(), compiler tell me Cannot invoke an expression whose type lacks a call signature. Type 'typeof "./node_modules/@types/cytoscape/index"' has no compatible call signatures.. But the compile result is right in this condition.

When I call with cytoscape.cytoscape(), ts compiler doesn't show an error but compile result is cytoscape_1.cytoscape() which is incorrect because the library supposed to be called directly.

cytoscape type source on DefinitelyTyped: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/d9ca7d7efff765abe162023a9aa47f51f473bfd7/types/cytoscape/index.d.ts

Can someone familiar with typescript look into it? I've worked on it for the whole day without any solution.

[opavader]

Shouldn't cytoscape be declared as a class with a constructor, like its done here types/dygraphs/index.d.ts#L924?

[wy193777]

I just submitted an fix for it: https://github.com/DefinitelyTyped/DefinitelyTyped/pull/20616. This would solve the import problem. @opavader

[WaynePlummer]

I am not sure what the best forum is for reporting problems with the cytoscape typings themselves?

I have seen two issues:

1. The function scratch() and friends should be available on Core
2. The function jsons() returns POJOs, not JSON strings as its name might suggest, so "string[]" is not the right return type (probably should be "ElementDefinition[]").

Thanks for finally getting this up on npm :)

[wy193777]

@WaynePlummer If you like you could submit a pull request on DefinitelyTyped project to fix the problem.