json-rest-api 1.0.7 → 1.0.8

package/plugins/core/rest-api-plugin-methods/patch.js

@@ -0,0 +1,193 @@
+import { RestApiResourceError } from '../../../lib/rest-api-errors.js';
+import { validatePatchPayload } from '../lib/querying-writing/payload-validators.js';
+import { processRelationships } from '../lib/writing/relationship-processor.js';
+import { updateManyToManyRelationship } from '../lib/writing/many-to-many-manipulations.js';
+import { ERROR_SUBTYPES } from '../lib/querying-writing/knex-constants.js';
+import { 
+  setupCommonRequest, 
+  validateResourceAttributesBeforeWrite,
+  validateRelationshipAccess,
+  applyFieldSetters,
+  validatePivotResource,
+  handleRecordReturnAfterWrite,
+  handleWriteMethodError
+} from './common.js';
+
+/**
+ * PATCH
+ * Performs a partial update on an existing resource's attributes or relationships.
+ * Unlike PUT, PATCH only updates the fields provided, leaving other fields unchanged.
+ * This method supports updating both attributes and relationships (1:1 and n:n).
+ * For relationships, only the ones explicitly provided will be updated.
+ * Just like PUT, it CANNOT have the `included` array in data.
+ */
+export default async function patchMethod({ 
+  params, 
+  context, 
+  vars, 
+  helpers, 
+  scope, 
+  scopes, 
+  runHooks, 
+  apiOptions, 
+  pluginOptions, 
+  scopeOptions, 
+  scopeName,
+  api,
+  log
+}) {
+  context.method = 'patch';
+    
+  try {
+    const { schema, schemaStructure, schemaRelationships } = await setupCommonRequest({
+      params, 
+      context, 
+      vars, 
+      scopes, 
+      scopeOptions, 
+      scopeName,
+      api, 
+      helpers
+    });
+    context.id = context.inputRecord.data.id;
+    
+    // Run early hooks for pre-processing (e.g., file handling)
+    await runHooks('beforeProcessing');
+    await runHooks('beforeProcessingPatch');
+
+    // Validate PATCH payload to ensure the partial update actually contains changes.
+    // PATCH requests must include either attributes to update or relationships to modify -
+    // an empty PATCH is invalid. This prevents accidental no-op requests and ensures clients
+    // are explicit about what they want to change. Unlike PUT, PATCH preserves all fields
+    // not mentioned in the request.
+    // Example: data must have either attributes: {title: 'New'} or relationships: {author: {...}}
+    validatePatchPayload(context.inputRecord, scopes);
+    
+    // Validate that user has read access to all related resources
+    // This ensures users can only create relationships to resources they can access
+    await validateRelationshipAccess(context, context.inputRecord, helpers, runHooks, api);
+
+    // Extract foreign keys from JSON:API relationships and prepare many-to-many operations
+    // Example: relationships.author -> author_id: '123' for storage
+    // Example: relationships.tags -> array of pivot records to create later (only for provided relationships in PATCH)
+    const { belongsToUpdates, manyToManyRelationships } = processRelationships(
+      scope,
+      { context }
+    );
+
+    await validateResourceAttributesBeforeWrite({ 
+      context, 
+      schema, 
+      belongsToUpdates, 
+      runHooks,
+      isPartialValidation: true 
+    });
+
+    // Fetch minimal record for authorization checks
+    const minimalRecord = await helpers.dataGetMinimal({
+      scopeName,
+      context,
+      runHooks
+    });
+
+    if (!minimalRecord) {
+      throw new RestApiResourceError(
+        `Resource not found: ${scopeName}/${context.id}`,
+        ERROR_SUBTYPES.NOT_FOUND
+      );
+    }
+
+    context.minimalRecord = minimalRecord;
+
+    // Centralised checkPermissions function
+    await scope.checkPermissions({
+      method: 'patch',
+      auth: context.auth,
+      id: context.id,
+      minimalRecord: context.minimalRecord,
+      transaction: context.transaction
+    });
+
+    // Merge belongsTo updates into attributes before patching the record
+    if (Object.keys(belongsToUpdates).length > 0) {
+      context.inputRecord.data.attributes = {
+        ...context.inputRecord.data.attributes,
+        ...belongsToUpdates
+      };
+    }
+
+    await runHooks('beforeDataCall');
+    await runHooks('beforeDataCallPatch');
+
+    // Apply field setters after validation and before storage
+    if (context.inputRecord?.data?.attributes) {
+      context.inputRecord.data.attributes = await applyFieldSetters(
+        context.inputRecord.data.attributes,
+        context.schemaInfo,
+        context,
+        api,
+        helpers
+      );
+    }
+
+    // Call the storage helper - should return the patched record
+    await helpers.dataPatch({
+      scopeName,
+      context
+    });
+
+    await runHooks('afterDataCallPatch');
+    await runHooks('afterDataCall');
+
+    // Process many-to-many relationships after main record update
+    // For PATCH, we only update the relationships that were explicitly provided
+    for (const { relName, relDef, relData } of manyToManyRelationships) {
+      
+      // Validate pivot resource exists
+      validatePivotResource(scopes, relDef, relName);
+      
+      // Update many-to-many relationships using intelligent synchronization that preserves pivot data.
+      // This compares current relationships with desired state: removes records no longer needed,
+      // adds new relationships, and crucially preserves existing pivot records with their metadata
+      // (like created_at timestamps or extra pivot fields). This is superior to delete-all-recreate
+      // because it maintains audit trails and custom pivot data.
+      // Example: If article has tags [1,2,3] and you update to [2,3,4], it keeps the pivot records
+      // for tags 2&3 (preserving their created_at), deletes tag 1, and adds new record for tag 4.
+      // Example: If article has tags [1,2,3] and update sends [2,3,4], tag 1 is removed, tags 2,3 kept, tag 4 added
+      await updateManyToManyRelationship(null, {
+        api,
+        context: {
+          resourceId: context.id,
+          relDef,
+          relData,
+          transaction: context.transaction
+        }
+      });
+    }
+    
+    const ret = await handleRecordReturnAfterWrite({
+      context,
+      scopeName,
+      api,
+      scopes,
+      schemaStructure,
+      schemaRelationships,
+      scopeOptions,
+      vars,
+      runHooks,
+      helpers,
+      log
+    });
+
+    // Commit transaction if we created it
+    if (context.shouldCommit) {
+      await context.transaction.commit();
+      await runHooks('afterCommit');
+    }
+
+    return ret;
+  
+  } catch (error) {
+    await handleWriteMethodError(error, context, 'PATCH', scopeName, log, runHooks);
+  }
+}

