json-rest-api 2.4.0 → 3.0.0

package/plugins/core/lib/storage/canonical-data-helpers.js

@@ -14,6 +14,8 @@ import { translateCanonicalAttributesForStorage, getCanonicalResourceId, getCano
 import { unwrapQueryBuilderState, withQueryFilteringContext } from '../querying/query-builder-utils.js'
 import { applyInsertReturning } from '../querying-writing/database-capabilities.js'
 import { serializeJsonApiQuery } from '../querying-writing/connectors-query-parser.js'
+import { deleteFoundRow, foundRow, lockFoundRow, updateFoundRow } from './single-row-writes.js'
+import { whereInIdentifiers } from '../querying/identifier-query.js'
 
 /** @param {StorageRow} row @param {CanonicalDescriptor} descriptor */
 function requireCanonicalResourceId (row, descriptor) {
@@ -91,6 +93,25 @@ export function createCanonicalDataHelpers ({
     return descriptors
   }
 
+  // The canonical row of the record a single write found with its scoped read.
+  /** @param {string} scopeName @param {{ db: import('./storage-types.js').StorageDatabase, id: string | number }} context */
+  const foundRecord = (scopeName, context) => {
+    const storageAdapter = getScopeStorageAdapter(scopeName)
+    if (!storageAdapter) throw new Error(`Storage adapter for resource '${scopeName}' not found`)
+    const descriptor = getDescriptor(scopeName)
+    const { canonical } = descriptor
+    return foundRow({
+      byId: () => context.db(canonical.tableName)
+        .where(getCanonicalResourceIdColumn(descriptor), context.id)
+        .where(canonical.resourceColumn, descriptor.resource)
+        .where(canonical.tenantColumn, descriptor.tenant),
+      context,
+      scopeName,
+      storageAdapter,
+      tableName: canonical.tableName
+    })
+  }
+
   /** @type {CanonicalDataWriteHelpers['dataExists']} */
   const dataExists = async ({ scopeName, context }) => {
     const storageAdapter = getScopeStorageAdapter(scopeName)
@@ -188,13 +209,7 @@ export function createCanonicalDataHelpers ({
       return 1
     }
 
-    const result = await context.db(canonical.tableName)
-      .where(logicalIdColumn, id)
-      .where(canonical.resourceColumn, descriptor.resource)
-      .where(canonical.tenantColumn, descriptor.tenant)
-      .update(writeRow)
-
-    return result
+    return updateFoundRow(foundRecord(scopeName, context), { db: context.db, scopeName, id, idColumn: logicalIdColumn, values: writeRow })
   }
 
   /** @type {CanonicalDataWriteHelpers['dataPatch']} */
@@ -204,7 +219,6 @@ export function createCanonicalDataHelpers ({
       context.storageAdapter = storageAdapter
     }
     const descriptor = getDescriptor(scopeName)
-    const { canonical } = descriptor
     const id = context.id
     const logicalIdColumn = getCanonicalResourceIdColumn(descriptor)
     const attributes = context.inputRecord?.data?.attributes || {}
@@ -216,17 +230,7 @@ export function createCanonicalDataHelpers ({
       Object.entries(row).filter(([, value]) => value !== undefined)
     )
 
-    if (Object.keys(updateRow).length === 0) {
-      return 0
-    }
-
-    const result = await context.db(canonical.tableName)
-      .where(logicalIdColumn, id)
-      .where(canonical.resourceColumn, descriptor.resource)
-      .where(canonical.tenantColumn, descriptor.tenant)
-      .update(updateRow)
-
-    return result
+    return updateFoundRow(foundRecord(scopeName, context), { db: context.db, scopeName, id, idColumn: logicalIdColumn, values: updateRow })
   }
 
   /** @type {CanonicalDataWriteHelpers['dataDelete']} */
@@ -236,23 +240,18 @@ export function createCanonicalDataHelpers ({
       context.storageAdapter = storageAdapter
     }
     const descriptor = getDescriptor(scopeName)
-    const { canonical } = descriptor
     const id = context.id
-    const logicalIdColumn = getCanonicalResourceIdColumn(descriptor)
-
-    await linkStore.invalidateDeletedLinkTargets(scopeName, context)
-    const result = await context.db(canonical.tableName)
-      .where(logicalIdColumn, id)
-      .where(canonical.resourceColumn, descriptor.resource)
-      .where(canonical.tenantColumn, descriptor.tenant)
-      .delete()
+    const row = foundRecord(scopeName, context)
 
+    const idColumn = getCanonicalResourceIdColumn(descriptor)
+    await linkStore.invalidateDeletedLinkTargets(scopeName, context, () => lockFoundRow(row, { scopeName, id, idColumn }))
+    const deleted = await deleteFoundRow(row, { scopeName, id })
     await linkStore.deleteResourceLinks({ descriptor, scopeName, id, db: context.db })
 
-    return result
+    return deleted
   }
 
-  // Supplying ids returns minimal records for the caller's bounded validation batch.
+  // Supplying ids returns minimal records for all of them, in one statement.
   /** @overload @param {DataMinimalRequest & { ids: Array<string | number> }} request @returns {Promise<DataResource[]>} */
   /** @overload @param {DataMinimalRequest & { ids?: undefined, context: DataReadContext & {id: string | number} }} request @returns {Promise<DataResource | null>} */
   /** @param {DataMinimalRequest & { ids?: Array<string | number> }} request */
@@ -279,8 +278,7 @@ export function createCanonicalDataHelpers ({
       .where(canonical.tenantColumn, descriptor.tenant)
     if (ids === undefined) query.where(logicalIdColumn, id)
     else {
-      // Knex types exclude unknown bindings; the configured driver still validates serializer results.
-      query.whereIn(logicalIdColumn, /** @type {import('knex').Knex.Value[]} */ (ids.map(value => storageAdapter.translateFilterValue('id', value))))
+      query.modify(whereInIdentifiers, logicalIdColumn, ids.map(value => storageAdapter.translateFilterValue('id', value)))
         .distinct(`${canonical.tableName}.${logicalIdColumn}`)
     }
 
@@ -332,7 +330,7 @@ export function createCanonicalDataHelpers ({
       return minimal
     }
     if (ids !== undefined) {
-      // Filtering owns predicates; the validation batch owns its identity projection.
+      // Filtering owns predicates; the id list owns its identity projection.
       query.clearSelect().distinct(`${canonical.tableName}.${logicalIdColumn}`)
       /** @type {StorageRow[]} */
       const rows = await applyDatabaseReadOptions(storageAdapter.buildBaseQuery({ transaction: context.db }).whereIn(logicalIdColumn, query))
@@ -343,7 +341,7 @@ export function createCanonicalDataHelpers ({
   }
 
   /** @type {CanonicalDataReadHelpers['dataGet']} */
-  const dataGet = async ({ scopeName, context }) => {
+  const dataGet = async ({ scopeName, context, runHooks, scoped = false }) => {
     const storageAdapter = getScopeStorageAdapter(scopeName)
     if (!storageAdapter) throw new Error(`Storage adapter for resource '${scopeName}' not found`)
     context.storageAdapter = storageAdapter
@@ -357,17 +355,40 @@ export function createCanonicalDataHelpers ({
     const fieldSelectionInfo = await buildFieldSelection(scope, { context })
     context.computedDependencies = fieldSelectionInfo.computedDependencies
 
+    // The preceding minimal read has already applied permission and row filters,
+    // unless the read is `scoped`: then it applies them itself, as the only read,
+    // and names its columns' table, since a row policy may join tables.
+    const column = (/** @type {string} */ name) => scoped ? `${canonical.tableName}.${name}` : name
     let query = context.db(canonical.tableName)
-      .where(logicalIdColumn, id)
-      .where(canonical.resourceColumn, descriptor.resource)
-      .where(canonical.tenantColumn, descriptor.tenant)
+      .where(column(logicalIdColumn), id)
+      .where(column(canonical.resourceColumn), descriptor.resource)
+      .where(column(canonical.tenantColumn), descriptor.tenant)
+    if (scoped) {
+      const filterHooks = runHooks
+      if (!filterHooks) throw new Error('A scoped read needs runHooks')
+      query = (await withQueryFilteringContext(context, {
+        query,
+        filters: context.queryParams?.filters,
+        schemaInfo: context.schemaInfo,
+        scopeName,
+        tableName: canonical.tableName,
+        db: context.db,
+        queryPurpose: 'single',
+        isAnyApi: true,
+        adapter: storageAdapter,
+        storageAdapter
+      }, async () => {
+        await applyBuiltInAnyApiQueryFilters(context)
+        await filterHooks('knexQueryFiltering')
+      })).query
+    }
 
     const selectionState = await applyFieldSelectionToQuery({
       query,
       scope,
       fieldSelectionInfo,
       tableName: canonical.tableName,
-      useTablePrefix: false,
+      useTablePrefix: scoped,
       storageAdapter,
       db: context.db,
       context,
@@ -512,6 +533,11 @@ export function createCanonicalDataHelpers ({
     let rows = await applyDatabaseReadOptions(queryBuilder)
     let cursorRecords = null
     let hasMore = false
+    // Without a count, a numbered page's one extra row answers hasMore.
+    if (paginationInfo.mode === 'offset' && !scope.vars.enablePaginationCounts) {
+      hasMore = rows.length > paginationInfo.pageSize
+      if (hasMore) rows = rows.slice(0, paginationInfo.pageSize)
+    }
 
     if (paginationInfo.mode === 'cursor') {
       const { pageSize } = paginationInfo
@@ -615,7 +641,7 @@ export function createCanonicalDataHelpers ({
         const total = Number(countResult?.count ?? countResult?.total ?? 0)
         paginationMeta = calculatePaginationMeta(total, page, pageSize)
       } else {
-        paginationMeta = { page, pageSize }
+        paginationMeta = { page, pageSize, hasMore }
       }
 
       context.returnMeta.paginationMeta = paginationMeta
@@ -699,13 +725,51 @@ export function createCanonicalDataHelpers ({
     return runAggregateQuery({ source: filteredState.query, sourceTable: tableAlias, storageAdapter, db, plan })
   }
 
+  /**
+   * The canonical rows of one resource with ownership and row policy applied.
+   * Many-row writes and row locks are table-storage features; AnyAPI resources
+   * get the read-only builder only. Resolves to `{ query, alias }`.
+   * @param {{ scopeName: string, context: DataReadContext, runHooks: (name: 'knexQueryFiltering') => unknown, alias?: string, purpose: string, filters?: Record<string, unknown> }} request
+   */
+  const dataScopedQuery = async ({ scopeName, context, runHooks, alias, purpose, filters }) => {
+    const storageAdapter = getScopeStorageAdapter(scopeName)
+    if (!storageAdapter) throw new Error(`Storage adapter for resource '${scopeName}' not found`)
+    context.storageAdapter = storageAdapter
+    const descriptor = getDescriptor(scopeName)
+    const db = context.db || context.transaction || api.knex.instance
+    const tableAlias = alias || context.schemaInfo.tableName || descriptor.resource
+    const filteredState = await withQueryFilteringContext(context, {
+      query: storageAdapter.buildBaseQuery({ transaction: db, tableAlias }),
+      filters,
+      schemaInfo: context.schemaInfo,
+      scopeName,
+      tableName: tableAlias,
+      db,
+      queryPurpose: purpose,
+      isAnyApi: true,
+      adapter: storageAdapter,
+      storageAdapter,
+    }, async () => {
+      await applyBuiltInAnyApiQueryFilters(context)
+      await runHooks('knexQueryFiltering')
+    })
+    // Wrapped: a builder is thenable, so an async function cannot return it bare.
+    return { query: filteredState.query, alias: tableAlias }
+  }
+
+  // A get with no reader of the minimal record reads once, scoped.
+  /** @type {NonNullable<CanonicalDataReadHelpers['dataGetScoped']>} */
+  const dataGetScoped = ({ scopeName, context, runHooks }) => dataGet({ scopeName, context, runHooks, scoped: true })
+
   return {
+    dataScopedQuery,
     dataExists,
     dataPost,
     dataPut,
     dataPatch,
     dataDelete,
     dataGet,
+    dataGetScoped,
     dataQuery,
     dataAggregate,
     dataGetMinimal