Use the javascript-compatible "use ..." string call for referencing paths

[ghost]

Why don't we just implement a javascript-compatible "use ..." string call, (e.g.: like the one used for "use strict";) for referencing paths, instead of using the /// comment notation?

It should look something like this:
"use 'some-file.d.ts'";
"use 'some-other-file.d.ts";

It's both compatible with js (ignored in js, if something goes wrong and the compiler does not include the file and remove the line in the output) and the code looks better.
Relying on comments to do some language enhancement/feature is proven to be an unhealthy approach.

Both this notation and the current approach (comment-style) could go together nicely (to please everybody).

Just my 2 cents for this minor(major?) language annoyance (path referencing in comment-style).

[irium]

Extremely clever idea! Voting +1 for this.

[RyanCavanaugh]

I don't think we should use "use ..." since that kind of syntax should be reserved for runtime semantics (as use strict or use asm are). We have talked about using something other than the ugly /// <reference ... /> syntax and should get around to that. Pinging @jonathandturner

[ivogabe]

Maybe something like this?

reference ./foo.d.ts
reference "./foo.d.ts"; // Looks like ES6 spec: import "foo";
reference("./foo.d.ts"); // Looks like TypeScript import foo = require("./foo")

[sophiajt]

@ivogabe - I think that third one is something we were considering at one point. On the flip side, that would be a backward breaking change (because now reference would be a reserved word)

[ghost]

One way or another, we should get out of the /// comment-style path referencing.

[ivogabe]

@jonathandturner This would be backwards compatible:

import reference("./foo.d.ts");

[irium]

@ivogabe Seems quite good for me.

[mhegazy]

I do not think this is something that should be supported by a language construct. currently the /// references serve one of two purposes: as a convenience to providing files to compile, and as a way to order generated js output when specifying --out.

For the first, the right place for providing build information is a build system, e.g. msbuild, make, grunt, etc.. using /// references can help in small applications, but does not scale well for the general case. in general mixing code and build instructions is not a good idea; for instance you do not get the up-to-date checks and incremental build if you are using /// references; and you can not share files between multiple projects unless you are sharing all its dependents as well. so for such reasons, I do not think /// references should be institutionalized with a language construct.

For the second, this is a product of the current implementation of the compiler. the compiler has enough information to infer order in the output, and in the future the compiler could do that, rendering this use obsolete.

[NoelAbrahams]

Yes, I agree with @mhegazy.

With regard to the Visual Studio build mechanism, the <reference> tags should be moved into the project XML (i.e. .csproj), and a user interface should be provided for managing references - similar to how other languages do it.

[ComFreek]

@mhegazy Maybe the comparison is flawed, but there are many programming languages who use include statements instead of leveraging this step to the build system. Examples include C, C++, PHP, Java. There are millions of programs written in these languages and I highly doubt that there aren't any "up-to-date checks and incremental build[s]".
Sharing files is not a problem if a clean (dependency-free) interface is written, I suppose.

If we were to move the dependency management to a configuration file (as @NoelAbrahams suggested), there would be three consequences:

1. Opening a single file (in an arbitrary text editor) doesn't tell me which dependencies it has.
2. The TS compiler would need to support reading the configuration file since one cannot require Visual Studio for using TS.
3. Developers need to create configuration files.

I like your second point, but I still see two problems:

1. The same as above: opening a file doesn't tell me which dependencies it has.
2. One must always feed the compiler with all dependencies.
   
   I cannot just execute tsc myFile.ts if myFile.ts has three dependencies. What happens if these dependencies have other dependencies in turn?

[NoelAbrahams]

I think the idea is that each build system defines its own mechanism for handling references. TypeScript just provides a plugin architecture.

TypeScript is essentially for building large-scale applications, hence fine-grained support for viewing the dependencies on a per-file basis is probably at odds with that objective.

[NoelAbrahams]

Also, I might add, if per-file dependencies are important then one should use external modules. The reason we like internal modules is that it abstracts away the need to maintain these dependencies.

[ComFreek]

@NoelAbrahams Right, I just noticed that I confused references with real includes, sorry.

[ghost]

This topic is derailing to a wrong turn... the (main) idea was to get the references (compiler-aware dependencies) out of the comments and into a human-readable plain-english form inside the actual TypeScript code... as I can see, there's all sorts of (unrealistic) fantasies about how to do it... one word: simplicity. Ain't nobody got time for that? there's got to be a plain simple way to do it.

[CyrusNajmabadi]

It's unclear what problem is being solved here. What is better about these suggestions versus what exists today?

"the (main) idea was to get the references (compiler-aware dependencies) out of the comments and into a human-readable plain-english form inside the actual TypeScript code... "

1. I'm not sure how 'being in a comment' is any different from 'the actual typescript code'. Both are simply syntactic constructs that the compiler needs to parse and then recognize.
2. i'm not sure what makes the proposed forms any more 'human readable'.

In essence, from what i'm seeing, it's simply a different syntactic form for the exact same feature. Now there would be two different ways to do the exact same thing. And i'm not sure how that helps consumers, the language, or the compiler.

Can you clarify what substantive benefits you think this would bring?

Thanks!

[danquirk]

In the early days part of the motivation for changing the syntax (regardless of build system design shenanigans) was simply that using a psuedo XML statement in JavaScript was just aesthetically at odds with the ecosystem and existing conventions

[NoelAbrahams]

I'm not sure how 'being in a comment' is any different from 'the actual typescript code'. Both are simply syntactic constructs that the compiler needs to parse and then recognize

Very true from a compiler writer's perspective, but not so from a user experience perspective. 😃

@adrianvoica, I don't think the topic has taken a wrong turn. As @danquirk remarks there was an earlier period when your suggestion would have been relevant, but it's a bit of a non-issue now after TypeScript made references, defined in any file, visible throughout the project. So now it's only necessary to add all the references to a single _references.ts and include it in the compile run. I'm hoping this will be taken one step further and encapsulated by the build system.

[CyrusNajmabadi]

@NoelAbrahams While the user experience might be slightly better (though I honestly think that's debatable) it seems like that's not at all enough to justify two entire ways to do the exact same thing. I'd be ok with a new approach if it brought something new and valuable to the table. Being slightly more aesthetically pleasing isn't sufficient at all to justify a language change for me.

[joewood]

For CommonJS modules, I think it would preferable to have a configuration file that maps module paths to their respective 'typings'. So, for each import XX = require(..) there would be a configuration indicating where the type information is.

This offers a much cleaner solution than over keeping build structure information in the source files.

[mhegazy]

As @CyrusNajmabadi mentioned, we can not remove existing syntax, and it is not clear that there is value in adding yet another variant.