feat(docgen): improve typescript generator #25

drauggres · 2019-12-18T17:15:08Z

Dictionary (typed factory methods):

const button = Ti.UI.createButton({
 width: 100,
 backgroundColor: '#ddd',
 text: '+',   // TS2345: [..] 'text' does not exist in type [..]
 left: 10
});

Typed this in addEventListner, removeEventListener:

const button = Ti.UI.createButton();
button.addEventListener('click', function(e) {
 this.backgroundColor = 'red';
 this.text = 123;  // TS2339: Property 'text' does not exist on type 'Button'.
});

Types for Events:

const button = Ti.UI.createButton();

// know event type
button.addEventListener('click', function(e) {
 e.source.backgroundColor = 'red';
 console.log(`x: ${e.x}`);
 console.log(`x: ${e.z}`);  // TS2339: Property 'z' does not exist on type 'Button_click_Event'.
});

// unknown event type
button.addEventListener('myEvent', function(e) {
 console.log(e.lol);  // ok, because 'myEvent' is unknown event type -> e: any
});

Modules declared as both namespace and class (with static methods). This allows to define types for specific events for Modules like Ti.Geolocation, Ti.Media, Ti.Network etc.:

Ti.Network.addEventListener('change', e => {
  console.log(e.reason);
  console.log(e.status);  // TS2339: Property 'status' does not exist on type 'Network_change_Event'
});

Additonal changes:

inject id?: string|number in Ti.Proxy
rest parameter for Titanium.Database.DB.execute

Explanations:

For every event generated:

base event interface with name ${ClassName}BaseEvent (e.g. ButtonBaseEvent)
event interface with name ${ClassName}_${EventName}_Event (e.g. Button_click_Event) and extended from the base event
"map" interface to math event name and event interface (e.g. ButtonEventMap)
note: : in the name of a event is replaced with _ for generated interfaces (event name itself is not changed)

IMPORTANT: event interface name is not documented and is generated as shown above. Since they will be in users code (if they decide to write in TypeScript), they could not be changed at any time. These names will be part of the API and must remain stable.

removed canExtend + removeMembers: were not really useful, only could decrease size of the output, but removeMembers did not take in accout excludes, so result was incorrect.
removed generateMethodOverloadsIfRequired: as was mentioned in the function description:

Currently only handles one case where a parameter can be passed as both a single value and as an array, e.g. Ti.UI.View, Array<Ti.UI.View>

TypeScript can handle this case e.g. add(view: Titanium.UI.View | Titanium.UI.View[]): void;

code from nodes constructors moved to the init method: since for one module could be generated two nodes (interface and namespace) in order to decrease output size I'm skipping namespace node without any internal interfaces and namespaces. To do this I need at first to build "the tree" and then deside where I want to keep properties and methods/functions.

~~Only thing that makes impossible to use generated file to write in TypeScript is the problem with PickerColumn~~

UPD: APIs from files under apidoc/Modules are removed from output. It is incorrect to put them inside of titanium/index.d.ts (ideally they should be placed in separate files ti.cloud/index.d.ts and ti.cloudpush/index.d.ts).

More things came up:

