Proposal: ///<reference path=""/> should allow for accessing DefinitelyTyped URLs

[SetTrend]

Creating TypeScript files using build/runtime environments, like Node, Gulp, etc., I regularly find myself referencing public repositories.

Currently it looks like the /// <reference path="" /> syntax only allows for referencing local files (at least I couldn't find any information of IRIs being supported, and TSC claims File not Found error when using a DefinitelyTyped URL).

But this results in a requirement to deliver .d.ts files of public repositories along with the project and to keep their relative position in sync with locally generated .d.ts files. (See SetTrend/TS18N failing project for reference).

So I propose to allow to use IRIs for reference:

/// <reference path="https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/node/node.d.ts" />

[blakeembrey]

@SetTrend Just a note, but you can use a project like Typings or TSD to manage these type dependencies. The URL you reference wouldn't be useful though, it's a page on GitHub - what you might mean is the raw URL.

[RyanCavanaugh]

There are a lot of good reasons not to do this (security, compiling on an airplane, etc) and not a lot of convenience saved over using one of the tools mentioned above.

[SetTrend]

@blakeembrey : These tools don't update or even deal with TypeScript references in code. They just download the files - something that can be done manually as well. I'm suggesting to add an option for providing a CDN for TypeScript type definitions.

@RyanCavanaugh : I suggest to allow URLs as an option - not a mandatory change. - TSC could maintain a local cache of downloaded TypeScript definitions. Then no online access would even be required - except for the first time a TypeScript definition would be downloaded. Security can't be an issue here as the TypeScript definitions are in fact coming from the same online website TSD downloads them from.

So, allowing for the /// <reference path="" /> to access URLs would in fact change nothing. But it would spare the referencing errors that occur when the output directory is not in the same directory hierarchy level as the referenced 3rd party .d.ts files.

[blakeembrey]

No, they don't. They make it easier to manage, update and share.

I can attest to the fact that supporting URLs will most definitely be a pain. For instance, you suggest using a local cache for files. For one, the file you used in the example won't work anyway, so there's already user confusion there. Secondly, you're referencing a file that can change at any time, so your TypeScript project could breakdown any time depending on when TypeScript fetches updates on the URLs. Thirdly, it's a confusing case for users and definitely is definitely a complicated feature to implement correctly that's best left to third-parties for now - if someone wants to develop offline for a time, how do they download the definitions they'll need ahead of time?

As someone who has spent the last 10 months working on TSD and Typings, I can say it's definitely not as straight-forward as you may think. There's an unlimited amount of edge-cases, user messaging and features that'll need to be handled.

[SetTrend]

I don't see any of your points being valid:

For one, the file you used in the example won't work anyway, so there's already user confusion there.

That's because no official links have been provided so far. That's not a procedural issue.

Secondly, you're referencing a file that can change at any time, so your TypeScript project could breakdown any time depending on when TypeScript fetches updates on the URLs.

Again, that's because I have used a hyperlink to a non-versioned file. I could as well have been using https://github.com/DefinitelyTyped/DefinitelyTyped/blob/0.9.5/node/node.d.ts - and, voilà ... The versioning issue disappears.

if someone wants to develop offline for a time, how do they download the definitions they'll need ahead of time?

Counter question: How would the do it using TSD - offline?

If TSC used a (global) cache that'd be the same functionality TSD provides right now, but without the hassle of either copying locally providing external .d.ts files along with your projects or having to redo all the external references after having downloaded your projects' .d.ts.

There's an unlimited amount of edge-cases, user messaging and features that'll need to be handled.

Which would these be? I don't see any difference between having TSC doing the same thing TSD does, but inline.

[SetTrend]

Moreover, TSD is a tool specific to DefinitelyTyped. Leaving the competence of TypeScript to TSC and allowing the compiler to utilize URLs would allow other repositories to store their own .d.ts files.

So Node may store their own .d.ts file versions in their project, Angular may store their own .d.ts file versions in their project and so on.

[RyanCavanaugh]

Whether or not it's easy (I am inclined to believe the person who's actually worked on it...) and whether or not it's a good idea (I'm not going to pass judgement either way), it's unquestionably out of scope for TSC. Maintaining a system for mapping arbitrary URLs to some cache in the filesystem is not the job of a compiler.

[blakeembrey]

That's because no official links have been provided so far.

I was talking about your example link - you provided it to start the conversation. It's not valid. Also, the link you provided for versioning is also not valid. When you open a rabbit hole which involved linking via a URL arbitrarily, I think it's safe to assume more links than just GitHub will be used and most links can be updated at any time, which can create confusion for users. This is especially important, as everything would be in a global cache and it would be difficult to discover why things aren't working suddenly.

