Use TypeScript definitions with Haxe: dts2hx is ready to use!

Hey all!

For the last year I’ve been working on a tool to convert TypeScript definitions to haxe externs using the TypeScript compiler and now I think it’s complete enough to announce :tada:

How to use:

  • Install dts2hx from npm

    npm install dts2hx --save-dev

  • Install a module with types, e.g. npm install three

  • Run dts2hx on the node module

    npx dts2hx three

  • Or alternatively, generate externs for all local package.json dependencies with

    npx dts2hx --all

  • This will generate externs for haxe 4+ into a directory called .haxelib/, which is a local list of haxelib libraries, similar to node_modules for npm.

  • Then to use the three externs, add --library three to your build hxml

See the github repository (haxiomic/dts2hx) for more details

It should work well for most game libraries, I’ve created examples for babylonjs, phaser, pixi.js, playcanvas and three.js

While I expect it to do a good job on most TypeScript modules, modules which rely heavily on advanced TypeScript features like mapped types will lose some type information, so for libraries like React and vue.js you’d be better off using hand-curated externs like haxe-react

Please test it out on your favorite and TypeScript libraries and report any issues you find :slight_smile:

Thanks to the Haxe Foundation for their support :haxe: :heart:

33 Likes

This is super awesome! Thanks for all your hard work on this!

What would be a great addtion is to have some extra flag which downloads the definition from DefinitelyTyped. That would make working with most definitions flawless.

1 Like

I’m not very familiar with TypeScript. What is the typical use-case and example workflow for dts2hx?

What I mean is, is dts2hx for when you want to create your app in Haxe, compile to JS, and make use of TypeScript libraries? (Are TS libs installed via npm?)

Or is it for when you have a TypeScript app and want to use your own Haxe libraries within it?

Or something different?

Thanks!

Many JavaScript libraries these days have type-definitions, this is essentially the same as haxe externs, but written for a different language: TypeScript.

If you find a nice library on npm that you want to use in your haxe js project, say playcanvas, without dts2hx you have to read the docs or source code and craft your own externs to use it. The purpose of dts2hx is to translate existing type definitions into haxe externs so you don’t haxe to do this yourself

You can try out the concrete examples to see how it works examples/playcanvas

The idea is that there are a lot of typescript definitions for javascript libraries. We can now convert those to Haxe. That means that you can use almost any JavaScript library (that has typescript definitions) in your Haxe/JavaScript application in a typesafe matter (where possible). This tool is great because in early days you had to keep them up to date manually, now it can be done automatically.

I’ve not played with it much, but I hear Microsoft’s dts-gen is quite good – this automatically generates TypeScript definitions from plain-old javascript files by analysing types at runtime. I’ve got it on the todolist to integrate this to dts2hx, this would mean you can generate haxe externs for just about any npm module, whether or not it has type definitions :smiley:

edit: nvm, dts-gen is not amazing

2 Likes

Ah! I was about to ask if TypeScript’s definition files were akin to Haxe’s externs! Excellent!

can I convert custom *.d.ts?

Yep :slight_smile:

npm install dts2hx
git clone https://github.com/cocos-creator/helloworld-typescript
npx dts2hx ./helloworld-typescript/creator --tsconfig helloworld-typescript/tsconfig.json
1 Like

there is a bug in your examples

     "postinstall": "dts2hx three three/examples/jsm/controls/OrbitControls"

shoud be ?

     "postinstall": "npx dts2hx three three/examples/jsm/controls/OrbitControls"

If you do npm install dts2hx it installs it into a local folder named node_modules, so to run it you need to access the script directly: ./node_modules/.bin/dts2hx
npx is a shorthand for this

npx isn’t needed inside package.json scripts – npx is a utility that changes the environment to make node_module scripts visible (it essentially adds node_modules/.bin to PATH)

Package.json scripts already execute in this environment

If you do npm install dts2hx -g then you can use dts2hx anywhere without npx

Probably the biggest surprise of haxe this year, is there any plan to add VUE support?

The problem with vue.js comes down to this monster of a type:

export type ThisTypedComponentOptionsWithArrayProps<V extends Vue, Data, Methods, Computed, PropNames extends string> =
  object &
  ComponentOptions<V, DataDef<Data, Record<PropNames, any>, V>, Methods, Computed, PropNames[], Record<PropNames, any>> &
  ThisType<CombinedVueInstance<V, Data, Methods, Computed, Readonly<Record<PropNames, any>>>>;

If you manually change it to

export type ThisTypedComponentOptionsWithArrayProps<V extends Vue, Data, Methods, Computed, PropNames extends string> =
  ComponentOptions<V, DataDef<Data, Record<PropNames, any>, V>, Methods, Computed, PropNames[], Record<PropNames, any>>

It works ok and I think the vue.js externs will be usable after that

It’s on the roadmap to improve handling of intersections, so maybe in the near future vue.js will be officially supported

(Update: I’ve resolved the issue with this type)

2 Likes

how to use async js style in haxe ?

like

@haxiomic

em,once you do that .some of libs without *.d.ts can be convert to haxe .like jsxgraph.

how to use async js style in haxe ?

That’s out of scope of this library, but you can try Showcasing JSAsync: Haxe library for generating native JS async/await functions - #7 by basro

2 Likes

How to use jquery within dts2hx gen ? any examples ?

npm install --save @types/jquery

npx dts2hx jquery

there are only two methods in Jquery.hx . how to use ?