Update to Support TypeScript Module Resolution

[northwoodssoftware]

Update to Support TypeScript Module Resolution

[schmuli]

I know it has been a while, but the TypeScript document has been updated too, please have a look at:

https://www.typescriptlang.org/docs/handbook/writing-declaration-files.html

Additionally, see the page of Modules.

[roni-frantchi]

+1

[AlmogShaul]

+1

[simonsarris]

Thanks for bringing this to our attention. Could you confirm that adding:

"typings": "./release/gojs.d.ts"

To the package.json is all that's needed?

Committed: 3825ec1

[schmuli]

Has this been published to NPM? I can test it and let you know. Thank you very much for the quick response.

[simonsarris]

No, it will be published with our next real release, probably in about a
week. Sorry for the delay.
On Apr 11, 2016 1:16 PM, "Schmulik Raskin" [email protected] wrote:

Has this been published to NPM? I can test it and let you know.

—
You are receiving this because you commented.
Reply to this email directly or view it on GitHub
#17 (comment)

[schmuli]

I tried changing the package.json on a local version, and unfortunately it doesn't work by just adding the above line.

I'm trying to understand what is required in order for it to work, and I will update this issue.

[simonsarris]

Thanks. It may be worth changing it to:

"typings": "release/gojs.d.ts"

(removing the ./) just to see if that works. I was following what I saw on a Typescript page as an example path.

[schmuli]

I'll check but I think the issue is more to do with the contents of the file.

I don't have confirmation yet, but I think the file needs to be written without:

declare module gojs {
    ...
}

declare module "gojs" {
    ...
}

I still have to test further, but if I understand correctly, the file needs to directly export the interfaces; the module name is automatically understood from the context.

I will continue testing and update the issue if I get something that works.

[schmuli]

So after testing this for a while, this is what I have learnt.

In the .d.ts file, all declare module need to be removed, as mentioned above. Additionally, all the exported classes, interfaces, etc. need to be exported using the export keyword.

The TypeScript compiler can generate such .d.ts files, if the original TypeScript code is written using ES6 Modules, meaning export and import statements.

I don't know how you are generating your .d.ts file today, but if this is something that is possible, that would be excellent. Considering that the current file doesn't do anything without a separate tool, like typings, maybe supporting both formats in the package is not a must.

[simonsarris]

Thanks for your findings. I'll keep investigating.

[simonsarris]

It looks like to me, that the line at the start of our .d.ts file:

