json-rest-api 1.0.24 → 1.0.26

package/plugins/core/lib/querying-writing/database-capabilities.js

@@ -63,7 +63,7 @@ const parseVersion = (versionString) => {
  *
  * @description
  * Used by:
- * - buildWindowedIncludeQuery to validate before using window functions
+ * - buildWindowedIncludeSubquery to validate before using window functions
  * - rest-api-knex-plugin to determine query strategies
  *
  * Purpose:

package/plugins/core/lib/querying-writing/database-value-normalizers.js

@@ -48,7 +48,7 @@
  * 4. Handles MySQL datetime format (no T separator)
  * 5. Forces UTC interpretation to prevent timezone issues
  */
-function normalizeDateValue (value, type) {
+export function normalizeDateValue (value, type) {
   // Handle null/undefined
   if (value === null || value === undefined) {
     return null
@@ -81,25 +81,34 @@ function normalizeDateValue (value, type) {
 
   // Handle string values
   if (typeof value === 'string') {
+    const trimmed = value.trim()
+
+    if (/^-?\d+$/.test(trimmed)) {
+      const numericDate = new Date(Number(trimmed))
+      if (!isNaN(numericDate.getTime())) {
+        return numericDate
+      }
+    }
+
     // Detect MySQL datetime format: 'YYYY-MM-DD HH:MM:SS'
     // These have no T separator and no timezone indicator
     const isMySQLDateTime = type === 'dateTime' &&
-                           /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/.test(value) &&
-                           !value.includes('T') &&
-                           !value.includes('Z') &&
-                           !value.includes('+') &&
-                           !value.includes('-', 10) // Don't match date separators
+                           /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/.test(trimmed) &&
+                           !trimmed.includes('T') &&
+                           !trimmed.includes('Z') &&
+                           !trimmed.includes('+') &&
+                           !trimmed.includes('-', 10) // Don't match date separators
 
     if (isMySQLDateTime) {
       // Convert to ISO format and force UTC interpretation
       // '2024-01-15 10:30:00' becomes '2024-01-15T10:30:00Z'
-      return new Date(value.replace(' ', 'T') + 'Z')
+      return new Date(trimmed.replace(' ', 'T') + 'Z')
     }
 
     // For date-only fields, ensure parsing at UTC midnight
     // This prevents timezone shifts when parsing dates
-    if (type === 'date' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
-      return new Date(value + 'T00:00:00Z')
+    if (type === 'date' && /^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+      return new Date(trimmed + 'T00:00:00Z')
     }
   }
 

package/plugins/core/lib/querying-writing/knex-field-helpers.js

@@ -150,7 +150,8 @@ export const buildFieldSelection = async (scope, deps) => {
   const scopeSchemaInfo = scope?.vars?.schemaInfo || {}
   const {
     schemaInstance,
-    computed: computedFields = {}
+    computed: computedFields = {},
+    idProperty = 'id'
   } = scopeSchemaInfo
   let schemaStructure = scopeSchemaInfo.schemaStructure
   const queryFields = scope?.vars?.queryFields || {}
@@ -196,6 +197,8 @@ export const buildFieldSelection = async (scope, deps) => {
     // Sparse fieldsets requested - only select specified fields
     // Example: ?fields[products]=name,price,profit_margin
     requested.forEach(field => {
+      if (field === 'id' || field === idProperty) return
+
       if (queryFieldNames.has(field)) {
         if (queryFields[field]?.hidden === true) return
         queryFieldsToSelect.add(field)
@@ -261,6 +264,8 @@ export const buildFieldSelection = async (scope, deps) => {
     // No sparse fieldsets - return all visible fields
     // This is the default behavior when no ?fields parameter is provided
     Object.entries(schemaStructure).forEach(([field, fieldDef]) => {
+      if (field === 'id' || field === idProperty) return
+
       // Skip virtual fields - they don't exist in database
       if (fieldDef.virtual === true) return
 

package/plugins/core/lib/querying-writing/relationship-contracts.js

@@ -0,0 +1,56 @@
+import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+
+export function getRelationshipCardinality (relDef) {
+  if (!relDef) return null
+
+  if (
+    relDef.belongsTo ||
+    relDef.belongsToPolymorphic ||
+    relDef.type === 'hasOne'
+  ) {
+    return 'one'
+  }
+
+  if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
+    return 'many'
+  }
+
+  return null
+}
+
+export function validateRelationshipDataCardinality ({
+  relationshipName,
+  relDef,
+  data,
+  fieldPath = `data.relationships.${relationshipName}.data`
+}) {
+  const cardinality = getRelationshipCardinality(relDef)
+
+  if (cardinality === 'one' && Array.isArray(data)) {
+    throw new RestApiValidationError(
+      `Relationship '${relationshipName}' expects a single resource identifier or null`,
+      {
+        fields: [fieldPath],
+        violations: [{
+          field: fieldPath,
+          rule: 'relationship_cardinality',
+          message: 'Expected a single resource identifier or null'
+        }]
+      }
+    )
+  }
+
+  if (cardinality === 'many' && !Array.isArray(data)) {
+    throw new RestApiValidationError(
+      `Relationship '${relationshipName}' expects an array of resource identifiers`,
+      {
+        fields: [fieldPath],
+        violations: [{
+          field: fieldPath,
+          rule: 'relationship_cardinality',
+          message: 'Expected an array of resource identifiers'
+        }]
+      }
+    )
+  }
+}

package/plugins/core/lib/querying-writing/request-contracts.js

@@ -1,5 +1,6 @@
 import { addType, addValidator, createSchema } from 'json-rest-schema'
 import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { getRelationshipCardinality } from './relationship-contracts.js'
 
 function isPlainObject (value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value)
@@ -28,9 +29,20 @@ function buildResourceIdentifierTransportSchema (allowedTypes = null) {
   }
 }
 
-function buildRelationshipDataTransportSchema (allowedTypes = null) {
+function buildRelationshipDataTransportSchema (allowedTypes = null, cardinality = null) {
   const identifierSchema = buildResourceIdentifierTransportSchema(allowedTypes)
 
+  if (cardinality === 'one') {
+    return identifierSchema
+  }
+
+  if (cardinality === 'many') {
+    return {
+      type: 'array',
+      items: identifierSchema
+    }
+  }
+
   return {
     anyOf: [
       identifierSchema,
@@ -156,16 +168,31 @@ function installRequestContractSupport () {
     const allowedTypes = Array.isArray(context.definition.allowedTypes)
       ? context.definition.allowedTypes
       : null
+    const cardinality = context.definition.cardinality || null
 
     if (Array.isArray(context.value)) {
+      if (cardinality === 'one') {
+        context.throwParamError(
+          'INVALID_RELATIONSHIP_CARDINALITY',
+          'Relationship data must be a single resource identifier or null.'
+        )
+      }
       context.value.forEach((entry) => validateResourceIdentifierValue(entry, context, allowedTypes))
       return context.value
     }
 
+    if (cardinality === 'many') {
+      context.throwParamError(
+        'INVALID_RELATIONSHIP_CARDINALITY',
+        'Relationship data must be an array of resource identifiers.'
+      )
+    }
+
     return validateResourceIdentifierValue(context.value, context, allowedTypes)
   }
   jsonApiRelationshipDataType.toJsonSchema = ({ definition }) => buildRelationshipDataTransportSchema(
-    Array.isArray(definition.allowedTypes) ? definition.allowedTypes : null
+    Array.isArray(definition.allowedTypes) ? definition.allowedTypes : null,
+    definition.cardinality || null
   )
   addType('jsonApiRelationshipData', jsonApiRelationshipDataType)
 
@@ -379,6 +406,7 @@ function buildRelationshipStructure (schemaInfo = {}) {
           type: 'jsonApiRelationshipData',
           required: true,
           nullable: true,
+          cardinality: 'one',
           allowedTypes: [fieldDef.belongsTo]
         }
       })
@@ -386,13 +414,15 @@ function buildRelationshipStructure (schemaInfo = {}) {
   }
 
   for (const [relName, relDef] of Object.entries(schemaRelationships)) {
+    const cardinality = getRelationshipCardinality(relDef)
     relationshipStructure[relName] = {
       type: 'object',
       schema: createSchema({
         data: {
           type: 'jsonApiRelationshipData',
           required: true,
-          nullable: true,
+          nullable: cardinality === 'one',
+          cardinality,
           allowedTypes: resolveRelationshipAllowedTypes(relName, relDef)
         }
       })
@@ -520,6 +550,22 @@ function buildQueryRequestContract ({ includeDepthLimit, sortableFields, searchS
   }
 }
 
+function buildRelationshipRouteBodyContract (operation) {
+  const isPatch = operation === 'patchRelationship'
+
+  return {
+    schema: createSchema({
+      data: {
+        type: 'jsonApiRelationshipData',
+        required: true,
+        nullable: isPatch,
+        cardinality: isPatch ? null : 'many'
+      }
+    }),
+    mode: 'replace'
+  }
+}
+
 function buildRequestContracts ({ scopeName, schemaInfo, includeDepthLimit, sortableFields }) {
   return {
     post: buildWriteDocumentContract(scopeName, schemaInfo, 'post'),
@@ -530,7 +576,10 @@ function buildRequestContracts ({ scopeName, schemaInfo, includeDepthLimit, sort
       includeDepthLimit,
       sortableFields,
       searchSchemaInstance: schemaInfo.searchSchemaInstance
-    })
+    }),
+    postRelationship: buildRelationshipRouteBodyContract('postRelationship'),
+    patchRelationship: buildRelationshipRouteBodyContract('patchRelationship'),
+    deleteRelationship: buildRelationshipRouteBodyContract('deleteRelationship')
   }
 }
 

package/plugins/core/lib/querying-writing/return-record-settings.js

@@ -0,0 +1,47 @@
+const RETURN_RECORD_METHODS = ['post', 'put', 'patch']
+const RETURN_RECORD_MODES = ['no', 'minimal', 'full']
+
+export function normalizeReturnRecordMode (value, defaultValue = 'no') {
+  if (value === true) return 'full'
+  if (value === false) return 'no'
+  if (RETURN_RECORD_MODES.includes(value)) return value
+
+  if (defaultValue === true) return 'full'
+  if (defaultValue === false) return 'no'
+  if (RETURN_RECORD_MODES.includes(defaultValue)) return defaultValue
+
+  return 'no'
+}
+
+function defaultModeForMethod (defaultValue, method) {
+  if (defaultValue && typeof defaultValue === 'object' && !Array.isArray(defaultValue)) {
+    return normalizeReturnRecordMode(defaultValue[method], 'no')
+  }
+
+  return normalizeReturnRecordMode(defaultValue, 'no')
+}
+
+export function normalizeReturnRecordSetting (value, defaultValue = 'no') {
+  if (value === undefined) {
+    return Object.fromEntries(
+      RETURN_RECORD_METHODS.map(method => [
+        method,
+        defaultModeForMethod(defaultValue, method)
+      ])
+    )
+  }
+
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return Object.fromEntries(
+      RETURN_RECORD_METHODS.map(method => [
+        method,
+        normalizeReturnRecordMode(value[method], defaultModeForMethod(defaultValue, method))
+      ])
+    )
+  }
+
+  const normalized = normalizeReturnRecordMode(value, defaultModeForMethod(defaultValue, 'post'))
+  return Object.fromEntries(
+    RETURN_RECORD_METHODS.map(method => [method, normalized])
+  )
+}

package/plugins/core/lib/querying-writing/schema-helpers.js

@@ -96,6 +96,36 @@ export function ensureSearchFieldsAreIndexed (searchSchema) {
   })
 }
 
+function createRelationshipSearchEntries (fieldName, fieldDef, searchEntry) {
+  if (!fieldDef?.belongsTo || !fieldDef?.as) {
+    return [[fieldName, searchEntry]]
+  }
+
+  const relationshipEntry = {
+    ...searchEntry,
+    actualField: fieldName,
+    isRelationship: true,
+    targetResource: fieldDef.belongsTo
+  }
+
+  return [
+    [fieldDef.as, relationshipEntry],
+    [fieldName, {
+      ...relationshipEntry
+    }]
+  ]
+}
+
+function registerSearchEntries (searchSchema, entries = []) {
+  for (const [searchFieldName, searchEntry] of entries) {
+    if (!searchFieldName || searchSchema[searchFieldName]) {
+      continue
+    }
+
+    searchSchema[searchFieldName] = searchEntry
+  }
+}
+
 /**
  * Generates complete searchSchema by merging schema search definitions with explicit searchSchema
  *
@@ -241,31 +271,12 @@ export const generateSearchSchemaFromSchema = (schema, explicitSearchSchema) =>
 
     if (effectiveSearch) {
       if (effectiveSearch === true) {
-        // For belongsTo relationships, use the relationship name (as property) instead of the field name
-        const searchFieldName = (fieldDef.belongsTo && fieldDef.as) ? fieldDef.as : fieldName
-
-        // Check if field already exists in explicit searchSchema
-        if (searchSchema[searchFieldName]) {
-          // Skip - explicit searchSchema takes precedence
-          // This allows searchSchema to override fields marked with search:true
-          return
-        }
-
         // Simple boolean - copy entire field definition (except search)
         const { search, ...fieldDefWithoutSearch } = fieldDef
-        const searchEntry = {
+        registerSearchEntries(searchSchema, createRelationshipSearchEntries(fieldName, fieldDef, {
           ...fieldDefWithoutSearch,
           // Do not set filterOperator here; centralized resolver will apply sensible defaults
-        }
-
-        // For belongsTo relationships, add metadata to map back to the actual field
-        if (fieldDef.belongsTo && fieldDef.as) {
-          searchEntry.actualField = fieldName  // Maps to the DB column
-          searchEntry.isRelationship = true
-          searchEntry.targetResource = fieldDef.belongsTo
-        }
-
-        searchSchema[searchFieldName] = searchEntry
+        }))
       } else if (typeof effectiveSearch === 'object') {
         // Check if search defines multiple filter fields
         const hasNestedFilters = Object.values(effectiveSearch).some(
@@ -288,29 +299,11 @@ export const generateSearchSchemaFromSchema = (schema, explicitSearchSchema) =>
             }
           })
         } else {
-          // For belongsTo relationships, use the relationship name (as property) instead of the field name
-          const searchFieldName = (fieldDef.belongsTo && fieldDef.as) ? fieldDef.as : fieldName
-
-          // Check if field already exists in explicit searchSchema
-          if (searchSchema[searchFieldName]) {
-            // Skip - explicit searchSchema takes precedence
-            return
-          }
-
           // Single filter with config
-          const searchEntry = {
+          registerSearchEntries(searchSchema, createRelationshipSearchEntries(fieldName, fieldDef, {
             type: fieldDef.type,
             ...effectiveSearch
-          }
-
-          // For belongsTo relationships, add metadata to map back to the actual field
-          if (fieldDef.belongsTo && fieldDef.as) {
-            searchEntry.actualField = fieldName  // Maps to the DB column
-            searchEntry.isRelationship = true
-            searchEntry.targetResource = fieldDef.belongsTo
-          }
-
-          searchSchema[searchFieldName] = searchEntry
+          }))
         }
       }
     }

package/plugins/core/lib/storage/canonical-storage-mapping.js

@@ -116,7 +116,8 @@ export const translateCanonicalRecordFromStorage = (row = {}, descriptor = {}, o
 export const getCanonicalFieldValue = (row, descriptor = {}, fieldName) => {
   if (!row || !fieldName) return undefined
 
-  if (fieldName === 'id') {
+  const idProperty = descriptor.idProperty || 'id'
+  if (fieldName === 'id' || fieldName === idProperty) {
     return getCanonicalResourceId(row, descriptor)
   }
 

package/plugins/core/lib/storage/storage-adapter.js

@@ -9,6 +9,7 @@ import {
   getCanonicalResourceIdColumn,
   translateCanonicalAttributesForStorage,
 } from './canonical-storage-mapping.js'
+import { normalizeDateValue } from '../querying-writing/database-value-normalizers.js'
 
 const passthrough = (value) => value
 const identityTranslate = (_field, value) => value
@@ -34,6 +35,54 @@ const normalizeBelongsToValue = (value) => {
   return String(value)
 }
 
+const normalizeBooleanValue = (value) => {
+  if (typeof value === 'boolean') return value
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase()
+    if (normalized === 'true' || normalized === '1') return true
+    if (normalized === 'false' || normalized === '0') return false
+  }
+  if (typeof value === 'number') {
+    if (value === 1) return true
+    if (value === 0) return false
+  }
+  return Boolean(value)
+}
+
+const normalizeFilterValueForDefinition = (value, definition = {}, { isRelationship = false } = {}) => {
+  if (value === null || value === undefined) return value
+  if (Array.isArray(value)) {
+    return normalizeArray(
+      value,
+      (entry) => normalizeFilterValueForDefinition(entry, definition, { isRelationship })
+    )
+  }
+
+  if (isRelationship) {
+    return normalizeBelongsToValue(value)
+  }
+
+  const type = definition?.type || definition?.dataType
+  if (!type) {
+    return value
+  }
+
+  if (['number', 'integer', 'float', 'decimal'].includes(type)) {
+    const numeric = Number(value)
+    return Number.isNaN(numeric) ? value : numeric
+  }
+
+  if (type === 'boolean') {
+    return normalizeBooleanValue(value)
+  }
+
+  if (['date', 'dateTime', 'time'].includes(type)) {
+    return normalizeDateValue(value, type)
+  }
+
+  return value
+}
+
 const translateSourceColumn = (source, adapter) => {
   if (!adapter || source === '*') return source
   return adapter.translateColumn(source) || source
@@ -124,13 +173,24 @@ const createLegacyAdapter = ({ knex, schemaInfo }) => {
   const translateColumn = (field) => getStorageColumn(schemaInfo, field)
   const toStorageRow = (attributes, options = {}) => translateAttributesForStorage(attributes, schemaInfo, options)
   const getFieldValue = (record, fieldName) => getLegacyFieldValue(record, schemaInfo, fieldName)
+  const translateFilterValue = (field, value) => {
+    const searchField = schemaInfo.searchSchemaStructure?.[field]
+    const schemaField = schemaInfo.schemaStructure?.[field]
+    const definition = searchField || schemaField || {}
+    const isRelationship = Boolean(
+      searchField?.isRelationship ||
+      schemaField?.belongsTo ||
+      schemaField?.belongsToPolymorphic
+    )
+    return normalizeFilterValueForDefinition(value, definition, { isRelationship })
+  }
 
   return baseAdapter({
     knex,
     tableName,
     idColumn,
     translateColumn,
-    translateFilterValue: identityTranslate,
+    translateFilterValue,
     applyResourceScope: identityScope,
     toStorageRow,
     getFieldValue,
@@ -144,10 +204,15 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
   const canonicalFieldMap = descriptor.canonicalFieldMap || {}
   const fieldsInfo = descriptor.fields || {}
   const belongsToInfo = descriptor.belongsTo || {}
+  const idProperty = schemaInfo.idProperty || descriptor.idProperty || 'id'
+  const isLogicalIdField = (field) => field === 'id' || field === idProperty
+  const descriptorWithIdProperty = descriptor.idProperty === idProperty
+    ? descriptor
+    : { ...descriptor, idProperty }
 
   const translateColumn = (field) => {
     if (!field) return field
-    if (field === 'id') return getCanonicalResourceIdColumn(descriptor)
+    if (isLogicalIdField(field)) return getCanonicalResourceIdColumn(descriptor)
 
     const canonicalEntry = canonicalFieldMap[field]
     if (typeof canonicalEntry === 'string') {
@@ -183,8 +248,6 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
   }
 
   const translateFilterValue = (field, value) => {
-    if (value === null || value === undefined) return value
-
     const searchField = schemaInfo.searchSchemaStructure?.[field]
     const schemaField = schemaInfo.schemaStructure?.[field]
     const isRelationship = Boolean(
@@ -192,15 +255,9 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
       schemaField?.belongsTo ||
       schemaField?.belongsToPolymorphic
     )
+    const definition = searchField || schemaField || {}
 
-    if (!isRelationship) {
-      if (Array.isArray(value)) {
-        return normalizeArray(value, passthrough)
-      }
-      return value
-    }
-
-    return normalizeBelongsToValue(value)
+    return normalizeFilterValueForDefinition(value, definition, { isRelationship })
   }
 
   const applyResourceScope = (query) => {
@@ -210,7 +267,11 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
   }
 
   const toStorageRow = (attributes) => translateCanonicalAttributesForStorage(attributes, descriptor)
-  const getFieldValue = (record, fieldName) => getCanonicalFieldValue(record, descriptor, fieldName)
+  const getFieldValue = (record, fieldName) => (
+    isLogicalIdField(fieldName)
+      ? getCanonicalFieldValue(record, descriptorWithIdProperty, fieldName)
+      : getCanonicalFieldValue(record, descriptor, fieldName)
+  )
 
   return baseAdapter({
     knex,

package/plugins/core/lib/writing/many-to-many-manipulations.js

@@ -136,7 +136,7 @@ export const updateManyToManyRelationship = async (scope, deps) => {
         await api.resources[related.type].get({
           id: related.id,
           transaction: trx
-        })
+        }, { ...context })
       } catch (error) {
         throw new RestApiResourceError(
           `Related ${related.type} with id ${related.id} not found`,
@@ -184,6 +184,7 @@ export const updateManyToManyRelationship = async (scope, deps) => {
  * @param {Object} relDef - The relationship definition
  * @param {Array} relData - Array of related resources to link
  * @param {Object} trx - Database transaction object
+ * @param {Object} [context] - Caller context forwarded to relationship validation
  * @returns {Promise<void>}
  *
  * @example
@@ -257,7 +258,7 @@ export const updateManyToManyRelationship = async (scope, deps) => {
  * 5. Performs single INSERT with all records
  * 6. Returns (no data returned, throws on error)
  */
-export const createPivotRecords = async (api, resourceId, relDef, relData, trx) => {
+export const createPivotRecords = async (api, resourceId, relDef, relData, trx, context = {}) => {
   relData = normalizeRelationshipIdentifiers(relData, { api })
   if (relData.length === 0) return // Early exit if nothing to create
 
@@ -277,7 +278,7 @@ export const createPivotRecords = async (api, resourceId, relDef, relData, trx)
         await api.resources[related.type].get({
           id: related.id,
           transaction: trx
-        })
+        }, { ...context })
       } catch (error) {
         throw new RestApiResourceError(
           `Related ${related.type} with id ${related.id} not found`,

package/plugins/core/lib/writing/relationship-processor.js

@@ -1,4 +1,5 @@
 import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { validateRelationshipDataCardinality } from '../querying-writing/relationship-contracts.js'
 
 /**
  * Processes JSON:API relationship data and converts to database operations
@@ -183,6 +184,14 @@ export const processRelationships = (scope, deps) => {
       fieldDef.as === relName
     )
 
+    if (schemaField || relDef) {
+      validateRelationshipDataCardinality({
+        relationshipName: relName,
+        relDef: schemaField ? schemaField[1] : relDef,
+        data: relData?.data
+      })
+    }
+
     if (schemaField) {
       const [fieldName, fieldDef] = schemaField
 
@@ -235,7 +244,7 @@ export const processRelationships = (scope, deps) => {
           foreignKey: relDef.foreignKey,
           otherKey: relDef.otherKey
         },
-        relData: relData.data || []  // null means empty array for many-to-many
+        relData: relData.data
       })
     }
     // Note: hasOne and hasMany don't need processing here as they don't update the current record