json-rest-api 1.0.29 → 2.0.0

package/plugins/core/lib/querying/knex-json-api-transformers-querying.js

@@ -1,366 +1,96 @@
-import { getForeignKeyFields as getForeignKeyFieldsFromUtils } from '../querying-writing/field-utils.js'
-import { RELATIONSHIPS_KEY, RELATIONSHIP_METADATA_KEY, ROW_NUMBER_KEY, COMPUTED_DEPENDENCIES_KEY, getSchemaStructure } from '../querying-writing/knex-constants.js'
-import { getUrlPrefix, buildResourceUrl, buildRelationshipUrl } from './url-helpers.js'
+// @ts-check
+/** @import { JsonApiRelationship, JsonApiResource } from '../../../../types/representations.js' */
+/** @import { DataDocument, DataOperationScope, DataReadContext, DataResource, DataStorageRow, ResourceConversionScope, StorageRow } from '../storage/storage-types.js' */
+import { RELATIONSHIPS_KEY, RELATIONSHIP_METADATA_KEY, ROW_NUMBER_KEY, COMPUTED_DEPENDENCIES_KEY } from '../querying-writing/knex-constants.js'
+import { getUrlPrefix, buildResourceUrl, buildRelationshipUrl, buildJsonApiLink } from './url-helpers.js'
 import { translateRecordFromStorage } from '../storage/storage-mapping.js'
+import { getPolymorphicLinkage } from '../querying-writing/relationship-contracts.js'
+import { wrapUnexpectedError } from '../../../../lib/error-context.js'
+
+const internalFields = new Set([
+  RELATIONSHIPS_KEY,
+  RELATIONSHIP_METADATA_KEY,
+  ROW_NUMBER_KEY,
+  COMPUTED_DEPENDENCIES_KEY
+])
 
 /**
- * Transforms a flat database record into JSON:API resource format
- *
- * @private
- * @param {Object} scope - Scope containing schema and configuration
- * @param {Object} record - Database record to transform
- * @param {Object} deps - Dependencies including context with scopeName and polymorphicFields
- * @returns {Object|null} JSON:API resource object or null if no record
- *
- * @example
- * // Input: Database record with foreign keys and internal fields
- * const record = {
- *   id: 1,
- *   title: 'Hello World',
- *   content: 'Article content',
- *   author_id: 2,           // Foreign key
- *   category_id: 5,         // Foreign key
- *   __$jsonrestapi_rn$__: 1 // Internal field
- * };
- *
- * const jsonApiResource = toJsonApi(scope, record, deps);
- *
- * // Output: Clean JSON:API resource
- * // {
- * //   type: 'articles',
- * //   id: '1',
- * //   attributes: {
- * //     title: 'Hello World',
- * //     content: 'Article content'
- * //     // Note: author_id, category_id, and internal fields are removed
- * //   }
- * // }
- *
- * @example
- * // Input: Polymorphic record
- * const record = {
- *   id: 10,
- *   text: 'Great article!',
- *   commentable_type: 'articles',  // Polymorphic type field
- *   commentable_id: 1               // Polymorphic id field
- * };
- * // deps.context.polymorphicFields = Set(['commentable_type', 'commentable_id'])
- *
- * const jsonApiResource = toJsonApi(scope, record, deps);
- *
- * // Output: Polymorphic fields filtered out
- * // {
- * //   type: 'comments',
- * //   id: '10',
- * //   attributes: {
- * //     text: 'Great article!'
- * //   }
- * // }
- *
- * @description
- * Used by:
- * - toJsonApiRecord calls this as the core transformation logic
- * - buildJsonApiResponse uses this indirectly through toJsonApiRecord
- *
- * Purpose:
- * - Separates database structure from API structure
- * - Filters out foreign keys that become relationships in JSON:API
- * - Removes internal fields used for query optimization
- * - Ensures clean attribute objects without implementation details
- *
- * Data flow:
- * - Called after database query returns flat records
- * - Transforms each record individually
- * - Output feeds into relationship building and response assembly
+ * @overload
+ * @param {ResourceConversionScope} scope
+ * @param {StorageRow} record
+ * @param {string} scopeName
+ * @returns {JsonApiResource}
  */
