package naming and file placing

[nadako]

Now when hxnodejs is finally released, we can discuss a bit about this extern collection.

I don't like how it's currently done here using js.node as a prefix package since it may introduce conflicts with core node modules added at some time, also I don't like the fact that one can't easily say which is node API and which is a npm module.

@clemos uses js.npm prefix which I think is better, but I don't quite like that different externs (of different quaility and by different authors) are placed in one root - it gets messy when there are lots of them, IMO.

I wonder if we can/should use separate source paths for different npm externs and somehow still be able to just do -lib hxnodelibs and then simply import js.npm.Whatever. Maybe with macro that adds class paths and is executed in extraParams.hxml?

That way extern authors can also provide README's, tests, examples, etc.

Thoughts? @clemos @ncannasse @andyli @dionjwa @fponticelli @eduardo-costa @tong @back2dos (please cc anyone i forgot)

[eduardo-costa]

I just cloned my currently being used libraries which uses js.node as
convention.
But I like the js.npmway.

Regarding the macro I’m not sure if it is cool because users could want to
select the version manually or have other
​alternatives
without something automatically choosing for them.
Or it could conflict somehow with his package.json directives.

Just guessing.
​

2015-11-10 0:41 GMT-02:00 Dan Korostelev notifications@github.com:

Now when hxnodejs is finally released, we can discuss a bit about this
extern collection.

I don't like how it's currently done here using js.node as a prefix
package since it may introduce conflicts with core node modules added at
some time, also I don't like the fact that one can't easily say which is
node API and which is a npm module.

@clemos https://github.com/clemos uses js.npm prefix which I think is
better, but I don't quite like that different externs (of different
quaility and by different authors) are placed in one root - it gets messy
when there are lots of them, IMO.

I wonder if we can/should use separate source paths for different npm
externs and somehow still be able to just do -lib hxnodelibs and then
simply import js.npm.Whatever. Maybe with macro that adds class paths and
is executed in extraParams.hxml?

That way extern authors can also provide README's, tests, examples, etc.

Thoughts? @clemos https://github.com/clemos @ncannasse
https://github.com/ncannasse @andyli https://github.com/andyli
@dionjwa https://github.com/dionjwa @fponticelli
https://github.com/fponticelli @eduardo-costa
https://github.com/eduardo-costa @tong https://github.com/tong
@back2dos https://github.com/back2dos (please cc anyone i forgot)

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

[image: Imagem inline 1]

[dionjwa]

I vote for using js.npm vs js.node for the npm externs.

Regarding managing all the externs: I have whole bunch I would like to commit somewhere. Having separate repositories for each individual extern is way too much work for me, there are simply too many, and some of them are a couple of small externs.

I would like at least one repo that is fairly loosely controlled that contains most externs and is updated often since externs do not change all that much.

Then for specific externs that require versioning, they can use some other mechanism. Perhaps a macro solution could be used that could version the externs? By default use the latest, but have some ability to specify older versions.

[clemos]

Obviously I'd vote for js.npm.*.

About extern "mess", the variable quality is pretty much that of the npm public repo itself.
I've been trying to somehow "curate" the npm packages in haxe-js-kit, though, which IMHO is easier / safer to do in one place.
Then anyone is free to add their own in their own repos / haxelib on top of that, with hxnodelibs as a dependency.

This being said, I believe it might be cleaner to always have js.npm.express.Express rather than js.npm.Express. This will avoid the js.npm namespace to be too dirty, like it is in haxe-js-kit right now...

[ncannasse]

a single js.npm is fine for me.

I think they should all be in the same repository. Even if that's harder to manage for us, it's much more easy for end users to use. If it's a single extern class we can have it in a single .hx directly in js.npm. If it's a more complete API creating a package seems necessary.

We should however define a format to deal with version requirements, for instance the users can use -D npm-mysql=1.5 and the code can check #if (npm_mysql >= 1.5) ...

[ncannasse]

PS: @clemos solution works for me as well

[nadako]

Okay, we agreed on the js.npm prefix, as for other questions it seems unclear:

