json-rest-api 2.4.0 → 3.0.0

package/docs/GUIDE/17-row-policies.md

@@ -198,6 +198,7 @@ A policy receives one object:
 | `scopeName` | The resource currently being selected. For includes, this is the child resource. |
 | `tableName` | The table name or active query alias for this selection. |
 | `queryPurpose` | Why the selection is running; see the table below. |
+| `system` | `true` for a context made by `createSystemContext`. The policy decides whether system work sees every row. |
 | `db` | The active Knex connection or transaction. Use it to build subqueries. |
 | `isAnyApi` | `true` when the AnyAPI storage path is active. |
 | `column(field, options?)` | Translate and qualify a logical field. |
@@ -293,10 +294,17 @@ Policies are reused for the resource selections that define externally visible d
 | `relationship-identifiers` | Child identifiers attached to a relationship, including has-many and AnyAPI many-to-many links. |
 | `relationship-validation` | A batch of up to 100 distinct target IDs referenced by a write payload, or a scoped lookup retaining database ID equality. |
 | `relationship-parent` | The parent of a relationship route such as `getRelated`. |
+| `report` | A `scopedQuery()` builder with the default purpose. |
+| `bulk-write` | The visible ids a many-row patch or delete may change, and `scopedQuery({ purpose: 'bulk-write' })`. |
+| `lock` | The rows `lockByIds()` and `lockWhere()` lock, in the locking read itself. A policy that joins other tables is refused here, as for `claim`. |
+| `claim` | The candidate rows `claim()` takes. A policy that joins other tables is refused here, because the database would lock the joined rows too. |
 | `unspecified` | A custom call to the lower-level query-filtering seam did not provide a purpose. |
 
 The important invariant is not the label. It is that the predicate is attached before any limit, offset, cursor boundary, per-parent include limit, or count is evaluated.
 
+A row policy cannot see the row an upsert merges into, so `postMany` refuses
+`onConflict: { action: 'merge' }` on a resource with a row policy.
+
 Treat `queryPurpose` as diagnostic context, not as permission to weaken a policy. A policy should normally add the same visibility predicate for every purpose. If an advanced policy uses a purpose-specific SQL shape, each branch must enforce equivalent visibility and must be tested independently; never skip a predicate for counts, includes, identifiers, or relationship validation.
 
 Relationship identifier visibility is selected in batches of at most 100 unique
@@ -308,11 +316,13 @@ and include limits in their operation/resource settings. Visibility hooks add
 row predicates and retain the query's selected ID and mandatory constraints.
 Their invocation count is not a per-request or per-record contract.
 
-Regular and polymorphic belongs-to includes also load at most 100 target IDs
-per query, with target permission and filtering hooks applied to every batch
-under `queryPurpose: 'include'`. SQL projection callbacks run for each query.
-Nested collection includes run after all target batches have been collected,
-so a global collection limit is not restarted for each batch.
+Regular and polymorphic belongs-to includes load each target type's records
+in one query, however many there are, with target permission and filtering
+hooks applied under `queryPurpose: 'include'`. A long id list is bound as one
+parameter on PostgreSQL and SQLite, so it stays within their parameter limits;
+MySQL and MariaDB have none. SQL projection callbacks run for each query.
+Nested collection includes run after all targets have been collected, so a
+global collection limit applies to the complete set.
 
 Relationship validation uses the same batch bound. Its query context has no
 individual `id` and no parent client filters. Retain the selected ID and scope

package/docs/GUIDE/19-managed-transactions.md

@@ -47,9 +47,9 @@ cannot be replaced by a later successful empty COMMIT.
 ## Participation and failure
 
 Ordinary resource and relationship calls without a transaction use the same
-completion mechanism for their own transaction. Atomic bulk uses it for the
-whole batch. Calls receiving its transaction participate and never complete it
-individually. Non-atomic bulk with an outer transaction continues to reject.
+completion mechanism for their own transaction, and so do many-row writes for
+the whole call. Calls receiving its transaction participate and never complete
+it individually.
 
 The final contract requires library writes to use a library-owned transaction.
 Standalone transactions created with `knex.transaction()` remain usable for raw
@@ -85,8 +85,9 @@ retry just the failed statement inside an already failed unit.
 
 Each accepted resource/relationship operation enlists its existing completion
 hook chain once. This includes nested resource calls made by relationship
