json-rest-api 1.0.28 → 2.0.0

package/docs/GUIDE/18-labels.md

@@ -0,0 +1,86 @@
+---
+title: "Labels"
+chapter: 18
+chapter_label: "18"
+---
+
+# 18. Labels
+
+Install `LabelPlugin` after `RestApiPlugin` and before adding resources:
+
+```js
+import { LabelPlugin } from 'json-rest-api'
+
+await api.use(LabelPlugin, { preferNameFields: ['name', 'title'] })
+```
+
+It adds a computed string `label` to resources that do not already declare one.
+The label is derived during reads and is not a stored column. GET, query, full
+write responses and included resources use the same computation in both plain
+and JSON:API formats.
+
+Candidates are derived during schema compilation, after attribute and search
+enrichment. Canonical `addKnexFields` rebuilds them from the new configuration,
+so a field addition retains the label and an added preferred/global-search
+source becomes eligible. Reads and descriptor-only refreshes reuse the compiled
+candidates. Ordinary Knex field-addition helpers perform DDL only; changing
+their runtime declarations still requires resource initialization.
+
+The plugin considers, in order:
+
+1. The first global-search field that resolves to a public stored field on this
+   resource. A search alias uses its `actualField`; a joined search path is not
+   a local label source.
+2. String fields listed in `preferNameFields`, in the configured order.
+3. The first public stored string field in the schema.
+4. The resource's logical ID.
+
+Null and undefined values fall through to the next candidate. Empty strings,
+zero and false are retained and converted to strings. Getters run before label
+computation. Hidden, normally hidden and virtual fields, belongs-to foreign keys
+and polymorphic backing fields are not automatic label sources. This keeps the default label from exposing private values or depending
+on a transient write input.
+
+Sparse fieldsets can select just the label:
+
+```js
+await api.resources.books.query({
+  format: 'jsonapi',
+  queryParams: { fields: { books: 'label' } }
+})
+```
+
+The existing computed-field dependency mechanism fetches the candidate values
+and removes unrequested dependencies from the result. Null fallbacks therefore
+work with sparse fieldsets too. Pass `{ disable: true }` when installing the
+plugin to disable automatic labels.
+
+## Authored labels and record identity
+
+An explicitly declared stored or computed `label` remains authoritative. The
+plugin does not remove its schema definition or replace its computation. For
+example, a resource may declare:
+
+```js
+label: {
+  type: 'string',
+  computed: true,
+  dependencies: ['title'],
+  compute: ({ id, attributes }) => `${id}: ${attributes.title ?? ''}`
+}
+```
+
+Computed callbacks receive the current resource's public logical `id` separately
+from `attributes`. This also works for custom `idProperty` names, collections
+and included resources; the ID is not taken from the parent request. Direct
+callers of `enrichAttributes` can supply its `id` argument explicitly.
+
+Computed fields honor `hidden` and `normallyHidden` like stored fields: hidden
+fields are omitted, and normally hidden fields appear only when requested.
+Authors who intentionally derive a public value from normally hidden dependencies should
+declare that computed field explicitly and review the information it returns.
+
+The shared label suite (source checkout: `tests/conformance-labels.test.js`) checks these
+contracts on regular and canonical storage. The
+[migration guide](33-migrating-to-v2.md#generated-labels-and-computed-visibility)
+describes corrections from the earlier behavior.

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

@@ -0,0 +1,179 @@
+---
+title: "Managed transactions"
+chapter: 19
+chapter_label: "19"
+---
+
+# 19. Managed transactions
+
+Use `api.transaction()` to group resource operations and raw SQL in one explicit
+unit. The helper owns commit, rollback and completion hooks. Pass its transaction
+to every participating operation; the library does not infer ambient ownership.
+
+## Callback and result
+
+```js
+const result = await api.transaction(async transaction => {
+  const book = await api.resources.books.post({
+    data: { title: 'New book' },
+    format: 'plain',
+    transaction
+  })
+  await transaction('audit_entries').insert({ book_id: book.id })
+  return book
+})
+```
+
+`api.transaction(callback, context = {})` acquires one top-level transaction,
+awaits the callback, completes the transaction, awaits its completion work and
+returns the callback's value unchanged. The second argument is mutable diagnostic
+context, consistent with other API methods; it is not a second options parser.
+Invalid callbacks fail before acquisition. The callback receives the actual
+Knex transaction, so existing first-argument `transaction` forwarding and raw SQL
+remain straightforward. No transaction is inferred from process-global or async
+ambient state. Callers must await all work before the callback returns.
+Individual resource calls inside the callback resolve while the unit is still
+pending; only the outer helper waits for commit and completion hooks. Both
+synchronous callback values and awaited promises are supported, including
+undefined. The helper does not clone or serialize the callback result.
+
+The helper owns completion. The callback must not invoke commit/rollback,
+transaction-control SQL or DDL that implicitly completes its transaction. A
+handle completed outside the helper is rejected with an unknown outcome unless
+the library has actual completion evidence; it must not trigger speculative
+rollback cleanup or commit notifications. SQL/connection error evidence also
+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.
+
+The final contract requires library writes to use a library-owned transaction.
+Standalone transactions created with `knex.transaction()` remain usable for raw
+SQL, but passing them into library writes will reject before partial work.
+Migrate those units to `api.transaction`; its callback still receives a real
+Knex handle. This replaces the previous ambiguous borrowed-write mode in which
+notifications/uploads can wait forever for an unobserved owner. Read-only/raw
+storage use is not a competing event-delivery mode.
+
+Canonical `addKnexFields()` batches use this helper too. Direct registry writes
+that receive a transaction require a managed handle. Their caller still
+invalidates the registry descriptor cache after confirmed commit; this does not
+publish a new compiled resource schema. Raw descriptor reads and schema/data
+migration helpers retain their separate documented transaction contracts.
+
+Any rejected participating write marks the unit failed, even if the callback
+catches the error and returns normally. Observed SQL failures also prevent a
+later commit from masking aborted work. A rejected callback or failed unit rolls
+back; no automatic retries or savepoints restore it. A failure before acquisition
+has outcome none. Participant errors retain their pending/none snapshot, and an
+outer error records the owner's eventual outcome without rewriting its cause.
+If the callback rejects, its rejection is primary. If it returns after catching
+failures, the first recorded participant/SQL failure is primary instead.
+
+A native lock timeout, deadlock or stale SQLite snapshot is reported to the
+caller. The library does not replay the callback, field setters or hooks.
+Effects performed outside the database before the conflict can therefore remain
+once even though the database write rolls back. Retry only a new complete unit
+whose external effects your application can safely repeat or reconcile; never
+retry just the failed statement inside an already failed unit.
+
+## Completion work
+
+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.
+
+After confirmed commit, invoke enlisted `afterCommit` chains in enlistment
+order. After confirmed rollback, invoke `afterRollback` chains in reverse order.
+A chain retains its normal local stop-on-error behavior; failure in one chain
+does not prevent other enlisted operations' completion work from being attempted.
+Collect secondary failures in owner diagnostics. Retain the original callback/
+write failure on rollback; after commit, report the first completion failure as
+the primary error with outcome committed. Unconfirmed completion runs neither
+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
+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.
+
+Use the existing diagnostic shape on the owner's context: `error` is the primary
+failure and `cleanupErrors` is an ordered array of `{ phase, error }` entries.
+Completion-chain entries additionally identify `operationIndex`, `scopeName`
+and `method`; phases distinguish `rollback`, `afterRollback` and `afterCommit`.
+Secondary finalizer failures use phase `finalization` and `finalizerIndex`.
+The error carrier retains its cause even when any of these values are frozen or
+non-Error throws. Do not serialize transaction handles or raw cleanup objects
+into HTTP errors.
+
+An operation's mutable context remains in use until its owner completes. Use a
+separate context object per operation; reject reuse through library calls while
+that context is still enlisted. Do not copy arbitrary contexts, replay mutations
+into reused objects, or rebuild scope-aware hook dispatch in the transaction
+helper. Completion hooks receive their operation's context, with the observed
+owner outcome added at completion. Previously thrown errors remain immutable
+snapshots. Application code must not mutate an enlisted context concurrently.
+The private owner record controls commit and rollback. Changing the diagnostic
+`shouldCommit` flag cannot transfer ownership to a participant or stop an
+implicit owner from completing. During rollback, a failed operation retains its
+original error; an operation that succeeded before the unit failed receives the
+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.
+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
+chains are reported on the owner. After confirmed commit, stored objects are
+application-owned. Replacement and deletion preserve previously committed files:
+opaque URLs may be shared by other records or external consumers. Rollback
+removes only new uploads belonging to the failed unit. See the
+[file ownership contract](26-file-uploads.md#ownership-after-commit)
+for application-managed garbage collection.
+
+Socket.IO notices are per-operation invalidations, without coalescing: a
+sequential create/update/delete can emit all three after commit. Callback
+rollback discards the queue. The selected tests check pending silence, ordered
+notices, real committed/rolled-back rows, visibility filtering and a later
+chain flushing once after the first chain fails. These are awaited in-memory
+notifications, not durable delivery or an exactly-once guarantee.
+
+Notification capture order is the order in which operations reach the Socket.IO
+finish hook's queue. For overlapping writes it can differ from enlistment order.
+The first successful delivery chain drains that queue without reordering it.
+Real polling/WebSocket tests deliberately pause the first enlisted write so the
+second finishes first, and verify both distinct orders.
+
+## Nesting and application ownership
+
+An application-created Knex transaction is unmanaged from this library's point
+of view: the application decides when it finally commits or rolls back. That
+final outcome controls after-commit hooks and rollback cleanup, so passing an
+arbitrary Knex transaction into resource writes is rejected. Use
+`api.transaction` to group resource operations and raw SQL under one owner.
+
+A savepoint is a rollback checkpoint inside an outer transaction. Releasing it
+does not commit that outer transaction. Resource writes therefore cannot treat
+savepoint success as permission to send notifications or run after-commit hooks.
+
+Every `api.transaction` call starts an independent top-level unit. There is no
+implicit joining or nested callback overload. To compose work within one unit,
+pass its transaction to ordinary functions and resource methods. Managed library
+writes do not support child savepoints; reject them explicitly instead of
+treating savepoint release as outer commit. The current owned-completion guard
+already rejects a custom factory's savepoint; its caller-owned parent survives.
+
+When migrating an application's transaction wrapper, delegate to `api.transaction`
+and forward the received handle. Port raw transaction creation, context reuse and
+error handling together. Preserve domain scope resolution in application code;
+keep completion ownership in one place.

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

@@ -0,0 +1,207 @@
+---
+title: "Transaction outcomes"
+chapter: 20
+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
+the failure is reported.
+
+[Managed transactions](19-managed-transactions.md) explains ownership and
+completion ordering. These guarantees cannot recover an error swallowed by
+an application extension.
+
+## The five states
+
+| State | Exact meaning |
+| --- | --- |
+| `none` | No transaction was acquired or accepted for this operation. This includes rejection before transaction setup. It does not certify that external or nontransactional work had no effects. |
+| `pending` | The operation participated in a transaction whose owner has not completed it. The owner still must decide its outcome. A database error may have made further SQL unusable; pending does not mean the owner can safely continue writing. |
+| `committed` | The backend confirmed commit of the represented outer transaction. Later hook, file, notification or logging failure does not change this outcome. Releasing a savepoint does not establish outer commit. |
+| `rolledBack` | The backend confirmed rollback of the represented transaction. Later cleanup failure does not undo that confirmation. This says nothing about external effects performed before rollback. |
+| `unknown` | A transaction was acquired or accepted, but the available evidence cannot establish its outcome or leave it confidently pending. Examples include lost completion acknowledgements, failed completion/rollback, and an accepted handle completed outside its owner without observed outcome. |
+
+Use these values consistently. Do not add
+synonyms for driver states or infer them from exception messages. Ownership is
+separate from outcome: an individual resource operation borrows its caller's
+transaction, including a transaction managed by an outer library operation.
+
+## Evidence and transitions
+
+Transaction setup starts with `none`. Successful acquisition or acceptance of
+an unfinished transaction moves to `pending`. An operation that merely borrows
+that transaction leaves it pending; its own success or rejection does not commit
+or roll back the outer unit. A rejected statement may require the owner to roll
+back even if the driver's handle remains usable-looking.
+
+The private transaction owner controls completion; a hook changing the mutable
+`shouldCommit` diagnostic flag neither takes ownership nor suppresses an implicit
+owner's commit or rollback. Participating operation errors stay pending snapshots
+even when the outer helper later reports rolledBack.
+
+Confirmed commit or rollback establishes `committed` or `rolledBack`. A failed
+completion attempt without confirmation establishes `unknown`. If a subsequent
+rollback is actually confirmed, the reported outcome can be `rolledBack`; a
+cleanup attempt or a resolved wrapper alone is insufficient. Once commit is
+confirmed, later failure remains committed and must not trigger rollback.
+
+Knex 3.1.0 exposes a specific trap: `commit()` and `rollback()` can resolve even
+when their control query failed, while `executionPromise` rejects. Its
+`isCompleted()` flag is set when completion starts and after failures; the flag
+alone proves neither commit nor rollback. The current shared completion helpers
+now await `executionPromise` before reporting successful completion to hooks or
+the registry. Driver-path regressions cover rejected SQL and injected lost
+acknowledgements after real execution.
+
+The shared helper also rejects a PostgreSQL COMMIT response reporting ROLLBACK.
+Both Knex promises can resolve in this case, but the backend has confirmed that
+the writes were rolled back. The existing failure path consumes that confirmation
+once, without sending another ROLLBACK. Resource rollback hooks can then clean
+uploaded files; commit hooks and registry cache publication do not run.
+
+Owned completion now requires a top-level transaction. A custom transaction
+factory returning a savepoint is rejected before release; the existing failure
+path rolls back that savepoint and leaves its caller-owned parent active.
+No commit hook or committed registry cache publication follows that rejection.
+The managed implementation rejects raw transactions and savepoints supplied to
+library writes before acceptance, with outcome none. A managed handle completed
+outside its owner after acceptance instead has outcome unknown. Connection
+failure during commit must remain unknown unless available evidence establishes
+the outcome. The error remains a snapshot even if the application later
+reconciles the database state.
+
+## When commit acknowledgement is lost
+
+A connection can fail before COMMIT reaches the database or after the database
+commits but before the caller receives confirmation. A rejected promise or HTTP
+500 alone cannot distinguish those cases. `unknown` deliberately preserves that
+uncertainty; it is not a synonym for rolledBack.
+
+| Observed evidence | Reported outcome and behavior |
+| --- | --- |
+| Commit and driver completion acknowledged, then an after-commit hook fails | `committed`; retain the failure, never attempt rollback of the committed write. |
+| Commit control statement or its completion promise rejects without acknowledged outcome | `unknown`; no speculative commit/rollback hooks. A driver's completed flag alone does not establish success. |
+| PostgreSQL acknowledges COMMIT as ROLLBACK | `rolledBack`; run rollback completion work without issuing a second rollback. |
+| Rollback is acknowledged, then cleanup fails | `rolledBack`; retain the primary write error and secondary cleanup diagnostics. |
+| Rollback itself cannot be acknowledged | `unknown`; keep the original failure and rollback diagnostic. |
+
+The Knex storage plugins and owned AnyAPI registry operations retain the
+physical connection lease until the
+transaction completion promise settles. A failed completion marks that connection
+disposed before releasing it, so even a request already waiting for the pool
+cannot borrow its unfinished transaction. A failed BEGIN also rejects before the
+application callback runs. Acknowledged completion keeps normal connection reuse.
+
+Owned PostgreSQL `alterKnexFields` also uses the managed completion runner.
+A deep-helper call given an existing transaction uses a savepoint and leaves
+completion to that caller. SQLite table rebuilds are Knex-managed internally;
+the library holds their connection lease through error cleanup, rolling back a
+transaction the driver reports still active and restoring foreign-key enforcement
+before release. If cleanup cannot establish a reusable connection, it is disposed.
+See the [schema guide](21-schema-and-migrations.md) for DDL-specific
+ownership, cleanup errors and dialect restrictions.
+
+If a completion method rejects without settling its driver completion promise,
+an owner finishing with outcome `unknown` also discards its unreleased connection
+lease. A later driver promise settlement cannot release the lease twice. The raw
+driver promise may remain unsettled; application completion follows the library
+call and its outcome, rather than waiting on that internal promise.
+
+Connection release is cleanup, separate from the driver's SQL-completion promise.
+A release error after acknowledged COMMIT keeps outcome `committed`; it becomes a
+post-commit error and later completion hooks/finalizers are still attempted. A
+release error after confirmed rollback keeps `rolledBack`, preserves the original
+failure, and adds a `connectionRelease` diagnostic to the owner's cleanup errors.
+Failed BEGIN also retains its original cause if releasing its lease fails.
+
+Disposal does not establish whether a write committed, and does not replay it.
+Knex destroys the disposed connection during pool validation or idle cleanup;
+this is not a guarantee of immediate server-side lock release. SQLite `:memory:`
+data belongs to its connection and is lost when that connection is discarded;
+use a file-backed database when data must survive connection replacement.
+
+After `unknown`, reconcile using application-owned operation identity and
+persisted state before deciding whether to issue a new write. Do not treat a
+previously captured participant error as the owner's final outcome. Do not infer
+that files in upload tracking are safe to delete: they may belong to committed
+rows. Outcome-dependent hooks are skipped when the outcome is unknown, so
+notifications and other in-memory completion work may require reconciliation as
+well. There is no durable outbox, automatic retry or exactly-once delivery.
+
+Database rollback does not undo email, remote calls or other effects performed
+outside that database. Even `rolledBack` permits a safe retry only when the
+application can repeat or reconcile those effects. See the
+[file ownership contract](26-file-uploads.md#ownership-after-commit).
+
+The completion tests inject failures at the actual driver query boundary before
+and after executing COMMIT/ROLLBACK, inspect persisted rows afterward, and
+assert no outcome hooks run for unknown completion. They cover real supported
+databases, but do not simulate every network partition, server failover or
+physical connection-loss sequence. This contract reports available evidence;
+it does not promise to resolve an acknowledgement the client never received.
+
+## Selected error carrier
+
+Writes reject with `RestApiWriteError`, exported from the package root. Its
+read-only `transactionOutcome` is one of the five strings above. `cause` retains
+the original thrown value, including a frozen error, null or undefined; a fresh
+wrapper is created for each failed operation. Read errors retain their existing
+contract. The runtime propagates null and undefined throws. Errors already lost
+inside an extension's own catch cannot be restored by the write boundary.
+
+The wrapper retains ordinary data fields used for classification: `code`,
+`type`, `subtype`, `details`, `statusCode`, `status`, `path`, `parameter` and
+`validation`, including inherited status fields from HTTP error classes. It does
+not execute diagnostic getters. Without an original code,
+its code is `REST_API_WRITE`. The original error class is available through
+`cause`; the wrapper itself has class `RestApiWriteError`. Its JSON representation
+omits the cause, stack and transaction handle while retaining diagnostic fields.
+
+An atomic child's wrapper can be the outer wrapper's cause. Both snapshots are
+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.
+
+## Errors, batches and later observations
+
+Outcome evidence must survive a secondary cleanup error without replacing the
+primary failure or its cause. The selected wrapper carries frozen errors and
+non-Error throws without mutating the original value.
+Completion hooks and internal diagnostic finalizers are attempted in their
+documented order despite earlier completion failures. After commit, the first
+such failure remains primary. Finalizer errors after rollback or unknown
+completion remain secondary; they do not change the observed outcome or cause
+speculative outcome hooks to run. See the
+[managed completion contract](19-managed-transactions.md#completion-work).
+Only safe, serializable outcome fields belong in transport errors. Transaction,
+connection, storage and raw cleanup objects remain internal diagnostics.
+
+An outcome attached to an error is a snapshot, not a live view. A borrowed
+operation can report pending and its owner later report rolledBack. Later
+confirmation belongs to the owner's completion result; do not mutate previously
+reported failures or their causes to rewrite that history.
+
+An atomic batch has one transaction outcome. A non-atomic batch has separate
+outcomes for its entries; it must not claim one shared committed/rolledBack
+outcome from aggregate success counts. Its `meta.failed` counts rejected calls,
+including possible post-commit failures. Each rejected entry carries its own
+outcome; mixed results do not introduce a sixth transaction state.
+
+None of these states is a general retry instruction. Repeating a committed or
+unknown write can duplicate effects. Pending work belongs to its owner. Even a
+confirmed rollback cannot undo an email, upload, external API call or other
+effect outside the database transaction. No automatic replay of arbitrary hooks
+or setters is part of this contract.
+
+### Dispatcher failures
+
+Resource dispatch and hook execution preserve the original thrown value, including
+null and undefined. The runtime does not add automatic failure logging or wrap plugin
+installation errors. The transaction layer attaches write outcomes and records failed
+cleanup diagnostics without replacing the primary cause.