json-rest-api 1.0.22 → 1.0.23

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

@@ -1,300 +0,0 @@
-     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

@@ -1,245 +0,0 @@
-     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	}