-implementation; helper-internal SQL does not create synthetic operations. Bulk
-or transaction owners do not also run a duplicate resource hook chain.
+implementation; helper-internal SQL does not create synthetic operations. A
+many-row write enlists one chain for the whole call. Transaction owners do not
+also run a duplicate resource hook chain.
 
 After confirmed commit, invoke enlisted `afterCommit` chains in enlistment
 order. After confirmed rollback, invoke `afterRollback` chains in reverse order.
@@ -99,8 +100,7 @@ set of outcome-dependent hooks.
 
 Enlistment happens when the library accepts an operation into the transaction.
 Overlapping operations can finish their writes in another order; that does not
-change completion-hook order. Internal finalizers, currently bulk diagnostic
-collection, run after those chains in registration order even when a chain or
+change completion-hook order. Internal finalizers run after those chains in registration order even when a chain or
 an earlier finalizer fails. They also collect diagnostics after unknown
 completion; they must not infer commit or run outcome-dependent side effects.
 The first post-commit failure remains primary across hooks and finalizers.
@@ -129,8 +129,7 @@ owner's error in its rollback context.
 
 File cleanup/tracking and Socket.IO delivery use these existing hooks. Uploaded
 files are cleaned only after confirmed rollback, and notifications run only
-after confirmed outer commit. Bulk diagnostics aggregate unresolved child state
-after finalization; the parent must not delete a child's files a second time.
+after confirmed outer commit.
 Tests cover repeated changes to the same resource, multiple uploads,
 callback/SQL failures and failing completion hooks. File-specific failures and
 unresolved upload tracking remain on each operation's context; rejected hook

package/docs/GUIDE/20-transaction-outcomes.md

@@ -6,9 +6,8 @@ chapter_label: "20"
 
 # 20. Transaction outcomes
 
-Resource, relationship, bulk and canonical registry write errors carry the
-outcome of the transaction they represent. HTTP and non-atomic bulk errors
-preserve that outcome. The states below describe the evidence available when
+Resource, relationship, many-row and canonical registry write errors carry the
+outcome of the transaction they represent. HTTP errors preserve that outcome. The states below describe the evidence available when
 the failure is reported.
 
 [Managed transactions](19-managed-transactions.md) explains ownership and
@@ -166,7 +165,7 @@ retained: for example, child pending and outer rolledBack. Existing code/subtype
 classification can usually remain at the outer error; code that checks original
 error identity or `instanceof` needs migration. HTTP mapping preserves status
 classification and adds `meta.transactionOutcome` to each JSON:API error.
-Non-atomic bulk entries expose `error.transactionOutcome` individually.
+A many-row write is one operation with one outcome for all its rows.
 
 ## Errors, batches and later observations
 

package/docs/GUIDE/21-schema-and-migrations.md

@@ -596,7 +596,13 @@ Current live introspection support:
 
 - SQLite
 - PostgreSQL via `pg` (verified on PostgreSQL 16)
