json-rest-api 1.0.20 → 1.0.22

package/audit/evidence/code/critical-pass1/json-rest-api__plugins__core__lib__writing__many-to-many-manipulations.js.txt

@@ -0,0 +1,300 @@
+     1	import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
+     2	import { transformSimplifiedToJsonApi } from '../querying-writing/simplified-helpers.js'
+     3	
+     4	/**
+     5	 * Updates many-to-many relationships intelligently by synchronizing pivot table records
+     6	 *
+     7	 * @param {Object} scope - The scope object (not used directly, for consistency)
+     8	 * @param {Object} deps - Dependencies object
+     9	 * @returns {Promise<void>}
+    10	 *
+    11	 * @example
+    12	 * // Input: Article currently has tags [1, 2], want to change to [1, 3]
+    13	 * const deps = {
+    14	 *   api,
+    15	 *   context: {
+    16	 *     resourceId: '100',
+    17	 *     relDef: {
+    18	 *       through: 'article_tags',     // Pivot table
+    19	 *       foreignKey: 'article_id',    // Points to article
+    20	 *       otherKey: 'tag_id'          // Points to tag
+    21	 *     },
+    22	 *     relData: [
+    23	 *       { type: 'tags', id: '1' },  // Keep this
+    24	 *       { type: 'tags', id: '3' }   // Add this
+    25	 *     ],
+    26	 *     transaction: trx
+    27	 *   }
+    28	 * };
+    29	 *
+    30	 * // Before: article_tags table
+    31	 * // article_id | tag_id | created_at
+    32	 * // 100        | 1      | 2024-01-01
+    33	 * // 100        | 2      | 2024-01-02
+    34	 *
+    35	 * await updateManyToManyRelationship(null, deps);
+    36	 *
+    37	 * // After: article_tags table
+    38	 * // article_id | tag_id | created_at
+    39	 * // 100        | 1      | 2024-01-01  (preserved!)
+    40	 * // 100        | 3      | 2024-12-01  (new)
+    41	 * // Tag 2 was deleted, Tag 1 kept its metadata
+    42	 *
+    43	 * @example
+    44	 * // Input: Pivot table has extra fields to preserve
+    45	 * // article_tags has: article_id, tag_id, display_order, featured
+    46	 *
+    47	 * // Current data:
+    48	 * // article_id | tag_id | display_order | featured
+    49	 * // 100        | 1      | 1            | true
+    50	 * // 100        | 2      | 2            | false
+    51	 *
+    52	 * const deps = {
+    53	 *   context: {
+    54	 *     resourceId: '100',
+    55	 *     relData: [
+    56	 *       { type: 'tags', id: '1' },  // Keep tag 1
+    57	 *       { type: 'tags', id: '5' }   // Add tag 5
+    58	 *     ]
+    59	 *   }
+    60	 * };
+    61	 *
+    62	 * await updateManyToManyRelationship(null, deps);
+    63	 *
+    64	 * // Result:
+    65	 * // article_id | tag_id | display_order | featured
+    66	 * // 100        | 1      | 1            | true      (preserved!)
+    67	 * // 100        | 5      | NULL         | NULL      (new with defaults)
+    68	 *
+    69	 * @example
+    70	 * // Input: Clear all relationships
+    71	 * const deps = {
+    72	 *   context: {
+    73	 *     resourceId: '100',
+    74	 *     relData: []  // Empty array means remove all
+    75	 *   }
+    76	 * };
+    77	 *
+    78	 * await updateManyToManyRelationship(null, deps);
+    79	 * // All article_tags records for article 100 are deleted
+    80	 *
+    81	 * @description
+    82	 * Used by:
+    83	 * - relationship-processor.js calls this for many-to-many updates
+    84	 * - Used in PATCH operations to sync relationships
+    85	 * - Also used in PUT operations (replaces deleteExistingPivotRecords pattern)
+    86	 *
+    87	 * Purpose:
+    88	 * - Intelligently syncs pivot table to match desired state
+    89	 * - Preserves existing pivot records that should remain (with their metadata)
+    90	 * - Only deletes records that should be removed
+    91	 * - Only creates records that are new
+    92	 * - Much better than delete-all-then-recreate pattern
+    93	 *
+    94	 * Data flow:
+    95	 * 1. Queries existing pivot records for the resource
+    96	 * 2. Compares existing IDs with desired IDs
+    97	 * 3. Calculates which to delete and which to add
+    98	 * 4. Validates new related resources exist (optional)
+    99	 * 5. Performs bulk delete for removed relationships
+   100	 * 6. Performs bulk insert for new relationships
+   101	 * 7. Records that exist in both are untouched (metadata preserved)
+   102	 */
+   103	export const updateManyToManyRelationship = async (scope, deps) => {
+   104	  // Extract values from deps
+   105	  const { api, context } = deps
+   106	  const { resourceId, relDef, relData, transaction: trx } = context
+   107	
+   108	  // Get the knex instance from the pivot scope
+   109	  const pivotScope = api.resources[relDef.through]
+   110	  if (!pivotScope) {
+   111	    throw new Error(`Pivot table resource '${relDef.through}' not found`)
+   112	  }
+   113	
+   114	  // Get the actual database table name (might be different from scope name)
+   115	  const tableName = pivotScope.vars.schemaInfo.tableName || relDef.through
+   116	
+   117	  // Get existing pivot records directly from database
+   118	  const existingRecords = await trx(tableName)
+   119	    .where(relDef.foreignKey, resourceId)
+   120	    .select(relDef.otherKey)
+   121	
+   122	  // Create sets for efficient comparison
+   123	  const existingIds = new Set(existingRecords.map(r => String(r[relDef.otherKey])))
+   124	  const newIds = new Set(relData.map(r => String(r.id)))
+   125	
+   126	  // Determine what to delete and add
+   127	  const toDelete = [...existingIds].filter(id => !newIds.has(id))
+   128	  const toAdd = [...newIds].filter(id => !existingIds.has(id))
+   129	
+   130	  // Validate related resources exist if needed (do this before any changes)
+   131	  if (relDef.validateExists !== false && toAdd.length > 0) {
+   132	    for (const relatedId of toAdd) {
+   133	      const related = relData.find(r => String(r.id) === relatedId)
+   134	      try {
+   135	        await api.resources[related.type].get({
+   136	          id: related.id,
+   137	          transaction: trx
+   138	        })
+   139	      } catch (error) {
+   140	        throw new RestApiResourceError(
+   141	          `Related ${related.type} with id ${related.id} not found`,
+   142	          {
+   143	            subtype: 'not_found',
+   144	            resourceType: related.type,
+   145	            resourceId: related.id
+   146	          }
+   147	        )
+   148	      }
+   149	    }
+   150	  }
+   151	
+   152	  // Bulk delete records that should be removed
+   153	  if (toDelete.length > 0) {
+   154	    await trx(tableName)
+   155	      .where(relDef.foreignKey, resourceId)
+   156	      .whereIn(relDef.otherKey, toDelete)
+   157	      .delete()
+   158	  }
+   159	
+   160	  // Bulk insert new records
+   161	  if (toAdd.length > 0) {
+   162	    const recordsToInsert = toAdd.map(relatedId => ({
+   163	      [relDef.foreignKey]: resourceId,
+   164	      [relDef.otherKey]: relatedId
+   165	    }))
+   166	
+   167	    await trx(tableName).insert(recordsToInsert)
+   168	  }
+   169	
+   170	  // Records that exist in both are automatically preserved with their pivot data
+   171	}
+   172	
+   173	// Note: deleteExistingPivotRecords has been removed in favor of using
+   174	// updateManyToManyRelationship for all sync operations (including PUT).
+   175	// This aligns with industry standards where ORMs use intelligent sync
+   176	// rather than delete-all-then-recreate patterns.
+   177	
+   178	/**
+   179	 * Creates new pivot table records for many-to-many relationships
+   180	 *
+   181	 * @param {Object} api - The API instance with access to resources
+   182	 * @param {string|number} resourceId - The ID of the primary resource
+   183	 * @param {Object} relDef - The relationship definition
+   184	 * @param {Array} relData - Array of related resources to link
+   185	 * @param {Object} trx - Database transaction object
+   186	 * @returns {Promise<void>}
+   187	 *
+   188	 * @example
+   189	 * // Input: Create article-tag relationships
+   190	 * const relDef = {
+   191	 *   through: 'article_tags',
+   192	 *   foreignKey: 'article_id',
+   193	 *   otherKey: 'tag_id'
+   194	 * };
+   195	 * const relData = [
+   196	 *   { type: 'tags', id: '10' },
+   197	 *   { type: 'tags', id: '20' },
+   198	 *   { type: 'tags', id: '30' }
+   199	 * ];
+   200	 *
+   201	 * await createPivotRecords(api, '100', relDef, relData, trx);
+   202	 *
+   203	 * // Result: 3 new records in article_tags table
+   204	 * // article_id | tag_id
+   205	 * // 100        | 10
+   206	 * // 100        | 20
+   207	 * // 100        | 30
+   208	 *
+   209	 * @example
+   210	 * // Input: Validation ensures related resources exist
+   211	 * const relData = [
+   212	 *   { type: 'tags', id: '999' }  // Non-existent tag
+   213	 * ];
+   214	 *
+   215	 * try {
+   216	 *   await createPivotRecords(api, '100', relDef, relData, trx);
+   217	 * } catch (error) {
+   218	 *   console.log(error.message);
+   219	 *   // "Related tags with id 999 not found"
+   220	 *   // Transaction rolled back, no records created
+   221	 * }
+   222	 *
+   223	 * @example
+   224	 * // Input: Skip validation for performance
+   225	 * const relDef = {
+   226	 *   through: 'user_permissions',
+   227	 *   foreignKey: 'user_id',
+   228	 *   otherKey: 'permission_id',
+   229	 *   validateExists: false  // Skip GET requests
+   230	 * };
+   231	 *
+   232	 * // With 100 permissions, saves 100 GET requests
+   233	 * await createPivotRecords(api, userId, relDef, permissions, trx);
+   234	 *
+   235	 * // Risk: Could create orphaned relationships if permissions don't exist
+   236	 * // Benefit: Much faster for bulk operations when you trust the data
+   237	 *
+   238	 * @description
+   239	 * Used by:
+   240	 * - relationship-processor.js for POST operations
+   241	 * - updateManyToManyRelationship internally for new relationships
+   242	 * - Any code that needs to create pivot records
+   243	 *
+   244	 * Purpose:
+   245	 * - Creates pivot table records to link resources
+   246	 * - Validates related resources exist by default (referential integrity)
+   247	 * - Supports bulk insert for efficiency
+   248	 * - Works within transactions for atomicity
+   249	 * - Allows skipping validation when performance matters
+   250	 *
+   251	 * Data flow:
+   252	 * 1. Validates pivot table resource exists
+   253	 * 2. Gets actual database table name
+   254	 * 3. Optionally validates each related resource exists (GET requests)
+   255	 * 4. Prepares bulk insert data with foreign keys
+   256	 * 5. Performs single INSERT with all records
+   257	 * 6. Returns (no data returned, throws on error)
+   258	 */
+   259	export const createPivotRecords = async (api, resourceId, relDef, relData, trx) => {
+   260	  if (relData.length === 0) return // Early exit if nothing to create
+   261	
+   262	  // Get pivot table info
+   263	  const pivotScope = api.resources[relDef.through]
+   264	  if (!pivotScope) {
+   265	    throw new Error(`Pivot table resource '${relDef.through}' not found`)
+   266	  }
+   267	
+   268	  // Get the actual database table name (might be different from scope name)
+   269	  const tableName = pivotScope.vars.schemaInfo.tableName || relDef.through
+   270	
+   271	  // Validate all related resources exist if needed (do this before any inserts)
+   272	  if (relDef.validateExists !== false) {
+   273	    for (const related of relData) {
+   274	      try {
+   275	        await api.resources[related.type].get({
+   276	          id: related.id,
+   277	          transaction: trx
+   278	        })
+   279	      } catch (error) {
+   280	        throw new RestApiResourceError(
+   281	          `Related ${related.type} with id ${related.id} not found`,
+   282	          {
+   283	            subtype: 'not_found',
+   284	            resourceType: related.type,
+   285	            resourceId: related.id
+   286	          }
+   287	        )
+   288	      }
+   289	    }
+   290	  }
+   291	
+   292	  // Prepare records for bulk insert
+   293	  const recordsToInsert = relData.map(related => ({
+   294	    [relDef.foreignKey]: resourceId,
+   295	    [relDef.otherKey]: related.id
+   296	  }))
+   297	
+   298	  // Bulk insert all pivot records in a single query
+   299	  await trx(tableName).insert(recordsToInsert)
+   300	}

