json-rest-api 1.0.28 → 2.0.0

package/docs/GUIDE/05-belongs-to.md

@@ -0,0 +1,177 @@
+---
+title: "Belongs-to relationships"
+chapter: 5
+chapter_label: "05"
+---
+
+# 05. Belongs-to relationships
+
+A publisher belongs to a country. In table-backed storage, the publisher holds
+the foreign key; several publishers can reference the same country. Use the
+[starting script](03-running-example.md), and insert the JavaScript
+blocks below in order before the server starts. Start with a fresh database.
+
+## Define resources and create records
+
+```javascript
+await api.addResource('countries', {
+  schema: {
+    name: { type: 'string', required: true, max: 100 },
+    code: { type: 'string', max: 2, unique: true, indexed: true }
+  }
+})
+await api.addResource('publishers', {
+  schema: {
+    name: { type: 'string', required: true, max: 255 },
+    country_id: { type: 'id', belongsTo: 'countries', as: 'country', nullable: true }
+  },
+  searchSchema: {
+    country: { type: 'id', actualField: 'country_id', nullable: true },
+    countryCode: { type: 'string', actualField: 'countries.code' }
+  }
+})
+await api.resources.countries.createKnexTable()
+await api.resources.publishers.createKnexTable()
+
+const france = await api.resources.countries.post({
+  data: { name: 'France', code: 'FR' }
+})
+const uk = await api.resources.countries.post({
+  data: { name: 'United Kingdom', code: 'GB' }
+})
+const frenchPublisher = await api.resources.publishers.post({
+  data: { name: 'French Books Inc.', country: france.id }
+})
+await api.resources.publishers.post({
+  data: { name: 'Another French Publisher', country: france.id }
+})
+const britishPublisher = await api.resources.publishers.post({
+  data: { name: 'UK Books Ltd.', country: uk.id }
+})
+await api.resources.publishers.post({
+  data: { name: 'Global Publishing', country: null }
+})
+```
+
+Plain writes use the relationship alias `country` inside `data`.
+Do not supply the foreign-key field `country_id` as a public relationship input.
+Without an include, the plain response contains `country: { id: france.id }`;
+an unassigned to-one relationship is omitted from plain output. JSON:API
+represents its linkage with `data: null`.
+
+`country_id` is the logical schema field. Its physical column can differ with
+storage configuration. Hooks must follow their stage's context contract instead
+of assuming that logical relationship fields are already SQL columns.
+
+## Include related records
+
+```javascript
+const includedPublisher = await api.resources.publishers.get({
+  id: frenchPublisher.id,
+  queryParams: { include: ['country'] }
+})
+console.log('Included country:', includedPublisher.country)
+
+const plainCollection = await api.resources.publishers.query({
+  queryParams: { include: ['country'], sort: ['id'] }
+})
+console.log('Publishers:', plainCollection.data)
+
+const jsonapiCollection = await api.resources.publishers.query({
+  format: 'jsonapi',
+  queryParams: { include: ['country'], sort: ['id'] }
+})
+console.log('JSON:API collection:', jsonapiCollection)
+```
+
+`includedPublisher.country.name` is `France`. Plain collections still have a
+`data` array; included records are embedded into their corresponding parent
+objects. JSON:API collections put related records in `included` and keep
+identifiers under each primary record's `relationships.country.data`. The two
+French publishers share one France entry in that document's `included` array.
+The unassigned publisher retains null linkage.
+
+## Select sparse fields
+
+```javascript
+const sparsePublisher = await api.resources.publishers.get({
+  id: frenchPublisher.id,
+  queryParams: {
+    include: ['country'],
+    fields: { publishers: 'name,country', countries: 'code' }
+  }
+})
+console.log('Sparse country:', sparsePublisher.country)
+```
+
+Include the `country` relationship in the publisher's fieldset when its linkage
+must appear. The related country has its ID and code `FR`, without its name.
+Sparse fields select output; they are not an authorization policy.
+
+## Filter by a relationship
+
+```javascript
+const fromFrance = await api.resources.publishers.query({
+  queryParams: { filters: { country: france.id } }
+})
+const fromUK = await api.resources.publishers.query({
+  queryParams: { filters: { countryCode: 'GB' } }
+})
+const unassigned = await api.resources.publishers.query({
+  queryParams: { filters: { country: null } }
+})
+console.log('French publishers:', fromFrance.data)
+console.log('British publishers:', fromUK.data)
+console.log('Unassigned publishers:', unassigned.data)
+```
+
+The declared `country` filter selects two French publishers, `countryCode`
+selects UK Books Ltd., and null selects Global Publishing. `actualField` maps
+these public filter names to the ID field or the related resource's code.
+Cross-table filtering requires the related code field to declare `indexed: true`.
+Filtering does not automatically include the related record's attributes.
+
+## Change or clear the relationship
+
+```javascript
+await api.resources.publishers.patch({
+  id: britishPublisher.id,
+  data: { country: france.id },
+  returning: 'none'
+})
+await api.resources.publishers.patchRelationship({
+  id: britishPublisher.id,
+  relationshipName: 'country',
+  relationshipData: null
+})
+const cleared = await api.resources.publishers.getRelationship({
+  id: britishPublisher.id, relationshipName: 'country'
+})
+console.log('Cleared linkage:', cleared.data)
+```
+
+PATCH can update an attribute and relationship in the same record operation.
+`patchRelationship` takes linkage in `relationshipData`, changes only the named
+relationship and returns undefined.
+Clearing it requires the relationship to allow null. The example ends with
+`cleared.data === null`; linkage reads return a JSON:API linkage document.
+
+## HTTP calls
+
+Generated routes use JSON:API. With the server running and the example's fresh
+records, these read commands exercise includes, fieldsets and related filtering.
+Use the IDs returned by your server for a persistent database.
+
+```bash
+curl --globoff 'http://localhost:3000/api/publishers/1?include=country'
+curl --globoff 'http://localhost:3000/api/publishers?include=country&fields[publishers]=name,country&fields[countries]=code'
+curl --globoff 'http://localhost:3000/api/publishers?filter[countryCode]=FR'
+
+curl -X PATCH http://localhost:3000/api/publishers/1/relationships/country \
+  -H 'Content-Type: application/vnd.api+json' \
+  -d '{"data":{"type":"countries","id":"2"}}'
+```
+
+The relationship endpoint body is a linkage document, distinct from a resource
+PATCH body with `data.type`, `data.id` and `data.relationships`. See the
+[API reference](../API.md) for both forms and their error/transaction contracts.

