Typing resolutions

[guybedford]

It sounds like the resolution problems tackled in typings/typings#123 are critical to this plugin's type checking feature. I'd be really interested to see what can be done to make this work, if you don't mind helping me understand this area a little better.

Firstly, jspm-npm will handle conversion of npm packages converting the Node resolution algorithm into the SystemJS resolution algorithm.

Are you saying that typings themselves are written assuming the Node resolution algorithm? Which assumptions are these usually based on? For example, are extensions usually used? Do directory requires or json requires get used? How exactly does SystemJS's naive import not work with this resolution currently?

[frankwallis]

A little bit of background on TypeScript typings - originally .d.ts files were included using /// reference path="./typings/angular.d.ts" comments in the source files which needed them. These ambient declaration files contain module definitions like this:

declare module "angular" {
   function bootstrap(modules: Module[]);
}

When you do import angular from "angular" TypeScript then finds the "angular' module declaration and uses that for type-checking. This is quite straightforward for the plugin as it knows all the files which it needs to load to type-check a source file.

Recently there has been change so that you can deliver external declaration files, these are a little different to the one above because the file itself is the module, so the one above would look like:

export function bootstrap(modules: Module[]);

and when you do import angular from "angular" TypeScript will see that the "angular" package has a typings file and use that when type-checking the file. So how does it know whether the angular package has a typings file? Well the algorithm goes something like:

a) Look in package.json for "typings" field. If found use that.
b) Resolve the imported .js file using node.js resolution and see if there is a .d.ts file of the same name

Rule (b) also applies when doing import router from "angular/router". The exact algorithm is described here

So this is the difficulty when loading tin the browser, because the plugin doesn't know which packages have typings files. SystemJS resolution can't be used because that needs to resolve to the .js file.

Angular2 delivers multiple typings files in the npm package and this makes it impossible to type-check in the browser unless you switch back to using one of the old-style ambient declaration files. Solving the angular2 problem ought to be the priority here I think.

If jspm could record any .d.ts files it finds when installing packages so that they were available somewhere in the runtime config then that might work, could jspm-npm do that? Otherwise the typings project may be able to provide this information but its not quite clear how that is going to pan out right now.

I hope this is clearer and we can find a way forward.

edit: updated the terminology to be in line with the rest of the thread.

[robwormald]

bit more info for background - there are two types of typings files now - "ambient" and "external" - angular2 uses the externals (they are basically es6 modules, more or less) and effectively its a reasonable guarantee that there's 1 .d.ts file per .js file - this is how typescript outputs them.

its unlikely we'll switch back to the old style (ambient) any time soon / ever, and ideally we'd like to not have to tell consumers of NG2 to do the same.

the typings project is for ambient modules only (afaik) and thus we won't be delivering the typings to it's registry for angular2.

@guybedford @frankwallis happy to have a pow-wow if you guys want to work through this.

[robwormald]

see also microsoft/TypeScript#6012 - and as of TS 1.8 there's a new (configurable) resolution strategy which is ~mostly JSPM style.

[frankwallis]

@robwormald yes maybe I am using wrong terminology so the first example above is "ambient" and the second one "external".

In the angular2 case, then, a simple boolean flag to say the package does have external typings would be enough. The plugin would always resolve and fetch external typings for files inside that package. That flag could go in:

• angular2 package.json typings: true (probably illegal)
• jspm section of angular2 package.json
• jspm registry
• typescriptOptions of consumers
• package config of consumers

So to account for most common scenarios, jspm could retrieve the value of typings from package,json and make it available to the plugin in runtime configuration. This field (or some other flag) would also be settable in the jspm registry and setting it to true would mean resolve external typings for all modules. Does this sound possible?

[frankwallis]

@robwormald I don't think I am able to use the new algorithm in the browser, because it needs to search for files. It solves the issue of missing intellisense and being able to use tsc with jspm and external typings though, which is progress.

[robwormald]

@frankwallis let me see what we can do about your first question, we should be able to make one of those options work.

The second though - assuming you know that there are typings, no search should be needed, as they are 1 to 1 for the actual source files. (that is, foo.ts becomes foo.js and foo.d.ts on npm) - or am i misunderstanding you?

[frankwallis]

@robwormald thanks, I'm really keen to get this working.

I need to have a look at the how this new paths compiler option is implemented and how it interacts with moduleResolution: node, but yes I suppose my point is more about implementing moduleResolution: node without doing nodejs file-system calls.

[alj1s]

@robwormald my understanding is that typings is for external modules. See here and here. So then Angular2 could be added to the registry. Or have I missed something?

[guybedford]

@frankwallis @robwormald thanks for the clear descriptions here. It does sound like Angular would be the nice case to crack here to set the precedent.

@robwormald did you say we really can assume the convention then that the typing file for a fully-resolved .../full/path/to/module.js is located at .../full/path/to/module.d.ts? Or would such a convention have edge case limitations when scaling over npm?

[frankwallis]

@ximenean as I understand it the aim of the typings project is to allow ambient modules to co-exist with external modules until everything has been moved to external modules. It's all rather confusing though...

Some new docs have just arrived on the subject: https://github.com/typings/typings/blob/master/docs/how-typings-makes-external-modules-first-class.md

[frankwallis]

@guybedford that is only true for the angular2 package.

As an example of another sort of package angular/zone.js contains a typings field in package.json (https://github.com/angular/zone.js/blob/master/package.json#L6)

{
  "name": "zone.js",
  "version": "0.5.13",
  "description": "Zones for JavaScript",
  "main": "build/lib/zone.js",
  "typings": "build/lib/core.d.ts",

This file (build/lib/core.d.ts) will contain bundled typings for the whole package.

[guybedford]

@frankwallis as far as I can tell zone.js does use the same convention within in its file structure. It does seem a very sensible convention that would be easily compatible with SystemJS if this is the way things are moving.

[frankwallis]

@guybedford yes and in fact the core.d.ts typings entry in package.json looks incorrect to me, it should point to zone.d.ts. Another example is RxJS, which in 5.0.0-beta also follows the same convention.

I think it is quite likely that packages which are developed in TypeScript will follow this convention, but packages which are developed in JavaScript may choose to have a single bundled typings file.