how are we going to distribute this?

as a part of std lib:

• out-of-the-box support which is very appealing to users (just install haxe and write stuff)
• more support because (because we have to maintain our std lib)
• inability to provide timely updates because haxe releases so rarely

as a haxelib:

• easier to provide small updates and fixes
• smaller and easier to maintain std lib
• users have to install the library and thus learn about haxelib first (it could be installed by default tho)
• possible desync and confusion with haxe/hxnodejs/node versions

also there seems to be some must-have node.js modules that everyone basically have in every app (e.g. express and its dependencies) - maybe we should also provide high-quality officially supported externs for that?

also what about nodejs Sys/sys implementation? it's not possible to implement full support because node.js lacks sync API that is required for haxe, but we could at least provide filesystem and Sys stuff.

One feature of nodejs EventEmitter are that its methods are chainable, i.e. returning the emitter object itself, however our current externs are somewhat limiting their usage because these methods return EventEmitter instead of original type.

What we could do is something like this:

extern class EventEmitter<T:EventEmitter<T>> {
    function on(event:String, listener:Function):T;
}

extern class Process extends EventEmitter<Process> {
}

I had to add the following on CastleDB:

untyped if( js.node.Fs.accessSync == null ) js.node.Fs.accessSync = (js.node.Fs : Dynamic).existsSync;

Not sure if we want to support this kind of backward compatibility or not. The issue in that case is that sys.FileSystem.exists was failing silently because of the catch( Dynamic )

Imho crypto methods provided by nodejs should be used instead of the haxe(js) implementation.
I guess they are faster and probably less error prone.

For haxe.crypto.Md5 this would look like:

package haxe.crypto;

import js.node.Crypto;
import haxe.io.Bytes;

class Md5 {

    public static function encode( s : String ) : String {
        var h = Crypto.createHash( "md5" );
        h.update( s );
        return h.digest( "hex" );
    }

    public static function make( b : Bytes ) : Bytes {
        var h = Crypto.createHash( "md5" );
        h.update( b.getData() );
        return Bytes.ofData( h.digest() );
    }
}

What do you think?

Fs.hx

var opt : FsWriteFileOptions = cast { };        
opt.flag = FsOpenFlag.AppendReadCreate;     

js.node.FsWriteFileOptions has no field flag

If we start to add npm stuff in hxnodejs the lib will quickly become bloated and hard to manage.
I think we should keep libraries externs in another repository and keep hxnodejs focused only in the official functionalities.

We should make a release of hxnodejs at some point, but I'm still reluctant to do that because I haven't receive much feedback on general structure and API design of the library which will be harder to change after an official release.

So please guys, speak up now and feel free to mention other people who are already using hxnodejs.

@fponticelli @clemos @ncannasse @ousado @frabbit @eduardo-costa @tong @back2dos

I don't get how these are supposed to be used.

extern class FileIOOption {
    var encoding : String;
    var flag : String;
    /* etc */
}

static function readFileSync(filename : String, options:FileIOOption):Dynamic;

In plain node.js, you just pass an object like {encoding: "utf-8"} to that function, so I think the correct way to map it to haxe would be:

typedef FileIOOption = {
    ?encoding:String,
    ?flag:String,
    /* etc */
}

1. After installing with haxelib git hxnodejs [email protected]:HaxeFoundation/hxnodejs.git;
2. Adding it to the build.hxml file:

-cp src/haxe
-D js-es5
-lib hxnodejs
-main Main
-js main.js

And using the following Main script to test the code:

package;

import js.node.http.*;

class Main {

static function main() {
  new Main();
}

public function new() {
    testRest();
  }

  public function testRest() {
    var http = new Client();
    trace(http.request(Method.Get, 'http://www.google.com'));
  }
}

After compiling and running it with node main.js, I get the following error:

$ node main.js                                                                                                                                                                              [2.2.1]
/Users/fullofcaffeine/workspace/code/projectgtd/main.js:100
        var http = new js.node.http.Client();
                       ^
