Triple-slash references should support library path aliases.

[johnnesky]

Search Terms

triple slash reference path library relative

Suggestion

Allow using the newer "paths" tsconfig flag to find triple-slash reference paths for .ts files.

Use Cases

I use triple-slash references to include exactly the ts source files I need, once each in dependency order, and no other files, and use --outFile to concat them into a single output file. Yes, I realize my tsc usage is unusual and probably discouraged, but as far as I'm concerned everyone else is weird. ;) Basically this allows me to skip all the other javascript tooling like webpack to be able to distribute a single compact js script. It's simple and it works and it doesn't add any boilerplate to the output and I don't have to manually order html script tags and it doesn't need any new browser features and there's no separate linker or packing step and I love it. Importing modules admittedly has better syntax but the module system just adds too much friction for me and I don't understand why everyone else puts up with it.

There's just one problem: For no obvious reason, my references appear to have been excluded from the excitement about finally supporting project-root-relative path aliases via the library "paths" flag which means I can't easily put ts files in deep folders without resorting to awkward "../../../" paths in my references. :(

So far I've been putting all my files in the same folder, but my projects are getting complex enough that I'd like to be able to structure them with some folders. You can see some of my code here if you're interested:
https://github.com/johnnesky/beepbox/tree/master/ts
(and you can try that webapp out at www.beepbox.co)

Examples

tsconfig.json:

{
  "compilerOptions": {
    "outFile": "out/index.js",
    "baseUrl": ".",
    "paths": { "physics/*": ["libraries/physics/*"] }
  },
  "files": [ "src/main.ts"  ],
}

src/main.ts:

/// <reference path="physics/integrator.ts" />

out/index.js:

// (contents of libraries/physics/integrator.ts)
// (contents of src/main.ts)

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Thanks for any consideration! You're also welcome to try to convince me that the module system is actually easy to use for my use-case but keep in mind I care a lot about minimizing the package size of the distribution javascript (the only post-compilation step I use is uglify-es for minification) and I don't plan on using anyone else's typescript libraries or web frameworks.

[sandersn]

Right now triple-slash references are not a commonly used feature and paths only applies to module resolution -- the paths in triple-slash references are used verbatim as far as I know.

We'd need a lot of other people to upvote this issue to consider putting effort into improving triple-slash references. Another piece of evidence would be finding a lot of triple-slashes with ../../../ in existing Typescript code. You might be able to scrape github to find that information.

[johnnesky]

Yes, I understand triple-slash references are less commonly used, but I think they would be more commonly used if they were more flexible. Besides, there are people like myself who are already using references, but are forced to make sacrifices in terms of structuring our code in order to use them.

For example, check out this file. The files are clearly organized into folders, but the author chose to include them all from a single file at the source root, and the rest of the files just reference ../_all.ts to include everything at once. Presumably the author decided that this would be easier than trying to use ../ to find and reference only the files they need.

Here's another example, where the author again chose to make a central ts file that references all the other ts files, but this time you can see that they had to use a bunch of ../ to access files from a library.

Here's a file that's a bit closer to my approach. This one only references the needed library files from each source file, but it needs to use ../ to find each library file.

You can find more examples with a search like this one.

Basically I think library source files ought to be able to have a canonical path, similar to a Java package name, that can be used to reference that file regardless of the location of the source file that's doing the referencing. This is the standard approach that most non-ecmascript languages use for finding library files, and it's frustrating that typescript references always have to take the location of the source file into account to be able to construct a relative path to the library to find it.

[tschettler]

You have my upvote, facing a different triple-slash reference path issue that paths could resolve, but found that it didn't work for me either.

[cwli24]

@sandersn when you say used verbatim, just to clarify, you mean that in my case, I expect something like ///<reference path="Organization" /> to resolve to the full "Organization.ts" (note the extension) via typescript module's resolveTripleslashReference() doesn't actually work as expected?
From the definition: export function resolveTripleslashReference(moduleName: string, containingFile: string): string;
It looks like it would resolve the path like a module (try to find .tsx, then .ts, then .d.ts, etc.) but doesn't actually.

[sandersn]

@johnnesky

Basically I think library source files ought to be able to have a canonical path, similar to a Java package name, that can be used to reference that file regardless of the location of the source file that's doing the referencing. This is the standard approach that most non-ecmascript languages use

This is also what ecmascript does with modules. Typescript's triple-slash references are a pre-module feature, which is one reason we're not excited about improving it.

@cli-panda With 'verbatim' I meant that paths in tsconfig doesn't rewrite triple-slash paths. I don't think resolveTripleslashReference is anything like Ecmascript module resolution. I looked at the source and it just collapses internal ../x sequences and converts \ to /.

[johnnesky]

I finally decided to embrace standard import syntax with johnnesky/beepbox@b6ccf7c so I'm closing this issue.

For reference, I found that rollup does pretty much what I want with settings like these:

npm install rollup
npm install rollup-plugin-sourcemaps

npx rollup build/index.js \ # after running tsc, feed all compiled JS files into rollup starting with the main file.
	--file public/index.js \ # output a single file containing all dependencies
	--format iife \ # format the file for use in a browser
	--output.name myNamespace \ # exports from index.js can be exposed to JS as properties of this namespace
	--sourcemap \ # generate a sourcemap for debugging
	--plugin rollup-plugin-sourcemaps # use the sourcemaps provided by typescript

And for the record, I think I agree that the triple-slash reference syntax should not be extended. However, it's a shame that the above rollup functionality is only provided by the typescript compiler when using triple-slash references, and must be supplemented using the rollup package when using standard import syntax.