declare module go {

Should actually be:

declare namespace go {

But as far as I can tell, the other declare module at the bottom:

declare module "go" {
    export = go;
}

needs to stay to support AMD require.

So if you overwrite the file in your project so that the first line says declare namespace instead of declare module, does it work as you'd expect?

[simonsarris]

This seems to be how other libraries are doing it, for example:

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/d3/d3.d.ts

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/flowjs/flowjs.d.ts

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/leaflet/leaflet.d.ts

etc.

So I think its correct if our definition file takes the form:

declare namespace go {
    ...
}

declare module "go" {
    export = go;
}

[schmuli]

Without going to deep into the subject, TypeScript has a number of different ways to determine the .d.ts file when it encounters a require('gojs') or import gojs from 'gojs' statement:

1. It will go to node_modules/gojs and look in the package.json for the typings key and use that, in which case it already knows that the file it is loading is the 'gojs' module, and it doesn't need (or want) the declare module as that is already inferred and useless
2. It will look through the files provided to the compiler as input, and will look for a module that matches the imported name, which it matches by comparing the declare module 'gojs' statement with the imported name

All the files found on DefinitelyTyped are used as part of the input to the TypeScript compiler, which is why they all use the old syntax. I'm calling it the old syntax, because there is active work by TypeScript and the community to move all definition files into node_modules.

Just changing the module to namespace doesn't work, the module/namespace needs to be removed, and all the interfaces and classes need to be exported.

I understand that this is an issue for you, because it basically requires supporting two versions of the .d.ts file, one for node_modules and another for DefinitelyTyped.

The only remaining question is, since I'm assuming that you guys are generating the .d.ts file, is it possible to support both formats, one which will work with the typings keyword in node_modules, and the other that will remain backwards-compatible?

If you could do that, you will be preparing for the future as well as earning mine and other's appreciation.

Thank you for your quick responses and willingness to help!

[simonsarris]

Can you link me to any discussions or guides about this new syntax?

Sorry for the trouble, I'm not well-versed in TypeScript.

We did make this definition file by hand, and not with a generator. (The source isn't .ts, its plain JS)

[schmuli]

There is a lot of detail in this answer by Ryan Cavanaugh, who is a contributor to TypeScript: http://stackoverflow.com/a/30357635.

You can also look at the original discussion on TypeScript for the ES6 Module support design: microsoft/TypeScript#2242.

[WalterNorthwoods]

Yes, I saw that; I still think the TypeScript documentation is quite inadequate regarding these issues.

I am still unable to create a .d.ts file that works with all of the usage styles that we can envision and that works with both TypeScript 1.* and TypeScript 2.0. You might want to look at http://gojs.net/beta/release/go.d.ts for the latest file.

Note the file name change. The name "goJS.d.ts" was chosen by someone on behalf of DefinitelyTyped, which was not our choice. With the name change I think finding the .d.ts file for the "go.js" library will be easier.

One can now use the definition file without using modules:

    /// <reference path="go.d.ts">
    function init() {
        const $ = go.GraphObject.make;
        var myDiagram: go.Diagram =
            $(go.Diagram, "myDiagramDiv",
                { layout: $(go.TreeLayout, { angle: 90 }) });
        . . .
    }

Or one can write:

    import go = require("go");
    export function init() {
        const $ = go.GraphObject.make;
        var myDiagram: go.Diagram =
            $(go.Diagram, "myDiagramDiv",
                { layout: $(go.TreeLayout, { angle: 90 }) });
        . . .
    }

and then require that file:

  <script>
    require(["go-tests"], function(app) {
      app.init();
    });
  </script>

I noticed in the 2.0 branch at DefinitelyTyped that there is a newer version of our .d.ts file, using some new syntax for which I could not find any documentation: export as namespace go;. This does not work in TypeScript 1.8. Furthermore it does an export = go not inside a module declaration. (This is commented out in at the end of our new go.d.ts file.)

Further experimentation found that if I remove the namespace declaration and the export = go from the go.d.ts file, it is possible to do things like:

    import { Diagram, GraphObject, Panel, Part, Node, Link, Group, Placeholder, Adornment, TextBlock, Shape, InputEvent, Point, Spot, Binding, GraphLinksModel, TreeLayout, TreeNetwork, TreeVertex, TreeEdge } from "go";
    export function init() {
        var $ = GraphObject.make;  // for conciseness in defining templates
        var myDiagram: Diagram =
            $(Diagram, "myDiagram",  // create a Diagram for the DIV HTML element
            . . .

Note that there is no longer any need to prefix GoJS types with "go.". However I do not then understand how to import all of the exported symbols using a wildcard or some other syntax for importing.

[schmuli]

The 2.0 branch is for TypeScript 2.0, which is still in Beta release currently. They have made many improvements for libraries such as yourself, that want to be able to include a definition file as part of the NPM module, while still supporting the different possible syntaxes (i.e. a comment, using require and using `import ... from 'go').

I will have another look at your beta go.d.ts (I like this name better too), and see how well this works.

To answer how to import with a wildcard, you can use:

import * as go from 'go';

and now go will act almost exactly like the current namespace object.

[WalterNorthwoods]

If there is no declare namespace go { ... } in the go.d.ts file, thereby having a lot of top-level exports, what you write:

    import * as go from 'go';

does not work to allow references to types such as Diagram without any "go." prefix. The "go." is still required.

I was hoping for a way to import selected types, perhaps with aliasing, and allow references not to be prefixed with "go.". So that's why something like this works:

    import { Diagram, GraphObject, Node } from "go";

    const $ = GraphObject.make;

But I was also hoping to be able to import all of the types using a wildcard, so that the programmer does not need to list all of the specific types as I did. I tried:

    import { * } from "go";

But that is not valid syntax. And:

    import * from "go";

is invalid syntax too.
This is valid syntax:

    import "go";

But it doesn't work either.
This does work:

import go = require("go");

But it requires prefixing all the GoJS class names with "go.".

[schmuli]

As you have seen, there is no way to import all without a prefix or referencing each individual export. But I think that is close enough for most use cases.

By the way, the last import example is called a side-effect import (or something similar), and is used to cause a side-effect without actually using anything from the imported file.

[WalterNorthwoods]

I think importing all of the exported symbols of a module should be a common usage.

Anyway, that along with working in TypeScript 1.* is why the new go.d.ts file continues to declare a namespace rather than only having top-level exports of the classes, which is what you had been requesting in this Issue.