json-rest-api 1.0.29 → 2.1.0

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

@@ -1,14 +1,17 @@
-import { RestApiResourceError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
-import { processRelationships } from '../lib/writing/relationship-processor.js'
+// @ts-check
+/** @import {
+ * CompletedWriteContext, LifecycleArguments
+ * } from './lifecycle-types.js' */
+import { applyResourceVersion, captureInverseVersions, invalidateInverseVersions } from '../lib/writing/resource-version.js'
+import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
+import { lockRelationshipParent, lockRelationshipTargets, processRelationships } from '../lib/writing/relationship-processor.js'
+import { updateReverseRelationship } from '../lib/writing/reverse-relationship-manipulations.js'
 import { updateManyToManyRelationship } from '../lib/writing/many-to-many-manipulations.js'
 import { ERROR_SUBTYPES } from '../lib/querying-writing/knex-constants.js'
-import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
-import {
-  requireDocumentResourceId,
-  requireExistingResourceId
-} from '../lib/querying-writing/resource-id-normalization.js'
+import { validateUpdateRequest } from '../lib/querying-writing/request-contracts.js'
 import {
   setupCommonRequest,
+  writePrecondition,
   validateResourceAttributesBeforeWrite,
   validateRelationshipAccess,
   applyFieldSetters,
@@ -19,103 +22,46 @@ import {
 } 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.
+ * Update only supplied attributes and relationships on an existing resource.
+ * Input normalization, selected write response and transaction ownership use
+ * the same contracts as POST/PUT; omitted fields remain unchanged.
+ * @param {LifecycleArguments} args
  */
 export default async function patchMethod ({
   params,
-  context,
+  context: callerContext,
   vars,
   helpers,
   scope,
   scopes,
   runHooks,
-  apiOptions,
-  pluginOptions,
   scopeOptions,
   scopeName,
   api,
   log
 }) {
-  context.method = 'patch'
+  callerContext.method = 'patch'
 
   try {
-    const { schema, schemaStructure, schemaRelationships } = await setupCommonRequest({
+    const { schema, versionState, context: preparedContext } = await setupCommonRequest({
       params,
-      context,
+      context: callerContext,
       vars,
       scopes,
-      scopeOptions,
       scopeName,
       api,
-      helpers
+      helpers,
+      runHooks
     })
-    // Run early hooks for pre-processing (e.g., file handling)
     await runHooks('beforeProcessing')
     await runHooks('beforeProcessingPatch')
 
-    const requestContracts = getRequestContracts({
-      scopeName,
-      schemaInfo: context.schemaInfo,
-      includeDepthLimit: vars.includeDepthLimit,
-      sortableFields: vars.sortableFields
-    })
-    const normalizedPathId = params.id === undefined
-      ? null
-      : requireExistingResourceId(params.id, {
-        scopeOptions,
-        vars,
-        scopeName
-      })
-
-    if (normalizedPathId && !context.inputRecord?.data?.id) {
-      context.inputRecord = {
-        ...context.inputRecord,
-        data: {
-          ...(context.inputRecord?.data || {}),
-          id: normalizedPathId
-        }
-      }
-    }
-
-    context.inputRecord = validateRequestContractOrThrow(
-      requestContracts.patch,
-      context.inputRecord,
-      'PATCH request body is invalid'
-    )
-    const normalizedBodyId = requireDocumentResourceId(context.inputRecord.data.id, {
-      scopeOptions,
-      vars
-    })
-
-    if (normalizedPathId && normalizedPathId !== normalizedBodyId) {
-      throw new RestApiValidationError(
-        `ID mismatch. URL path ID '${normalizedPathId}' does not match request body ID '${normalizedBodyId}'`,
-        {
-          fields: ['data.id'],
-          violations: [{
-            field: 'data.id',
-            rule: 'id_consistency',
-            message: 'Request body ID must match URL path ID when both are provided'
-          }]
-        }
-      )
-    }
-    context.inputRecord.data.id = normalizedBodyId
-    context.id = normalizedPathId || normalizedBodyId
+    validateUpdateRequest({ method: 'patch', params, context: preparedContext, vars, scopeOptions, scopeName })
+    const context = /** @type {CompletedWriteContext} */ (preparedContext)
 
-    // 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, 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(
+    const { belongsToUpdates, belongsToTargets, manyToManyRelationships, reverseRelationships } = processRelationships(
       scope,
       { context }
     )
@@ -138,18 +84,19 @@ export default async function patchMethod ({
     if (!minimalRecord) {
       throw new RestApiResourceError(
         `Resource not found: ${scopeName}/${context.id}`,
-        ERROR_SUBTYPES.NOT_FOUND
+        { subtype: ERROR_SUBTYPES.NOT_FOUND }
       )
     }
 
     context.minimalRecord = minimalRecord
 
-    // Centralised checkPermissions function
     await scope.checkPermissions({
       method: 'patch',
       originalContext: context,
     })
 
+    await params[writePrecondition]?.()
+
     // Merge belongsTo updates into attributes before patching the record
     if (Object.keys(belongsToUpdates).length > 0) {
       context.inputRecord.data.attributes = {
@@ -161,23 +108,23 @@ export default async function patchMethod ({
     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
-      )
+    await lockRelationshipTargets(api, context.transaction, belongsToTargets)
+
+    if (manyToManyRelationships.length || reverseRelationships.length) {
+      await lockRelationshipParent({ context, helpers, scopeName })
     }
 
-    // Call the storage helper - should return the patched record
+    await applyFieldSetters(context, api, helpers)
+    const inverseVersions = await captureInverseVersions({ api, helpers, context, scopeName })
+    await applyResourceVersion({ state: versionState, context, helpers, scopeName })
+
     await helpers.dataPatch({
       scopeName,
       context
     })
 
+    await invalidateInverseVersions({ state: inverseVersions, context, helpers, api })
+
     await runHooks('afterDataCallPatch')
     await runHooks('afterDataCall')
 
@@ -201,6 +148,7 @@ export default async function patchMethod ({
       await updateManyToManyRelationship(null, {
         api,
         context: {
+          ...context,
           resourceId: context.id,
           relDef,
           relData,
@@ -209,24 +157,23 @@ export default async function patchMethod ({
       })
     }
 
-    const ret = await handleRecordReturnAfterWrite({
+    for (const { relDef, relData } of reverseRelationships) {
+      await updateReverseRelationship({ api, helpers, context, scopeName, relDef, relData })
+    }
+
+    const response = await handleRecordReturnAfterWrite({
       context,
       scopeName,
       api,
       scopes,
-      schemaStructure,
-      schemaRelationships,
-      scopeOptions,
-      vars,
       runHooks,
-      helpers,
-      log
+      helpers
     })
 
-    await commitOwnedTransaction(context, runHooks)
+    await commitOwnedTransaction(context)
 
-    return ret
+    return response
   } catch (error) {
-    await handleWriteMethodError(error, context, 'PATCH', scopeName, log, runHooks)
+    await handleWriteMethodError(error, callerContext, 'PATCH', scopeName, log)
   }
 }

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

@@ -1,58 +1,63 @@
+// @ts-check
+/** @import {
+ * Identifier, RelationshipWriteArguments, WriteRelationshipContext
+ * } from './lifecycle-types.js' */
+import { lockRelationshipParent } from '../lib/writing/relationship-processor.js'
+import { advanceResourceVersion } from '../lib/writing/resource-version.js'
+import { beginWriteTransaction } from '../../../lib/error-context.js'
+import { rejectRemovedOptions, resolveFormat } from '../lib/querying-writing/response-options.js'
 import { RestApiResourceError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
 import {
   commitOwnedTransaction,
-  findRelationshipDefinition,
   getVisibleRelationshipParent,
   handleWriteMethodError,
+  validateRelationshipAccess,
   validateRelationshipRoutePayload
 } from './common.js'
 import { createPivotRecords } from '../lib/writing/many-to-many-manipulations.js'
+import { updateReverseRelationship } from '../lib/writing/reverse-relationship-manipulations.js'
+import { findRelationshipDefinition } from '../lib/querying-writing/relationship-contracts.js'
 import {
   normalizeRelationshipIdentifiers,
   requireExistingResourceId
 } from '../lib/querying-writing/resource-id-normalization.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, scopeOptions, scopeName, api, log }) {
-  context.method = 'postRelationship'
-  context.id = requireExistingResourceId(params.id, {
+ * Add the identifiers in params.relationshipData to a to-many relationship.
+ * Authorization and parent/version locking precede mutation. The method
+ * returns no resource and completes only an owned transaction.
+ * @param {RelationshipWriteArguments<Identifier[]>} args
+ */
+export default async function postRelationshipMethod ({ params, context: callerContext, vars, helpers, scope, scopes, runHooks, scopeOptions, scopeName, api, log }) {
+  rejectRemovedOptions(params)
+  if (params.format !== undefined) resolveFormat(params.format)
+  callerContext.method = 'postRelationship'
+  callerContext.scopeName = scopeName
+  callerContext.id = requireExistingResourceId(params.id, {
     scopeOptions,
     vars,
     scopeName
   })
-  context.relationshipName = params.relationshipName
-  context.schemaInfo = scopes[scopeName].vars.schemaInfo
+  callerContext.relationshipName = params.relationshipName
+  callerContext.schemaInfo = scope.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
+  await beginWriteTransaction(callerContext, params.transaction, helpers.newTransaction, runHooks)
+  callerContext.db = callerContext.transaction || api.knex.instance
+  const context = /** @type {WriteRelationshipContext} */ (callerContext)
 
   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' }
+        `Relationship '${context.relationshipName}' not found on resource '${scopeName}'`,
+        { subtype: 'relationship_not_found' }
       )
     }
 
     if (relDef.type !== 'hasMany' && relDef.type !== 'manyToMany') {
       throw new RestApiValidationError(
-      `Cannot POST to to-one relationship '${context.relationshipName}'. Use PATCH instead.`,
-      { fields: ['data'] }
+        `Cannot POST to to-one relationship '${context.relationshipName}'. Use PATCH instead.`,
+        { fields: ['data'] }
       )
     }
 
@@ -63,7 +68,7 @@ export default async function postRelationshipMethod ({ params, context, vars, h
       operation: 'postRelationship',
       relationshipData: params.relationshipData
     })
-    params.relationshipData = normalizeRelationshipIdentifiers(params.relationshipData, { api })
+    params.relationshipData = /** @type {Identifier[]} */ (normalizeRelationshipIdentifiers(params.relationshipData, { api }))
 
     // Check permissions
     await runHooks('checkPermissions')
@@ -80,6 +85,18 @@ export default async function postRelationshipMethod ({ params, context, vars, h
     if (!parentRecord) {
       throw new RestApiResourceError('Resource not found', { subtype: 'not_found' })
     }
+    context.minimalRecord = parentRecord
+    context.originalMinimalRecord = parentRecord
+
+    await runHooks('beforeDataCall')
+    await runHooks('beforeDataCallPostRelationship')
+
+    const revision = await advanceResourceVersion({ scopeName, context, helpers, expectedVersion: params.expectedVersion })
+    if (revision === undefined) await lockRelationshipParent({ context, helpers, scopeName })
+
+    await validateRelationshipAccess(context, {
+      data: { relationships: { [context.relationshipName]: { data: params.relationshipData } } }
+    }, helpers, api)
 
     // Add relationships
     if (relDef?.through) {
@@ -92,38 +109,17 @@ export default async function postRelationshipMethod ({ params, context, vars, h
           relData: params.relationshipData,
         })
       } else {
-        await createPivotRecords(api, context.id, {
-          through: relDef.through,
-          foreignKey: relDef.foreignKey,
-          otherKey: relDef.otherKey
-        }, params.relationshipData, context.transaction, context)
+        await createPivotRecords(api, context.id, relDef, params.relationshipData, context.transaction)
       }
     } else if (relDef.type === 'hasMany') {
-      // Update foreign keys for hasMany
-      const targetType = relDef.target
-      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
-        }, { ...context })
-      }
+      await updateReverseRelationship({ api, helpers, context, scopeName, relDef, relData: params.relationshipData, operation: 'add' })
     }
 
     await runHooks('finish')
     await runHooks('finishPostRelationship')
 
-    await commitOwnedTransaction(context, runHooks)
-
-    // 204 No Content
+    await commitOwnedTransaction(context)
   } catch (error) {
-    await handleWriteMethodError(error, context, 'POST_RELATIONSHIP', scopeName, log, runHooks)
+    await handleWriteMethodError(error, context, 'POST_RELATIONSHIP', scopeName, log)
   }
-};
+}

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

@@ -1,7 +1,13 @@
-import { processRelationships } from '../lib/writing/relationship-processor.js'
+// @ts-check
+/** @import {
+ * CompletedWriteContext, LifecycleArguments, WriteContext
+ * } from './lifecycle-types.js' */
+import { applyResourceVersion, captureInverseVersions, invalidateInverseVersions } from '../lib/writing/resource-version.js'
+import { lockRelationshipTargets, processRelationships } from '../lib/writing/relationship-processor.js'
+import { updateReverseRelationship } from '../lib/writing/reverse-relationship-manipulations.js'
 import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import { createPivotRecords } from '../lib/writing/many-to-many-manipulations.js'
-import { requireDocumentResourceId } from '../lib/querying-writing/resource-id-normalization.js'
+import { defaultNormalizeResourceId, requireDocumentResourceId } from '../lib/querying-writing/resource-id-normalization.js'
 import {
   setupCommonRequest,
   validateResourceAttributesBeforeWrite,
@@ -14,55 +20,53 @@ import {
 } 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.
+ * Create a resource from plain data or a JSON:API document.
+ * Supplied IDs and existing-resource linkage are validated before writing.
+ * Prepare the selected returning result before completing an owned transaction.
+ * @param {LifecycleArguments} args
  */
 export default async function postMethod ({
   params,
-  context,
+  context: callerContext,
   vars,
   helpers,
   scope,
   scopes,
   runHooks,
-  apiOptions,
-  pluginOptions,
   scopeOptions,
   scopeName,
   api,
   log
 }) {
-  context.method = 'post'
+  callerContext.method = 'post'
 
   try {
-    const { schema, schemaStructure, schemaRelationships } = await setupCommonRequest({
+    const { schema, versionState, context: preparedContext } = await setupCommonRequest({
       params,
-      context,
+      context: callerContext,
       vars,
       scopes,
-      scopeOptions,
       scopeName,
       api,
-      helpers
+      helpers,
+      runHooks
     })
 
-    // Run early hooks for pre-processing (e.g., file handling)
     await runHooks('beforeProcessing')
     await runHooks('beforeProcessingPost')
 
     const requestContracts = getRequestContracts({
       scopeName,
-      schemaInfo: context.schemaInfo,
+      schemaInfo: preparedContext.schemaInfo,
       includeDepthLimit: vars.includeDepthLimit,
       sortableFields: vars.sortableFields
     })
-    context.inputRecord = validateRequestContractOrThrow(
+    preparedContext.inputRecord = validateRequestContractOrThrow(
       requestContracts.post,
-      context.inputRecord,
+      preparedContext.inputRecord,
       'POST request body is invalid'
     )
+    const context = /** @type {WriteContext} */ (preparedContext)
 
     if (context.inputRecord?.data?.id !== undefined) {
       context.inputRecord.data.id = requireDocumentResourceId(context.inputRecord.data.id, {
@@ -71,14 +75,9 @@ export default async function postMethod ({
       })
     }
 
-    // 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, 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(
+    const { belongsToUpdates, belongsToTargets, manyToManyRelationships, reverseRelationships } = await processRelationships(
       scope,
       { context }
     )
@@ -108,7 +107,6 @@ export default async function postMethod ({
       }
     }
 
-    // Centralised checkPermissions function
     await scope.checkPermissions({
       method: 'post',
       originalContext: context,
@@ -117,23 +115,27 @@ export default async function postMethod ({
     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
-      )
-    }
+    await lockRelationshipTargets(api, context.transaction, belongsToTargets)
+
+    await applyFieldSetters(context, api, helpers)
+    const inverseVersions = await captureInverseVersions({ api, helpers, context, scopeName, isCreate: true })
+    await applyResourceVersion({ state: versionState, context, helpers, scopeName, isCreate: true })
 
-    // Create the main record - storage helper should return the created record with its ID
-    context.id = await helpers.dataPost({
+    // Create the main record and retain the logical ID returned by storage.
+    const storedId = await helpers.dataPost({
       scopeName,
       context
     })
 
+    const resourceId = typeof storedId === 'bigint' ? String(storedId) : storedId
+    if ((typeof resourceId !== 'string' && typeof resourceId !== 'number') || !defaultNormalizeResourceId(resourceId)) {
+      throw new Error('Storage POST did not return a valid resource ID')
+    }
+    context.id = resourceId
+    const completedContext = /** @type {CompletedWriteContext} */ (context)
+
+    await invalidateInverseVersions({ state: inverseVersions, context, helpers, api })
+
     await runHooks('afterDataCallPost')
     await runHooks('afterDataCall')
 
@@ -141,7 +143,7 @@ export default async function postMethod ({
     for (const { relName, relDef, relData } of manyToManyRelationships) {
       if (api.anyapi?.links?.attachMany && relDef?.through) {
         await api.anyapi.links.attachMany({
-          context,
+          context: completedContext,
           scopeName,
           relName,
           relDef,
@@ -150,29 +152,27 @@ export default async function postMethod ({
         continue
       }
 
-      // Validate pivot resource exists
       validatePivotResource(scopes, relDef, relName)
-      await createPivotRecords(api, context.id, relDef, relData, context.transaction, context)
+      await createPivotRecords(api, context.id, relDef, relData, context.transaction)
     }
 
-    const ret = await handleRecordReturnAfterWrite({
-      context,
+    for (const { relDef, relData } of reverseRelationships) {
+      await updateReverseRelationship({ api, helpers, context, scopeName, relDef, relData })
+    }
+
+    const response = await handleRecordReturnAfterWrite({
+      context: completedContext,
       scopeName,
       api,
       scopes,
-      schemaStructure,
-      schemaRelationships,
-      scopeOptions,
-      vars,
       runHooks,
-      helpers,
-      log
+      helpers
     })
 
-    await commitOwnedTransaction(context, runHooks)
+    await commitOwnedTransaction(context)
 
-    return ret
+    return response
   } catch (error) {
-    await handleWriteMethodError(error, context, 'POST', scopeName, log, runHooks)
+    await handleWriteMethodError(error, callerContext, 'POST', scopeName, log)
   }
 }