dts2nim: a TypeScript/Nim bridge
Using the tool looks like:
dts2nim example.ts -o example.nim -q
The tool takes in exactly one
.d.ts file. If you need to use multiple
.ts files worth of material, make a joiner file and put some
// <reference />s in it. The output file is specified with
-o. While running, the tool will emit [many] warnings describing the symbols it was not able to translate; you can direct these to a file with
-l, or silence them with
The tool maintains a "blacklist" of symbols it should not try to translate. This is needed because there are at the moment some types which the tool will attempt to translate even though translating them will result in a Nim compile error. About fourteen items from the standard library are on the blacklist by default. You can add more items using the
--blacklist flag, which takes a comma-separated list.
Blacklist items are of the format
kind:class.name. You can shorten this to
class.name or just
kind if you want. The allowed "kinds" are
class (interfaces count as classes). So for example, if the blacklist contains the item
static:Performance.timing, then this means the static field or method
timing on the class
Performance will be ignored.
More flags are described in the
Names from TypeScript are slightly modified to work in Nim:
- The constructor for a class
newExample(). (Interfaces are not given constructors.)
- Static members of classes become variables with the class name followed by the member name (so
$symbols in names are replaced with the letters
- Groups of two or more underscores in names are replaces with a single underscore.
- An underscore at the start of the name is replaced with a
- Any symbol which is a Nim reserved word gets an
xprepended (so for example a TypeScript variable named
typewould be presented to Nim as
- A combination interface+variable whose variable type is an interface that overloads
newwill be collapsed all into one single class with the variable-type interface members treated as statics. This is an idiom which is used heavily in the TypeScript standard library.
This is an early attempt at this tool, and
dts2nim has a series of feature improvements I would like to make to it:
- It does not support generics. This is a huge problem because
ArrayLikeboth require generics.
- It does not support
any, which is a big part of TypeScript. Although has nothing like an
anytype, in principle
anycould be in some situations by using generics.
- Interfaces are currently imported as object types. It would make more sense for them to be concepts. (This would also help with
dts2nimspits all symbols into one file. It would be nice if, when given a tree of several
TypeScriptfiles, it could create a separate module for each one.
dts2nimcurrently assumes that the symbols from the TypeScript side are exported into the global namespace, as if all your source files were being declared with
<script />tags. It does not interoperate with commonjs or any sort of module system.
- The TypeScript
namespacekeywords are not supported.
- Union types are handled only under narrow circumstances (when used in method parameters).
- The name conversion
dts2nimdoes can currently sometimes result in namespace collisions on the Nim side, which causes Nim errors.
In addition, there are two large "conceptual" fixes that should be done:
- At the moment,
dts2nimworks by loading type and symbol information out of the TypeScript compiler API. The compiler API features were not designed for the purpose of analyzing a whole program, and were intended to be used for syntax highlighting in text editors. Because of this, in several places
dts2nimuses unsupported API features or relies on internal values of data structures. This is likely to break with future TypeScript upgrades. A better way for
dts2nimto work would be either to request additional API points from the TypeScript team to get what it needs in a supported way, or to ignore the type/symbol database and instead parse ASTs exported from the compiler API.
- I would like the tool to eventually evolve to create bindings for other languages (such as Haxe, or maybe even C++ or C#). Although the tool only supports Nim currently, it is designed for additional output languages to be added easily.
The tool is being developed in a Mercurial repository at BitBucket. Since most people prefer git, a GitHub mirror is also maintained. If you wish to report issues or submit a pull request, please do so at the GitHub page.
You can install the tool by running
npm install dts2nim. The tool will be installed into
To build your own copy from source, you will need to have
make, TypeScript, and
typings installed and available from your command line. You can get those last two by running
npm install -g typescript typings.
Once you have these things, run
npm install followed by
To run the tests, run
npm test. This will run the tests in node, and after you have done this you can open tests/index.html to run the same tests in a browser.
Copyright (c) 2016 Andi McClure
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The software makes use of NPM packages including TypeScript itself. These will have their own licenses.
If you have any questions, you can contact me by email: <firstname.lastname@example.org>