json-rest-api 1.0.22 → 1.0.24

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

@@ -0,0 +1,133 @@
+export const translateCanonicalAttributesForStorage = (attributes = {}, descriptor = {}) => {
+  const row = {}
+
+  for (const [fieldName, value] of Object.entries(attributes)) {
+    const slot = descriptor.fields?.[fieldName]
+    if (!slot) continue
+
+    if (slot.slotType === 'belongsTo') {
+      row[slot.slot] = value == null ? null : String(value)
+    } else {
+      row[slot.slot] = value
+    }
+
+    if (slot.slotType === 'belongsTo') {
+      const alias = slot.alias || descriptor.fields?.[fieldName]?.alias
+      const belongsToInfo = alias ? descriptor.belongsTo?.[alias] : null
+      if (belongsToInfo) {
+        row[belongsToInfo.typeColumn] = value == null ? null : belongsToInfo.target
+      }
+    }
+  }
+
+  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 logicalIdColumn = getCanonicalResourceIdColumn(descriptor)
+  const consumedColumns = new Set(['id', logicalIdColumn])
+  const allowedExtraFields = new Set(options.allowedExtraFields || [])
+
+  for (const [slot, logical] of Object.entries(descriptor.reverseAttributes || {})) {
+    if (slot in row) {
+      attributes[logical] = row[slot]
+      consumedColumns.add(slot)
+    }
+  }
+
+  const relationships = {}
+
+  for (const [alias, info] of Object.entries(descriptor.belongsTo || {})) {
+    const idValue = row[info.idColumn]
+    consumedColumns.add(info.idColumn)
+    if (info.typeColumn) {
+      consumedColumns.add(info.typeColumn)
+    }
+    const relationshipData = idValue == null
+      ? null
+      : { type: info.target, id: String(idValue) }
+
+    relationships[alias] = { data: relationshipData }
+  }
+
+  for (const [alias, info] of Object.entries(descriptor.polymorphicBelongsTo || {})) {
+    const typeValue = info.typeColumn ? row[info.typeColumn] : null
+    const idValue = info.idColumn ? row[info.idColumn] : null
+    if (info.typeColumn) {
+      consumedColumns.add(info.typeColumn)
+    }
+    if (info.idColumn) {
+      consumedColumns.add(info.idColumn)
+    }
+
+    let relationshipData = null
+    if (typeValue != null && idValue != null) {
+      relationshipData = {
+        type: String(typeValue),
+        id: String(idValue),
+      }
+    }
+
+    relationships[alias] = { data: relationshipData }
+  }
+
+  const canonical = descriptor.canonical || {}
+  const internalColumns = new Set([
+    canonical.tenantColumn,
+    canonical.resourceColumn,
+    'created_at',
+    'updated_at',
+    'deleted_at'
+  ].filter(Boolean))
+
+  for (const [columnName, value] of Object.entries(row)) {
+    if (consumedColumns.has(columnName) || internalColumns.has(columnName)) {
+      continue
+    }
+    if (!allowedExtraFields.has(columnName)) {
+      continue
+    }
+    attributes[columnName] = value
+  }
+
+  return { attributes, relationships }
+}
+
+export const getCanonicalFieldValue = (row, descriptor = {}, fieldName) => {
+  if (!row || !fieldName) return undefined
+
+  if (fieldName === 'id') {
+    return getCanonicalResourceId(row, descriptor)
+  }
+
+  const fieldInfo = descriptor.fields?.[fieldName]
+  if (fieldInfo?.slot && Object.hasOwn(row, fieldInfo.slot)) {
+    return row[fieldInfo.slot]
+  }
+
+  if (Object.hasOwn(row, fieldName)) {
+    return row[fieldName]
+  }
+
+  return undefined
+}

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

@@ -1,3 +1,15 @@
+import {
+  getFieldValue as getLegacyFieldValue,
+  getIdColumn,
+  getStorageColumn,
+  translateAttributesForStorage,
+} from './storage-mapping.js'
+import {
+  getCanonicalFieldValue,
+  getCanonicalResourceIdColumn,
+  translateCanonicalAttributesForStorage,
+} from './canonical-storage-mapping.js'
+
 const passthrough = (value) => value
 const identityTranslate = (_field, value) => value
 const identityScope = (query) => query
@@ -22,6 +34,59 @@ const normalizeBelongsToValue = (value) => {
   return String(value)
 }
 
