Skip to content
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

Generate TypeScript ical.d.ts from jsdoc and include in releases #367

Open
knu73r1k opened this issue Sep 20, 2018 · 34 comments
Open

Generate TypeScript ical.d.ts from jsdoc and include in releases #367

knu73r1k opened this issue Sep 20, 2018 · 34 comments

Comments

@knu73r1k
Copy link

Anybody which know if there exists a ical.d.ts file for TypeScript @types module?

@kewisch
Copy link
Owner

kewisch commented Nov 9, 2018

I'm mostly worried about keeping this file up to date. @glixlur Did you write that by hand, or was it automatically generated?

@knu73r1k
Copy link
Author

knu73r1k commented Nov 9, 2018

Cool - tx @glixlur

@sebius8780
Copy link

@kewisch Do you have any work around to import ical.js into angular 6 project ?
If not @glixlur it will be really cool if you could work it out with @kewisch ?

i am looking forward to see if you can pull it of, would be really nice to have this lib Ts compliant :)

@ALGDB
Copy link

ALGDB commented Dec 10, 2018

hi, how can I use @glixlur types?

@ALGDB
Copy link

ALGDB commented Dec 11, 2018

Hi Just to understand.

in:

new Component(jCal, parent)

parent is optional or mandatory as stated in the docs?

because, as far as I can see it seems optional component.js

function Component(jCal, parent) { 
if (typeof(jCal) === 'string') {
 // jCal spec (name, properties, components)
 jCal = [jCal, [], []];
}
 // mostly for legacy reasons.
 this.jCal = jCal; 
this.parent = parent || null;
  }

@sebius8780
Copy link

I made it work using undefined, you should be able to make it right within the d.ts file though.

@tasn
Copy link

tasn commented Jul 25, 2019

I have a manually created (though incomplete) typing file I created. I use it extensively in and add parts as I get to them https://github.com/etesync/etesync-web The actual file: https://github.com/etesync/etesync-web/blob/master/src/types/ical.js.d.ts (I updated it a bit more since, will push those local changes soon I hope).
Also, I created it manually. If there's a way to create it automatically (@Proteria ?) that would be much better (as long as it respects optional parameters). :P

I can take a look into making it more complete and submit a patch if there's interest. @kewisch ?

Otherwise it can go to https://github.com/DefinitelyTyped/DefinitelyTyped but then you'd have even less control when it comes to keeping it up to date.

@kewisch
Copy link
Owner

kewisch commented Jul 25, 2019

I'd prefer something that is auto-generated, I don't want to be updating this file manually or requiring it for people making pull requests.

@tasn
Copy link

tasn commented Jul 25, 2019

