STATUS: WIP usable with limitations, feedback welcome!
This is a TypeScript declaration file generator for the Haxe JavaScript output target.
What it does is generate a .d.ts file next to the .js file generated by Haxe compiler,
containing TypeScript declarations for classes and functions exposed from Haxe using the
@:expose metadata, and all their
related types (function arguments and return types).
To make using Haxe/JS modules from both JavaScript and TypeScript much easier, of course! Just compile your Haxe library to a JS module and use it in TypeScript in a perfectly typed way.
Just add -lib hxtsdgen to compiler arguments and a .d.ts file will be produced along the normal JS output.
Using compiler option -D hxtsdgen_enums_ts, the library will produce an extra output-enums.ts
with concrete TypeScript enums from Haxe Abstract Enums (see "Limitations").
To change the enums' file name, use -D hxtsggen_enums_ts=other_name to produce other_name.ts.
Using compiler option -D hxtsdgen_types_ts, the library will produce an extra output-types.d.ts
with all the interfaces and typedefs separated from the classes & functions declarations.
To change the types' file name, use -D hxtsggen_types_ts=other_name to produce other_name.d.ts.
By default, generated files include a comment warning that the file is generated.
-
Using compiler option
-D hxtsdgen_skip_header, no header will be included. -
Header can be overriden by adding the following compiler macro to your build:
--macro hxtsdgen.Generator.setHeader('/* tslint:disable */')
Certain Haxe features are compiler abstractions and thus may not be possible to translate to TypeScript.
- Classes
- Interfaces
- Anonymous Structure Typedefs
- Option to generate interfaces from Typedefs?
- Other uses of typedefs
- Properties (as
get_prop/set_prop) - Native properties (needs compiler support)
- Enums (needs compiler support)
- Abstract enums (see limitations)
- Abstract enums as concrete
.tsenums (-D hxtsdgen_enums_ts) - Option to generate "fat enums" from Abstract enums?
- More general abstracts (unlikely, excepted possibly for return values)
By default, Haxe packages are flattened.
E.g. com.foo.Thing in Haxe can be imported as:
import { com_foo_Thing } from './thing';
const thing = new com_foo_Thing();You can use @:expose('FriendlyName'), which will export
module-level declarations:
package com.foo;
@:expose('Thing')
class Thing {...}Can be (nicely) imported as:
import { Thing } from './thing';
const thing = new Thing();To prevent flattening, set -D hxtsdgen_namespaced, but it doesn't play well with
hxtsdgen_enums_ts and hxtsdgen_types_ts...
Currently all the types have to be explicitly exposed; types used by functions won't be automatically exported so everything must be currently annotated for export.
hxtsdgen can generate TypeScript const enums,
which are a pure compiler construction, substituted at compile time with their value.
However .ts code can be compiled by 2 compilers: TypeScript and Babel.
- Check Babel's
const enumsupport: babel/babel#8741 - TypeScript supports
const enumin.d.tsfiles only in full compilations.
For optimal compiler compatibility, add -D hxtsdgen_enums_ts to hint hxtsdgen to
generate enums in a separate .ts file which will be compatible with
--transpileOnly --preserveConstEnums.
Enums and Abstracts are a key feature of the Haxe language, but They don't translate well to JavaScript APIs as they are a compiler feature.
General Abstracts, offering compile-time types abstractions and operators overloading will probably never be supported.
Enums could be somehow supported, but currently the compiler doesn't allow exposing them.
Haxe JS doesn't generate native properties in any language - they are always transformed
into get_prop/set_prop functions. It is possible that in the future the Haxe compiler
will allow exporting native properties.
Check out these 3 awesome panes (left-to-right):
Main.hx(Haxe source code)main.d.ts(generated TypeScript declarations)test.ts(TypeScript source code that uses the declarations)
