Skip to content

Commit

Permalink
README: Clarify about relational-pouch's id vs. Pouch's _id (#137)
Browse files Browse the repository at this point in the history
README: Clarify about relational-pouch's `id` vs. Pouch's `_id`
  • Loading branch information
floer32 committed Jun 17, 2023
1 parent c212d67 commit 65286bb
Showing 1 changed file with 12 additions and 4 deletions.
16 changes: 12 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,8 @@ You can define one-to-one, one-to-many, and many-to-many relationships using any

You need to explicitly define the singular and plural forms of your entities, because I'm not a big fan of applying magic Anglocentric defaults to everything.

#### `db.rel.<method>`

Once you call `setSchema`, your `db` will be blessed with a `rel` object, which is where you can start using the rest of this plugin's API.

#### documentType
Expand Down Expand Up @@ -197,7 +199,7 @@ Result:
}
```

If you want, you can specify an `id`. Otherwise an `id` will be created for you.
You can optionally specify an `id`, otherwise `relational-pouch` will create an `id` for you. (What's the difference between `id` and `_id`? See below.)

```js
db.rel.save('post', {
Expand All @@ -218,7 +220,13 @@ Result:

You'll notice the special field `rev`, which is a revision identifier. That'll come into play later.

`id` and `rev` are reserved fields when you use this plugin. You shouldn't try to use them for something else. An `id` can be any string or integer.
#### `id` and `rev` are reserved field names!

This plugin uses `id` and `rev`. You shouldn't use those fields for anything else. An `id` can be any string or integer.

#### `id` vs `_id`

[`id` belongs to `relational-pouch`](https://github.com/pouchdb-community/relational-pouch#how-does-it-work), whereas [`_id`](https://docs.couchdb.org/en/latest/best-practices/documents.html) belongs to PouchDB/PouchDB. `relational-pouch` uses `id` for references to related records. You _can_ put the same value for `id` as `_id`, but if one is autogenerated you might want to autogenerate the other, too. Use-cases vary so do what works for you! See also: `db.rel.parseDocID` and `db.rel.makeDocID`, covered in this README below.

### db.rel.find(type)

Expand Down Expand Up @@ -1098,7 +1106,7 @@ How does it work?
A relational Pouch/Couch is just a regular database that has been partitioned by type.
So for instance, a document with type `"pokemon"` and id `"1"` might have an actual `_id` like `"pokemon_1"`, whereas a `"trainer"` with id `"2"` might have an actual `_id` like `"trainer_2"`. It's not rocket science.
So for instance, a document with type `"pokemon"` and id `"1"` might have an actual `_id` like `"pokemon_1"`, whereas a `"trainer"` with id `"2"` might have an actual `_id` like `"trainer_2"`. Simple, but effective.
What is important is that this plugin leverages the very efficient `allDocs()` API, rather than the slower `query()` API. Also, it joins related documents by simply making extra requests, rather than using native map/reduce joined documents. And it's smart enough to group the requests, so the data is fetched in the fewest posisble number of requests.
Expand Down Expand Up @@ -1161,4 +1169,4 @@ This will run the tests automatically and the process will exit with a 0 or a 1
```
- This library now uses Typescript, Webpack and Babel in its build setup. The build creates files in 2 output directories: lib and dist.
- The lib directory will contain the output of `tsc` in esnext mode. So this can be used by Webpack and other module aware systems. These will require Babel transformations if you want to use them, but this way you can specify your own target.
- The dist directory contains 2 files, pouchdb.relational-pouch.browser.js and pouchdb.relational-pouch.node.js. These are compiled by webpack with targets ">2%, not ie 11" and "node 10". This should be sufficient for now, but otherwise you can build your own with Webpack.
- The dist directory contains 2 files, pouchdb.relational-pouch.browser.js and pouchdb.relational-pouch.node.js. These are compiled by webpack with targets ">2%, not ie 11" and "node 10". This should be sufficient for now, but otherwise you can build your own with Webpack.

0 comments on commit 65286bb

Please sign in to comment.