Obviously preferable, though how often does the API actually change? At the moment people (like myself and @Proteria) end up manually implementing it for ourselves, and who knows how many others like us are there. I think having a version (@Proteria's?) that covers what there's there now and worst case have her lag behind a bit in the future or until an automatic generator is implemented may be better, no?

I'm content with my hand-rolled types for myself, so no rush on my side. I'm just giving feedback based on my usage of this library and others with missing or incomplete typings.

@HugoGresse
Copy link

up! I'm just writing a new project and I don't really like to take half a day fixing other types or writing it myself.

@tasn
Copy link

tasn commented Dec 23, 2019

@HugoGresse, it's far from complete, but take a look at: https://github.com/etesync/ios/blob/master/src/types/ical.js.d.ts

@HugoGresse
Copy link

thanks @tasn 👍
Small note: add TSlint to your project, the main error is public static that replace static public

@tasn
Copy link

tasn commented Dec 23, 2019

@HugoGresse, tslint is deprecated, I use eslint with the typescript plugin (you can see the config in the root of the repo).
What rule was it that was triggered for you? I'll add it to my config.

@HugoGresse
Copy link

arf, Firebase functions still use it :(
this is the default firebase functions config for tslint: https://github.com/HugoGresse/open-feedback/blob/master/functions/tslint.json

@tasn
Copy link

tasn commented Dec 23, 2019

No idea then, not important enough to try to figure out the tslint rule. Thanks though.

@amadeus-torwell
Copy link

amadeus-torwell commented Mar 2, 2020

Are there any official typings available yet for ical.js?

@Catlike14
Copy link

Up

@zomars
Copy link

zomars commented Nov 25, 2021

Would you mind if I use your definitions in the meantime? @tasn

@MattRiddell
Copy link

Careful using that .d.ts file - the top of it states it is GPL3 meaning your entire codebase becomes GPL if you include it.

@MattRiddell
Copy link

@tasn any chance you'd be able to make a copy with the same license as this codebase?

@tasn
Copy link

tasn commented Feb 25, 2022

@zomars, sorry, sure thing!

@MattRiddell, sure thing, sorry about that, will do now.

@tasn
Copy link

tasn commented Feb 25, 2022

Done. We actually have two versions, not sure which is newer/better:

https://github.com/etesync/ios/blob/master/src/types/ical.js.d.ts
https://github.com/etesync/etesync-web/blob/master/src/types/ical.js.d.ts

Relicensed both.

@MattRiddell
Copy link

@tasn awesome, thanks man!

@kewisch
Copy link
Owner

kewisch commented Feb 25, 2022

In light of new recent comments I took a quick look on the net, apparently tsc can create the declaration file based on jsdoc? ical.js uses fairly comprehensive jsdoc, so maybe auto generated types are not too far off.

If someone wants to see how well these compare to the manual version that would be pretty cool. Note for the record I have a draft pr for es6 modules support which changes some doc patterns, so maybe base any changes off of that.

@joelshepherd
Copy link

I had a look at auto generating typescript definitions from jsdocs.

Overall it worked well, but typescript stumbled on the ICAL namespace. I could not find @namespace or @alias in the typescript jsdoc docs, which might be the problem, but I'm not enough of an expert of jsdoc to know for sure. This meant that any function that returns a class from said namespace would not resolve (for example: Event.startDate would have no type).

Side note on es modules, I added a re-export of items from the default namespace as named exports. This means you can import classes directly, and get the advantage of tree-shaking like:

import { parse, Event } from 'ical.js';

Here if a diff of what I did: es6...joelshepherd:es6

@ryzokuken
Copy link

@kewisch https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html, could set up either CI or a commit hook to update the types automatically.

@alex-kinokon
Copy link

Related: I forked the project and ported the entire project to TypeScript. I’m open to merging this to upstream if anyone is interested.

@zomars
Copy link

zomars commented Apr 14, 2023

I'll happily migrate if we get passing tests and full coverage @alex-kinokon 🙏🏽

@frozencap
Copy link

slightly urgent considering the entire ecosystem is going to ts. Can't run this at all in post 0.71 react-native projects

@alex-kinokon
Copy link

slightly urgent considering the entire ecosystem is going to ts. Can't run this at all in post 0.71 react-native projects

I’m fairly certain you can just put declare module "ical.js" in a .d.ts file somewhere and it would work.

@kewisch kewisch changed the title TypeScript ical.d.ts anybody? Generate TypeScript ical.d.ts from jsdoc and include in releases Apr 1, 2024
@jannikac
Copy link
Contributor

You mentioned in #597 that you'd prefer not to write a separate d.ts file but generate it from jsdoc which is definitely possible with tsc. I tried generating the d.ts file based of the jsdoc comments which worked but it has some limitation as mentioned already in this comment #367 (comment). Here is a snippet that demonstrates the issue:

const data = "...some ical data";
const jCalData: any = ICAL.parse(data);
const comp = new ICAL.Component(jCalData, null);
const events = comp.getAllSubcomponents("vevent");
for (const event of events) {
  // event is of type ICAL.Component but it has no methods attached
  event.addSubcomponent();
}

I believe this would have to be fixed in the jsdoc comments as @alias is not supported per https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html. So the classes would have to be refactored in a way that omits @alias I believe.

Hopefully this points someone more familiar with this project and jsdoc in the right direction.

@kewisch
Copy link
Owner

kewisch commented Apr 12, 2024

Yes, absolutely happy to take fixes to the docs to support this. I think some of the aliases were used to fix the reference docs generation, I got them from https://jsdoc.app/tags-alias . If there is a better way to do this in TS let's see!

@jannikac I know you mentioned you'd prefer someone more familiar to take a look, but maybe you'd be interested in tinkering until it works? It looks like you're already half way in :)

@jannikac
Copy link
Contributor

I took a stab at it and created a PR to discuss this matter further #662.

@septatrix
Copy link

I will be stoked when this gets implemented. First the v2 with proper ES6 modules, and then hopefully this. This is even more important due to the potential for confusion with @types/ical (see #371)

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

No branches or pull requests