json-rest-api 1.0.23 → 1.0.24

package/plugins/core/lib/querying-writing/resource-id-normalization.js

@@ -0,0 +1,131 @@
+import {
+  RestApiResourceError,
+  RestApiValidationError
+} from '../../../../lib/rest-api-errors.js'
+
+export function defaultNormalizeResourceId (value) {
+  if (value === null || value === undefined) {
+    return null
+  }
+
+  if (typeof value === 'string') {
+    const normalized = value.trim()
+    return normalized || null
+  }
+
+  if (typeof value === 'number') {
+    return Number.isFinite(value) ? String(value) : null
+  }
+
+  if (typeof value === 'bigint') {
+    return String(value)
+  }
+
+  const normalized = String(value).trim()
+  return normalized || null
+}
+
+export function resolveResourceIdNormalizer ({ scopeOptions = null, vars = null } = {}) {
+  if (typeof scopeOptions?.normalizeId === 'function') {
+    return scopeOptions.normalizeId
+  }
+
+  if (typeof vars?.normalizeId === 'function') {
+    return vars.normalizeId
+  }
+
+  return defaultNormalizeResourceId
+}
+
+export function normalizeResourceId (value, options = {}) {
+  const normalizer = resolveResourceIdNormalizer(options)
+  return defaultNormalizeResourceId(normalizer(value))
+}
+
+export function requireExistingResourceId (value, {
+  scopeOptions = null,
+  vars = null,
+  scopeName = ''
+} = {}) {
+  const normalizedId = normalizeResourceId(value, { scopeOptions, vars })
+  if (normalizedId) {
+    return normalizedId
+  }
+
+  throw new RestApiResourceError(
+    'Resource not found',
+    {
+      subtype: 'not_found',
+      resourceType: scopeName,
+      resourceId: value == null ? null : String(value)
+    }
+  )
+}
+
+export function requireDocumentResourceId (value, {
+  scopeOptions = null,
+  vars = null
+} = {}) {
+  const normalizedId = normalizeResourceId(value, { scopeOptions, vars })
+  if (normalizedId) {
+    return normalizedId
+  }
+
+  throw new RestApiValidationError(
+    'Resource document id is invalid',
+    {
+      fields: ['data.id'],
+      violations: [{
+        field: 'data.id',
+        rule: 'invalid_resource_id',
+        message: 'Resource document id must normalize to a non-empty value.'
+      }]
+    }
+  )
+}
+
+function resolveResourceNormalizationOptions (resourceType, { api } = {}) {
+  const scope = api?.resources?.[resourceType]
+  return {
+    scopeOptions: scope?.scopeOptions || scope?._scopeOptions || null,
+    vars: scope?.vars || null,
+    scopeName: resourceType
+  }
+}
+
+export function requireReferencedResourceId (resourceType, value, { api } = {}) {
+  return requireExistingResourceId(
+    value,
+    resolveResourceNormalizationOptions(resourceType, { api })
+  )
+}
+
+function normalizeRelationshipIdentifier (identifier, { api } = {}) {
+  if (!identifier || typeof identifier !== 'object' || Array.isArray(identifier)) {
+    return identifier
+  }
+
+  const type = typeof identifier.type === 'string' ? identifier.type : ''
+  if (!type || !Object.hasOwn(identifier, 'id')) {
+    return {
+      ...identifier
+    }
+  }
+
+  return {
+    ...identifier,
+    id: requireReferencedResourceId(type, identifier.id, { api })
+  }
+}
+
+export function normalizeRelationshipIdentifiers (relationshipData, { api } = {}) {
+  if (Array.isArray(relationshipData)) {
+    return relationshipData.map((identifier) => normalizeRelationshipIdentifier(identifier, { api }))
+  }
+
+  if (relationshipData == null) {
+    return relationshipData
+  }
+
+  return normalizeRelationshipIdentifier(relationshipData, { api })
+}

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

