Add info on dependencies needed for TypeScript users

[Souldrinker]

In the existing documentation about the aurelia-fetch-client it isn't really clear to us TypeScript users that we need to include the special version of whatwg-fetch.d.ts included in the docs folder of this project to be able to compile it.

We also need Promise declared somewhere both for this and other libraries. Earlier I've used one of @cmichaelgraham's es6.d.ts files (that also included Map used by aurelia-dependency-injection), but Promise also exists in es6-promise.d.ts whose reference is commented out in this version of whatwg-fetch.d.ts, but is a dependency in DefinitelyTyped.

The changes in this version of whatwg-fetch as opposed to the "official" on DefinitelyTyped is that the es6-promise reference is removed and that BufferSource and URLSearchParams is added.

[cmichaelgraham]

hi @Souldrinker - that modified whatwg-fetch.d.ts is included in the docs folder so that the typescript compiler will successfully compile during the generation of the api.json file (which will be used by the reference doc application).

these typings and this tsconfig.json seem to work. what dev env are you using?

[Souldrinker]

I'm using VS2015/jspm/systemjs and have Visual Studio transpile my TypeScript 1.5 to AMD and thus not using a tsconfig.json (or should I?).

I've got things running here after Rob told me to look in the doc folder for your modified whatwg-fetch.d.ts that includes the two empty interfaces for BufferSource and URLSearchParams and the es6-promise.d.ts that I got when I did a "tsd install whatwg-fetch" that you commented out. But in that es6-promise.d.ts I had to add interface Map<K, V> { } to get dependency injection working which depended on Map.

Up until yesterday when I did what I mentioned above I've been using the "./typings/es6.d.ts" that you point to in your tsconfig.js, but I was a bit curious where you got that which seems to be made by Microsoft and if that is preferred over the es6-promise.d.ts from DefinitelyTyped.

Anyway it's not really clear for TypeScript users (at least it wasn't for me) that we need to get this whatwg-fetch typings file and some version of Promise files, thus Rob said I could add an issue about adding information about this in the docs.

[cmichaelgraham]

I think Microsoft is actually struggling a bit with this on also. What is happening is that the objects that are global to the typescript language like Promise and Map weren't part of ES5 version of JavaScript, but are part of ES6. Some folks are using polyfills to get those features in ES5. So now, out in the wild, there is no good way for the compiler to tell if those types should be included. I don't understand all the details, but I read some comments that if they included all of the new global types by default, it would break code that is out in the wild.

The microsoft distribution is here: https://github.com/Microsoft/TypeScript/tree/master/lib

you can see they have several different versions.

here's an example of one of the issues they faced:
microsoft/TypeScript#2934

[Souldrinker]

Ok, that probably explains why I didn't need an es6-typings file in another project that is currently on hold where I had Visual Studio transpile to ES6 and then used slightly modified skeleton gulp tasks to let babel transpile to ES5.

[cmichaelgraham]

yeah- i think you are 100% correct 👍

[bryanrsmith]

@cmichaelgraham @Souldrinker Is there anything that needs to be changed in this project to improve the TS experience, or can this be closed?

[Souldrinker]

Well, maybe you can close it. If we use the TypeScript definitions located in the docs folder that @cmichaelgraham has modified in combination with the es6.d.ts from his github repo (unless you transpile to ES6 in which case you won't need his es6.d.ts) it works. I just didn't know to look there for them, but rather tried to use the "official" what-wg definitions and I didn't see anything in the docs about looking there.

But hopefully this will be sorted when the new documentation stuff arrives in the Aurelia beta in a few weeks or maybe it was just me that didn't think to look in the right places.

[cmichaelgraham]

i think this can be closed for now.

hopefully typescript, javascript, module loading, and package management will evolve so that there isn't a mismatch between updates to the repository and its associated types, and the typing tools in ide's will be able to pull in type info when module loading is specified via import rather than via specific project configuration

[doktordirk]

@EisenbergEffect @cmichaelgraham this did get lost in the updates it seems. since this whatwg-fetch.d.ts version includes types in the 'official' one, i'd recommend to re-add it

[EisenbergEffect]

What got lost exactly?

[doktordirk]

@EisenbergEffect The build.js in this old commit included a fixed whatwg-fetch.d.ts with all those UrlParameterXY types sdded which many have problems now, added.

[doktordirk]

the file even is still there. it.s just not used/mentioned

https://github.com/aurelia/fetch-client/blob/master/doc/whatwg-fetch.d.ts

[EisenbergEffect]

Ok. We are in the process of setting up a consistent way of handling 3rd party d.ts files that aren't readily available.

[niieani]

You can use the whatwg-fetch from DefinitelyTyped (installed by Typings) combined with this little file, which is used in the Webpack TS Skeleton.
We'll update the skeletons with corrected typings soon.
Also, if you're using TypeScript 2.0 dev you can now also use: npm install @types/whatwg-fetch instead of Typings.
Microsoft prepared a nice search for Typings installable via NPM: http://microsoft.github.io/TypeSearch/. It's the same catalogue as available via DefinitelyTyped.

[robertmclaws]

Just wanted to check in and see where you guys were at with making the TypeScript process easier? With TypeScript 2.0 now using NPM instead of NuGet, it's gotten more of a pain. The actions @niieani mentioned are still necessary, and there is no easy way to get all of the TypeScript file you need for Aurelia in one shot.

Thanks!

[EisenbergEffect]

Are you referring to fetch? or other libraries? For all Aurelia libraries, using NPM install to get the library should "just work". That's they way our cli is setup up as well as the webpack skeletons. If you are using jspm, you need additional steps to install the typings. That should all be documented.

[robertmclaws]

I was talking about all of them. If you're setting up Aurelia manually for some reason, it's still not quite seamless yet. Even the CLI installer didn't add the Fetch types. And if I want to mover all of my Aurelia Types to the TypeScript 2.0 way, there is no easy way to do that yet.

Also was curious where you thought this was all documented? I searched the DocHub for "typescript" and didn't come up with any docs with a rundown of how the TypeScript stuff should be configured..

[EisenbergEffect]

The fetch d.ts files have nothing to do with Aurelia. Those are part of the standard and should be implemented by TypeScript itself.

I believe the skeletons have docs for how to set up the dts files for jspm. @AshleyGrant Can you confirm or add it if it's missing?

Everything else should be automatic as far as Aurelia's dts files are concerned. If it's not an Aurelia dts, then you have to handle that yourself. That's part of how the TS ecosystem works. If the library you are using hasn't set up their package.json file with dts info, then you have to manually find/configure it. That's the case with fetch.

[robertmclaws]

You have a Aurelia bootstrapper package that brings in a bunch of other packages, right? Wouldn't the same thing be possible for the typescript files? Would be really useful when you are trying to do things like build Aurelia plugins or use the JSPM version of the install. Would probably be similar to https://www.npmjs.com/package/aurelia-types-installer, but as just a Types package that installs other Types packages.