package/docs/GUIDE/06-has-many.md

@@ -0,0 +1,184 @@
+---
+title: "Has-many relationships"
+chapter: 6
+chapter_label: "06"
+---
+
+# 06. Has-many relationships
+
+A publisher has many authors; each author belongs to one publisher. The
+`hasMany` declaration points to the logical foreign-key field on the child.
+It does not store an array of IDs in the publisher's table.
+
+Insert these blocks in order into the [starting script](03-running-example.md)
+on a fresh database, before the HTTP server starts.
+
+## Define and populate the resources
+
+```javascript
+await api.addResource('publishers', {
+  schema: { name: { type: 'string', required: true, indexed: true } },
+  relationships: {
+    authors: { type: 'hasMany', target: 'authors', foreignKey: 'publisher_id' }
+  },
+  searchSchema: {
+    authorSurname: { type: 'string', actualField: 'authors.surname', filterOperator: 'startsWith' }
+  }
+})
+await api.addResource('authors', {
+  schema: {
+    name: { type: 'string', required: true },
+    surname: { type: 'string', required: true, indexed: true },
+    publisher_id: { type: 'id', belongsTo: 'publishers', as: 'publisher', nullable: true }
+  },
+  searchSchema: {
+    publisherName: { type: 'string', actualField: 'publishers.name', filterOperator: 'contains' }
+  }
+})
+await api.resources.publishers.createKnexTable()
+await api.resources.authors.createKnexTable()
+
+const frenchPublisher = await api.resources.publishers.post({
+  data: { name: 'French Books Inc.' }
+})
+const germanPublisher = await api.resources.publishers.post({
+  data: { name: 'German Press GmbH' }
+})
+const emptyPublisher = await api.resources.publishers.post({
+  data: { name: 'Global Publishing' }
+})
+const victor = await api.resources.authors.post({
+  data: { name: 'Victor', surname: 'Hugo', publisher: frenchPublisher.id }
+})
+const emile = await api.resources.authors.post({
+  data: { name: 'Émile', surname: 'Zola', publisher: frenchPublisher.id }
+})
+await api.resources.authors.post({
+  data: { name: 'Johann', surname: 'Goethe', publisher: germanPublisher.id }
+})
+const unassigned = await api.resources.authors.post({
+  data: { name: 'Unknown', surname: 'Author', publisher: null }
+})
+```
+
+Link children through the public `publisher` alias in `data`, not the
+foreign-key field name. Declaring the inverse `belongsTo` also gives authors
+a public relationship representation. Cross-table filter targets explicitly
+declare `indexed: true`.
+
+## Read linkage and include child records
+
+```javascript
+const identifiers = await api.resources.publishers.get({ id: frenchPublisher.id })
+const embedded = await api.resources.publishers.get({
+  id: frenchPublisher.id,
+  queryParams: { include: ['authors'] }
+})
+const document = await api.resources.publishers.get({
+  id: frenchPublisher.id,
+  format: 'jsonapi',
+  queryParams: { include: ['authors'] }
+})
+const empty = await api.resources.publishers.get({ id: emptyPublisher.id })
+console.log('Author identifiers:', identifiers.authors)
+console.log('Included authors:', embedded.authors)
+console.log('JSON:API document:', document)
+console.log('Empty relationship:', empty.authors)
+```
+
+Without includes, plain `authors` contains `{ id }` objects for Victor and Émile.
+With includes it contains their selected attributes too. JSON:API retains
+identifier linkage in `data.relationships.authors.data` and puts full child
+records in `included`. An empty to-many relationship is an empty array.
+Discovering child identifiers has a query cost even without fetching attributes.
+
+## Page related records and select fields
+
+```javascript
+const firstAuthorPage = await api.resources.publishers.getRelated({
+  id: frenchPublisher.id,
+  relationshipName: 'authors',
+  queryParams: { sort: ['surname'], page: { number: 1, size: 1 } }
+})
+const sparse = await api.resources.publishers.get({
+  id: frenchPublisher.id,
+  queryParams: {
+    include: ['authors'],
+    fields: { publishers: 'name,authors', authors: 'surname' }
+  }
+})
+console.log('First related page:', firstAuthorPage)
+console.log('Sparse authors:', sparse.authors)
+```
+
+The first related page contains Hugo and has `meta.pagination.total === 2`.
+`getRelated` returns a collection for a to-many relationship. Its page options
+apply to children; page options on a publisher query apply to publishers.
+The sparse include keeps author IDs and surnames and omits their names. Keep
+`authors` in the parent fieldset when you need its linkage in the response.
+
+## Filter in either direction
+
+```javascript
+const matchingPublishers = await api.resources.publishers.query({
+  queryParams: { filters: { authorSurname: 'Hu' } }
+})
+const matchingAuthors = await api.resources.authors.query({
+  queryParams: { filters: { publisherName: 'German' } }
+})
+console.log('Publishers with a matching author:', matchingPublishers.data)
+console.log('Authors with a matching publisher:', matchingAuthors.data)
+```
+
+These return French Books Inc. and Johann respectively. The server's search
+schema declares allowed paths and operators. Filtering parents by matching
+children does not itself request an include or restrict an included collection
+to only those matching children.
+
+## Change membership
+
+```javascript
+await api.resources.publishers.postRelationship({
+  id: frenchPublisher.id,
+  relationshipName: 'authors',
+  relationshipData: [{ type: 'authors', id: unassigned.id }]
+})
+await api.resources.publishers.deleteRelationship({
+  id: frenchPublisher.id,
+  relationshipName: 'authors',
+  relationshipData: [{ type: 'authors', id: victor.id }]
+})
+await api.resources.publishers.patch({
+  id: frenchPublisher.id,
+  data: { authors: [emile.id] },
+  returning: 'none'
+})
+const finalLinkage = await api.resources.publishers.getRelationship({
+  id: frenchPublisher.id, relationshipName: 'authors'
+})
+const detachedVictor = await api.resources.authors.get({ id: victor.id })
+console.log('Final members:', finalLinkage.data)
+console.log('Detached author still exists:', detachedVictor.name)
+```
+
+POST relationship adds an existing child, DELETE relationship removes specified
+membership, and the parent PATCH replaces the collection with the supplied IDs.
+The final member is Émile. Removing membership does not delete the author:
+Victor remains, with no publisher. Detaching children requires their relationship
+to allow null; required relationships cannot be cleared this way. Relationship
+writes use `relationshipData` and return undefined. Resource writes put their
+record, including any relationships, under `data`.
+
+## HTTP examples
+
+After the full example above, the French publisher has only Émile:
+
+```bash
+curl --globoff 'http://localhost:3000/api/publishers/1?include=authors'
+curl --globoff 'http://localhost:3000/api/publishers/1/authors?page[number]=1&page[size]=10'
+curl 'http://localhost:3000/api/publishers/1/relationships/authors'
+```
+
+The related endpoint returns author resources; the relationship endpoint returns
+linkage. Generated HTTP routes use JSON:API documents. Use IDs from your server
+when working with a persistent database.

