[jira] [Commented] (TINKERPOP-2027) Add a Typescript definitions file to the project

["Nicolas KP (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/TINKERPOP-2027?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16730474#comment-16730474 ] 

Nicolas KP commented on TINKERPOP-2027:
---------------------------------------

Dear [~mattallenuk], how is this progressing? I agree that a typescript definitions file would be very helpful, and I could help with that

I created [a hand-written one|https://github.com/tec-goblin/npm-gremlin/blob/master/index.d.ts] for a small part of the API that many clients will use and in the process I discovered some issues with the existing comment-based approach.

A few examples:
 * Client.js and Connection.js use the same options, but the javadoc-like comments describe them differently (none is complete).
 * The typing of some parameters (ca, cert) passed to the WebSocket do not correspond to the typings exposed by the WebSocket npm package. (ex: ca is any[] while the WebSocket package describes it as 
{color:#4ec9b0}string{color} {color:#d4d4d4}|{color} {color:#4ec9b0}string{color}{color:#d4d4d4}[] {color}{color:#d4d4d4}|{color} {color:#4ec9b0}Buffer{color} {color:#d4d4d4}|{color} {color:#4ec9b0}Buffer{color}{color:#d4d4d4}[]{color} )
 * The list of valid step and source names for a Bytecode object is not clear if it's free-text or constrained. By reverse engineering the code I tried to constrain it in my file, ex: 
{color:#4ec9b0}stepName{color} {color:#d4d4d4}={color} {color:#ce9178}'E'{color} {color:#d4d4d4}|{color} {color:#ce9178}'V'{color} {color:#d4d4d4}|{color} {color:#ce9178}'addE'{color} {color:#d4d4d4}|{color} {color:#ce9178}'addV'{color} {color:#d4d4d4}|{color} {color:#ce9178}'inject'{color} {color:#d4d4d4}|{color} {color:#ce9178}'io'{color}

To my eyes, these are mistakes waiting to happen. Maybe it would be even more interesting if the hand-written files were converted to Typescript directly. That way, the devs of the library themselves would have the help of typing and the effort to describe the signatures wouldn't be duplicated. [~jorgebg], [~spmallette] what do you think?

> Add a Typescript definitions file to the project
> ------------------------------------------------
>
>                 Key: TINKERPOP-2027
>                 URL: https://issues.apache.org/jira/browse/TINKERPOP-2027
>             Project: TinkerPop
>          Issue Type: Improvement
>          Components: javascript
>    Affects Versions: 3.3.3, 3.2.9
>            Reporter: Matthew Allen
>            Priority: Major
>
> For those using Typescript it would be great to provide a type definition file for the glv. 



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)