For reference, the URL you'd need to put is https://raw.githubusercontent.com/DefinitelyTyped/DefinitelyTyped/0.9.5/node/node.d.ts. Without that, you're loading a HTML page. This is one such thing that could cause confusion if TypeScript supported URLs and it's meant to "just work".

I understand that the core issue feels very trivial, but once you start on one small thing like this it does turn into a cascade of features that need to be handled correctly. I believe the core teams time would be better spent improving TypeScript itself, while community members (like myself) can work on improving tooling of things like this (whether official or unofficial).

Counter question: How would the do it using TSD - offline?

I only asked about ahead of time, not about it being offline. With TSD or Typings you can just install them locally (explicitly) ahead of time, just as you'd install the NPM packages you want to use ahead of time.

Which would these be? I don't see any difference between having TSC doing the same thing TSD does, but inline.

There's the things I've mentioned so far and it's mostly usability issues and messaging. Here's a couple of thoughts, but how do you know the files have been downloaded correctly? What about if a response is corrupt? Local caches vs global caches? What if someone injected content when you downloaded something (a proxy, an ISP or even the wifi router)? Sure, it comes down to implementation and visibility into that implementation, but I suspect it could be hard to debug. Typings content updates, registry search, issues logging, getting help, corporate proxies, environment replicate - some more things to think about.

In any case, you're welcome to try using TSD or Typings to solve your issues. If there's something missing, you're welcome to contribute.

[SetTrend]

I was talking about your example link - you provided it to start the conversation. It's not valid. Also, the link you provided for versioning is also not valid.

Yes, agreed. But giving technically invalid, yet semantically valid examples should not be regarded a reason for declining a semantic proposal. Don't you think so?

I think it's safe to assume more links than just GitHub will be used and most links can be updated at any time, which can create confusion for users.

AngularJS is hosted at various CDNs. Same for jQuery. Node packages are published at npm. Do you believe using these sources is causing less confusion? I regard it to be a good idea to have .d.ts files stored along with nor nearby with their corresponding .js files.

Wouldn't you believe it to be fairly more confusing to use a particular CDN version for a .js file and being required to download some entirely unrelated .d.ts version, maintained by someone else, from somewhere else (i.e. DefinitelyTyped)?

I believe the core teams time would be better spent improving TypeScript itself, while community members (like myself) can work on improving tooling of things like this (whether official or unofficial).

I believe there are two types of TypeScript teams: (a) The ones concerned with the language and (b) the others concerned with the technical implementation, i.e. the compiler. Compiler and language are two entirely different things. Otherwise there'd be only one compiler per language in the world of programming - which there isn't.

From my perspective, the team concerned with the compiler is responsible for providing the most seamless compiling experience possible. And, hence, requiring the user to manually maintain generated references I don't regard as a seamless compilation experience in any way.

Instead of flooding the hard drive with unnecessary local copies of .d.ts files which the user is required to maintain manually it would be a far better compiling experience to have the TSC compiler maintaining a global ZIP file containing all the .d.ts files downloaded from the URLs in all their different versions. The ZIP file content's file names would be the URL of the .d.ts files, so each version would be stored separately within the ZIP file while content is only stored once.

My proposal implicates that every referenced URL not found in the global .d.ts cache ZIP file by TSC should be downloaded by TSC and after being found syntactically correct should be added to the global .d.ts cache ZIP file.

The global .d.ts cache could easily be cleared by simply deleting the ZIP file.

My proposal would make things so much easier. And quicker. And leaner. And available offline.

how do you know the files have been downloaded correctly?

What is the semantic difference between TSC downloading the files and TSD downloading the files?

What about if a response is corrupt?

What about if any of a CDN's/npm's JavaScript files is corrupt? Wouldn't that be a rather more severe issue?

Local caches vs global caches?

No local cache. What should it be good for when importing release packages?

May I add that my proposal is to allow for using IRLs in the path attribute? It is not to utilize IRLs mandatorily.

References to local files in the file system will still be possible and will still behave as they behave now. No caching will be performed with file system references. It just wouldn't make sense.

Allowing to utilize IRLs for /// <reference path="" /> would greatly add comfort to the existing functionality. It wouldn't break anything.

If there's something missing, you're welcome to contribute.

No. I'm not getting paid for contributing to either TSC nor TSD. I'm not working for Microsoft nor am I officially invited to TypeScript meetings or teams. I believe that any of this implementation has to be done from within the TypeScript team. I have other tasks to accomplish.

[SetTrend]

@RyanCavanaugh : Please discuss and eventually re-open.

[DanielRosenwasser]

I have other tasks to accomplish.

So does the TypeScript team. We don't consider this within our scope a this time, nor do we feel it is necessarily a good idea. We'll continue weighing out what will make for a great experience while you use TypeScript, but like anyone else, we're not a team with unlimited resources.