ReferenceError: js is not defined
    at Object.Main.testRest (/Users/fullofcaffeine/workspace/code//main.js:100:18)
    at Object.Main [as __class__] (/Users/fullofcaffeine/workspace//main.js:92:7)
    at Function.Main.main (/Users/fullofcaffeine/workspace/code/main.js:96:2)
    at /Users/fullofcaffeine/workspace/code//main.js:744:6
    at Object.<anonymous> (/Users/fullofcaffeine/workspace/code//main.js:745:3)
    at Module._compile (module.js:430:26)
    at Object.Module._extensions..js (module.js:448:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:471:10)

The generated javascript: http://pastie.org/private/c8eboqpnrawbxvucolodqa#18

What am I missing?

Subj.

so, node 0.12 released before hxnodejs and we need to adapt externs for the new version

Can we create a new repository called hxnodelibs so we can do the same work adapting the most common nodejs libraries?
Some like:

• mongodb
• authom (git, google, FB, twitter, OAuth login system)
• express
• NW.js (node desktop apps)
• peerjs (webrtc)
• socket.io (websockets)
• ws (websockets)

I have some work done in those libs, so I'm open to share things like I did in the start of hxnodejs
This is something I would advance in the long run. But some help from the community would be cool!

we should somehow test these externs.

of course, we don't have resources to port and maintain node.js unit tests, but we at least need to make sure that every module can be parsed and typed and hope we made things right.

we can automate this by writing a macro that recurses into source directory and does Context.getModule(...) similar to what documentation generator does.

We need to develop a clear package/module/type naming/placing conventions to use for these externs.

For example, right now (as of 681d4bb) we have the node.js fs module available as js.node.fs.File which seems weird.

Another demonstrative example is js.node.Buffer module that contains the BufferConst class that gives access to the INSPECT_MAX_BYTES value of the buffer node.js module.

Also, I believe Haxe std library doesn't capitalize acronyms, while node.js does.

We should sort this out.

Some methods in node.js accept one or another type, e.g. either String or Int. While it is easy to handle using @:overload in a basic case, it's more complicated when that type is used as a type parameter. For example, see: http://nodejs.org/api/process.html#process_process_setgroups_groups. The groups argument there is an Array that can contain both Int and String elements.

One option is to simply use Array<Dynamic>, however this is weak typing we'd like to avoid.

Another option is to introduce an abstract like this:

abstract Either<T1,T2>(Dynamic) from T1 to T1 from T2 to T2 {}

and then type that argument as Array<Either<String,Int>> which will restrict types to Int and String.

I believe this approach is used quite successfully by @andyli in his jQuery externs.

The questions are: do we want to introduce this? if yes, where do we want it to be (as it's quite universal) and how do we want it to be implemented (what about 3 and more Either types?)

For a newcomer, it's right now quite confusing to start with hxnodejs. Considering hxnodejs should the official set of Haxe externs for Nodejs and that it's already being used by other libs/frameworks out there (like Franco's Abe) I'm surprised we don't have more documentation, particularly on how to actually set it up for new Haxe nodejs projects.

Also, a quick mention of other externs and their relationship to this one (and why the user should pick this one over the others already available) would be nice.

As a side question - does anyone know why https://github.com/clemos/haxe-js-kit isn't the official nodejs extern repo instead? It seems to be under quite active development.

See http://nodejs.org/api/stream.html#stream_api_for_stream_implementors

I guess we can provide signatures for that by specifying private methods in externs.

Is there any plan to support haxe.io.Input/Output from js.node.Buffer and similar?

It currently has a bunch of untyped __js__ things that are not really safe and can potentially conflict with local vars. To address that, I think we could add e.g. process and/or global to the list of JS pseudo-keywords, like we do for console, window and require.

There are places where @:overload is used instead of simply making argument optional, i.e.:

@:overload(function():HTTPSServer { } ) 
static function createServer(listener : IncomingMessage -> ServerResponse -> Void):HTTPSServer;

could be reduced to

static function createServer(?listener : IncomingMessage -> ServerResponse -> Void):HTTPSServer;

In php target, Sys.args() returns only the "arguments", i.e. exclude the executable and the script.
For example it will return ['arg1', 'arg2', 'arg3'] for the command php script.php arg1 arg2 arg3

However, in hxnodejs, Sys.args() returns process.argv; which include the executable and the script.
For example the command node script.js arg1 arg2 arg3 will become ['node', 'script.js', 'arg1', 'arg2', 'arg3']

Ref:
http://php.net/manual/en/reserved.variables.argv.php
https://github.com/HaxeFoundation/haxe/blob/development/std/php/_std/Sys.hx#L34

I saw that in recent update, Http.headers had became EitherType<String, Array<String>>, I suppose to support the set-cookie header which is an array.

But I'm wondering why this haven't been changed in IncomingMessage. Was there a compatibility issue? If not, I'll make a PR to change it as well.

Thank you

C:\HaxeToolkit\haxe\lib\hxnodejs/4,0,4/src/js/node/buffer/Buffer.hx:65: characters 8-65 : Same field name can't be use for both static and instance : byteLength

haxe 3.3

Subj. Not only for the sake of purity, but also because of HaxeFoundation/haxe#3050, so we don't generate unnecessary require's.

Some news arrived.

http://www.wired.com/2014/12/io-js/

Do we smell another lib? :)

... so extraParams.hxml works, etc ?

Subj. See usage here: http://haxe.org/manual/target-javascript-require.html

i added a bunch of @:overloads without knowing that haxe doesn't do return type overload selection (see HaxeFoundation/haxe#3501). now we have to review all @:overloads of this kind and replace them with EitherType return values.

Currently our event enumerations is a bit messy because we duplicate SOME (but not ALL) events of parent classes. We have to develop a convention on that.

Some thoughts:

• Duplicating every parent event creates a lot of noise, but is probably good for documentation.
• Not duplicating parent events makes externs cleaner, but we have to mention that it also can emit parent class events. Also, it makes switch too restrictive.
• Maybe we could think of some technical solution to express @:enum abstract inheritance in Haxe itself. E.g. @:forward @:enum abstract ChildEvent(ParentEvent) {} or something. @Simn @ncannasse what do you think?

Subj. I.e.

class SomeEventType {
    public static inline var SomeEvent = "someEvent";
}

to

@:enum abstract SomeEventType(String) to String {
    var SomeEvent = "someEvent";
}

Subj. See http://nodejs.org/api/os.html#os_os_networkinterfaces, for example.
These don't map to any standard Haxe type and working with them via Reflect is uncomfortable and untyped.

Even with no regard to node.js externs, people are often asking for a convenient and typed way to work with JS/JSON objects in Haxe and we still don't have one.

I wrote a DynamicObject abstract for myself (https://github.com/nadako/haxe-thingies/blob/master/src/DynamicObject.hx), but I remember we decided not to include it in the standard library. However, now that we want to provide "official" node.js externs, we need something like that.

What's our position on that, @Simn, @ncannasse?

When I started nodehx I made the URL class a bit too custom.
Will revert it to the official API.

I think we should enforce something like -D nodejs for using hxnodejs externs. That way we could know for sure whether we're on nodejs or not. This could be used in compiler, for example to conditionally add nodejs-specific identifiers to genjs pseudo-keywords (e.g. process or global). Another use is to provide Sys implementation on js using @:require(nodejs).

Thoughts?

While working on externs, I've left some unresolved questions marked with TODO in the code. Before we "release" (by either merging into std lib or making a haxelib), we should handle all these.

see https://www.npmjs.com/package/deasync

https://nodejs.org/en/blog/release/v4.0.0/

there are some deprecated API documented in current node.js docs. we could add @:deprecated metadata in haxe to warn user about that. think that's a nice free feature that plain node.js doesn't have.

thoughts?

produces this :

/home/clemos/Work/hxnodejs/src/_hxnodejs/VersionWarning.hx:9: characters 12-86 : Primitive not found macro@include_file:2
--macro:1: character 0 : Called from
Aborted

using haxe 3.2.1 (installed from official deb) + neko 2.0

I noticed that many (but not all) methods have arguments starting with p_ which is probably is a convention in Haxor engine, but we don't really use those in Haxe std library. Moreover, I think we should name extern methods arguments strictly after ones in node.js API docs

Pending the implementation of HaxeFoundation/haxe#3441 in the Haxe compiler and assuming we get the @:selfCall meta data we should discuss how to implement constructor-without-new-keyword pattern. Here is an example of the pattern which is common in some NodeJS code:

var express = require("express");
var app = express();
express.static(...);

I recommend the following pattern for implementing this:

@:jsRequire("express")
extern class Express {

    ...

    @:selfCall function apply (ctorArgs ...):Express;

    ...

}

Converting the above example to Haxe will look like this:

var app = Express.apply();
Express._static(...);

This will also work for the utility function pattern as well. See here HaxeFoundation/haxe#3441 (comment)

It seems that haxe std lib is uses the following format for API docs:

/**
<tab>Return whether `v` is not a zero.
**/
function nonZero(v:Int):Bool;

Notice the comment format and backticks that mark arguments.
I think this style is "official" (@Simn is it?), so we should conform to it.

Or should it?

I tried to add haxe.io.Bytes implementation, but there's a problem that in a macro it also tries to use the overriden class and then complains about using js.node.Buffer in a macro context.

What can we do with that? One option is to just move nodejs sys stuff into Haxe itself (and fence with #if nodejs), another one is to make it possible to override types only for target output context, not the macro one.

Also, @:coreApi metadata doesn't work on our overriden types.

cc @Simn @ncannasse

Subj. It's either a string with octal number or an Int.

For instance, fs.symlink accepts the type parameter that is String with predefined values in JS: dir, file and junction (see http://nodejs.org/api/fs.html#fs_fs_symlink_srcpath_dstpath_type_callback).

For those values, we provide a @:enum abstract SymlinkType (see

The question is: should we add from String to that abstract?

• if we don't, user won't be able to just copy-paste js code and will have to change strings to enum values
• if we do, user may pass an invalid string so we lose strict typing

Another option is add a @:from method with validation, but I don't think that's a good idea because that would add runtime cost (we could only add it in -debug mode tho).

I wonder if we should add @:jsRequire to e.g. http.Server. In upstream modules they are exported but they are not meant to be created with new. I don't know about extending however. Any thoughts?

Also, currently Haxe generates a lot of requires that are not really used in the code (see HaxeFoundation/haxe#3050). I wonder how big issue is that? My guess that it's negligible for long-running processes (such as servers), but what about one-time scripts? Could the startup time slowdown be significant for those?

we need to make a guideline document that describes how to write externs for third-party node.js modules so they fit nicely in our official structure.

• module classes/packages, @:jsRequire
• event enums
• structure typing
• overloading and optional args
• usage of EitherType and DynamicAccess (when it's finally merged)
• anything else?

They do also exist in js.html.Promise so an alias might be sufficient.

Current implementation is using Fs.mkdirSync() which will fail if some intermediate directories don't exist, while haxe API docs are stating that createDirectory() is recursive.

I guess a solution might be to implement something similar to this: https://github.com/substack/node-mkdirp/blob/master/index.js

Thanks for the great work anyway!