HaxeFoundation
extern guidelines
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?
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?
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!
I think I'll do things similar I was doing.
js.node.express.*
js.node.mongodb.*
- 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.
Yep.
I'll adapt some common nodejs modules in the nodehxgit.
Maybe we can spawn a hxnodemodules later.
@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...
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.
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 usingstatic 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)
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 [email protected]:
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]
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.
@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
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.
@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.
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?
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 [email protected]:
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]
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.
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 [email protected]:
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]