package/plugins/core/rest-api-plugin-methods/post-relationship.js

@@ -0,0 +1,104 @@
+import { RestApiResourceError } from "../../../lib/rest-api-errors.js";
+import { findRelationshipDefinition, handleWriteMethodError } from "./common.js";
+import { createPivotRecords } from "../lib/writing/many-to-many-manipulations.js";
+import { RestApiValidationError } from "../../../lib/rest-api-errors.js";
+
+/**
+   * POST RELATIONSHIP
+   * Adds members to a to-many relationship
+   * POST /api/articles/1/relationships/tags
+   * 
+   * @param {string} id - The ID of the resource
+   * @param {string} relationshipName - The name of the relationship
+   * @param {array} relationshipData - Array of resource identifiers to add
+   * @returns {Promise<void>} 204 No Content
+  */ 
+ export default async function postRelationshipMethod({ params, context, vars, helpers, scope, scopes, runHooks, scopeName, api, log }) {
+  context.method = 'postRelationship';
+  context.id = params.id;
+  context.relationshipName = params.relationshipName;
+  context.schemaInfo = scopes[scopeName].vars.schemaInfo;
+
+  // Transaction handling
+  context.transaction = params.transaction || 
+  (helpers.newTransaction && !params.transaction ? await helpers.newTransaction() : null);
+  context.shouldCommit = !params.transaction && !!context.transaction;
+
+  context.db = context.transaction || api.knex.instance
+
+  try {
+  // Validate
+  const relDef = findRelationshipDefinition(context.schemaInfo, context.relationshipName);
+  if (!relDef) {
+      throw new RestApiResourceError(
+      `Relationship '${context.relationshipName}' not found on resource '${scopeName}'`,
+      { subtype: 'relationship_not_found' }
+      );
+  }
+
+  if (!relDef.hasMany && !relDef.manyToMany) {
+      throw new RestApiValidationError(
+      `Cannot POST to to-one relationship '${context.relationshipName}'. Use PATCH instead.`,
+      { fields: ['data'] }
+      );
+  }
+
+  if (!Array.isArray(params.relationshipData)) {
+      throw new RestApiPayloadError('POST to relationship requires array of resource identifiers');
+  }
+
+  // Check permissions
+  await runHooks('checkPermissions');
+  await runHooks('checkPermissionsPostRelationship');
+
+  // Verify parent exists
+  const exists = await helpers.dataExists({
+      scopeName,
+      context: { db: context.db, id: context.id, schemaInfo: context.schemaInfo },
+  });
+
+  if (!exists) {
+      throw new RestApiResourceError('Resource not found', { subtype: 'not_found' });
+  }
+
+  // Add relationships
+  if (relDef.manyToMany || (relDef.hasMany && relDef.through)) {
+      const manyToManyDef = relDef.manyToMany || {
+      through: relDef.through,
+      foreignKey: relDef.foreignKey,
+      otherKey: relDef.otherKey
+      };
+      
+      await createPivotRecords(api, context.id, manyToManyDef, params.relationshipData, context.transaction);
+  } else {
+      // Update foreign keys for hasMany
+      const targetType = relDef.hasMany;
+      for (const identifier of params.relationshipData) {
+      await api.resources[targetType].patch({
+          id: identifier.id,
+          inputRecord: {
+          data: {
+              type: targetType,
+              id: identifier.id,
+              attributes: { [relDef.foreignKey]: context.id }
+          }
+          },
+          transaction: context.transaction,
+          simplified: false
+      });
+      }
+  }
+
+  await runHooks('finish');
+  await runHooks('finishPostRelationship');
+
+  if (context.shouldCommit) {
+      await context.transaction.commit();
+  }
+
+  return; // 204 No Content
+
+  } catch (error) {
+  await handleWriteMethodError(error, context, 'POST_RELATIONSHIP', scopeName, log, runHooks);
+}
+};

