extern guidelines - Githubissues

nadako commented 9 years ago

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?

eduardo-costa commented 9 years ago

Good. In the next update of nodehx I'll remove the node externs and improve the supported libs!

When does the next Haxe + nodejs will be released?

mockey commented 9 years ago

I'm just trying to write an extern for express based on these. Was just wondering, where to put it. js.node.modules.Express seems kind of logical to me, but also quite long. That would mean: js.node.modules.express.Request and so on. Is that the right place? What do you think? BTW: great effort so far!

eduardo-costa commented 9 years ago

I think I'll do things similar I was doing.

js.node.express.* js.node.mongodb.*

clemos commented 9 years ago

naming conventions (package, casing, and also non-native API such as typedefs)

For instance, I use to systematically "prefix" my typedefs with the name of the module (to avoid same package naming conflicts), like JQueryEvent.

clemos commented 9 years ago

From what I understand, hxnodejs is about the core nodejs API only.

eduardo-costa commented 9 years ago

Yep. I'll adapt some common nodejs modules in the nodehxgit. Maybe we can spawn a hxnodemodules later.

mockey commented 9 years ago

@clemos: See first post. @eduardo-costa: js.node.express.* mixes the core modules with the additional modules. Not sure if that's good. Maybe it doesn't matter. BTW: Did you think about integrating middleware modules in your express extern? I miss that from every express extern I've seen so far. And it's quite important for express 4 I think...

eduardo-costa commented 9 years ago

Usually nodejs modules are their own root package, because you can't have 2 npm packages with the same name. So I think it is ok to use js.node.express.* So we can avoid too long js.node.modules.some_module.SomeClass For now in nodehx I have the basic setup for express, but I think it is ok to add support for its middleware.

clemos commented 9 years ago

Ok then if it's about third-party :p :D It might be useful to add "tips and tricks" such as :

reserved keywords (ex: express.static) : can be accessed using static inline + untyped this['static']
in which cases is it ok to use __init__
versionning metadata recommandation like @npm('express','3.0') (even if not used for now)

eduardo-costa commented 9 years ago

Good. I suggest we move these guidelines to the README.md or a HOWTO.md

2014-10-13 13:09 GMT-03:00 Clément Charmet notifications@github.com:

Ok then if it's about third-party :p :D It might be useful to add "tips and tricks" such as :

reserved keywords (ex: express.static) : can be accessed using static inline + untyped this['static']

in which cases is it ok to use init

versionning metadata recommandation like @npm('express','3.0') (even if not used for now)

— Reply to this email directly or view it on GitHub https://github.com/HaxeFoundation/hxnodejs/issues/22#issuecomment-58914916 .

[image: Imagem inline 1]

nadako commented 9 years ago

I'm not sure if we should enforce third-party package structure. For official haxe js.node makes sense because we already have js package and js.html for the web api, so js.node will fit in nicely.

As for something like Express, I'd just use express root package or something.

mockey commented 9 years ago

@clemos: Yeah, welcome to the (third-)party :-) And good points. BTW: I like your approach of automatic package.json handling. Did you think about automatically creating it from the main class also, like:

@:package_json({
  name: "my-app",
  description: "...",
  version: "0.0.1",
  ...
})
class Main

nadako commented 9 years ago

For instance, I use to systematically "prefix" my typedefs with the name of the module (to avoid same package naming conflicts), like JQueryEvent.

I also did this for hxnodejs, i.e. ChildProcess -> ChildProcessEvent. I think that is good practice.

nadako commented 9 years ago

I've started writing that HOWTO doc.

clemos commented 9 years ago

@mockey I like simplicity, so for now I prefer to have package.json in... package.json ;) But it's getting quite OT :D

About js.node package, there are quite a lot of packages that either have both client and server functionnality (socket.io) or are available both on client and server ((twitter-text)[https://github.com/twitter/twitter-text-js]).

It would be nice to have guidelines regarding this as well, including :

package mapping for these different js packages
package manager metadata ( @:bower('twitter-text', '1.0'), @:npm('foo','1.0') )

I personnally don't really like the idea of using either js.node or js.html for these. For client packages, I use js.browser, which I find ok, and for server packages, I use js.npm which I don't like that much... maybe js.sys would fit better ? As for common packages, I guess js would be enough...

Also, one thing I had considered (but never did), was to encourage / force the user to use -D nodejs, -D npm, -D bower or similar to be able to warn him during compilation that he uses libs that are not compatible with the target environment, and also to eventually generate dependency files (package.json, bower.json) and fetch these for him. One thing that stopped me from actually going in that direction (enforcing environment definition) is that for instance js.html definitions get pretty useful when you work with JSDOM, so we need to be careful regarding these potential rules / warnings.

nadako commented 9 years ago

I still see no real reason to enforce specific package name for third-party packages. I kind of like something simple like just socketio. What are real arguments for it being something like js.npm.socketio?

eduardo-costa commented 9 years ago

Well we can't enforce. But I think that the common sense in package naming is to give the user some context. So, at least a [js.nodelib] should be used. I think I'll stick with [js.node.libx] for my nodehx externs. Users will be used to [js.node.*] so they can search for things in this namespace.

2014-10-14 13:13 GMT-03:00 Dan Korostelev notifications@github.com:

I still see no real reason to enforce specific package name for third-party packages. I kind of like something simple like just socketio. What are real arguments for it being something like js.npm.socketio?

— Reply to this email directly or view it on GitHub https://github.com/HaxeFoundation/hxnodejs/issues/22#issuecomment-59072098 .

[image: Imagem inline 1]

nadako commented 9 years ago

what if someone releases a lib that has the same name as node.js module and you want to make extern for that? you can't use js.node.libx then.

anyway, i think it's outside of hxnodejs scope.

eduardo-costa commented 9 years ago

Yes it is :)

If someone does a lib in the npm scope its name must be unique (like haxelib). So for 2 official npm packages there will be no conflict in the [js.node.*] scope.

2014-10-14 13:32 GMT-03:00 Dan Korostelev notifications@github.com:

what if someone releases a lib that has the same name as node.js module and you want to make extern for that? you can't use js.node.libx then.

anyway, i think it's outside of hxnodejs scope.

— Reply to this email directly or view it on GitHub https://github.com/HaxeFoundation/hxnodejs/issues/22#issuecomment-59074879 .

[image: Imagem inline 1]

nadako commented 9 years ago

you lost me :)

eduardo-costa commented 9 years ago

When the next release build of Haxe + Node is schedule to come out?

nadako commented 9 years ago

there's no schedule i know of

HaxeFoundation / hxnodejs

extern guidelines #22