Do we want to just haxelib install/haxelib git this lib and make all externs available to users?

Pros:

• easy to get started
• no need to manage classpaths (especially for npm dependencies, which npm modules tend to have A LOT)

Cons:

• source source root gets messy (though strict naming convention, like we have for hxnodejs helps a bit)
• no easy way to use different versions of a lib
• no lib defines

The bit about different using versions could be solved by what @clemos suggests (using js.npm.express.Express, but IMO it gets ugly for complex modules (e.g. js.npm.express.express.Request, following our naming scheme).

---

OTOH we could go the DefinitelyTyped way and just provide a repo with externs for users to simply add -cp and use concrete lib.

Pros:

• easy to manage multiple lib versions
• better separation of extern libs
• extern authors can add non-src files such as tests, examples and READMEs (which I'd personally really love to do for my externs)

Cons:

• SLIGHTLY harder to get started
• user required to manage classpaths which can get annoying when using a lot of npm modules
• still no lib defines

---

What I'm thinking about is a bit more complex solution that gives us both from two worlds:

• place externs in a separate directory within this repo, along with tests, readmes and stuff, e.g.

hxnodelibs
|--cookie
|  |--src
|  |--examples
|  |--test.hxml
|  \--README
|
|--express
|  |--src
|  |--tests
|  \--test.hxml
|
\--etc...

• maintain some json file to manage those library classpaths, defines and maybe tests, docgen (for travis)

[
  {
    name: "express", // this is name of the top library dir
    version: "1.0", // this is version that we're compatible with
    depends: ["cookie", /* etc... */] // other externs we want to add to classpaths along with this
    classpath: "src",
    test: "test.hxml" // this can be used by travis to build/run tests for a lib
  },
  {
    // etc...
  }
]

• have a macro that one can pass an extern name and have all required class paths added and defines defined (so for example --macro Hxnodelibs.use("express") would add express/src and cookie/src to classpaths as well as add defines for those libs, e.g. express-1.0 from the json above)

Pros:

• classpaths are managed automatically and user can select what they want to use precisely
• easy to have several versions of extern lib (just name it e.g. express1, express2, etc.)
• extern defs are separated from each other, allowing extra files for concrete externs
• automatic defines for extern libs

Cons:

• a bit harder to get started (tho I think it's still very easy if we have a nice short README)
• more complex to manage the whole collection (the json, macros, etc)

[clemos]

@nadako
IMHO what you describe should be implemented in haxelib.
If it's haxelib, then I agree it could be nice to implement some kind of "package bundle" feature that would allow such thing as -lib hxnodelibs/express#2.0 or similar.

Also, about js.npm.express.Express, other classes in the package could simply be js.npm.express.Request. Just the js.npm.express.Express class would be, by convention, the package "entry point" (require('express')).
Then mongoose could be a bit tricky (see https://github.com/clemos/haxe-js-kit/blob/master/js/npm/Mongoose.hx) because require('mongoose') returns a default instance of a require('mongoose').Mongoose object... If we follow the convention I propose, it would be js.npm.mongoose.Mongoose.mongoose (!!!).
Mongoose is a pretty convoluted example, and I think we'd better remove support for using require('mongoose') alone as a singleton, because IMHO it's a bad pattern anyway...

[nadako]

If it's haxelib, then I agree it could be nice to implement some kind of "package bundle" feature that would allow such thing as -lib hxnodelibs/express#2.0 or similar.

That is an interesting idea for the haxelib! cc @back2dos

Unfortunately, the example such as mongoose one you mentioned is quite common in nodejs world, for example the popular request module also contain exports.Request which is a class inside this module, so I'd better stick to strict structure we invented for hxnodejs.

Let's (for now) keep it simple and just use a single source root following the hxnodejs packaging convention (like in haxe-js-kit) and hear more opinions on this meanwhile.

[eduardo-costa]

I think too, that a single package name is better for now.
So situations like:

js.npm.a.b.c

should be treated as only

js.npm.a
Em 10/11/2015 11:15, "Dan Korostelev" notifications@github.com escreveu:

If it's haxelib, then I agree it could be nice to implement some kind of
"package bundle" feature that would allow such thing as -lib
hxnodelibs/express#2.0 or similar.
That is an interesting idea for the haxelib! cc @back2dos
https://github.com/back2dos

Unfortunately, the example such as mongoose one you mentioned is quite
common in nodejs world, for example the popular request module also
contain exports.Request which is a class inside this module, so I'd
better stick to strict structure we invented for hxnodejs.

Let's (for now) keep it simple and just use a single source root following
the hxnodejs packaging convention (like in haxe-js-kit) and hear more
opinions on this meanwhile.

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

[back2dos]

I'd like to propose that npm might be a better place than haxelib to distribute haxe code that is npm specific. Maybe it's just a crazy idea. I haven't thought through the technical details, but I think down the line it will probably make for a more natural workflow. As for putting everything into one repo: I think it won't scale. It just feels wrong that the way to get mkdirp externs is by installing express and react and what not along with it. If (as Nicolas said) having separate repos is less hard to manage, then there's nothing in the way of having separate repos and then just one hxnodelibs haxelib that adds the rest as dependencies (or do that with npm).​ The main reason for keeping these different projects separate is versioning. What if there's a new major release of express? Will hxnodelibs adapt and screw everyone who can't upgrade? Or will it stick to the older version and be useless to all those who want to switch to the new version? I'm pretty certain that after the io.js merge we're in for quite a few major releases in the next year or two.

[nadako]

As for putting everything into one repo: I think it won't scale. It just
feels wrong that the way to get mkdirp externs is by installing express and
react and what not along with it. If (as Nicolas said) having separate
repos is less hard to manage, then there's nothing in the way of having
separate repos and then just one hxnodelibs haxelib that adds the rest as
dependencies (or do that with npm).​

The main reason for keeping these different projects separate is
versioning. What if there's a new major release of express? Will hxnodelibs
adapt and screw everyone who can't upgrade? Or will it stick to the older
version and be useless to all those who want to switch to the new version?
I'm pretty certain that after the io.js merge we're in for quite a few
major releases in the next year or two.

These are very valid points. I personally have nothing against multiple-repo scenario, since I really would like to properly support my externs with examples and travis compile-testing. One thing I'm not sure whether it should be done using HaxeFoundation github account, maybe a separate one would be better.

[eduardo-costa]

Maybe a HaxeNodeFoundation :D

Doesn't Git have a submodules feature?
So the npm libs repositories would be submodules of hxnodelibs.

But I liked the idea of maybe creating another account or organization to
curate externs of NodeJS libs

2015-11-10 14:43 GMT-02:00 Dan Korostelev notifications@github.com:

As for putting everything into one repo: I think it won't scale. It just
feels wrong that the way to get mkdirp externs is by installing express and
react and what not along with it. If (as Nicolas said) having separate
repos is less hard to manage, then there's nothing in the way of having
separate repos and then just one hxnodelibs haxelib that adds the rest as
dependencies (or do that with npm).​

The main reason for keeping these different projects separate is
versioning. What if there's a new major release of express? Will hxnodelibs
adapt and screw everyone who can't upgrade? Or will it stick to the older
version and be useless to all those who want to switch to the new version?
I'm pretty certain that after the io.js merge we're in for quite a few
major releases in the next year or two.

These are very valid points. I personally have nothing against
multiple-repo scenario, since I really would like to properly support my
externs with examples and travis compile-testing. One thing I'm not sure
whether it should be done using HaxeFoundation github account, maybe a
separate one would be better.

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

[image: Imagem inline 1]

[nadako]

I've made an example extern lib for the popular commander module to illustrate what I consider quality extern lib: https://github.com/nadako/hxnodejs-commander.

[eduardo-costa]

@nadako
I liked it!
I just think that we should keep things inside their folder to avoid polluting the js/npm folder itself

[back2dos]

Yep, that's nice. Personally, I think it's ok if the facade is at the same level as the package. Short names are good ;)