json-rest-api 1.0.24 → 1.0.26

package/plugins/core/rest-api-knex-plugin.js

@@ -38,6 +38,7 @@ import {
   parseSortEntry
 } from './lib/querying/query-field-sort-helpers.js'
 import { unwrapQueryBuilderState } from './lib/querying/query-builder-utils.js'
+import { serializeJsonApiQuery } from './lib/querying-writing/connectors-query-parser.js'
 
 export const RestApiKnexPlugin = {
   name: 'rest-api-knex',
@@ -456,7 +457,14 @@ export const RestApiKnexPlugin = {
      * @param {Object} params.context.db - Database connection (knex instance or transaction)
      * @returns {Promise<Object|null>} JSON:API formatted resource with belongsTo relationships, or null if not found
      */
-    helpers.dataGetMinimal = async ({ scopeName, context, runHooks, applyQueryFilters }) => {
+    helpers.dataGetMinimal = async ({
+      scopeName,
+      context,
+      runHooks,
+      applyQueryFilters,
+      filters = context.queryParams?.filters,
+      queryPurpose = 'single'
+    }) => {
       const storageAdapter = getScopeStorageAdapter(scopeName)
       if (storageAdapter) {
         context.storageAdapter = storageAdapter
@@ -482,29 +490,37 @@ export const RestApiKnexPlugin = {
       if (typeof applyQueryFilters === 'function') {
         const scopedQueryState = await applyQueryFilters({
           query,
-          filters: context.queryParams?.filters,
+          filters,
           tableName,
           db,
           scopeName,
+          queryPurpose,
           storageAdapter
         })
         query = unwrapQueryBuilderState(scopedQueryState, query)
       } else if (runHooks) {
+        const previousKnexQuery = context.knexQuery
         context.knexQuery = {
           query,
-          filters: context.queryParams?.filters,
+          filters,
           schemaInfo: context.schemaInfo,
           scopeName,
           tableName,
           db,
+          queryPurpose,
           adapter: storageAdapter,
           storageAdapter,
         }
 
-        await runHooks('knexQueryFiltering')
-
-        if (context.knexQuery) {
-          delete context.knexQuery
+        try {
+          await runHooks('knexQueryFiltering')
+          query = context.knexQuery?.query || query
+        } finally {
+          if (previousKnexQuery === undefined) {
+            delete context.knexQuery
+          } else {
+            context.knexQuery = previousKnexQuery
+          }
         }
       }
 
@@ -620,7 +636,9 @@ export const RestApiKnexPlugin = {
           scopeName,
           tableName,
           db,
+          queryPurpose: 'collection',
           adapter: storageAdapter,
+          storageAdapter,
         }
 
         log.trace('[DATA-QUERY] Stored data in context', { hasStoredData: !!context.knexQuery, filters: queryParams.filters })
@@ -708,7 +726,13 @@ export const RestApiKnexPlugin = {
               sortDescriptors,
               cursorData,
               (direction) => (direction === 'DESC' ? '<' : '>'),
-              (builder, descriptor, operator, value) => builder.where(descriptor.column, operator, value),
+              (builder, descriptor, operator, value) => builder.where(
+                descriptor.column,
+                operator,
+                storageAdapter?.translateFilterValue
+                  ? storageAdapter.translateFilterValue(descriptor.field, value)
+                  : value
+              ),
               {
                 onMissingValue: (fieldName) => log.warn(`Cursor missing value for sort field: ${fieldName}`)
               }
@@ -736,7 +760,13 @@ export const RestApiKnexPlugin = {
               sortDescriptors,
               cursorData,
               (direction) => (direction === 'DESC' ? '>' : '<'),
-              (builder, descriptor, operator, value) => builder.where(descriptor.column, operator, value),
+              (builder, descriptor, operator, value) => builder.where(
+                descriptor.column,
+                operator,
+                storageAdapter?.translateFilterValue
+                  ? storageAdapter.translateFilterValue(descriptor.field, value)
+                  : value
+              ),
               {
                 onMissingValue: (fieldName) => log.warn(`Cursor missing value for sort field: ${fieldName}`)
               }
@@ -755,38 +785,10 @@ export const RestApiKnexPlugin = {
       // Execute query
       const records = await query
 
-      // Store query string for response building
-      const queryParts = []
-      Object.entries(queryParams).forEach(([key, value]) => {
-        if (Array.isArray(value)) {
-          // Handle arrays (like sort, include)
-          if (value.length > 0) {
-            queryParts.push(`${key}=${value.map(v => encodeURIComponent(v)).join(',')}`)
-          }
-        } else if (typeof value === 'object' && value !== null) {
-          // Handle nested objects (like filters, fields, page)
-          Object.entries(value).forEach(([subKey, subValue]) => {
-            if (subValue !== undefined && subValue !== null) {
-              if (typeof subValue === 'object' && !Array.isArray(subValue)) {
-                // Handle deeply nested objects (like filters[country][code])
-                Object.entries(subValue).forEach(([subSubKey, subSubValue]) => {
-                  if (subSubValue !== undefined && subSubValue !== null) {
-                    queryParts.push(`${key}[${subKey}][${subSubKey}]=${encodeURIComponent(subSubValue)}`)
-                  }
-                })
-              } else {
-                queryParts.push(`${key}[${subKey}]=${encodeURIComponent(subValue)}`)
-              }
-            }
-          })
-        } else if (value !== undefined && value !== null) {
-          queryParts.push(`${key}=${encodeURIComponent(value)}`)
-        }
-      })
-
       // Initialize returnMeta namespace for thread-safe metadata
       context.returnMeta = context.returnMeta || {}
-      context.returnMeta.queryString = queryParts.length > 0 ? `?${queryParts.join('&')}` : ''
+      const queryString = serializeJsonApiQuery(queryParams)
+      context.returnMeta.queryString = queryString ? `?${queryString}` : ''
 
       // Execute count query for pagination if offset-based pagination is used
       if (queryParams.page?.number !== undefined || (queryParams.page?.size !== undefined && !queryParams.page?.after && !queryParams.page?.before)) {
@@ -796,28 +798,31 @@ export const RestApiKnexPlugin = {
         // Only execute count query if enabled
         if (scope.vars.enablePaginationCounts) {
           // Build count query with same filters as main query
-          const countQuery = db(tableName)
-
-          // Apply filters through hooks (same as main query)
-          if (queryParams.filters && Object.keys(queryParams.filters).length > 0) {
-            // Store query data in context for hooks
-            if (context) {
-              context.knexQuery = {
-                query: countQuery,
-                filters: queryParams.filters,
-                scopeName,
-                tableName,
-                schemaInfo,
-                db
-              }
-            }
+          let countQuery = db(tableName)
+
+          // Mandatory server-side filters must also run when the client supplied no filters.
+          // Otherwise pagination metadata can disclose or count rows excluded from the page.
+          const previousKnexQuery = context.knexQuery
+          context.knexQuery = {
+            query: countQuery,
+            filters: queryParams.filters,
+            scopeName,
+            tableName,
+            schemaInfo,
+            db,
+            queryPurpose: 'count',
+            adapter: storageAdapter,
+            storageAdapter
+          }
 
-            // Run the same filtering hooks
+          try {
             await runHooks('knexQueryFiltering')
-
-            // Clean up
-            if (context && context.knexQuery) {
+            countQuery = context.knexQuery?.query || countQuery
+          } finally {
+            if (previousKnexQuery === undefined) {
               delete context.knexQuery
+            } else {
+              context.knexQuery = previousKnexQuery
             }
           }
 
@@ -863,7 +868,9 @@ export const RestApiKnexPlugin = {
 
         const sortFields = sortDescriptors.map((descriptor) => descriptor.field)
 
-        context.returnMeta.paginationMeta = buildCursorMeta(records, pageSize, hasMore, sortFields)
+        context.returnMeta.paginationMeta = buildCursorMeta(records, pageSize, hasMore, sortFields, {
+          schemaInfo
+        })
         const urlPrefix = getUrlPrefix(context, scope)
         context.returnMeta.paginationLinks = generateCursorPaginationLinks(
           urlPrefix,
@@ -872,7 +879,10 @@ export const RestApiKnexPlugin = {
           records,
           pageSize,
           hasMore,
-          sortFields
+          sortFields,
+          {
+            schemaInfo
+          }
         )
       }
 

package/plugins/core/rest-api-plugin-hooks/turn-scope-init-into-vars.js

@@ -1,3 +1,5 @@
+import { normalizeReturnRecordSetting } from '../lib/querying-writing/return-record-settings.js'
+
 export default async function turnScopeInitIntoVars ({ context, scopes, vars: apiVars }) {
   // Refer to the scope's vars
   const scope = scopes[context.scopeName]
@@ -19,8 +21,12 @@ export default async function turnScopeInitIntoVars ({ context, scopes, vars: ap
   if (typeof scopeOptions.simplifiedTransport !== 'undefined') vars.simplifiedTransport = scopeOptions.simplifiedTransport
 
   // Set returnRecord settings as scope vars
-  if (typeof scopeOptions.returnRecordApi !== 'undefined') vars.returnRecordApi = scopeOptions.returnRecordApi
-  if (typeof scopeOptions.returnRecordTransport !== 'undefined') vars.returnRecordTransport = scopeOptions.returnRecordTransport
+  if (typeof scopeOptions.returnRecordApi !== 'undefined') {
+    vars.returnRecordApi = normalizeReturnRecordSetting(scopeOptions.returnRecordApi, vars.returnRecordApi || 'full')
+  }
+  if (typeof scopeOptions.returnRecordTransport !== 'undefined') {
+    vars.returnRecordTransport = normalizeReturnRecordSetting(scopeOptions.returnRecordTransport, vars.returnRecordTransport || 'no')
+  }
 
   // Set idProperty as scope var
   if (typeof scopeOptions.idProperty !== 'undefined') vars.idProperty = scopeOptions.idProperty

package/plugins/core/rest-api-plugin-methods/common.js

@@ -5,7 +5,16 @@ import {
 import { transformSimplifiedToJsonApi } from '../lib/querying-writing/simplified-helpers.js'
 import { normalizeRelationshipIdentifiers } from '../lib/querying-writing/resource-id-normalization.js'
 import { createEnhancedLogger } from '../../../lib/enhanced-logger.js'
-import { unwrapQueryBuilderState } from '../lib/querying/query-builder-utils.js'
+import {
+  normalizeReturnRecordMode,
+  normalizeReturnRecordSetting
+} from '../lib/querying-writing/return-record-settings.js'
+import {
+  getRequestContracts,
+  validateRequestContractOrThrow
+} from '../lib/querying-writing/request-contracts.js'
+
+export { normalizeReturnRecordMode as normalizeReturnValue }
 
 /**
  * Gets an enhanced logger instance with full error details and stack traces
@@ -29,16 +38,6 @@ export const getEnhancedLogger = (log) => {
 export const cascadeConfig = (settingName, sources, defaultValue) =>
   sources.find(source => source?.[settingName] !== undefined)?.[settingName] ?? defaultValue
 
-/**
- * Normalizes return record settings to valid values
- * @param {string|boolean} value - The value to normalize
- * @returns {string} Normalized value: 'no', 'minimal', or 'full'
- */
-export function normalizeReturnValue (value) {
-  if (['no', 'minimal', 'full'].includes(value)) return value
-  return 'no' // default
-}
-
 /**
  * Sets up common request context for REST API methods
  * Handles simplified mode, transaction setup, and initial validation
@@ -76,7 +75,7 @@ export async function setupCommonRequest ({ params, context, vars, scopes, scope
     } else {
       context.inputRecord = params
       // Preserve returnFullRecord if specified in params
-      context.params = params.returnFullRecord ? { returnFullRecord: params.returnFullRecord } : {}
+      context.params = params.returnFullRecord !== undefined ? { returnFullRecord: params.returnFullRecord } : {}
     }
   } else {
     context.inputRecord = params.inputRecord
@@ -90,33 +89,10 @@ export async function setupCommonRequest ({ params, context, vars, scopes, scope
   const defaultReturnFullRecord = isTransport ? vars.returnRecordTransport : vars.returnRecordApi
 
   // Get return record setting - from params only (per-call override) or use default
-  const returnFullRecordRaw = context.params.returnFullRecord !== undefined
-    ? context.params.returnFullRecord
-    : defaultReturnFullRecord
-
-  // Normalize return record setting to always be an object with method keys
-  if (typeof returnFullRecordRaw === 'object' && returnFullRecordRaw !== null) {
-    // It's already an object, normalize the values
-    context.returnRecordSetting = {
-      post: normalizeReturnValue(returnFullRecordRaw.post),
-      put: normalizeReturnValue(returnFullRecordRaw.put),
-      patch: normalizeReturnValue(returnFullRecordRaw.patch)
-    }
-  } else {
-    // It's a single value (string or boolean), apply to all methods
-    const normalized = normalizeReturnValue(returnFullRecordRaw)
-    context.returnRecordSetting = {
-      post: normalized,
-      put: normalized,
-      patch: normalized
-    }
-  }
-
-  // Helper function to normalize return values (same as above)
-  function normalizeReturnValue (value) {
-    if (['no', 'minimal', 'full'].includes(value)) return value
-    return 'no' // default
-  }
+  context.returnRecordSetting = normalizeReturnRecordSetting(
+    context.params.returnFullRecord,
+    defaultReturnFullRecord
+  )
 
   // These only make sense as parameter per query, not in vars etc.
   context.queryParams = params.queryParams || {}
@@ -161,7 +137,7 @@ export async function setupCommonRequest ({ params, context, vars, scopes, scope
  */
 export const handleWriteMethodError = async (error, context, method, scopeName, log, runHooks) => {
   // Rollback transaction if we created it
-  if (context.shouldCommit) {
+  if (context.shouldCommit && !context.transactionCommitted) {
     await context.transaction.rollback()
     await runHooks('afterRollback')
   }
@@ -179,6 +155,39 @@ export const handleWriteMethodError = async (error, context, method, scopeName,
   throw error
 }
 
+export const commitOwnedTransaction = async (context, runHooks) => {
+  if (!context.shouldCommit) {
+    return
+  }
+
+  await context.transaction.commit()
+  context.transactionCommitted = true
+  await runHooks('afterCommit')
+}
+
+export const validateRelationshipRoutePayload = ({
+  context,
+  vars,
+  scopeName,
+  operation,
+  relationshipData
+}) => {
+  const contracts = getRequestContracts({
+    scopeName,
+    schemaInfo: context.schemaInfo,
+    includeDepthLimit: vars.includeDepthLimit,
+    sortableFields: vars.sortableFields
+  })
+
+  const validated = validateRequestContractOrThrow(
+    contracts[operation],
+    { data: relationshipData },
+    `${operation} relationship request body is invalid`
+  )
+
+  return validated.data
+}
+
 /**
  * Validates that a pivot resource exists for many-to-many relationships
  *
@@ -473,31 +482,18 @@ export const validateRelationshipAccess = async (context, inputRecord, helpers,
         isUpdate: false
       }
 
-      const targetScope = api.resources?.[item.type]
-      const applyQueryFilters = targetScope?.applyQueryFilters
-        ? async ({ query, filters, tableName, db, scopeName, storageAdapter, isAnyApi }) => {
-          const queryState = await targetScope.applyQueryFilters({
-            query,
-            filters,
-            schemaInfo: getContext.schemaInfo,
-            scopeName,
-            tableName,
-            db,
-            isAnyApi,
-            storageAdapter
-          }, getContext)
-
-          return {
-            query: unwrapQueryBuilderState(queryState, query)
-          }
-        }
-        : undefined
-
       // Get the minimal record
       const record = await helpers.dataGetMinimal({
         scopeName: item.type,
         context: getContext,
-        applyQueryFilters
+        applyQueryFilters: relatedScope.applyQueryFilters
+          ? (filterParams) => relatedScope.applyQueryFilters({
+              ...filterParams,
+              schemaInfo: getContext.schemaInfo
+            }, getContext)
+          : undefined,
+        filters: {},
+        queryPurpose: 'relationship-validation'
       })
 
       if (!record) {
@@ -524,6 +520,22 @@ export const validateRelationshipAccess = async (context, inputRecord, helpers,
   }
 }
 
+export const getVisibleRelationshipParent = async ({
+  context,
+  helpers,
+  scopeName,
+  runHooks
+}) => {
+  // Related-route filters belong to the target resource, not its parent.
+  return helpers.dataGetMinimal({
+    scopeName,
+    context,
+    runHooks,
+    filters: {},
+    queryPurpose: 'relationship-parent'
+  })
+}
+
 /**
  * Applies field setters to transform attribute values before storage
  * Setters are applied in dependency order to handle interdependent fields
@@ -570,8 +582,18 @@ export const applyFieldSetters = async (attributes, schemaInfo, context, api, he
         setterContext
       )
     } catch (error) {
-      console.warn(`Setter for field '${fieldName}' failed:`, error)
-      // Keep original value if setter fails
+      const message = error instanceof Error ? error.message : String(error)
+      throw new RestApiValidationError(
+        `Setter for field '${fieldName}' failed: ${message}`,
+        {
+          fields: [`data.attributes.${fieldName}`],
+          violations: [{
+            field: `data.attributes.${fieldName}`,
+            rule: 'setter_failed',
+            message
+          }]
+        }
+      )
     }
   }
 

package/plugins/core/rest-api-plugin-methods/delete-relationship.js

@@ -1,5 +1,11 @@
-import { RestApiResourceError, RestApiValidationError, RestApiPayloadError } from '../../../lib/rest-api-errors.js'
-import { findRelationshipDefinition, handleWriteMethodError } from './common.js'
+import { RestApiResourceError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
+import {
+  commitOwnedTransaction,
+  findRelationshipDefinition,
+  getVisibleRelationshipParent,
+  handleWriteMethodError,
+  validateRelationshipRoutePayload
+} from './common.js'
 import {
   normalizeRelationshipIdentifiers,
   requireExistingResourceId
@@ -48,22 +54,28 @@ export default async function deleteRelationshipMethod ({ params, context, vars,
       )
     }
 
-    if (!Array.isArray(params.relationshipData)) {
-      throw new RestApiPayloadError('DELETE from relationship requires array of resource identifiers')
-    }
+    params.relationshipData = validateRelationshipRoutePayload({
+      context,
+      vars,
+      scopeName,
+      operation: 'deleteRelationship',
+      relationshipData: params.relationshipData
+    })
     params.relationshipData = normalizeRelationshipIdentifiers(params.relationshipData, { api })
 
     // Check permissions
     await runHooks('checkPermissions')
     await runHooks('checkPermissionsDeleteRelationship')
 
-    // Verify parent exists
-    const exists = await helpers.dataExists({
+    // Verify the parent exists in the caller's visible dataset.
+    const parentRecord = await getVisibleRelationshipParent({
+      context,
+      helpers,
       scopeName,
-      context: { db: context.db, id: context.id, schemaInfo: context.schemaInfo }
+      runHooks
     })
 
-    if (!exists) {
+    if (!parentRecord) {
       throw new RestApiResourceError('Resource not found', { subtype: 'not_found' })
     }
 
@@ -108,16 +120,14 @@ export default async function deleteRelationshipMethod ({ params, context, vars,
           },
           transaction: context.transaction,
           simplified: false
-        })
+        }, { ...context })
       }
     }
 
     await runHooks('finish')
     await runHooks('finishDeleteRelationship')
 
-    if (context.shouldCommit) {
-      await context.transaction.commit()
-    }
+    await commitOwnedTransaction(context, runHooks)
 
     // 204 No Content
   } catch (error) {

package/plugins/core/rest-api-plugin-methods/delete.js

@@ -1,5 +1,5 @@
 import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
-import { handleWriteMethodError } from './common.js'
+import { commitOwnedTransaction, handleWriteMethodError } from './common.js'
 import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
 
 /**
@@ -96,11 +96,7 @@ export default async function deleteMethod ({
     await runHooks('finish')
     await runHooks('finishDelete')
 
-    // Commit transaction if we created it
-    if (context.shouldCommit) {
-      await context.transaction.commit()
-      await runHooks('afterCommit')
-    }
+    await commitOwnedTransaction(context, runHooks)
 
     // DELETE typically returns void/undefined (204 No Content)
   } catch (error) {

package/plugins/core/rest-api-plugin-methods/get-related.js

@@ -1,5 +1,5 @@
 import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
-import { findRelationshipDefinition } from './common.js'
+import { findRelationshipDefinition, getVisibleRelationshipParent } from './common.js'
 import { buildRelationshipUrl } from '../lib/querying/url-helpers.js'
 import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
 
@@ -57,13 +57,15 @@ export default async function getRelatedMethod ({ params, context, vars, helpers
   await runHooks('checkPermissions')
   await runHooks('checkPermissionsGetRelated')
 
-  // Verify parent exists
-  const exists = await helpers.dataExists({
+  // Verify the parent exists in the caller's visible dataset.
+  const parentRecord = await getVisibleRelationshipParent({
+    context,
+    helpers,
     scopeName,
-    context: { db: context.db, id: context.id, schemaInfo: context.schemaInfo }
+    runHooks
   })
 
-  if (!exists) {
+  if (!parentRecord) {
     throw new RestApiResourceError('Resource not found', { subtype: 'not_found' })
   }
 
@@ -102,7 +104,7 @@ export default async function getRelatedMethod ({ params, context, vars, helpers
         transaction: context.transaction,
         simplified: false,
         isTransport: params.isTransport
-      })
+      }, { ...context })
 
       const relatedId = parent.data.relationships?.[context.relationshipName]?.data?.id
       if (!relatedId) {
@@ -119,7 +121,7 @@ export default async function getRelatedMethod ({ params, context, vars, helpers
         transaction: context.transaction,
         simplified: false,
         isTransport: params.isTransport
-      })
+      }, { ...context })
 
       return {
         links: { self: buildRelationshipUrl(context, scope, scopeName, context.id, context.relationshipName, false) },
@@ -140,7 +142,7 @@ export default async function getRelatedMethod ({ params, context, vars, helpers
         transaction: context.transaction,
         simplified: false,
         isTransport: params.isTransport
-      })
+      }, { ...context })
 
       // Extract the related resource from the parent's relationships
       const relatedId = parent.data.relationships?.[context.relationshipName]?.data?.id
@@ -194,7 +196,7 @@ export default async function getRelatedMethod ({ params, context, vars, helpers
         transaction: context.transaction,
         simplified: false,
         isTransport: params.isTransport
-      })
+      }, { ...context })
 
       if (!result.links) {
         result.links = {}
@@ -228,7 +230,7 @@ export default async function getRelatedMethod ({ params, context, vars, helpers
         transaction: context.transaction,
         simplified: false,
         isTransport: params.isTransport
-      })
+      }, { ...context })
 
       if (!result.links) {
         result.links = {}
@@ -256,7 +258,7 @@ export default async function getRelatedMethod ({ params, context, vars, helpers
           transaction: context.transaction,
           simplified: false,
           isTransport: params.isTransport,
-        })
+        }, { ...context })
         if (related?.data) {
           results.push(related.data)
         }
@@ -307,7 +309,7 @@ export default async function getRelatedMethod ({ params, context, vars, helpers
       transaction: context.transaction,
       simplified: false,
       isTransport: params.isTransport
-    })
+    }, { ...context })
     let includedResources = pivotResult.included?.filter((r) => r.type === targetType) || []
 
     if (includedResources.length === 0) {
@@ -339,7 +341,7 @@ export default async function getRelatedMethod ({ params, context, vars, helpers
             transaction: context.transaction,
             simplified: false,
             isTransport: params.isTransport,
-          })
+          }, { ...context })
           if (related?.data) {
             includedResources.push(related.data)
           }

package/plugins/core/rest-api-plugin-methods/get-relationship.js

@@ -46,7 +46,7 @@ export default async function getRelationshipMethod ({ params, context, vars, he
     transaction: context.transaction,
     simplified: false,
     isTransport: params.isTransport
-  })
+  }, { ...context })
 
   if (!fullRecord || !fullRecord.data) {
     throw new RestApiResourceError('Resource not found', { subtype: 'not_found' })