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

[knut-erik]

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

[kewisch]

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

[knut-erik]

Cool - tx @glixlur

[sebius8780]

@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]

hi, how can I use @glixlur types?

[ALGDB]

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]

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

[tasn]

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]

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]

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]

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]

@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]

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

[tasn]

@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]

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]

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

[amadeus-torwell]

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

[Catlike14]

Up

[zomars]

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

[MattRiddell]

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]

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

[tasn]

@zomars, sorry, sure thing!

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

[tasn]

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]

@tasn awesome, thanks man!

[kewisch]

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]

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: https://github.com/kewisch/ical.js/compare/es6...joelshepherd:es6

[ryzokuken]

@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]

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]

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

[frozencap]

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]

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.

[jannikac]

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 https://github.com/kewisch/ical.js/issues/367#issuecomment-1110946354. 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]

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]

I took a stab at it and created a PR to discuss this matter further https://github.com/kewisch/ical.js/pull/662.

[septatrix]

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)