Issues exporting a single d.ts for our code base

[Davidhanson90]

So we have built a large library which is structured as follows

src
---------- >Foo
----------> Bar
----------> Baz

Foo folder contains many ts files and at the root of each folder is a index.ts Folders like foo may also have sub folders with their own index.ts files in them. We compile all this by doing a tsc compile to produce a single js file.

tsc src/index.ts --out app.js. 

This all works well in our current app because all the type information flows through and we are using namespaces to group functionality. Example App.Framework.Foo.Bar.

Now we have new projects being kicked off by other teams who would like to use our library. Ideally we wanted to given them the single JS file to import into the app and a single d.ts file they they can use for the type annotations. However we have run into an issue generating the d.ts.

We updated our compilation step to use the --declaration flag and it does generate a single d.ts file with what looks like all the types in it. However, this d.ts file cannot currently be used by other teams due to the following.

The d.ts file has an type specified like this

declare module Foo.Bar {
    class Baz extends Implements Quax{
        constructor(message: string, source?: any);
    }
}

and then at the top of the d.ts file is a reference to some other d.ts file which has type info for Quax

/// <reference path="foo/bar/contracts.d.ts" />

Now the problem occurs due to the fact that inside that contracts.d.ts file it has additional refs to .ts files.

/// <reference path="enums.ts" />

So the two major issues I have here are that firstly I have to dist all d.ts files in the same tree structure in order for the single d.ts that was generated to be consumed by another team, but also the .ts file references would actually require me to dist the source too.

So I feel like I have run out of options. Creating these d.ts file manually would take a very long time and they would inevitable get out of sync so I am loathed to do that.

Hope people can provide some help,

Dave

[SonofNun15]

We resolved this issue to a degree by removing all /// <reference path="*.d.ts" /> and instead feeding all of the type definitions to the compiler in the compile step. This fixed the issue for us (relative paths to *.d.ts files were no longer required), but most editors can't follow this so the global types referenced in those *.d.ts files are listed as errors in the editors even though the compiler is happy. 😦

[jpierson]

Do /// <reference path="mylib.d.ts" /> statements support URL paths? If not should they? It seems like an interesting way to resolve and expose typescript definition files. For internal projects it wouldn't be much different than setting up a private NuGet server which appears to be pretty common place for .NET project.

[jpierson]

Is dts-generator a solution? I haven't had time to explore it. I was hoping to leverage something built into the compiler to create a type definition file and also an equally simple way to consume it without having to either place on DefinitelyTyped or copy locally into each project.

[SonofNun15]

I'll take a look at dts-generator. I was hoping for some native TypeScript support so that external TypeScript libraries could be imported via ES6 imports as well. Something like import {part1, part2} from 'path/to/my/js/and/dts/files';

[SonofNun15]

If you are using external modules, dts-generator looks like a good solution. Unfortunately, as far as I can tell if you are using external modules you need to use requirejs to import your module / library file into other TS code, which is tricky to do in TS. You would have to include requirejs and add the d.ts file for requirejs so you could require the external module in your TS. This seems messy. If you are using commonjs external modules I have yet to find a good way to import the result into a TS file.

[SonofNun15]

For the record, I assume you are referring to: (https://github.com/SitePen/dts-generator)

[jpierson]

@SonofNun15 yes that is the dts-generator that I was referring to. I'm not using external modules at the moment because of the similar points of complexity but I do prefer the explicitness of that style code.

[SonofNun15]

@jpierson, I totally agree with you. External modules are not only cleaner, but are generally recommended by "the webs" 😀. We switched to internal modules only because it seemed necessary in order to make external TS libraries work. You can get a single js and d.ts file out of internal modules from the compiler and then as long as you ultimately load the js file you can reference the namespaces as globals to consume a library.

[SonofNun15]

Ultimately my hope with this issue was that better support could be added for building TS libraries while using external modules.

[mhegazy]

Sorry for the delay.

/// <reference path="enums.ts" />

this is not generated by the compiler. this is a hand-authored file. if this the case, then the solution seems simple, do not do that, if it is not then it is a compiler bug that needs to be fixed, and would appreciate more information.

I have to dist all d.ts files in the same tree structure in order for the single d.ts

Is not that the same issue with .js files? your contracts.d.ts provide typings for a contracts.js file, i am assuming. and any other teams that depend on you, will need contract.js along with your library output; same would apply to declarations.