@@ -9,8 +9,6 @@
  * - Detecting circular dependencies in field definitions
  */
 
-import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
-
 /**
  * Marks all fields in a searchSchema as indexed for database optimization
  *

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

@@ -280,22 +280,15 @@ export const transformSimplifiedToJsonApi = (scope, deps) => {
         relationshipsData[relName] = {
           data: value.map(relId => ({ type: targetType, id: String(relId) }))
         }
-      }
-      // Handle hasOne relationships
-      else if (relConfig.type === 'hasOne' && value !== undefined) {
+      } else if (relConfig.type === 'hasOne' && value !== undefined) {
         relationshipsData[relName] = {
           data: value ? { type: relConfig.target, id: String(value) } : null
         }
-      }
-      // Handle single belongsTo relationships if they were also defined in 'relationships'
-      // (though typically they are defined in schema.belongsTo)
-      else if (relConfig.belongsTo && value !== undefined) {
+      } else if (relConfig.belongsTo && value !== undefined) {
         relationshipsData[relName] = {
           data: value ? { type: relConfig.belongsTo, id: String(value) } : null
         }
-      }
-      // Handle polymorphic belongsTo relationships with minimal object format
-      else if (relConfig.belongsToPolymorphic && value !== undefined) {
+      } else if (relConfig.belongsToPolymorphic && value !== undefined) {
         if (value === null) {
           relationshipsData[relName] = { data: null }
         } else if (typeof value === 'object' && value !== null && value.id && value._type) {
@@ -780,7 +773,7 @@ export const transformSingleJsonApiToSimplified = (scope, deps) => {
       const schemaEntry = Object.entries(schema).find(([_, def]) => def.as === relName)
 
       if (schemaEntry) {
-        const [fieldName, fieldDef] = schemaEntry
+        const [, fieldDef] = schemaEntry
         if (fieldDef.belongsTo && relData.data) {
           // Create minimal relationship object (no more foreign key field)
           simplified[relName] = { id: relData.data.id }

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

@@ -23,9 +23,29 @@ export const translateCanonicalAttributesForStorage = (attributes = {}, descript
   return row
 }
 
+export const getCanonicalResourceIdColumn = (descriptor = {}) => (
+  descriptor?.canonical?.logicalIdColumn || 'logical_id'
+)
+
+export const getCanonicalResourceId = (row = {}, descriptor = {}) => {
+  const logicalIdColumn = getCanonicalResourceIdColumn(descriptor)
+  const logicalId = row?.[logicalIdColumn]
+
+  if (logicalId !== undefined && logicalId !== null) {
+    return String(logicalId)
+  }
+
+  if (row?.id !== undefined && row?.id !== null) {
+    return String(row.id)
+  }
+
+  return null
+}
+
 export const translateCanonicalRecordFromStorage = (row = {}, descriptor = {}, options = {}) => {
   const attributes = {}
-  const consumedColumns = new Set(['id'])
+  const logicalIdColumn = getCanonicalResourceIdColumn(descriptor)
+  const consumedColumns = new Set(['id', logicalIdColumn])
   const allowedExtraFields = new Set(options.allowedExtraFields || [])
 
   for (const [slot, logical] of Object.entries(descriptor.reverseAttributes || {})) {
@@ -97,7 +117,7 @@ export const getCanonicalFieldValue = (row, descriptor = {}, fieldName) => {
   if (!row || !fieldName) return undefined
 
   if (fieldName === 'id') {
-    return row.id
+    return getCanonicalResourceId(row, descriptor)
   }
 
   const fieldInfo = descriptor.fields?.[fieldName]

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

@@ -6,6 +6,7 @@ import {
 } from './storage-mapping.js'
 import {
   getCanonicalFieldValue,
+  getCanonicalResourceIdColumn,
   translateCanonicalAttributesForStorage,
 } from './canonical-storage-mapping.js'
 
@@ -146,7 +147,7 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
 
   const translateColumn = (field) => {
     if (!field) return field
-    if (field === 'id') return 'id'
+    if (field === 'id') return getCanonicalResourceIdColumn(descriptor)
 
     const canonicalEntry = canonicalFieldMap[field]
     if (typeof canonicalEntry === 'string') {
@@ -214,7 +215,7 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
   return baseAdapter({
     knex,
     tableName: canonical.tableName,
-    idColumn: 'id',
+    idColumn: getCanonicalResourceIdColumn(descriptor),
     translateColumn,
     translateFilterValue,
     applyResourceScope,

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

@@ -1,5 +1,8 @@
 const EMPTY_STORAGE_INFO = Object.freeze({
   idColumn: 'id',
+  storage: Object.freeze({
+    naming: 'snake_case'
+  }),
   fields: Object.freeze({}),
   columns: Object.freeze({})
 })
@@ -10,14 +13,75 @@ const isPlainObject = (value) => (
   !Array.isArray(value)
 )
 
-export const normalizeFieldStorage = (fieldName, definition = {}, { idColumn = 'id' } = {}) => {
-  const storage = definition.storage
+const SNAKE_CASE_STORAGE_NAMING = 'snake_case'
+const EXACT_STORAGE_NAMING = 'exact'
 
-  if (storage !== undefined && !isPlainObject(storage)) {
+const STORAGE_NAMING_ALIASES = Object.freeze({
+  snake: SNAKE_CASE_STORAGE_NAMING,
+  snake_case: SNAKE_CASE_STORAGE_NAMING,
+  snakeCase: SNAKE_CASE_STORAGE_NAMING,
+  exact: EXACT_STORAGE_NAMING,
+  field: EXACT_STORAGE_NAMING,
+  verbatim: EXACT_STORAGE_NAMING
+})
+
+const toSnakeCase = (value) => String(value)
+  .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+  .replace(/([A-Z]+)([A-Z][a-z0-9])/g, '$1_$2')
+  .toLowerCase()
+
+export const normalizeStorageConfig = (storage = undefined) => {
+  if (storage === undefined || storage === null) {
+    return {
+      naming: SNAKE_CASE_STORAGE_NAMING
+    }
+  }
+
+  if (!isPlainObject(storage)) {
+    throw new Error('Resource storage metadata must be an object.')
+  }
+
+  const rawNaming = storage.naming
+  const naming = rawNaming === undefined
+    ? SNAKE_CASE_STORAGE_NAMING
+    : STORAGE_NAMING_ALIASES[rawNaming]
+
+  if (!naming) {
+    throw new Error(
+      `Invalid resource storage.naming value '${String(rawNaming)}'. Expected 'snake_case' or 'exact'.`
+    )
+  }
+
+  return {
+    ...storage,
+    naming
+  }
+}
+
+const resolveDefaultStorageColumn = (fieldName, { idColumn = 'id', storageConfig = undefined } = {}) => {
+  if (fieldName === 'id') {
+    return idColumn
+  }
+
+  const normalizedStorage = normalizeStorageConfig(storageConfig)
+  if (normalizedStorage.naming === EXACT_STORAGE_NAMING) {
+    return fieldName
+  }
+
+  return toSnakeCase(fieldName)
+}
+
+export const normalizeFieldStorage = (fieldName, definition = {}, { idColumn = 'id', storageConfig = undefined } = {}) => {
+  const fieldStorage = definition.storage
+
+  if (fieldStorage !== undefined && !isPlainObject(fieldStorage)) {
     throw new Error(`Field '${fieldName}' has invalid storage metadata. Expected an object.`)
   }
 
-  const column = storage?.column ?? fieldName
+  const column = fieldStorage?.column ?? resolveDefaultStorageColumn(fieldName, {
+    idColumn,
+    storageConfig
+  })
   if (typeof column !== 'string' || column.trim() === '') {
     throw new Error(`Field '${fieldName}' has an invalid storage.column value.`)
   }
@@ -28,25 +92,29 @@ export const normalizeFieldStorage = (fieldName, definition = {}, { idColumn = '
     )
   }
 
-  if (storage?.serialize !== undefined && typeof storage.serialize !== 'function') {
+  if (fieldStorage?.serialize !== undefined && typeof fieldStorage.serialize !== 'function') {
     throw new Error(`Field '${fieldName}' has an invalid storage.serialize value. Expected a function.`)
   }
 
   return {
     column,
-    serialize: storage?.serialize || null,
+    serialize: fieldStorage?.serialize || null,
     persisted: definition.virtual !== true && definition.computed !== true
   }
 }
 
-export const buildStorageInfo = ({ schemaStructure = {}, idProperty = 'id' } = {}) => {
+export const buildStorageInfo = ({ schemaStructure = {}, idProperty = 'id', storage = undefined } = {}) => {
   const idColumn = idProperty || 'id'
+  const storageConfig = normalizeStorageConfig(storage)
   const fields = {}
   const columns = {}
   const usedColumns = new Map([[idColumn, 'id']])
 
   for (const [fieldName, definition] of Object.entries(schemaStructure)) {
-    const normalized = normalizeFieldStorage(fieldName, definition, { idColumn })
+    const normalized = normalizeFieldStorage(fieldName, definition, {
+      idColumn,
+      storageConfig
+    })
     const isIdSurrogateField = fieldName === idColumn && definition.type === 'id'
 
     if (fieldName !== 'id' && normalized.column === idColumn && !isIdSurrogateField) {
@@ -75,6 +143,7 @@ export const buildStorageInfo = ({ schemaStructure = {}, idProperty = 'id' } = {
 
   return {
     idColumn,
+    storage: storageConfig,
     fields,
     columns
   }
@@ -91,7 +160,8 @@ export const getStorageInfo = (schemaInfo = {}) => {
 
   return buildStorageInfo({
     schemaStructure: schemaInfo.schemaStructure,
-    idProperty: schemaInfo.idProperty || 'id'
+    idProperty: schemaInfo.idProperty || 'id',
+    storage: schemaInfo.storage
   })
 }
 
@@ -165,13 +235,13 @@ export const translateAttributesForStorage = (attributes, schemaInfo = {}, optio
       : fieldStorage?.column || fieldName
     const serializedValue = fieldStorage?.serialize
       ? fieldStorage.serialize(value, {
-          fieldName,
-          columnName,
-          definition: fieldStorage.definition,
-          schemaInfo,
-          context,
-          operation
-        })
+        fieldName,
+        columnName,
+        definition: fieldStorage.definition,
+        schemaInfo,
+        context,
+        operation
+      })
       : value
 
     translated[columnName] = serializedValue

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

@@ -1,5 +1,5 @@
 import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
-import { transformSimplifiedToJsonApi } from '../querying-writing/simplified-helpers.js'
+import { normalizeRelationshipIdentifiers } from '../querying-writing/resource-id-normalization.js'
 
 /**
  * Updates many-to-many relationships intelligently by synchronizing pivot table records
@@ -103,7 +103,8 @@ import { transformSimplifiedToJsonApi } from '../querying-writing/simplified-hel
 export const updateManyToManyRelationship = async (scope, deps) => {
   // Extract values from deps
   const { api, context } = deps
-  const { resourceId, relDef, relData, transaction: trx } = context
+  const { resourceId, relDef, transaction: trx } = context
+  const relData = normalizeRelationshipIdentifiers(context.relData || [], { api })
 
   // Get the knex instance from the pivot scope
   const pivotScope = api.resources[relDef.through]
@@ -257,6 +258,7 @@ export const updateManyToManyRelationship = async (scope, deps) => {
  * 6. Returns (no data returned, throws on error)
  */
 export const createPivotRecords = async (api, resourceId, relDef, relData, trx) => {
+  relData = normalizeRelationshipIdentifiers(relData, { api })
   if (relData.length === 0) return // Early exit if nothing to create
 
   // Get pivot table info