package/docs/GUIDE/07-polymorphic-relationships.md

@@ -0,0 +1,191 @@
+---
+title: "Polymorphic relationships"
+chapter: 7
+chapter_label: "07"
+---
+
+# 07. Polymorphic relationships
+
+A review can belong to a publisher or an author. Its relationship identity has
+two parts: the resource type and ID. A publisher and an author can share an ID
+without sharing reviews.
+
+The child declares `belongsToPolymorphic` with allowed target types and the two
+logical storage fields. Each parent declares a reverse `hasMany` with `via`
+pointing to that child relationship. Insert these blocks in order into the
+[starting script](03-running-example.md), using a fresh database.
+
+## Define the relationships and filters
+
+```javascript
+await api.addResource('publishers', {
+  schema: { name: { type: 'string', required: true, indexed: true } },
+  relationships: { reviews: { type: 'hasMany', target: 'reviews', via: 'reviewable' } },
+  searchSchema: {
+    reviewComment: { type: 'string', actualField: 'reviews.comment', filterOperator: 'contains' }
+  }
+})
+await api.addResource('authors', {
+  schema: { name: { type: 'string', required: true, indexed: true } },
+  relationships: { reviews: { type: 'hasMany', target: 'reviews', via: 'reviewable' } },
+  searchSchema: {
+    reviewComment: { type: 'string', actualField: 'reviews.comment', filterOperator: 'contains' }
+  }
+})
+await api.addResource('reviews', {
+  schema: {
+    rating: { type: 'number', required: true, min: 1, max: 5 },
+    comment: { type: 'string', required: true, indexed: true },
+    reviewable_type: { type: 'string', required: true },
+    reviewable_id: { type: 'id', required: true }
+  },
+  relationships: {
+    reviewable: {
+      belongsToPolymorphic: {
+        types: ['publishers', 'authors'],
+        typeField: 'reviewable_type',
+        idField: 'reviewable_id'
+      }
+    }
+  },
+  searchSchema: {
+    reviewableName: {
+      type: 'string',
+      polymorphicField: 'reviewable',
+      targetFields: { publishers: 'name', authors: 'name' },
+      filterOperator: 'contains'
+    }
+  }
+})
+await api.resources.publishers.createKnexTable()
+await api.resources.authors.createKnexTable()
+await api.resources.reviews.createKnexTable()
+```
+
+Target name and review comment fields declare `indexed: true` for cross-table
+filtering. `reviewableName` explicitly maps each allowed target type to its
+search field. The two reverse `reviewComment` filters search only reviews of
+the corresponding parent type.
+
+## Write plain records and JSON:API documents
+
+```javascript
+const publisher = await api.resources.publishers.post({
+  data: { id: '1', name: 'French Books' }
+})
+const author = await api.resources.authors.post({
+  data: { id: '1', name: 'Victor Hugo' }
+})
+const publisherReview = await api.resources.reviews.post({
+  data: {
+    rating: 4, comment: 'Reliable publisher',
+    reviewable: { _type: 'publishers', id: publisher.id }
+  }
+})
+const authorReviewDocument = await api.resources.reviews.post({
+  format: 'jsonapi',
+  document: {
+    data: {
+      type: 'reviews',
+      attributes: { rating: 5, comment: 'Excellent author' },
+      relationships: {
+        reviewable: { data: { type: 'authors', id: author.id } }
+      }
+    }
+  }
+})
+```
+
+Plain polymorphic input uses `{ _type, id }` under the relationship alias.
+JSON:API uses `{ type, id }` under `data.relationships.reviewable.data`.
+Do not write `reviewable_type` or `reviewable_id` as public attributes. Those
+logical fields describe storage; the public relationship represents them together.
+Plain output uses `_type` to identify the related resource type as well.
+
+## Include either direction
+
+```javascript
+const publisherWithReviews = await api.resources.publishers.get({
+  id: publisher.id, queryParams: { include: ['reviews'] }
+})
+const authorWithReviews = await api.resources.authors.get({
+  id: author.id, queryParams: { include: ['reviews'] }
+})
+const reviewsWithTargets = await api.resources.reviews.query({
+  queryParams: { include: ['reviewable'], sort: ['id'] }
+})
+const reviewDocument = await api.resources.reviews.query({
+  format: 'jsonapi',
+  queryParams: { include: ['reviewable'], sort: ['id'] }
+})
+console.log('Publisher reviews:', publisherWithReviews.reviews)
+console.log('Author reviews:', authorWithReviews.reviews)
+console.log('Embedded targets:', reviewsWithTargets.data)
+console.log('JSON:API targets:', reviewDocument.included)
+```
+
+Each parent has exactly its own review, despite both having ID `1`. Plain
+included targets contain `_type`, ID and selected attributes. The JSON:API
+`included` array contains both target resources, distinguished by `type` and
+`id`; it must not merge them merely because their IDs match.
+
+## Filter forward and backward
+
+```javascript
+const reviewsOfVictor = await api.resources.reviews.query({
+  queryParams: { filters: { reviewableName: 'Victor' } }
+})
+const reliablePublishers = await api.resources.publishers.query({
+  queryParams: { filters: { reviewComment: 'Reliable' } }
+})
+const reliableAuthors = await api.resources.authors.query({
+  queryParams: { filters: { reviewComment: 'Reliable' } }
+})
+console.log('Reviews of Victor:', reviewsOfVictor.data)
+console.log('Reliable publishers:', reliablePublishers.data)
+console.log('Reliable authors:', reliableAuthors.data)
+```
+
+The forward filter finds the author review. The reverse filter finds French
+Books; the same filter on authors returns no records. These are declared search
+contracts, not arbitrary client-selected SQL paths. Filtering does not itself
+request included resource attributes.
+
+## Move a review to a different target type
+
+```javascript
+await api.resources.reviews.patchRelationship({
+  id: publisherReview.id,
+  relationshipName: 'reviewable',
+  relationshipData: { type: 'authors', id: author.id }
+})
+const publisherLinkage = await api.resources.publishers.getRelationship({
+  id: publisher.id, relationshipName: 'reviews'
+})
+const authorLinkage = await api.resources.authors.getRelationship({
+  id: author.id, relationshipName: 'reviews'
+})
+console.log('Publisher linkage after move:', publisherLinkage.data)
+console.log('Author linkage after move:', authorLinkage.data)
+```
+
+The target ID stays `1` but its type changes. The publisher then has no reviews,
+and the author has both. Relationship-only writes take `relationshipData` and
+return undefined. Because this schema makes the type and ID fields required,
+the relationship cannot be cleared to null. Use a nullable relationship design
+when reviews are allowed to remain unassigned.
+
+## HTTP representation
+
+For a server running the completed example, read either side with:
+
+```bash
+curl --globoff 'http://localhost:3000/api/authors/1?include=reviews'
+curl --globoff 'http://localhost:3000/api/reviews?include=reviewable'
+curl --globoff 'http://localhost:3000/api/reviews?filter[reviewableName]=Victor'
+```
+
+HTTP uses JSON:API type/ID linkage. To move a review, PATCH
+`/api/reviews/{id}/relationships/reviewable` with a body such as
+`{"data":{"type":"publishers","id":"1"}}` and content type
+`application/vnd.api+json`. Use returned IDs for an existing database.