Distinction between pact-node and pact-js isn't clear

I’m often confused about the purpose of pact-node vs pact-js - my current understanding (which may be wrong) is that:

• pact-node is meant as a wrapper for the binaries, exposing both a js API and the CLI
• pact-js is meant for the functionality built on top of the binaries (eg matchers and other helpers to make the experience of writing pact tests and using pact nicer).

I don’t think this is documented anywhere (and I’m not certain I have it right, either).

I’ve also seen one or two pact deployments where people had wrapped pact-node themselves, and rebuilt functionality that already exists in pact-js.

Currently I don’t believe the documentation for either library even mentions the other. I think it would be an improvement if the documentation communicated the distinction between the purpose of the two libraries, and clarified how they are expected to be used.

Thoughts? Perhaps a “do you want pact-js or pact-node” section?

[TimothyJones]

I really like @mefellows’s suggestion about having preamble in the different readmes. And, I also think “you probably don’t want to use pact-node directly” would solve the strange deployments I have seen.

Is some of the confusion to do with the naming? As in, if I’m writing a node app, it seems like I’d want pact-node, when the reality is that I probably want pact-js. Would pact-node be better named pact-binaries, or pact-bindings (or similar)?

[TimothyJones]

Honestly, I think we should rename pact-node.

I think no matter what the documentation says, people will (quite reasonably) be like “oh, but if I’m using node, I should just use this one, right?”

Another thing we could do is move most of the pact-node readme out to other markdown files, so that the readme is mostly the “you probably don’t want this” note, with links to the rest of the docs if you really need it.

To answer your question @webia1 , I think the current state is:

• pact-js is the front door to Pact, including interfaces, matchers and test writing DSL.
• pact-node is the core for pact, wrapping the core binaries, and exposing them as binstubs. It would be appropriate to think of pact-node as pact-internals or pact-cli

The two exist for historical reasons. We haven’t renamed pact-node because we’re looking at bringing in a different (closer to native) core to provide V3 pact specification features.

This might obviate the need for a separate package entirely, at which point maybe this becomes pact-cli, and just provides the binstubs. Maybe. It would be good to start a dialog with the users of javascript pact and find out what people are using.