package/audit/evidence/code/critical-pass1/json-rest-api__plugins__core__lib__writing__relationship-processor.js.txt

@@ -0,0 +1,245 @@
+     1	import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+     2	
+     3	/**
+     4	 * Processes JSON:API relationship data and converts to database operations
+     5	 *
+     6	 * @param {Object} scope - The scope object containing schema info
+     7	 * @param {Object} deps - Dependencies object
+     8	 * @returns {Object} Object with belongsToUpdates and manyToManyRelationships arrays
+     9	 *
+    10	 * @example
+    11	 * // Input: Simple belongsTo relationship
+    12	 * const inputRecord = {
+    13	 *   data: {
+    14	 *     type: 'articles',
+    15	 *     attributes: { title: 'My Article' },
+    16	 *     relationships: {
+    17	 *       author: {
+    18	 *         data: { type: 'users', id: '123' }
+    19	 *       },
+    20	 *       category: {
+    21	 *         data: { type: 'categories', id: '5' }
+    22	 *       }
+    23	 *     }
+    24	 *   }
+    25	 * };
+    26	 *
+    27	 * // Schema has:
+    28	 * // author_id: { belongsTo: 'users', as: 'author' }
+    29	 * // category_id: { belongsTo: 'categories', as: 'category' }
+    30	 *
+    31	 * const result = processRelationships(scope, { context: { inputRecord } });
+    32	 *
+    33	 * // Output: Foreign keys extracted
+    34	 * // {
+    35	 * //   belongsToUpdates: {
+    36	 * //     author_id: '123',
+    37	 * //     category_id: '5'
+    38	 * //   },
+    39	 * //   manyToManyRelationships: []
+    40	 * // }
+    41	 *
+    42	 * @example
+    43	 * // Input: Polymorphic relationship
+    44	 * const inputRecord = {
+    45	 *   data: {
+    46	 *     type: 'comments',
+    47	 *     relationships: {
+    48	 *       commentable: {
+    49	 *         data: { type: 'posts', id: '456' }
+    50	 *       }
+    51	 *     }
+    52	 *   }
+    53	 * };
+    54	 *
+    55	 * // Schema relationships has:
+    56	 * // commentable: {
+    57	 * //   belongsToPolymorphic: {
+    58	 * //     types: ['posts', 'videos'],
+    59	 * //     typeField: 'commentable_type',
+    60	 * //     idField: 'commentable_id'
+    61	 * //   }
+    62	 * // }
+    63	 *
+    64	 * const result = processRelationships(scope, { context: { inputRecord } });
+    65	 *
+    66	 * // Output: Both type and id fields set
+    67	 * // {
+    68	 * //   belongsToUpdates: {
+    69	 * //     commentable_type: 'posts',
+    70	 * //     commentable_id: '456'
+    71	 * //   },
+    72	 * //   manyToManyRelationships: []
+    73	 * // }
+    74	 *
+    75	 * @example
+    76	 * // Input: Many-to-many relationship
+    77	 * const inputRecord = {
+    78	 *   data: {
+    79	 *     type: 'articles',
+    80	 *     relationships: {
+    81	 *       tags: {
+    82	 *         data: [
+    83	 *           { type: 'tags', id: '10' },
+    84	 *           { type: 'tags', id: '20' }
+    85	 *         ]
+    86	 *       }
+    87	 *     }
+    88	 *   }
+    89	 * };
+    90	 *
+    91	 * // Schema relationships has:
+    92	 * // tags: {
+    93	 * //   type: 'manyToMany',
+    94	 * //   through: 'article_tags',
+    95	 * //   foreignKey: 'article_id',
+    96	 * //   otherKey: 'tag_id'
+    97	 * // }
+    98	 *
+    99	 * const result = processRelationships(scope, { context: { inputRecord } });
+   100	 *
+   101	 * // Output: Many-to-many data collected
+   102	 * // {
+   103	 * //   belongsToUpdates: {},
+   104	 * //   manyToManyRelationships: [{
+   105	 * //     relName: 'tags',
+   106	 * //     relDef: {
+   107	 * //       through: 'article_tags',
+   108	 * //       foreignKey: 'article_id',
+   109	 * //       otherKey: 'tag_id'
+   110	 * //     },
+   111	 * //     relData: [
+   112	 * //       { type: 'tags', id: '10' },
+   113	 * //       { type: 'tags', id: '20' }
+   114	 * //     ]
+   115	 * //   }]
+   116	 * // }
+   117	 *
+   118	 * @example
+   119	 * // Input: Clearing relationships
+   120	 * const inputRecord = {
+   121	 *   data: {
+   122	 *     relationships: {
+   123	 *       author: { data: null },      // Clear belongsTo
+   124	 *       tags: { data: [] }           // Clear many-to-many
+   125	 *     }
+   126	 *   }
+   127	 * };
+   128	 *
+   129	 * const result = processRelationships(scope, { context: { inputRecord } });
+   130	 *
+   131	 * // Output: Null for belongsTo, empty array for many-to-many
+   132	 * // {
+   133	 * //   belongsToUpdates: { author_id: null },
+   134	 * //   manyToManyRelationships: [{
+   135	 * //     relName: 'tags',
+   136	 * //     relDef: { ... },
+   137	 * //     relData: []  // Will delete all pivot records
+   138	 * //   }]
+   139	 * // }
+   140	 *
+   141	 * @description
+   142	 * Used by:
+   143	 * - rest-api-knex-plugin's dataPut and dataPatch methods
+   144	 * - Called before database writes to prepare relationship updates
+   145	 *
+   146	 * Purpose:
+   147	 * - Converts JSON:API relationship format to database operations
+   148	 * - Handles all relationship types: belongsTo, polymorphic, many-to-many
+   149	 * - Validates polymorphic types against allowed values
+   150	 * - Separates concerns: foreign keys vs pivot table operations
+   151	 *
+   152	 * Data flow:
+   153	 * 1. Receives JSON:API document with relationships section
+   154	 * 2. Analyzes schema to determine relationship types
+   155	 * 3. For belongsTo: extracts foreign key values
+   156	 * 4. For polymorphic: extracts both type and id fields
+   157	 * 5. For many-to-many: collects data for pivot operations
+   158	 * 6. Returns structured data for database updates
+   159	 */
+   160	export const processRelationships = (scope, deps) => {
+   161	  // Extract values from scope
+   162	  const {
+   163	    vars: {
+   164	      schemaInfo: { schemaStructure: schemaFields, schemaRelationships: relationships }
+   165	    }
+   166	  } = scope
+   167	
+   168	  // Extract values from deps
+   169	  const { context } = deps
+   170	  const { inputRecord } = context
+   171	  const belongsToUpdates = {}
+   172	  const manyToManyRelationships = []
+   173	
+   174	  if (!inputRecord.data.relationships) {
+   175	    return { belongsToUpdates, manyToManyRelationships }
+   176	  }
+   177	
+   178	  for (const [relName, relData] of Object.entries(inputRecord.data.relationships)) {
+   179	    const relDef = relationships?.[relName]
+   180	
+   181	    // Find the schema field that defines this relationship
+   182	    const schemaField = Object.entries(schemaFields).find(([fieldName, fieldDef]) =>
+   183	      fieldDef.as === relName
+   184	    )
+   185	
+   186	    if (schemaField) {
+   187	      const [fieldName, fieldDef] = schemaField
+   188	
+   189	      // Handle regular belongsTo (1:1)
+   190	      if (fieldDef.belongsTo) {
+   191	        if (relData.data === null) {
+   192	          belongsToUpdates[fieldName] = null
+   193	        } else if (relData.data?.id) {
+   194	          belongsToUpdates[fieldName] = relData.data.id
+   195	        }
+   196	      }
+   197	    }
+   198	
+   199	    // Check for polymorphic belongsTo defined in relationships object (not as schema field)
+   200	    if (!schemaField && relDef?.belongsToPolymorphic && relData.data !== undefined) {
+   201	      if (relData.data === null) {
+   202	        const { typeField, idField } = relDef.belongsToPolymorphic
+   203	        belongsToUpdates[typeField] = null
+   204	        belongsToUpdates[idField] = null
+   205	      } else if (relData.data) {
+   206	        const { type, id } = relData.data
+   207	        const { types, typeField, idField } = relDef.belongsToPolymorphic
+   208	
+   209	        // Validate type is allowed
+   210	        if (!types.includes(type)) {
+   211	          throw new RestApiValidationError(
+   212	            `Invalid type '${type}' for polymorphic relationship '${relName}'. Allowed types: ${types.join(', ')}`,
+   213	            {
+   214	              fields: [`data.relationships.${relName}.data.type`],
+   215	              violations: [{
+   216	                field: `data.relationships.${relName}.data.type`,
+   217	                rule: 'polymorphic_type',
+   218	                message: `Type must be one of: ${types.join(', ')}`
+   219	              }]
+   220	            }
+   221	          )
+   222	        }
+   223	
+   224	        belongsToUpdates[typeField] = type
+   225	        belongsToUpdates[idField] = id
+   226	      }
+   227	    }
+   228	
+   229	    // Check relationship type and process accordingly
+   230	    if (relDef?.type === 'manyToMany' && relData.data !== undefined) {
+   231	      manyToManyRelationships.push({
+   232	        relName,
+   233	        relDef: {
+   234	          through: relDef.through,
+   235	          foreignKey: relDef.foreignKey,
+   236	          otherKey: relDef.otherKey
+   237	        },
+   238	        relData: relData.data || []  // null means empty array for many-to-many
+   239	      })
+   240	    }
+   241	    // Note: hasOne and hasMany don't need processing here as they don't update the current record
+   242	  }
+   243	
+   244	  return { belongsToUpdates, manyToManyRelationships }
+   245	}