fix global.console and global.JSON variables (currently they are interfaces) (docs: fix global methods and properties titanium-sdk#11464)
fix methods of global.console (log/err/warn/info/debug accepts "vararg") (docs: add "repeatable" property on methods parameters titanium-sdk#11468)

- generate Global properties - generate namespace and interface for modules

drauggres · 2019-12-18T17:22:15Z

Here is the result for this + #24 + tidev/titanium-sdk/pull/11348

drauggres · 2019-12-25T17:50:24Z

Tested file from the comment above with DefinitelyTyped linter. Work fine. Even found an error in the tests.

- remove trailing spaces from jsdoc - use "any[]" as parameter for Ti.Database.DB.execute - use "Array<Dictionany<T>>" type instead of "Dictionary<T>[]" - add "tslint:disable-next-line:ban-types" for "Function" type - update TypeScript Version to 3.0: "excluded" methods are typed as properties with "methodName: never", this is not allowed before 3.0

first class, then namespace: https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-namespaces-with-classes

generated class for Titanium will have only static members

…sOnlyProxy

It is valid to pass a function (e.g. "onload") to Ti.Network.createHTTPClient() in Dictionary<Ti.Network.HTTPClient>. So now we exclude from T only Functions that came from Ti.Proxy Since SDK 9.0 accessors will be removed, so they will not bother us here.

drauggres · 2020-01-17T10:13:19Z

Last changes:

Remove from output APIs from files under apidoc/Modules. It is incorrect to put them inside of titanium/index.d.ts (as Ti.Modules.<Name>): they should be placed in separate files ti.cloud/index.d.ts and ti.cloudpush/index.d.ts (TBD, I have no plans on this).
Add @deprecated annotation and deprecation notes into jsdoc for deprecated APIs.

Now (after tidev/titanium-sdk#11348 is merged) it is possible to generate valid definitions with this generator.

I think, I'm finally done here. @janvennemann please review.

janvennemann

@drauggres First of all, a big thank you for porting this to the existing typescript generator. The typed create functions and events are super awesome!

I did a first pass through this and added a couple of notes. I also have a question about one of the things you removed:

removed canExtend + removeMembers: were not really useful, only could decrease size of the output, but removeMembers did not take in accout excludes, so result was incorrect.

Instead of just ripping it out completely, why not improve it to respect excludes? Your generated output is twice the size of how it was before. Did you test it with excludes to see if it's worth it?

packages/titanium-docgen/generators/typescript_generator.js

drauggres · 2020-02-06T14:16:57Z

Instead of just ripping it out completely, why not improve it to respect excludes? Your generated output is twice the size of how it was before. Did you test it with excludes to see if it's worth it?

We don't need canExtend all information about inheritance is already present in __inherits property.
This and this will reduce size of the output (so it will be about 32% larger than original).

janvennemann

@drauggres Awesome, the size looks much better now.

I copied the generated types with this PR over to the types in DefinitelyTyped and tried to run npm run lint titanium to see if it validates. It's spitting out errors about duplicate identifiers console and JSON. Can you check that? Removing dom gets rid of the console error. But JSON seems to be always included, even with es5 only. Do we need to exclude that in our typings?

The only remaining thing i'd really like to change are the event names to have a consistent camel-cased naming scheme, but since that is not possible due to technical limitations i guess we have to go with the underscored names.

drauggres · 2020-02-14T15:24:50Z

I didn't try to run the linter after this comment (only compiled my projects with new definitions).

Removing dom gets rid of the console error.

Work fine for me even with dom (my DefinitelyTyped fork). If linter fails with dom we can exlude it; compliation with dom included works fine (as you know, it is required by backbone).

But JSON seems to be always included, even with es5 only.

It looks like we can't (and probably shouldn't) declare JSON variable and interface in global space, because it's part of the ECMA-262 5.1 specification (and always exists in es5+ environment). Solutions:

Skip JSON in generator
Remove JSON.yml from apidoc (and JSON property from Global.yml)

Also, because I added @deprecated tag, linter complains about violation of no-redundant-jsdoc-2 rule. Solutions:

Add "no-redundant-jsdoc-2": false into tslint.json
Remove @deprecated tag

janvennemann · 2020-02-14T16:36:42Z

Removing dom gets rid of the console error.

Work fine for me even with dom (my DefinitelyTyped fork). If linter fails with dom we can exlude it; compliation with dom included works fine (as you know, it is required by backbone).

I see the following error when including dom lib and @types/titanium together in a project. Note that they only pop up when i actually try to compile using tsc, linting in VSCode works fine.

node_modules/@types/titanium/index.d.ts:1152:1 - error TS1046: Top-level declarations in .d.ts files must start with either a 'declare' or 'export' modifier.

1152 class console {
     ~~~~~

node_modules/@types/titanium/index.d.ts:1152:7 - error TS2300: Duplicate identifier 'console'.

1152 class console {
           ~~~~~~~

  node_modules/typescript/lib/lib.dom.d.ts:19661:13
    19661 declare var console: Console;
                      ~~~~~~~
    'console' was also declared here.

node_modules/typescript/lib/lib.dom.d.ts:19661:13 - error TS2300: Duplicate identifier 'console'.

19661 declare var console: Console;
                  ~~~~~~~

  node_modules/@types/titanium/index.d.ts:1152:7
    1152 class console {
               ~~~~~~~
    'console' was also declared here.


Found 3 errors.

So we can't use both together or it will blow up. But we also can't exclude our global console, because then it would be missing if dom lib is not included.

This is kind of a mess, especially when using TypeScript in Alloy (as it uses backbone). Please see some related discussion here and here. I haven't come up with a proper solution for this yet, so any ideas are greatly appreciated. IMHO, including dom in Titanium projects is wrong, since we don't support 99% of the types that are defined there. The only possible fix for this that i see is that we fork our own versions of the backbone types and rip out all types that create the dependency on the dom lib.

But JSON seems to be always included, even with es5 only.

It looks like we can't (and probably shouldn't) declare JSON variable and interface in global space, because it's part of the ECMA-262 5.1 specification (and always exists in es5+ environment). Solutions:

Skip JSON in generator

Remove JSON.yml from apidoc (and JSON property from Global.yml)

Agreed, we should remove JSON from our docs since it's part of the ECMA spec. Users can refer to JSON on MDN for example.

Also, because I added @deprecated tag, linter complains about violation of no-redundant-jsdoc-2 rule. Solutions:

Add "no-redundant-jsdoc-2": false into tslint.json

Remove @deprecated tag

Ok, that's odd. I don't see those linting issues. These are the only linting issues is see once i resolve the above issues (removed dom lib and removed JSON types):

~/Development/typescript/DefinitelyTyped on master ❱❱❱ npm run lint titanium

> definitely-typed@0.0.3 lint /Users/jvennemann/Development/typescript/DefinitelyTyped
> dtslint types "titanium"

Error: /Users/jvennemann/Development/typescript/DefinitelyTyped/types/titanium/index.d.ts:1152:1
ERROR: 1152:1  no-unnecessary-class  Every member of this class is static. Use namespaces or plain objects instead.
ERROR: 1152:1  expect                TypeScript@next compile error: 
Top-level declarations in .d.ts files must start with either a 'declare' or 'export' modifier.

/Users/jvennemann/Development/typescript/DefinitelyTyped/types/titanium/titanium-tests.ts:35:4
ERROR: 35:4    expect                TypeScript@next compile error: 
Type 'string' is not assignable to type 'never'.

    at /Users/jvennemann/Development/typescript/DefinitelyTyped/node_modules/dtslint/bin/index.js:193:19
    at Generator.next (<anonymous>)
    at fulfilled (/Users/jvennemann/Development/typescript/DefinitelyTyped/node_modules/dtslint/bin/index.js:6:58)v

drauggres · 2020-02-17T09:52:51Z

I see the following error when including dom lib and @types/titanium together in a project. Note that they only pop up when i actually try to compile using tsc, linting in VSCode works fine.

node_modules/@types/titanium/index.d.ts:1152:1 - error TS1046: Top-level declarations in .d.ts files must start with either a 'declare' or 'export' modifier. 
1152 class console {

There is no class console in the output from this version of the generator.

Ok, that's odd. I don't see those linting issues.

For some reason they don't come up when I run linting in DefinitelyTyped repo clone, only in my fork (probably there are different versions of some packages). Nevermind.

These are the only linting issues is see once i resolve the above issues (removed dom lib and removed JSON types):

ERROR: 1152:1  no-unnecessary-class  Every member of this class is static. Use namespaces or plain objects instead.
ERROR: 1152:1  expect                TypeScript@next compile error: 
Top-level declarations in .d.ts files must start with either a 'declare' or 'export' modifier.

Line 1152 is class console, it shouldn't be there.

ERROR: 35:4    expect                TypeScript@next compile error: 
Type 'string' is not assignable to type 'never'.

    at /Users/jvennemann/Development/typescript/DefinitelyTyped/node_modules/dtslint/bin/index.js:193:19
    at Generator.next (<anonymous>)
    at fulfilled (/Users/jvennemann/Development/typescript/DefinitelyTyped/node_modules/dtslint/bin/index.js:6:58)v

That is a valid error: url property was removed from Ti.UI.ImageView long time ago.

janvennemann · 2020-02-18T11:04:47Z

There is no class console in the output from this version of the generator.

Sry, my bad, it seems like i was running an outdated version of your branch. Regenerated it and now the error is gone.

ERROR: 35:4    expect                TypeScript@next compile error: 
Type 'string' is not assignable to type 'never'.

    at /Users/jvennemann/Development/typescript/DefinitelyTyped/node_modules/dtslint/bin/index.js:193:19
    at Generator.next (<anonymous>)
    at fulfilled (/Users/jvennemann/Development/typescript/DefinitelyTyped/node_modules/dtslint/bin/index.js:6:58)v

That is a valid error: url property was removed from Ti.UI.ImageView long time ago.

Duh, of course! About time to update our tests inside DefinitelyTyped, which is where i got that from.

Everything seem to be sorted out now, approved! Awesome work man!

drauggres added 7 commits December 18, 2019 18:06

fix(docgen): typescript: eslint problems in the generator

618a379

fix(docgen): typescript: sort APIs, methods and properties

452fc9e

fix(docgen): typescript: improve generator

bdc6096

- generate Global properties - generate namespace and interface for modules

feat(docgen): typescript: generate interfaces for events

572c478

feat(docgen): typescript: inject "id" prop into "Ti.Proxy"

3eecc87

fix(docgen): typescript: "Windows" addon

12a5011

fix(docgen): typescript: rest parameter for Ti.Database.DB.execute

6f231c6

drauggres mentioned this pull request Dec 18, 2019

feat(docgen): new generator for TypeScript declaration #8

Closed

drauggres added 2 commits December 25, 2019 12:15

fix(docgen): typescript: restore "defaultValue"

f70d3b3

fix(docgen): typescript: skip removed events

12cb24e

drauggres added 6 commits December 26, 2019 11:59

fix(docgen): typescript: reorder nodes.

9bc6012

first class, then namespace: https://www.typescriptlang.org/docs/handbook/declaration-merging.html#merging-namespaces-with-classes

fix(docgen): typescript: generate only namespace for Titanium

f9c655b

generated class for Titanium will have only static members

fix(docgen): typescript: remove "declare" from interfaces

b73bcbb

fix(docgen): typescript: don't skip namespace generation for Constant…

4281e68

…sOnlyProxy

drauggres force-pushed the feature/improve_ts branch from 5e555c5 to c9571cc Compare December 26, 2019 09:00

fix(docgen): typescript: handle "excludes" in isConstantOnlyProxy

8443b56

drauggres force-pushed the feature/improve_ts branch from 8fc4b97 to 8443b56 Compare January 9, 2020 14:33

drauggres added 2 commits January 9, 2020 17:35

fix(docgen): typescript: update header

0015133

fix(docgen): typescript: add new line after removed members

fa8ee78

janvennemann self-requested a review January 10, 2020 14:14

fix(docgen): typescript: skip bundled documentation for modules

cc26435

feat(docgen): typescript: add @deprecated to jsdoc

ae6483d

drauggres force-pushed the feature/improve_ts branch from 3d6efa8 to ae6483d Compare January 17, 2020 10:20

janvennemann requested changes Feb 5, 2020

View reviewed changes

fix(docgen): typescript: skip inherited properties

0b7916c

drauggres added 4 commits February 6, 2020 15:54

fix(docgen): typescript: skip inherited methods

b2e0251

fix(docgen): typescript: handle top level classes

94111d0

fix(docgen): typescript: parent namespace search

0fabf50

fix(docgen): typescript: remove check for "Ti.Modules"

8f6ebe2

drauggres requested a review from janvennemann February 6, 2020 15:28

drauggres added 2 commits February 10, 2020 14:02

feat(docgen): typescript: handle global variables

8e97909

feat(docgen): typescript: handle "repeatable" args

4ad7a41

drauggres force-pushed the feature/improve_ts branch from 886557a to 4ad7a41 Compare February 10, 2020 14:17

janvennemann requested changes Feb 14, 2020

View reviewed changes

drauggres mentioned this pull request Feb 17, 2020

docs: remove JSON from documentation tidev/titanium-sdk#11479

Merged

janvennemann approved these changes Feb 18, 2020

View reviewed changes

janvennemann merged commit 34f07c5 into tidev:develop Feb 18, 2020

drauggres mentioned this pull request Mar 4, 2020

TS generator. JSON #32

Closed

janvennemann mentioned this pull request Mar 5, 2020

[titanium] update types for Titanium 9.0.0 DefinitelyTyped/DefinitelyTyped#42856

Merged

9 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

feat(docgen): improve typescript generator #25

feat(docgen): improve typescript generator #25

Uh oh!

drauggres commented Dec 18, 2019 •

edited

Loading

Uh oh!

drauggres commented Dec 18, 2019

Uh oh!

drauggres commented Dec 25, 2019

Uh oh!

drauggres commented Jan 17, 2020

Uh oh!

janvennemann left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

drauggres commented Feb 6, 2020

Uh oh!

janvennemann left a comment

Uh oh!

drauggres commented Feb 14, 2020

Uh oh!

janvennemann commented Feb 14, 2020

Uh oh!

drauggres commented Feb 17, 2020

Uh oh!

janvennemann commented Feb 18, 2020

Uh oh!

Uh oh!

Uh oh!

feat(docgen): improve typescript generator #25

feat(docgen): improve typescript generator #25

Uh oh!

Conversation

drauggres commented Dec 18, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

drauggres commented Dec 18, 2019

Uh oh!

drauggres commented Dec 25, 2019

Uh oh!

drauggres commented Jan 17, 2020

Uh oh!

janvennemann left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

drauggres commented Feb 6, 2020

Uh oh!

janvennemann left a comment

Choose a reason for hiding this comment

Uh oh!

drauggres commented Feb 14, 2020

Uh oh!

janvennemann commented Feb 14, 2020

Uh oh!

drauggres commented Feb 17, 2020

Uh oh!

janvennemann commented Feb 18, 2020

Uh oh!

Uh oh!

drauggres commented Dec 18, 2019 •

edited

Loading