elsassph / hxtsdgen

TypeScript declaration file generator for Haxe JavaScript output target

TypeScript Declaration Generator for Haxe/JS

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).

Why?

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.

Usage

Just add -lib hxtsdgen to compiler arguments and a .d.ts file will be produced along the normal JS output.

Options

Concrete enums export

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.

Separate types export

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.

Custom output header

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 */')
  

Supported Haxe features

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 .ts enums (-D hxtsdgen_enums_ts)
• Option to generate "fat enums" from Abstract enums?
• More general abstracts (unlikely, excepted possibly for return values)

Haxe packages

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...

Limitations

No automatic export

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.

Abstract enums

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 enum support: babel/babel#8741
• TypeScript supports const enum in .d.ts files 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.

Abstracts and (regular) Enums

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.

Native properties

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.

How does it look?

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)