-- MySQL via `mysql2` (verified on MySQL 8; this does not establish MariaDB coverage)
+- MySQL via `mysql2` (verified on MySQL 8)
+- MariaDB via `mysql2` (verified on MariaDB 11.4)
+
+MariaDB reports column defaults as SQL (a quoted literal, the word `NULL` for no
+default) and stores a `json` column as `longtext` with a `json_valid` column
+check; the snapshot reads both as MySQL's forms, so the JSON check is part of
+the column type and not a check constraint of its own.
 
 PostgreSQL inspection reads the current schema's
 [columns](https://www.postgresql.org/docs/16/infoschema-columns.html),

package/docs/GUIDE/22-version-field-migrations.md

@@ -41,7 +41,7 @@ It is not a hash of the complete response and is not an HTTP ETag.
 | Child creation, reparenting, detachment or deletion | Rotates affected configured has-many/has-one parent revisions, including declared polymorphic inverses. |
 | Child attribute change with unchanged membership | Does not rotate the parent's revision merely because included child attributes changed. |
 | Ordinary pivot-resource write | Invalidates affected configured parents when either membership key changes. Canonical through-resource records remain separate from canonical links. |
-| Bulk PATCH or DELETE | Applies the same rules per child. Optional `expectedVersions` must contain one token per input entry. |
+| Many-row writes | Refused with `REST_API_BULK_WRITE_UNSUPPORTED` on a versioned resource and on resources whose writes advance a version; use single writes. |
 | Transaction rollback | Restores revisions together with the associated writes and links. |
 
 Submit conditions through `expectedVersion`, not as an attribute update. Omitting
@@ -147,8 +147,8 @@ a current conditional PATCH succeeds, and a stale one returns
 `REST_API_VERSION_CONFLICT` without changing stored data. Test rollback before
 allowing writers to resume.
 
-Clients send `expectedVersion` alongside the single-write options, or aligned
-`expectedVersions` for bulk PATCH/DELETE. They must not submit the revision among
+Clients send `expectedVersion` alongside the single-write options. They must
+not submit the revision among
 the record attributes. A conflict requires fetching and reconciling the current
 record; blindly retrying with a newly fetched token can overwrite another
 client's edits. These tokens are not HTTP ETags.

package/docs/GUIDE/27-many-row-writes.md

@@ -0,0 +1,458 @@
+---
+title: "Many-row writes"
+chapter: 27
+chapter_label: "27"
+---
+
+# 27. Many-row writes
+
+Every table-storage resource has six methods that write many rows at once:
+
+| Method | Writes |
+| --- | --- |
+| `postMany({ data })` | one new record per entry |
+| `patchMany({ data: [{ id, ... }] })` | each entry's own changes to the record with that id |
+| `patchWhereIds({ ids, data })` | the same changes to every listed record |
+| `patchWhere({ filters, data })` | the same changes to every record the filters select (or `all: true`) |
+| `deleteMany({ ids })` | the listed records |
+| `deleteWhere({ filters })` | every record the filters select (or `all: true`) |
+
+Each call is all-or-nothing. Every row still goes through validation,
+ownership stamping (autofilter), setters, relationship checks and
+`checkPermissions`, but in memory; the database then sees one statement per
+chunk of rows, not one per row. A batch of 10 rows and a batch of 200 run the
+same number of statements. Use these methods for imports, mass updates and
+jobs; use the single-record methods when each write needs its own hooks.
+
+## Runnable example
+
+Insert the following four JavaScript blocks into the
+[starting script](03-running-example.md), after installing table storage and
+before declaring other resources, on a fresh database. Many-row writes need
+table storage (`RestApiKnexPlugin`); AnyAPI storage refuses them.
+
+```javascript
+await api.addResource('books', {
+  schema: {
+    title: { type: 'string', required: true, search: true },
+    isbn: { type: 'string', required: true },
+    stock: { type: 'integer', defaultTo: 0 }
+  },
+  indexes: [{ columns: ['isbn'], unique: true }]
+})
+await api.resources.books.createKnexTable()
+```
+
+```javascript
+const created = await api.resources.books.postMany({
+  data: [
+    { title: 'Alpha', isbn: '111', stock: 3 },
+    { title: 'Beta', isbn: '222', stock: 0 }
+  ],
+  format: 'plain',
+  returning: 'full'
+})
+const restocked = await api.resources.books.postMany({
+  data: [{ title: 'Alpha', isbn: '111', stock: 9 }, { title: 'Gamma', isbn: '333' }],
+  onConflict: { keys: ['isbn'], action: 'merge', merge: ['stock'] },
+  returning: 'minimal'
+})
+console.log(created.data, restocked.data)
+```
+
+Rows come back in input order. Many-row writes return nothing unless you ask:
+`returning: 'minimal'` gives identifiers, `returning: 'full'` the records,
+read back in the write's transaction, and `returning: 'count'` only
+`{ meta: { count } }`, the number of rows written, without reading any back.
+The second call is an upsert: Alpha's ISBN already exists, so its stock
+becomes 9, and Gamma is inserted.
+
+```javascript
+const [alpha, beta] = created.data
+const updated = await api.resources.books.patchMany({
+  data: [{ id: alpha.id, title: 'Alpha, 2nd edition' }, { id: beta.id, stock: 4 }],
+  returning: 'minimal'
+})
+const emptied = await api.resources.books.patchWhere({
+  filters: { title: 'Gamma' }, data: { stock: 0 }, returning: 'minimal'
+})
+console.log(updated.data, emptied.data)
+```
+
+`patchMany` takes one change set per id. `patchWhereIds` and `patchWhere` apply
+one change set to many records. `filters` are the resource's search filters,
+validated exactly as `query` validates them.
+
+```javascript
+let invalidRow
+try {
+  await api.resources.books.postMany({ data: [{ title: 'Delta', isbn: '444' }, { isbn: '555' }] })
+} catch (error) { invalidRow = error.cause ?? error }
+const deleted = await api.resources.books.deleteMany({ ids: [beta.id], returning: 'minimal' })
+const remaining = await api.resources.books.query({ format: 'plain' })
+console.log(invalidRow.details.index, deleted.data, remaining.data.map(book => book.title))
+```
+
+The second row has no title, so the batch writes nothing and the error names
+the row: `details.index` is 1 and the field paths start with `data.1.`. Delta
+is not stored. The delete removes Beta; Alpha, 2nd edition and Gamma remain.
+
+## Input
+
+`postMany` and `patchMany` take either plain records as `data: [...]` or
+JSON:API resource objects as `document: { data: [...] }`, never both. The
+`format` option selects only the output. `patchWhereIds` and `patchWhere` take
+one record: `data: { ... }` or `document: { data: { type, attributes } }`.
+
+```js
+await api.resources.books.postMany({
+  document: { data: [{ type: 'books', attributes: { title: 'Epsilon', isbn: '666' } }] }
+})
+```
+
+Rows may set belongs-to relationships. The library checks every target the
+batch names with one scoped read per related type, and locks them once for the
+batch with one statement per type, however many rows name them. Rows that set
+many-to-many or reverse (has-many) relationships are refused; change those
+links with single writes or the relationship methods.
+
+`patchMany`, `patchWhereIds` and `patchWhere` refuse:
+
+- the id;
+- autofilter (ownership) fields and the relationships that set them;
+- the resource's `lockVersionField`, which every update advances by itself.
+
+A row of a resource with a lock version may change no field at all: its UPDATE
+then only advances the version, which tells other writers' `onlyIf` the
+record has changed.
+
+They accept a `knex.raw(...)` value for a stored, non-relationship field, so a
+counter can move inside the statement:
+
+```js
+const knex = api.knex.instance
+await api.resources.books.patchWhereIds({
+  ids: ['1', '2'], data: { stock: knex.raw('?? + 1', ['stock']) }
+})
+```
+
+Only a real Knex raw value counts. An object that merely carries an
+`isRawInstance` flag, as JSON input can, is refused with a validation error, so
+the HTTP routes never pass SQL through. Batch hooks find the fields that raw
+values set in `context.rawFields`, and the file-field and positioning refusals
+below apply to them as well.
+
+Every row also goes through the resource's setters, and creates through
+`defaultTo` values and autofilter stamping, as single writes do. Rows may omit
+different fields. On SQLite, a field that some rows set and others omit is
+written as NULL for the rows that omit it, so a column default that the schema
+does not declare with `defaultTo` does not apply to them.
+
+## Options
+
+| Option | Methods | Default | Meaning |
+| --- | --- | --- | --- |
+| `returning` | all | `'none'` | `'minimal'` returns `{ data: [{ type, id }] }`; `'full'` (not for deletes) returns the records; `'count'` returns `{ meta: { count } }` |
+| `format` | writes | resource default | Output format of `'full'` records |
+| `queryParams` | writes | | `fields` and `include` of `'full'` records |
+| `transaction` | all | | A transaction from `api.transaction` to join |
+| `chunkSize` | all | 500 | Rows per statement, lowered further to the database's parameter limit |
+| `missing` | `patchMany`, `patchWhereIds`, `deleteMany` | `'throw'` | `'skip'` ignores ids the caller cannot see |
+| `onlyIf` | patches | | Compare-and-set: change only rows whose stored values equal these |
+| `all` | `patchWhere`, `deleteWhere` | | `true` acts on every row the caller can see; needed when there are no `filters` |
+| `onConflict` | `postMany` | | Upsert, below |
+
+Ids that do not exist or that the caller cannot see (another owner's rows,
+rows a row policy hides) throw `RestApiRecordsNotFoundError` (subtype
+`not_found`, HTTP 404) before anything is written. The error gives only a
+count, so it does not reveal which ids exist. With `missing: 'skip'` they are
+left out. A batch may not name the same id twice.
+
+With `missing: 'skip'`, `patchMany`, `patchWhereIds` and `deleteMany` read
+nothing first when the resource has no `checkPermissions` hook and no
+`beforeDataCallPatchMany` or `beforeDataCallDeleteMany` hook (those need the
+visible rows before the write), except on MySQL and MariaDB. The UPDATE or
+DELETE carries the caller's scope, row policy included, as a subquery, and its
+changed rows are the answer, returned with `RETURNING` on PostgreSQL and
+SQLite. MySQL and MariaDB keep the visibility read for ids from the caller:
+InnoDB would lock every listed row before checking the scope, rows the caller
+cannot see included, and hold those locks until commit. After that read, a
+statement of one row there runs the UPDATE with its ownership conditions and
+`onlyIf`, and its row count is the answer. A longer statement locks the rows
+that still match and then updates exactly those, and so does a one-row
+statement on a connection that disables the drivers' default `FOUND_ROWS`
+flag, where MySQL counts the rows an UPDATE changed rather than those it
+matched.
+
+`patchWhere` and `deleteWhere` are set operations. They read the ids of the
+rows their selection finds, then write those rows with the caller's scope and
+the filters inside every UPDATE or DELETE (on MySQL and MariaDB inside a locking
+read of the rows, followed by the write of exactly those). A row that another
+transaction deletes, moves out of the caller's scope or changes so that it no
+longer matches in the meantime is left out. The result lists the rows actually
+written, and the methods never throw `RestApiRecordsNotFoundError`; they take no
+`missing` option.
+
+The filters are checked on each row as it is once locked, so a selection write
+is a compare-and-set on them: of two transactions whose filters matched the
+same row, the one that waits for the other's lock finds the row the other
+committed, and leaves it out if it no longer matches. PostgreSQL locks the rows
+first, so the statement that writes them starts after the wait; MySQL and
+MariaDB check the scope and the filters in the locking read itself, which
+therefore also locks the rows it joins from other tables. With MariaDB's
+`innodb_snapshot_isolation` on, the waiting transaction fails instead ("Record
+has changed since last read", errno 1020); retry it. SQLite has one writer:
+the second transaction fails with `SQLITE_BUSY` rather than write over the
+first, or, if it starts after the first commits, finds the row the first
+committed.
+
+A filter on another table's field (a `searchSchema` field whose `actualField`
+names another table) is read through a derived table. PostgreSQL reads it
+again after the wait, so it too is a compare-and-set; InnoDB would read it from
+the snapshot without locking it, so on MySQL and MariaDB `patchWhere` and
+`deleteWhere` refuse filters whose scope joins a derived table (rule
+`selection_cross_table`), whatever rows they match. Filter on the row's own
+columns instead, for example on the link itself after locking its targets with
+`lockByIds` on their resource. A custom `applyFilter` that reads another table
+through its own subquery is not detected: MySQL and MariaDB read that subquery
+from the snapshot too, so it is no compare-and-set there.
+
+The UPDATE, DELETE and lock statements repeat the caller's ownership
+(autofilter) conditions as plain column predicates. A row that another
+transaction moves to a different owner between the visibility read and the
+write is therefore neither written nor locked, and counts as missing:
+`missing: 'throw'` rolls the batch back, `'skip'` leaves the row out of the
+result, and with `onlyIf` it is reported unchanged. Single `patch`, `put` and
+`delete`, on table and AnyAPI storage, do the same with their one scoped read:
+the UPDATE or DELETE carries the owner that read found, and a row that has gone
+or moved to another owner since answers `not_found`. The statement's own row
+count tells. A DELETE counts the rows it removed, and an UPDATE the rows it
+matched on PostgreSQL, SQLite and default MySQL connections. On a MySQL or
+MariaDB connection without `FOUND_ROWS`, an UPDATE that changes nothing counts
+zero, so a zero count there is checked again with a locking read of the row.
+Under READ COMMITTED that re-check leaves a window: a row deleted and created
+again with the same id and owner between the UPDATE and the re-check passes
+it, and the write is reported done although nothing was written. REPEATABLE
+READ, InnoDB's default, closes it: the UPDATE's gap lock holds the new row off
+until commit. A proxy that does not pass the `FOUND_ROWS` flag on to its
+backend connections makes a no-op `patch` of a resource without a lock version
+answer `not_found`.
+
+Row policies are checked by the visibility read only, for single and
+many-row writes alike: a row that another transaction moves out of the policy
+(for example into a group the caller cannot see) between the read and the
+write is still written. The ownership conditions close that window for the
+owner. The policy would need a subquery on the written table, which MySQL
+refuses in an UPDATE or DELETE, so no database checks it there. To keep a
+policy-relevant change from slipping between the read and the write, lock the
+row in the writing transaction first (`lockByIds`, which helps only for a
+policy on the row's own columns: [it refuses](17-row-policies.md) a policy
+that joins other tables), or give a many-row write an `onlyIf` on the policy's
+fields. Without a
+visibility read (`missing: 'skip'`, above) the policy is checked by the
+write's subquery, which reads as of the statement's start.
+
+`patchWhere` and `deleteWhere` need non-empty `filters`. To change or delete
+every row the caller can see, pass `all: true` instead (not both); in a
+[system context](34-scoped-reads-and-locks.md#system-contexts) that is the whole
+table.
+
+`onlyIf` makes a patch conditional. Only the rows whose stored values still
+equal the given ones change, and with `returning: 'minimal'` or `'full'` the
+result lists only those rows. With a
+[`lockVersionField`](34-scoped-reads-and-locks.md#lock-versions) this is
+optimistic locking for many rows:
+
+```js
+const changed = await api.resources.orders.patchMany({
+  data: [{ id: order.id, status: 'shipped' }],
+  onlyIf: { lock_version: order.lock_version },
+  returning: 'minimal'
+})
+if (changed.data.length === 0) {
+  // Someone else changed the order first.
+}
+```
+
+## Upserts
+
+`onConflict: { keys, action, merge }` turns `postMany` into an upsert.
+`keys` are the stored fields of a unique index. Each row must give them values,
+no two rows may repeat them, and rows may not carry an `id`: the keys identify
+the record. On a resource with no autofilter (ownership) fields and no row
+policy, `keys: ['id']` makes the id itself the key (the `idProperty` name, such
+as `email` for a natural key, means the same); every row then carries its id,
+and the primary key is the unique index. There is no other owner whose row the
+id could match, so this is the atomic create-if-missing for such tables.
+With `action: 'ignore'`, rows that match an existing record are skipped and
+only the inserted rows are returned. With `action: 'merge'`, the matching
+record is updated: the fields in `merge` that the row supplies, or by
+default every stored field the rows supply except the keys, the id, ownership
+fields and the lock version. A row supplies the fields the caller sent, its
+belongs-to links and the fields a setter adds; schema defaults (`defaultTo`)
+apply only to the rows merge inserts, never to the records it updates.
+
+Keys compare exactly. A stored value is first read as its field reads it, so
+`true` matches a boolean stored as 1 and `1.5` a decimal stored as `1.50`, but
+strings compare as they are, without the column's collation. When the database
+finds a record that matches the keys only by its own comparison, for example
+`'Urgent'` against `'urgent'` under MySQL's case-insensitive collations, the
+batch fails with a `conflict` error (409) instead of guessing.
+
+Upserts cannot reach another owner's rows:
+
+- `keys` must include every autofilter (ownership) field of the resource. The
+  unique index should include them too. The id is a key only on a resource
+  with no ownership fields and no row policy.
+- `merge` is refused on a resource with a row policy. Insert with `ignore`,
+  then `patchMany` the rows the caller may change.
+- Only a match on the conflict keys counts. A row that clashes with an existing
+  record on any other unique index, the primary key included, fails the batch.
+- `merge`, and `ignore` on MySQL and MariaDB, need a unique index whose
+  columns are all among the keys, and refuse the batch
+  (`RestApiBulkWriteUnsupportedError`) without one. Without it the keys could
+  match several records, and the locking read would examine, and on MySQL
+  lock, every row of the table. (`ignore` on PostgreSQL and SQLite needs a
+  unique index on exactly the keys, as `ON CONFLICT` does.) The first upsert
+  on a table reads its indexes once.
+
+`merge` reads the records that match the keys under a row lock, inserts the
+other rows with a plain INSERT and updates the matched records by id, a fixed
+number of statements per chunk. The records it updates go through a patch's
+checks as well as a create's: `checkPermissions` runs with `method: 'patch'`
+and the matched record as `minimalRecord`, the resource is refused if a
+per-record patch hook without `{ batch: true }` runs for it, and a key that
+matches a record the caller cannot see fails the batch as `forbidden`.
+
+With `returning: 'count'` an upsert counts the rows it inserted, and with
+`merge` the records it updated as well.
+
+`ignore` runs `INSERT … ON CONFLICT DO NOTHING` on PostgreSQL and SQLite. On
+MySQL and MariaDB, whose `ON DUPLICATE KEY` fires on every unique index, it
+reads the matching keys under a row lock and inserts the rest. With `merge`,
+and with `ignore` on MySQL and MariaDB, two transactions that upsert the same
+new key at the same time can fail with a unique-key error (PostgreSQL 23505)
+or a deadlock (MySQL 1213); retry the batch. InnoDB keeps the locks of every
+row a locking read examined until the transaction ends, so keep upserting
+transactions short.
+
+A single `put` creates a record at the id the caller chose, and is the one
+write that tells an id taken by another owner or hidden from the caller
+apart from a free one: it
+answers `not_found` for the first and creates the second. Where ids must not
+leak between owners, let the server choose them: create with `post` or
+`postMany` (or upsert on keys that include the owner) and keep `put` for
+records the caller already has.
+
+`merge` on every database, and `ignore` on MySQL and MariaDB, find the rows
+that match the conflict keys with a locking read of the bare table, before the
+caller's scope is checked. A matching row the caller cannot see, such as one a
+`knexQueryFiltering` hook hides, is therefore locked until commit, and waited
+for while another transaction holds it, as `lockByIds` does with a hidden id
+(see [scoped reads and locks](34-scoped-reads-and-locks.md)). `merge` then fails
+the batch as `forbidden`, and `ignore` skips the row. With `keys: ['id']` that
+read locks the listed ids by primary key.
+
+## Transactions
+
+Without a `transaction` the call owns one transaction and commits it at the end,
+or rolls everything back on any failure. To combine a many-row write with other
+work, pass a transaction from `api.transaction`; the method joins it and never
+commits or rolls it back.
+
+```js
+await api.transaction(async transaction => {
+  const order = await api.resources.orders.post({ data: { number: 'A-1' }, transaction, format: 'plain' })
+  await api.resources.order_lines.postMany({
+    data: lines.map(line => ({ ...line, order: order.id })), transaction
+  })
+})
+```
+
+A raw Knex transaction, a savepoint or a completed transaction is refused before
+anything runs. Errors are `RestApiWriteError`s carrying the
+`transactionOutcome`; the original error is their `cause`.
+
+## Hooks and refusals
+
+Many-row methods run batch hooks once per call instead of the per-record write
+hooks:
+
+| Method | Batch hooks (in order) | Context |
+| --- | --- | --- |
+| `postMany` | `beforeProcessingPostMany`, `beforeDataCallPostMany`, `afterDataCallPostMany` | `inputRecords`; `ids` after the insert |
+| `patchMany`, `patchWhereIds`, `patchWhere` | `beforeProcessingPatchMany`, `beforeDataCallPatchMany`, `afterDataCallPatchMany` | `inputRecords`, `rawFields`, `ids` |
+| `deleteMany`, `deleteWhere` | `beforeDataCallDeleteMany`, `afterDataCallDeleteMany` | `ids` |
+
+In the `afterDataCall…Many` hooks, `ids` lists only the rows the write
+changed, and for patches `inputRecords` lists their inputs in the same order,
+so a row that `missing: 'skip'`, `onlyIf` or a selection left out appears in
+neither. `afterCommit` and `afterRollback` run once, with `context.method` set
+to the many-row method. `checkPermissions` still runs for every row, with
+`method` `'post'`, `'patch'` or `'delete'` and the row's position as
+`originalContext.bulkIndex`.
+
+A resource whose per-record write hooks would be skipped is refused rather than
+written around them. Register a per-record handler with `{ batch: true }` when
+a batch hook does its work, or when it does not apply to many-row writes:
+
+```js
+api.addHook('afterDataCallPost', 'audit-create', { batch: true }, auditOne)
+api.addHook('afterDataCallPostMany', 'audit-create-many', {}, auditMany)
+```
+
+The built-in plugins have batch forms. Autofilter stamps every row; Socket.IO
+notifies each changed record that matches a subscription; query projections
+apply to every row. Some features stay single-row. The methods throw
+`RestApiBulkWriteUnsupportedError` (code `REST_API_BULK_WRITE_UNSUPPORTED`,
+HTTP 422) before writing when:
+
+- the resource uses AnyAPI storage;
+- the resource has a `versionField`, or its writes advance another resource's
+  version (use single writes with `expectedVersion`, or a `lockVersionField`
+  with `onlyIf`);
+- a per-record write hook without `{ batch: true }` runs for the resource
+  (the error's `details.hooks` names them; HTTP responses leave details out);
+- rows set many-to-many or reverse relationships;
+- rows set file fields (`FileHandlingPlugin`), directly or with raw values;
+- rows create positioned records or move them (`PositioningPlugin`), directly
+  or with raw values.
+
+## HTTP routes
+
+`BulkOperationsPlugin` exposes the methods over HTTP. Install it after the
+connector and before declaring resources:
+
+```js
+import { BulkOperationsPlugin } from 'json-rest-api/plugins/core/bulk-operations-plugin.js'
+
+await api.use(BulkOperationsPlugin, { maxBulkOperations: 1000 })
+```
+
+`maxBulkOperations` (default 1,000) is the only option; requests with more
+entries fail with 422 before anything runs.
+
+| Request | Body | Runs | Response |
+| --- | --- | --- | --- |
+| `POST /api/books/bulk` | `{ data: [resource objects] }` | `postMany` | 201, `{ data: [records] }` |
+| `PATCH /api/books/bulk` | `{ data: [resource objects with id] }` | `patchMany` | 200, `{ data: [records] }` |
+| `DELETE /api/books/bulk` | `{ data: [{ type, id }] }` | `deleteMany` | 200, `{ data: [identifiers] }` |
+
+```json
+{
+  "data": [
+    { "type": "books", "id": "1", "attributes": { "title": "Revised" } },
+    { "type": "books", "id": "2", "attributes": { "stock": 5 } }
+  ]
+}
+```
+
+Responses are full JSON:API records. The routes take no query parameters and
+no `If-Match`. The request's authenticated context reaches every permission
+check. Ids the caller cannot see give 404, a permission denial 403, invalid
+rows and refused resources 422. Nothing is written in any of these cases. The
+plugin reserves `/RESOURCE/bulk`, including when the resource accepts opaque
+ids. This protocol is not the JSON:API Atomic Operations extension.
+
+Coming from the 2.x `bulkPost`, `bulkPatch` and `bulkDelete`? See
+[migrating to v3](35-migrating-to-v3.md#many-row-writes-replace-the-bulk-methods).

package/docs/GUIDE/28-socketio.md

@@ -166,6 +166,9 @@ subscribe. It does not replay changes missed during disconnection.
 | PATCH or PUT replacement | `resource.updated` | `patch` or `put` |
 | Relationship POST/PATCH/DELETE | `resource.updated` | `patch` |
 | Resource DELETE | `resource.deleted` | `delete` |
+| `postMany` | `resource.created`, one per row | `post` |
+| `patchMany`, `patchWhereIds`, `patchWhere` | `resource.updated`, one per row | `patch` |
+| `deleteMany`, `deleteWhere` | `resource.deleted`, one per row | `delete` |
 
 IDs are strings. Deletion also includes `deletedRecord: { id }`, without deleted
 attributes. Reverse relationship changes notify the parent and the changed
@@ -186,6 +189,11 @@ failures are logged and count as nonmatches; a successful match before or after
 is sufficient. Applications should account for these additional queries and
 ensure query hooks can run inside the write transaction.
 
+[Many-row writes](27-many-row-writes.md) run the same eligibility check for all
+their rows at once: one query per subscription for each 1,000 changed ids,
+before and after the write. Each subscription receives one notification for
+every changed row that matched it.
+
 ## Authentication and permissions
 
 For an application with authenticated users, install the plugin with a
@@ -261,8 +269,8 @@ change. A rejected call after commit can still have emitted notifications. These
 HTTP polling, including relationship changes and child rollback.
 
 Library writes now require the handle from `api.transaction` when joining an
-outer unit. Resource and atomic-bulk child completion hooks run after confirmed
-owner completion; non-atomic bulk retains one outcome per entry. Rolled-back
+outer unit. Resource and many-row completion hooks run after confirmed
+owner completion. Rolled-back
 units do not flush queued notifications. Explicit callbacks are tested with
 repeated changes to the same record, callback/caught-write/caught-SQL failures,
 and rejected completion hooks on both storage modes and all three databases.