Naming conventions about hxnodejs HOT 23 CLOSED

I kind of like @clemos haxe-js-kit layout, where the fs node.js module is represented by a js.node.Fs extern class and its child types reside in js.node.fs package. I think we've used the same scheme for Python standard library.

from hxnodejs.

I kind of like my layout as well :D
I believe it's important to transform the original API as few as possible, so js.node.Fs/js.node.fs should be kept.

The problem with Buffer is that it's available globally (even though it's defined in the buffer package : http://nodejs.org/api/buffer.html#buffer_buffer), so it makes sense to just have it in js.node.Buffer (to avoid js.node.Buffer with only one static constant, and js.node.buffer.Buffer with a class that is in reality accessible globally...).

But then INSPECT_MAX_BYTES being accessible through require('buffer').INSPECT_MAX_BYTES,we can't directly make it a public static var.
I guess in this very special case, we can have something like :

public static var INSPECT_MAX_BYTES (get,null) : Int;
inline function get_INSPECT_MAX_BYTES() return untyped require('buffer').INSPECT_MAX_BYTES;

from hxnodejs.

I think we should access our Buffer extern class via buffer module as well, because user might define their own conflicting Buffer class.

from hxnodejs.

But yeah, it makes sense to have it in js.node.Buffer even if we generate it as require('buffer').Buffer

from hxnodejs.

Good idea about INSPECT_MAX_BYTES thing, I think we should do that.

from hxnodejs.

I created extra packages to help users find classes grouped by the same
'require'.
I believe it can help when a user wants to see all 'fs' stuff available,
and will not bother other users which wants to use the classes.

Also creating extra packages can avoid conflicts if ever nodejs creates
something like this:

fs.Stats
xy.Stats

If we remove the packages we'll need to handle it by renaming the classes
which will be weirder.

Considering that 'fs' is both package and class, I used the most commonly
API name "File". But we can still do fs.Fs to keep it 100% like the API.
Em 07/10/2014 09:04, "Dan Korostelev" [email protected] escreveu:

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

For example, right now (as of 681d4bb
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.

—
Reply to this email directly or view it on GitHub
#16.

from hxnodejs.

I don't understand the part about fs/xy.Stats. If we place node.js fs.Stats into js.node.fs.Stats, it won't conflict with anything.

from hxnodejs.

I think I understood that you guys want to remove the sub-packages folders
like:

js.node.fs
js.node.buffer
js.node.stream
...

And make everything inside js.node
Em 07/10/2014 09:59, "Dan Korostelev" [email protected] escreveu:

I don't understand the part about fs/xy.Stats. If we place node.js
fs.Stats into js.node.fs.Stats, it won't conflict with anything.

—
Reply to this email directly or view it on GitHub
#16 (comment)
.

from hxnodejs.

Ok so I think we agree :

• buffer.Buffer goes to js.node.Buffer with @:requireJs('buffer','Buffer') and public static var INSPECT_MAX_BYTES (get,null) : Int` + getter
• adopt the convention js.node.Fs for static fs methods, js.node.fs package for possible package classes / typedefs (such as Stats).

from hxnodejs.

Yes. My line of thought is that as Buffer came from the require 'buffer' so
it belongs to the buffer package.

But I'm cool with this pattern you suggested but keeping some sub-packages
Em 07/10/2014 11:43, "Clément Charmet" [email protected] escreveu:

Ok so I think we agree :

• buffer.Buffer goes to js.node.Buffer with
  @:requireJs('buffer','Buffer') and public static var INSPECT_MAX_BYTES
  (get,null) : Int` + getter
• adopt the convention js.node.Fs for static fs methods, js.node.fs
  package for possible package classes / typedefs (such as Stats).

—
Reply to this email directly or view it on GitHub
#16 (comment)
.

from hxnodejs.

We can always package js.node; typedef Buffer = js.node.buffer.Buffer;, which is somehow what the native API does, without the risk to overwrite the global Buffer...

from hxnodejs.

Yes.
My fear was to group everything inside js.node only.
Em 07/10/2014 11:47, "Clément Charmet" [email protected] escreveu:

We can always package js.node; typedef Buffer = js.node.buffer.Buffer;,
which is somehow what the native API does, without the risk to overwrite
the global Buffer...

—
Reply to this email directly or view it on GitHub
#16 (comment)
.

from hxnodejs.

Regarding the Http classes (and others).
Considering that nodejs itself calls it HTTP [http://nodejs.org/api/http.html#http_http] don't we need to follow their pattern?

from hxnodejs.

There's no HTTP class in node.js, the module is called http, so I think it's fine to follow our convention and use Http for the module static class.

from hxnodejs.

Ok then!

from hxnodejs.

Related to these changes:
d82d639

I kind of don't like to have two Socket named classes.
I know that nodejs does it that way but when I'm doing a project and have to do this:

var tcp : js.node.net.Socket; //my tcp socket;
var udp : js.node.dgram.Socket; //my udp socket;

It will make me choose between imports.
That is why I chose to create UDPSocket and TCPSocket.

Maybe we can open an exception in this (and other cases) in order to improve the integration with code completion.

Maybe do something like this:
js.node.net.TcpSocket
js.node.dgram.UdpSocket

from hxnodejs.

I don't think we should break our convention because of that. For your problem the obvious solution is to do import js.node.dgram.Socket in UdpSocket

from hxnodejs.

In general I can't make up my mind about the unique type name issue, but due to the French "as" import it's easily dealt with.

from hxnodejs.

Or can we offer both?
Like officially write js.node.dgram.Socket but in a line above offers the user this solution.

I think these solutions can survive alongside.

from hxnodejs.

I say that because, it can happen not only with me.
And if we can avoid the user always adding the same snippet in every project, we can pretty much offer this second option to users.

Can typedef also solve this?

typdef js.node.net.TcpSocket = js.node.net.Socket
typdef js.node.dgram.UdpSocket = js.node.dgram.Socket

If it helps the user and don't mess with the official API, there is no harm I guess.

from hxnodejs.

Is it really an issue? I mean, people don't use e.g. dgram and tcp sockets in a single module very often and for that case haxe provides the import in mechanism.

I just don't feel like adding these typedefs, because IMO it would create noise and confusion without real benefit.

from hxnodejs.

​Hmm fair enough.
Functionalities can be in different modules.

If everyone is ok with that, I'm cool.​

2014-10-10 15:39 GMT-03:00 Dan Korostelev [email protected]:

Is it really an issue? I mean, people don't use e.g. dgram and tcp sockets
in a single module very often and for that case haxe provides the import
in mechanism.

I just don't feel like adding these typedefs, because IMO it would create
noise and confusion without real benefit.

—
Reply to this email directly or view it on GitHub
#16 (comment)
.

[image: Imagem inline 1]

from hxnodejs.

Seems like there's nothing here left to discuss.

from hxnodejs.