-const toJsonApi = (scope, record, deps) => {
-  if (!record) return null
-
-  const schemaInfo = scope.vars.schemaInfo
-  const schemaInstance = schemaInfo.schemaInstance
-  const logicalRecord = translateRecordFromStorage(record, schemaInfo)
+/**
+ * @overload
+ * @param {ResourceConversionScope} scope
+ * @param {StorageRow | null | undefined} record
+ * @param {string} scopeName
+ * @returns {JsonApiResource | null}
+ */
+/** @param {ResourceConversionScope} scope @param {StorageRow | null | undefined} record @param {string} scopeName @returns {JsonApiResource | null} */
+export function toJsonApiRecord (scope, record, scopeName) {
+  let foreignKeys
+  try {
+    foreignKeys = scope.vars.schemaInfo.foreignKeyFields
+  } catch (error) {
+    throw wrapUnexpectedError(error, {
+      message: `Failed to read relationship metadata for '${scopeName}'`,
+      context: { scopeName, phase: 'relationshipMetadata' }
+    })
+  }
 
-  const { context } = deps
-  const scopeName = context.scopeName
-  const idProperty = context.schemaInfo?.idProperty || 'id'
-  const polymorphicFields = context.polymorphicFields || new Set()
+  const { idProperty = 'id' } = scope.vars.schemaInfo
+  if (!record) return null
 
+  const logicalRecord = translateRecordFromStorage(record, scope.vars.schemaInfo)
   const { id, ...allAttributes } = logicalRecord
-
-  const foreignKeys = schemaInstance ? getForeignKeyFieldsFromUtils(schemaInstance) : new Set()
-
-  const internalFields = new Set([
-    RELATIONSHIPS_KEY,
-    RELATIONSHIP_METADATA_KEY,
-    ROW_NUMBER_KEY,
-    COMPUTED_DEPENDENCIES_KEY
-  ])
-
+  /** @type {StorageRow} */
   const attributes = {}
-  Object.entries(allAttributes).forEach(([key, value]) => {
-    if (!foreignKeys.has(key) && !polymorphicFields.has(key) && !internalFields.has(key) && key !== idProperty) {
+  for (const [key, value] of Object.entries(allAttributes)) {
+    if (!foreignKeys.has(key) && !internalFields.has(key) && key !== idProperty) {
       attributes[key] = value
     }
-  })
-
-  return {
-    type: scopeName,
-    id: String(id),
-    attributes
   }
+  return { type: scopeName, id: String(id), attributes }
 }
 
 /**
- * Converts a database record to JSON:API format with proper field filtering
- *
- * @param {Object} scope - Scope containing schema and relationship definitions
- * @param {Object} record - Raw database record
- * @param {string} scopeName - Resource type name
- * @returns {Object} JSON:API formatted resource
- *
- * @example
- * // Input: Database record with various field types
- * const record = {
- *   id: 1,
- *   title: 'My Article',
- *   author_id: 2,      // belongsTo relationship
- *   category_id: 3,    // belongsTo relationship
- *   views: 150,
- *   published: true
- * };
- *
- * const jsonApi = toJsonApiRecord(scope, record, 'articles');
- *
- * // Output: Foreign keys filtered out
- * // {
- * //   type: 'articles',
- * //   id: '1',
- * //   attributes: {
- * //     title: 'My Article',
- * //     views: 150,
- * //     published: true
- * //   }
- * // }
- *
- * @example
- * // Input: Record with polymorphic relationship
- * const record = {
- *   id: 5,
- *   body: 'Nice post!',
- *   author_id: 10,
- *   commentable_type: 'posts',    // Polymorphic
- *   commentable_id: 3              // Polymorphic
- * };
- * // Schema has polymorphic relationship defined
- *
- * const jsonApi = toJsonApiRecord(scope, record, 'comments');
- *
- * // Output: Both foreign keys and polymorphic fields filtered
- * // {
- * //   type: 'comments',
- * //   id: '5',
- * //   attributes: {
- * //     body: 'Nice post!'
- * //   }
- * // }
- *
- * @description
- * Used by:
- * - rest-api-knex-plugin's dataGet method for single resource responses
- * - rest-api-knex-plugin's dataQuery method for collection responses
- * - processIncludes when transforming included resources
- * - buildJsonApiResponse as the primary transformation function
- *
- * Purpose:
- * - Provides consistent JSON:API transformation across all query operations
- * - Automatically identifies and filters foreign keys based on schema
- * - Handles polymorphic relationship fields (type/id pairs)
- * - Ensures IDs are always strings as required by JSON:API spec
- *
- * Data flow:
- * 1. Database query returns flat records with all fields
- * 2. toJsonApiRecord identifies foreign keys from schema
- * 3. Filters out foreign keys and internal fields from attributes
- * 4. Returns clean JSON:API resource ready for relationship processing
- * 5. buildJsonApiResponse adds relationships and links to complete the response
+ * @overload
+ * @param {DataOperationScope} scope
+ * @param {DataStorageRow[]} records
+ * @param {DataResource[]} included
+ * @param {true} isSingle
+ * @param {string} scopeName
+ * @param {DataReadContext} context
+ * @returns {Promise<DataDocument<DataResource>>}
  */
-export const toJsonApiRecord = (scope, record, scopeName) => {
-  const {
-    vars: {
-      schemaInfo: { schemaRelationships: relationships, idProperty }
-    }
-  } = scope
-
-  const polymorphicFields = new Set()
-  try {
-    Object.entries(relationships || {}).forEach(([relName, relDef]) => {
-      if (relDef.belongsToPolymorphic) {
-        const typeFieldName = relDef.belongsToPolymorphic.typeField || `${relName}_type`
-        const idFieldName = relDef.belongsToPolymorphic.idField || `${relName}_id`
-        polymorphicFields.add(typeFieldName)
-        polymorphicFields.add(idFieldName)
-      }
-    })
-  } catch (e) {
-  }
-
-  const deps = {
-    context: {
-      scopeName,
-      schemaInfo: { idProperty },
-      polymorphicFields
-    }
-  }
-
-  return toJsonApi(scope, record, deps)
-}
-
 /**
- * Builds complete JSON:API response with data, relationships, links, and optional includes
- *
- * @async
- * @param {Object} scope - Scope containing schema and configuration
- * @param {Array<Object>} records - Primary records to include in response
- * @param {Array<Object>} included - Resources to include in 'included' array
- * @param {boolean} isSingle - Whether this is a single resource response
- * @param {string} scopeName - Resource type name
- * @param {Object} context - Request context with pagination metadata
- * @returns {Promise<Object>} Complete JSON:API response document
- *
- * @example
- * // Input: Single article with author include
- * const records = [{
- *   id: 1,
- *   title: 'Article Title',
- *   content: 'Article content',
- *   author_id: 2,
- *   category_id: 3
- * }];
- *
- * const included = [{
- *   type: 'authors',
- *   id: '2',
- *   attributes: { name: 'John Doe', email: 'john@example.com' }
- * }];
- *
- * const response = await buildJsonApiResponse(scope, records, included, true, 'articles', context);
- *
- * // Output: Complete JSON:API document
- * // {
- * //   data: {
- * //     type: 'articles',
- * //     id: '1',
- * //     attributes: {
- * //       title: 'Article Title',
- * //       content: 'Article content'
- * //     },
- * //     relationships: {
- * //       author: {
- * //         data: { type: 'authors', id: '2' },
- * //         links: {
- * //           self: '/articles/1/relationships/author',
- * //           related: '/articles/1/author'
- * //         }
- * //       },
- * //       category: {
- * //         data: { type: 'categories', id: '3' },
- * //         links: {
- * //           self: '/articles/1/relationships/category',
- * //           related: '/articles/1/category'
- * //         }
- * //       }
- * //     },
- * //     links: {
- * //       self: '/articles/1'
- * //     }
- * //   },
- * //   included: [{
- * //     type: 'authors',
- * //     id: '2',
- * //     attributes: { name: 'John Doe', email: 'john@example.com' },
- * //     links: { self: '/authors/2' }
- * //   }],
- * //   links: {
- * //     self: '/articles/1'
- * //   }
- * // }
- *
- * @example
- * // Input: Collection with pagination
- * const records = [
- *   { id: 1, title: 'Article 1', author_id: 10 },
- *   { id: 2, title: 'Article 2', author_id: 10 },
- *   { id: 3, title: 'Article 3', author_id: 11 }
- * ];
- *
- * context.returnMeta = {
- *   paginationMeta: { page: 2, pageSize: 3, pageCount: 10, total: 30 },
- *   paginationLinks: {
- *     self: '/articles?page[number]=2&page[size]=3',
- *     first: '/articles?page[number]=1&page[size]=3',
- *     prev: '/articles?page[number]=1&page[size]=3',
- *     next: '/articles?page[number]=3&page[size]=3',
- *     last: '/articles?page[number]=10&page[size]=3'
- *   }
- * };
- *
- * const response = await buildJsonApiResponse(scope, records, [], false, 'articles', context);
- *
- * // Output: Collection with pagination metadata
- * // {
- * //   data: [
- * //     { type: 'articles', id: '1', attributes: { title: 'Article 1' }, ... },
- * //     { type: 'articles', id: '2', attributes: { title: 'Article 2' }, ... },
- * //     { type: 'articles', id: '3', attributes: { title: 'Article 3' }, ... }
- * //   ],
- * //   meta: {
- * //     pagination: { page: 2, pageSize: 3, pageCount: 10, total: 30 }
- * //   },
- * //   links: {
- * //     self: '/articles?page[number]=2&page[size]=3',
- * //     first: '/articles?page[number]=1&page[size]=3',
- * //     prev: '/articles?page[number]=1&page[size]=3',
- * //     next: '/articles?page[number]=3&page[size]=3',
- * //     last: '/articles?page[number]=10&page[size]=3'
- * //   }
- * // }
- *
- * @description
- * Used by:
- * - rest-api-knex-plugin's dataGet method for single resource responses
- * - rest-api-knex-plugin's dataQuery method for collection responses
- * - Called at the end of the query pipeline to assemble the final response
- *
- * Purpose:
- * - Assembles all parts of a JSON:API response in the correct structure
- * - Adds relationship objects with proper links for each foreign key
- * - Handles both regular belongsTo and polymorphic relationships
- * - Adds self links to all resources as required by JSON:API
- * - Includes pagination metadata and links when applicable
- *
- * Data flow:
- * 1. Query operations fetch primary records and optional includes
- * 2. Records are transformed to JSON:API format via toJsonApiRecord
- * 3. buildJsonApiResponse adds relationship objects for all foreign keys
- * 4. Adds proper links (self, related) for navigating the API
- * 5. Assembles included resources with their own links
- * 6. Adds pagination metadata and links if provided
- * 7. Returns complete JSON:API document ready for HTTP response
+ * @overload
+ * @param {DataOperationScope} scope
+ * @param {DataStorageRow[]} records
+ * @param {DataResource[]} included
+ * @param {false} isSingle
+ * @param {string} scopeName
+ * @param {DataReadContext} context
+ * @returns {Promise<DataDocument<DataResource[]>>}
  */
-export const buildJsonApiResponse = async (scope, records, included = [], isSingle = false, scopeName, context) => {
-  const {
-    vars: {
-      schemaInfo
-    }
-  } = scope
+/**
+ * @param {DataOperationScope} scope
+ * @param {DataStorageRow[]} records
+ * @param {DataResource[]} included
+ * @param {boolean} isSingle
+ * @param {string} scopeName
+ * @param {DataReadContext} context
+ */
+export async function buildJsonApiResponse (scope, records, included = [], isSingle = false, scopeName, context) {
+  const { schemaInfo } = scope.vars
 
   const {
-    schemaInstance,
+    schemaStructure,
     schemaRelationships: relationships
   } = schemaInfo
 
-  const schemaStructure = getSchemaStructure(schemaInstance)
-
   const processedRecords = records.map(record => {
     const { [RELATIONSHIPS_KEY]: _relationships, ...cleanRecord } = record
     const logicalRecord = translateRecordFromStorage(cleanRecord, schemaInfo)
@@ -372,34 +102,18 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
     }
 
     for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
-      if (fieldDef.belongsTo && fieldDef.as && fieldName in logicalRecord) {
+      if (fieldDef.belongsTo && fieldDef.as && Object.hasOwn(logicalRecord, fieldName)) {
         jsonApiRecord.relationships = jsonApiRecord.relationships || {}
-        if (!jsonApiRecord.relationships[fieldDef.as]) {
-          if (logicalRecord[fieldName] !== null && logicalRecord[fieldName] !== undefined) {
-            const relationshipObject = {
-              data: {
-                type: fieldDef.belongsTo,
-                id: String(logicalRecord[fieldName])
-              }
-            }
-
-            relationshipObject.links = {
+        if (!Object.hasOwn(jsonApiRecord.relationships, fieldDef.as)) {
+          const value = logicalRecord[fieldName]
+          jsonApiRecord.relationships[fieldDef.as] = {
+            data: value === null || value === undefined
+              ? null
+              : { type: fieldDef.belongsTo, id: String(value) },
+            links: {
               self: buildRelationshipUrl(context, scope, scopeName, resourceId, fieldDef.as, true),
               related: buildRelationshipUrl(context, scope, scopeName, resourceId, fieldDef.as, false)
             }
-
-            jsonApiRecord.relationships[fieldDef.as] = relationshipObject
-          } else {
-            const relationshipObject = {
-              data: null
-            }
-
-            relationshipObject.links = {
-              self: buildRelationshipUrl(context, scope, scopeName, resourceId, fieldDef.as, true),
-              related: buildRelationshipUrl(context, scope, scopeName, resourceId, fieldDef.as, false)
-            }
-
-            jsonApiRecord.relationships[fieldDef.as] = relationshipObject
           }
         }
       }
@@ -409,27 +123,18 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
       if (relDef.belongsToPolymorphic) {
         const typeValue = logicalRecord[relDef.belongsToPolymorphic.typeField]
         const idValue = logicalRecord[relDef.belongsToPolymorphic.idField]
-
-        if (typeValue && idValue) {
+        const data = getPolymorphicLinkage({
+          type: typeValue,
+          id: idValue,
+          types: relDef.belongsToPolymorphic.types,
+          scopeName,
+          relationshipName: relName
+        })
+
+        if (data || typeValue === null || idValue === null) {
           jsonApiRecord.relationships = jsonApiRecord.relationships || {}
-          const relationshipObject = {
-            data: {
-              type: typeValue,
-              id: String(idValue)
-            }
-          }
-
-          relationshipObject.links = {
-            self: buildRelationshipUrl(context, scope, scopeName, resourceId, relName, true),
-            related: buildRelationshipUrl(context, scope, scopeName, resourceId, relName, false)
-          }
-
-          jsonApiRecord.relationships[relName] = relationshipObject
-        } else if (typeValue === null || idValue === null) {
-          jsonApiRecord.relationships = jsonApiRecord.relationships || {}
-          const relationshipObject = {
-            data: null
-          }
+          /** @type {JsonApiRelationship} */
+          const relationshipObject = { data }
 
           relationshipObject.links = {
             self: buildRelationshipUrl(context, scope, scopeName, resourceId, relName, true),
@@ -441,28 +146,21 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
       }
     })
 
+    jsonApiRecord.links ||= {}
+    jsonApiRecord.links.self = buildResourceUrl(context, scope, scopeName, resourceId)
     return jsonApiRecord
   })
 
-  const normalizedData = isSingle ? processedRecords[0] : processedRecords
-
-  if (normalizedData) {
-    if (Array.isArray(normalizedData)) {
-      normalizedData.forEach(item => {
-        if (!item.links) item.links = {}
-        item.links.self = buildResourceUrl(context, scope, scopeName, item.id)
-      })
-    } else {
-      if (!normalizedData.links) normalizedData.links = {}
-      normalizedData.links.self = buildResourceUrl(context, scope, scopeName, normalizedData.id)
-    }
-  }
+  const singleRecord = processedRecords[0]
+  if (isSingle && !singleRecord) throw new Error('A single-resource response requires a record')
+  const normalizedData = isSingle && singleRecord ? singleRecord : processedRecords
 
+  /** @type {DataDocument<DataResource | DataResource[]>} */
   const response = {
     data: normalizedData
   }
 
-  if (included.length > 0) {
+  if (included.length > 0 || context.queryParams?.include !== undefined) {
     included.forEach(item => {
       if (!item.links) item.links = {}
       item.links.self = buildResourceUrl(context, scope, item.type, item.id)
@@ -482,8 +180,8 @@ export const buildJsonApiResponse = async (scope, records, included = [], isSing
   } else {
     const urlPrefix = getUrlPrefix(context, scope)
     response.links = {
-      self: isSingle
-        ? buildResourceUrl(context, scope, scopeName, normalizedData.id)
+      self: isSingle && singleRecord
+        ? buildJsonApiLink(buildResourceUrl(context, scope, scopeName, singleRecord.id), context.queryParams)
         : `${urlPrefix}/${scopeName}${context?.returnMeta?.queryString || ''}`
     }
   }