+const translateSourceColumn = (source, adapter) => {
+  if (!adapter || source === '*') return source
+  return adapter.translateColumn(source) || source
+}
+
+export const createSelectTranslator = (adapter) => {
+  if (!adapter) return null
+
+  return (field, alias) => {
+    if (field === '*') {
+      return alias ? `${alias}.*` : '*'
+    }
+
+    const translated = adapter.translateColumn(field)
+    const result = translated || field
+
+    if (field === 'id' && result !== 'id') {
+      const qualified = alias ? `${alias}.${result}` : result
+      return `${qualified} as id`
+    }
+
+    if (!alias) {
+      return result
+    }
+
+    if (result.includes('.')) {
+      return result
+    }
+
+    return `${alias}.${result}`
+  }
+}
+
+export const translateSelectFieldsForAdapter = (fields, adapter) => {
+  if (!adapter || !fields) return fields
+
+  const translateField = createSelectTranslator(adapter)
+
+  return fields.map((field) => {
+    if (typeof field !== 'string') return field
+    if (field === '*') return '*'
+
+    const aliasMatch = field.match(/\s+as\s+/i)
+    if (aliasMatch) {
+      const [source, alias] = field.split(/\s+as\s+/i)
+      const translatedSource = translateSourceColumn(source.trim(), adapter)
+      return `${translatedSource} as ${alias.trim()}`
+    }
+
+    return translateField(field)
+  })
+}
+
 const baseAdapter = ({
   knex,
   tableName,
@@ -29,6 +94,8 @@ const baseAdapter = ({
   translateColumn,
   translateFilterValue = identityTranslate,
   applyResourceScope = identityScope,
+  toStorageRow = passthrough,
+  getFieldValue = (record, fieldName) => record?.[fieldName],
   isCanonical = false,
 }) => {
   const buildBaseQuery = ({ transaction } = {}) => {
@@ -43,6 +110,8 @@ const baseAdapter = ({
     translateColumn,
     translateFilterValue,
     applyResourceScope,
+    toStorageRow,
+    getFieldValue,
     buildBaseQuery,
     selectColumns: (builder, columns) => selectColumnsOnBuilder(builder, columns),
   }
@@ -50,9 +119,11 @@ const baseAdapter = ({
 
 const createLegacyAdapter = ({ knex, schemaInfo }) => {
   const tableName = schemaInfo.tableName
-  const idColumn = schemaInfo.idProperty || 'id'
+  const idColumn = getIdColumn(schemaInfo)
 
-  const translateColumn = (column) => column
+  const translateColumn = (field) => getStorageColumn(schemaInfo, field)
+  const toStorageRow = (attributes, options = {}) => translateAttributesForStorage(attributes, schemaInfo, options)
+  const getFieldValue = (record, fieldName) => getLegacyFieldValue(record, schemaInfo, fieldName)
 
   return baseAdapter({
     knex,
@@ -61,6 +132,8 @@ const createLegacyAdapter = ({ knex, schemaInfo }) => {
     translateColumn,
     translateFilterValue: identityTranslate,
     applyResourceScope: identityScope,
+    toStorageRow,
+    getFieldValue,
     isCanonical: false,
   })
 }
@@ -74,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') {
@@ -136,13 +209,18 @@ const createCanonicalAdapter = ({ knex, schemaInfo }) => {
       .where(canonical.resourceColumn, descriptor.resource)
   }
 
+  const toStorageRow = (attributes) => translateCanonicalAttributesForStorage(attributes, descriptor)
+  const getFieldValue = (record, fieldName) => getCanonicalFieldValue(record, descriptor, fieldName)
+
   return baseAdapter({
     knex,
     tableName: canonical.tableName,
-    idColumn: 'id',
+    idColumn: getCanonicalResourceIdColumn(descriptor),
     translateColumn,
     translateFilterValue,
     applyResourceScope,
+    toStorageRow,
+    getFieldValue,
     isCanonical: true,
   })
 }

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

@@ -0,0 +1,274 @@
+const EMPTY_STORAGE_INFO = Object.freeze({
+  idColumn: 'id',
+  storage: Object.freeze({
+    naming: 'snake_case'
+  }),
+  fields: Object.freeze({}),
+  columns: Object.freeze({})
+})
+
+const isPlainObject = (value) => (
+  value !== null &&
+  typeof value === 'object' &&
+  !Array.isArray(value)
+)
+
+const SNAKE_CASE_STORAGE_NAMING = 'snake_case'
+const EXACT_STORAGE_NAMING = 'exact'
+
+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 = fieldStorage?.column ?? resolveDefaultStorageColumn(fieldName, {
+    idColumn,
+    storageConfig
+  })
+  if (typeof column !== 'string' || column.trim() === '') {
+    throw new Error(`Field '${fieldName}' has an invalid storage.column value.`)
+  }
+
+  if (fieldName === 'id' && column !== idColumn) {
+    throw new Error(
+      `Field 'id' must use storage.column '${idColumn}' to match the resource id column.`
+    )
+  }
+
+  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: fieldStorage?.serialize || null,
+    persisted: definition.virtual !== true && definition.computed !== true
+  }
+}
+
+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,
+      storageConfig
+    })
+    const isIdSurrogateField = fieldName === idColumn && definition.type === 'id'
+
+    if (fieldName !== 'id' && normalized.column === idColumn && !isIdSurrogateField) {
+      throw new Error(
+        `Field '${fieldName}' cannot use storage.column '${idColumn}' because it is reserved for the resource id.`
+      )
+    }
+
+    const existingField = usedColumns.get(normalized.column)
+    if (existingField && existingField !== fieldName && !(isIdSurrogateField && existingField === 'id')) {
+      throw new Error(
+        `Fields '${existingField}' and '${fieldName}' both map to storage column '${normalized.column}'.`
+      )
+    }
+
+    usedColumns.set(normalized.column, fieldName)
+    fields[fieldName] = {
+      ...normalized,
+      definition
+    }
+
+    if (normalized.persisted && !isIdSurrogateField) {
+      columns[normalized.column] = fieldName
+    }
+  }
+
+  return {
+    idColumn,
+    storage: storageConfig,
+    fields,
+    columns
+  }
+}
+
+export const getStorageInfo = (schemaInfo = {}) => {
+  if (schemaInfo.storageInfo) {
+    return schemaInfo.storageInfo
+  }
+
+  if (!schemaInfo.schemaStructure) {
+    return EMPTY_STORAGE_INFO
+  }
+
+  return buildStorageInfo({
+    schemaStructure: schemaInfo.schemaStructure,
+    idProperty: schemaInfo.idProperty || 'id',
+    storage: schemaInfo.storage
+  })
+}
+
+export const getIdColumn = (schemaInfo = {}) => {
+  return getStorageInfo(schemaInfo).idColumn || schemaInfo.idProperty || 'id'
+}
+
+export const getStorageColumn = (schemaInfo = {}, fieldName) => {
+  if (!fieldName) return fieldName
+  if (fieldName === 'id') return getIdColumn(schemaInfo)
+
+  const fieldStorage = getStorageInfo(schemaInfo).fields[fieldName]
+  return fieldStorage?.column || fieldName
+}
+
+export const getLogicalFieldName = (schemaInfo = {}, columnName) => {
+  if (!columnName) return columnName
+  if (columnName === getIdColumn(schemaInfo)) return 'id'
+
+  const logicalField = getStorageInfo(schemaInfo).columns[columnName]
+  return logicalField || columnName
+}
+
+export const getFieldValue = (record, schemaInfo = {}, fieldName) => {
+  if (!record || !fieldName) return undefined
+
+  if (fieldName === 'id') {
+    if (Object.hasOwn(record, 'id')) {
+      return record.id
+    }
+
+    const idColumn = getIdColumn(schemaInfo)
+    if (Object.hasOwn(record, idColumn)) {
+      return record[idColumn]
+    }
+
+    return translateRecordFromStorage(record, schemaInfo).id
+  }
+
+  if (Object.hasOwn(record, fieldName)) {
+    return record[fieldName]
+  }
+
+  const columnName = getStorageColumn(schemaInfo, fieldName)
+  if (Object.hasOwn(record, columnName)) {
+    return record[columnName]
+  }
+
+  return translateRecordFromStorage(record, schemaInfo)[fieldName]
+}
+
+export const translateAttributesForStorage = (attributes, schemaInfo = {}, options = {}) => {
+  if (!attributes) return attributes || {}
+
+  const { context = null, operation = null } = options
+  const storageInfo = getStorageInfo(schemaInfo)
+  const computed = schemaInfo.computed || {}
+
+  return Object.entries(attributes).reduce((translated, [fieldName, value]) => {
+    if (fieldName in computed) {
+      return translated
+    }
+
+    const fieldStorage = storageInfo.fields[fieldName]
+    if (fieldStorage && !fieldStorage.persisted) {
+      return translated
+    }
+
+    const columnName = fieldName === 'id'
+      ? storageInfo.idColumn
+      : fieldStorage?.column || fieldName
+    const serializedValue = fieldStorage?.serialize
+      ? fieldStorage.serialize(value, {
+        fieldName,
+        columnName,
+        definition: fieldStorage.definition,
+        schemaInfo,
+        context,
+        operation
+      })
+      : value
+
+    translated[columnName] = serializedValue
+    return translated
+  }, {})
+}
+
+export const translateRecordFromStorage = (record, schemaInfo = {}) => {
+  if (!record || !schemaInfo) return record
+
+  const storageInfo = getStorageInfo(schemaInfo)
+  const translated = {}
+
+  for (const [columnName, value] of Object.entries(record)) {
+    if (columnName === storageInfo.idColumn) {
+      translated.id = value
+      continue
+    }
+
+    const logicalField = storageInfo.columns[columnName]
+    if (logicalField) {
+      translated[logicalField] = value
+      continue
+    }
+
+    translated[columnName] = value
+  }
+
+  return translated
+}

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