package/plugins/core/rest-api-plugin-methods/post.js

@@ -0,0 +1,157 @@
+import { validatePostPayload } from '../lib/querying-writing/payload-validators.js';
+import { processRelationships } from '../lib/writing/relationship-processor.js';
+import { createPivotRecords } from '../lib/writing/many-to-many-manipulations.js';
+import { 
+  setupCommonRequest, 
+  validateResourceAttributesBeforeWrite,
+  validateRelationshipAccess,
+  applyFieldSetters,
+  validatePivotResource,
+  handleRecordReturnAfterWrite,
+  handleWriteMethodError
+} from './common.js';
+
+/**
+ * POST
+ * Creates a new resource. The request must include a JSON:API document with a 'data' object
+ * containing 'type' and 'attributes'. It can also establish relationships to existing resources.
+ * The returned document contains the created resource with its server-assigned ID.
+ */
+export default async function postMethod({ 
+  params, 
+  context, 
+  vars, 
+  helpers, 
+  scope, 
+  scopes, 
+  runHooks, 
+  apiOptions, 
+  pluginOptions, 
+  scopeOptions, 
+  scopeName,
+  api,
+  log
+}) {
+  context.method = 'post';
+
+  try {
+    const { schema, schemaStructure, schemaRelationships } = await setupCommonRequest({
+      params, 
+      context, 
+      vars, 
+      scopes, 
+      scopeOptions, 
+      scopeName, 
+      api,
+      helpers
+    });
+
+    // Run early hooks for pre-processing (e.g., file handling)
+    await runHooks('beforeProcessing');
+    await runHooks('beforeProcessingPost');
+
+    // Validate POST payload to ensure it follows JSON:API format and references valid resources.
+    // This checks the payload has required 'data' object with 'type' and 'attributes', validates
+    // that data.type matches a real resource type (preventing creation of non-existent resources),
+    // and ensures any relationships reference valid resource types with proper ID format.
+    // Example: data.type: 'articles' must be a registered scope, relationships.author must reference 'users'.
+    validatePostPayload(context.inputRecord, scopes);
+    
+    // Validate that user has read access to all related resources
+    // This ensures users can only create relationships to resources they can access
+    await validateRelationshipAccess(context, context.inputRecord, helpers, runHooks, api);
+    
+    // Extract foreign keys from JSON:API relationships and prepare many-to-many operations
+    // Example: relationships.author -> author_id: '123' for storage
+    // Example: relationships.tags -> array of pivot records to create later
+    const { belongsToUpdates, manyToManyRelationships } = await processRelationships(
+      scope,
+      { context }
+    );
+
+    // Merge belongsTo updates into attributes before validation (like PUT/PATCH do)
+    if (Object.keys(belongsToUpdates).length > 0) {
+      context.inputRecord.data.attributes = {
+        ...context.inputRecord.data.attributes,
+        ...belongsToUpdates
+      };
+    }
+
+    await validateResourceAttributesBeforeWrite({ 
+      context, 
+      schema, 
+      belongsToUpdates, 
+      runHooks
+    });
+
+    // Centralised checkPermissions function
+    await scope.checkPermissions({
+      method: 'post',
+      auth: context.auth,
+      transaction: context.transaction
+    });
+
+    await runHooks('beforeDataCall');
+    await runHooks('beforeDataCallPost');
+    
+    // Apply field setters after validation and before storage
+    if (context.inputRecord?.data?.attributes) {
+      context.inputRecord.data.attributes = await applyFieldSetters(
+        context.inputRecord.data.attributes,
+        context.schemaInfo,
+        context,
+        api,
+        helpers
+      );
+    }
+    
+    // Create the main record - storage helper should return the created record with its ID
+    context.id = await helpers.dataPost({
+      scopeName,
+      context
+    });
+    
+    await runHooks('afterDataCallPost');
+    await runHooks('afterDataCall');
+    
+    // Process many-to-many relationships after main record creation
+    for (const { relName, relDef, relData } of manyToManyRelationships) {
+      // Validate pivot resource exists
+      validatePivotResource(scopes, relDef, relName);
+      
+      // Create pivot records in the through table to establish many-to-many relationships.
+      // This creates records in the intermediary table (like 'article_tags') that link the main
+      // resource to each related resource. Before creating each pivot record, it validates that
+      // the related resource actually exists (preventing orphaned relationships). If validateExists
+      // is false, it skips validation for performance in bulk operations.
+      // Example: article.tags: [{id: '1'}, {id: '2'}] creates two article_tags records:
+      // {article_id: 100, tag_id: 1} and {article_id: 100, tag_id: 2}
+      await createPivotRecords(api, context.id, relDef, relData, context.transaction);
+    }
+    
+    const ret = await handleRecordReturnAfterWrite({
+      context,
+      scopeName,
+      api,
+      scopes,
+      schemaStructure,
+      schemaRelationships,
+      scopeOptions,
+      vars,
+      runHooks,
+      helpers,
+      log
+    });
+
+    // Commit transaction if we created it
+    if (context.shouldCommit) {
+      await context.transaction.commit();
+      await runHooks('afterCommit');
+    }
+
+    return ret;
+    
+  } catch (error) {
+    await handleWriteMethodError(error, context, 'POST', scopeName, log, runHooks);
+  }
+}