Clarification of documentation for hasAndBelongsToMany

[Overdrivr]

Documentation for HasAndBelongsToMany relations is a bit confusing, and seems also outdated.

First, documentation starts by

A hasAndBelongsToMany relation creates a direct many-to-many connection with another model, with no intervening model.

Then, the schematic shows three different models, two related together and the last one seems a through model. It seems contradictory with the "no intervening model" statement.

Then, quick typo

For example, here is an excerpt from a model JSON

It may be intended but JSON examples are given for a student model, which is unrelated to the schematic above.

Then, after reading #226, is the following paragraph still valid ?

Adding a relation via REST API
When adding relation through the REST API, a join model must exist before adding relations.
For Example in the above example with "Assembly" and "Part" models, to add an instance of "Part" >to "Assembly" through the REST API interface an "AssemblyPart" model must exist for it to work.

I tried this morning and I was able to add relations without creating a "join" model. I'm not entirely sure but I believe this is deprecated.

Just thought of sharing some feedback.

[jannyHou]

Thank you @Overdrivr, the description is not accurate, hasAndBelongsToMany has no explicit intervening model and it will create an intervening model implicitly if not present, please check relation definition here to see more details.

---

excerpt is not a typo since it's just part of the whole .json file :)
And I think it makes sense to keep example consistent with UML above and tutorial "Adding a relation via REST API" below.
In /common/models/assembly.json:

{
  "name": "Assembly",
  "plural": "Assemblies",
  "relations": {
    "parts": {
      "type": "hasAndBelongsToMany",
      "model": "Part"
    },

and in /common/models/assembly.js:

Part.hasAndBelongsToMany(Assembly);
Assembly.hasAndBelongsToMany(Part);

Any thoughts about the change here @crandmck ? Thank you!

---

I am afraid the join model still need to be existed, I create a sandbox to test it:
https://github.com/jannyHou/loopback-sandbox/tree/has-and-belongs-to-many
Space hasAndBelongsToMany Customer
if the join model spaceCustomer removed, user cannot add relation by space.customers.add(customer, function(err) { // Your code });

[crandmck]

@jannyHou Your suggested change looks fine. Please go ahead and edit it yourself. Thanks!

[jannyHou]

I am closing it since changes are applied, thanks!
https://docs.strongloop.com/display/public/LB/HasAndBelongsToMany+relations#HasAndBelongsToManyrelations-DefiningahasAndBelongsToManyrelation

[Overdrivr]

@jannyHou Thank you for the changes

Here is some feedback, sorry I haven't provided it earlier.
A hasAndBelongsToMany relation creates a direct many-to-many connection with another model, *with no intervening model.*
is contradictory with
When adding relation through the REST API, *a join model must exist* before adding relations.
As a user, I don't understand if I must or not create a join model, or if it's automatically managed by loopback.

Also, I disagree further with you regarding this join model. Using the REST API through the explorer
with this config https://github.com/Overdrivr/sandbox-hasAndBelongToMany
POST api\spaces
POST api\customers
PUT api\spaces\1\customers\rel\1
This effectively creates the relation without me having to create any join model. I believe it is not calling space.customer.add but instead space.customer.link

And also,
POST api\spaces
POST api\spaces\1\customers
also works just fine. I am not sure it is calling space.customers.add however it does creates a new customer and attachs it to space instance, which is pretty much what add does.

Could try my repo and see if you get the same results ?

[jannyHou]

@Overdrivr that's fine. thanks for your feedback, I am reopening it and I will retest it ASAP.

[jannyHou]

@Overdrivr you are right, this line means loopback will create an intervening model implicitly.
I run into error with .add() because I defined "through": "spaceCustomer" in relation in space.json.

Function space.customers.add() is defined here:
https://github.com/strongloop/loopback-datasource-juggler/blob/master/lib/relation-definition.js#L1555-L1561
But I cannot find function space.customers.link(), I will update the doc after confirming more details.
And finally the answer is, an existed intervening model is not required, but you need to create one if you want to add properties/remote methods/etc.. to it.