json-rest-api 1.0.29 → 2.1.0

package/plugins/core/rest-api-plugin-methods/put.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, PivotField
+ * } 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, createPivotRecords } 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,
   validateCompleteReplacePayload,
   validateResourceAttributesBeforeWrite,
   validateRelationshipAccess,
@@ -20,109 +23,51 @@ import {
 } from './common.js'
 
 /**
- * PUT
- * Updates an existing top-level resource by completely replacing it.
- * This method supports updating both attributes and relationships (1:1 and n:n).
- * Existing persisted values cannot be silently dropped: if a stored attribute or belongsTo
- * relationship already has a value, PUT must include it explicitly. Relationship collections
- * still follow replacement semantics when a relationships object is provided.
- * This method does NOT support creating new related resources via an `included` array.
+ * Create or replace a resource at the selected ID. Replacement requires existing
+ * stored values to be explicitly represented; relationship collections follow
+ * replacement semantics when a relationships object is supplied. This operation
+ * links existing related resources rather than creating an included graph.
+ * @param {LifecycleArguments} args
  */
 export default async function putMethod ({
   params,
-  context,
+  context: callerContext,
   vars,
   helpers,
   scope,
   scopes,
   runHooks,
-  apiOptions,
-  pluginOptions,
   scopeOptions,
   scopeName,
   api,
   log
 }) {
-  context.method = 'put'
+  callerContext.method = 'put'
 
   try {
-    const { schema, schemaStructure, schemaRelationships } = await setupCommonRequest({
+    const { schema, schemaStructure, schemaRelationships, 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('beforeProcessingPut')
 
-    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.put,
-      context.inputRecord,
-      'PUT 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: 'put', 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
-    const { belongsToUpdates, manyToManyRelationships } = processRelationships(
+    const { belongsToUpdates, belongsToTargets, manyToManyRelationships, reverseRelationships } = processRelationships(
       scope,
       { context }
     )
 
-    // Check existence first
     context.exists = await helpers.dataExists({
       scopeName,
       context
@@ -142,7 +87,7 @@ export default async function putMethod ({
       if (!minimalRecord) {
         throw new RestApiResourceError(
           `Resource not found: ${scopeName}/${context.id}`,
-          ERROR_SUBTYPES.NOT_FOUND
+          { subtype: ERROR_SUBTYPES.NOT_FOUND }
         )
       }
 
@@ -161,53 +106,26 @@ export default async function putMethod ({
       runHooks
     })
 
-    // For PUT, we also need to handle relationships that are NOT provided
-    // (they should be set to null/empty when a relationships object is provided)
-    const allRelationships = {}
-
-    // Collect all defined relationships for this resource
-    for (const [relName, relDef] of Object.entries(schemaRelationships || {})) {
-      if (relDef.type === 'manyToMany') {
-        allRelationships[relName] = {
-          type: 'manyToMany',
-          relDef: {
-            through: relDef.through,
-            foreignKey: relDef.foreignKey,
-            otherKey: relDef.otherKey
-          }
-        }
-      }
-    }
-
-    // Also check schema fields for belongsTo relationships
-    for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
-      if (fieldDef.as && fieldDef.belongsTo) {
-        allRelationships[fieldDef.as] = {
-          type: 'belongsTo',
-          fieldName,
-          fieldDef
+    // Supplying relationships makes PUT clear omitted linkage; omitting the object preserves it.
+    if (context.inputRecord.data.relationships !== undefined) {
+      const provided = new Set(Object.keys(context.inputRecord.data.relationships))
+      for (const [relName, relDef] of Object.entries(schemaRelationships)) {
+        if (provided.has(relName)) continue
+        if (relDef.type === 'hasOne' || relDef.type === 'hasMany') {
+          reverseRelationships.push({ relName, relDef, relData: relDef.type === 'hasOne' ? null : [] })
+        } else if (relDef.type === 'manyToMany') {
+          manyToManyRelationships.push({
+            relName,
+            relDef: /** @type {PivotField} */ ({
+              through: relDef.through, foreignKey: relDef.foreignKey, otherKey: relDef.otherKey
+            }),
+            relData: []
+          })
         }
       }
-    }
-
-    // Process missing relationships (PUT should null them out only if relationships object exists)
-    const hasRelationshipsObject = context.inputRecord.data.relationships !== undefined
-    const providedRelationships = new Set(Object.keys(context.inputRecord.data.relationships || {}))
-
-    // Only null out missing relationships if a relationships object was provided
-    if (hasRelationshipsObject) {
-      for (const [relName, relInfo] of Object.entries(allRelationships)) {
-        if (!providedRelationships.has(relName)) {
-          if (relInfo.type === 'belongsTo') {
-            belongsToUpdates[relInfo.fieldName] = null
-          } else if (relInfo.type === 'manyToMany') {
-            // Add to manyToManyRelationships with empty array
-            manyToManyRelationships.push({
-              relName,
-              relDef: relInfo.relDef,
-              relData: []  // Empty array means delete all
-            })
-          }
+      for (const [field, definition] of Object.entries(schemaStructure)) {
+        if (definition.belongsTo && definition.as && !provided.has(definition.as)) {
+          belongsToUpdates[field] = null
         }
       }
     }
@@ -220,31 +138,34 @@ export default async function putMethod ({
       }
     }
 
-    // Centralised checkPermissions function
     await scope.checkPermissions({
       method: 'put',
       originalContext: context,
     })
 
+    await params[writePrecondition]?.()
+
     await runHooks('beforeDataCall')
     await runHooks('beforeDataCallPut')
 
-    // 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 (!context.isCreate && (manyToManyRelationships.length || reverseRelationships.length)) {
+      await lockRelationshipParent({ context, helpers, scopeName })
     }
 
-    // Pass the operation type to the helper
+    await applyFieldSetters(context, api, helpers)
+    const inverseVersions = await captureInverseVersions({ api, helpers, context, scopeName, isCreate: context.isCreate })
+    await applyResourceVersion({ state: versionState, context, helpers, scopeName, isCreate: context.isCreate })
+
+    const putContext = /** @type {CompletedWriteContext & { isCreate: boolean }} */ (context)
+
     await helpers.dataPut({
       scopeName,
-      context
+      context: putContext
     })
+    await invalidateInverseVersions({ state: inverseVersions, context, helpers, api })
+
     await runHooks('afterDataCallPut')
     await runHooks('afterDataCall')
 
@@ -268,6 +189,7 @@ export default async function putMethod ({
         await updateManyToManyRelationship(null, {
           api,
           context: {
+            ...context,
             resourceId: context.id,
             relDef,
             relData,
@@ -275,28 +197,27 @@ export default async function putMethod ({
           }
         })
       } else if (relData.length > 0) {
-        await createPivotRecords(api, context.id, relDef, relData, context.transaction, context)
+        await createPivotRecords(api, context.id, relDef, relData, context.transaction)
       }
     }
 
-    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, 'PUT', scopeName, log, runHooks)
+    await handleWriteMethodError(error, callerContext, 'PUT', scopeName, log)
   }
 }

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

@@ -1,72 +1,61 @@
+// @ts-check
+/** @import {
+ * LifecycleArguments, QueryContext, Resource
+ * } from './lifecycle-types.js' */
+import { enrichIncludedAttributes } from './enrich-attributes.js'
+import { rejectRemovedOptions, resolveFormat } from '../lib/querying-writing/response-options.js'
 import { normalizeRecordAttributes } from '../lib/querying-writing/database-value-normalizers.js'
+import { filterResponseFields, getResourceFieldset } from '../lib/querying-writing/field-utils.js'
 import { getRequestedComputedFields, validateRequestedFieldsets } from '../lib/querying-writing/knex-field-helpers.js'
 import { getEffectiveSortableFields } from '../lib/querying/query-field-sort-helpers.js'
 import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js'
 import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
-import { cascadeConfig } from './common.js'
+import { validateRequestedIncludes, filterToOneResponseLinkage } from './common.js'
+import { queryConstraint } from '../lib/querying/query-constraint.js'
 
 /**
- * QUERY
- * Retrieves a collection of resources (e.g., a list of articles) based on provided criteria.
- * This function sends a GET request to /api/{resourceType}.
- *
- * @param {string} resourceType - The type of resource collection to fetch (e.g., "articles").
- * @param {object} [queryParams={}] - Optional. An object to customize the query for the collection.
- * @param {string[]} [queryParams.include=[]] - An optional array of relationship paths to sideload for each resource in the collection. These paths will be converted to a comma-separated string for the URL (e.g., `['author', 'comments.user']` becomes `author,comments.user`). Supports deep relationships (e.g., "publisher.country").
- * @param {object} [queryParams.fields] - An object to request only specific fields (sparse fieldsets) for each resource in the collection and its included relationships. Keys are resource types, values are comma-separated field names.
- * @param {object} [queryParams.filters] - An object to filter the collection. Keys are filter parameters (specific to your API's implementation, e.g., 'status', 'title'), values are the filter criteria.
- * @param {string[]} [queryParams.sort=[]] - An optional array of fields to sort the collection by. Each string represents a field; prefix with '-' for descending order (e.g., `['title', '-published-date']` becomes `title,-published-date`).
- * @param {object} [queryParams.page] - An object for pagination. Typically includes `number` (page number) and `size` (items per page). E.g., `{ number: 1, size: 10 }`.
- * @returns {Promise<object>} A Promise that resolves to the JSON:API response document containing the resource collection.
+ * Read a filtered collection using params.queryParams and the selected format.
+ * Preserve authorization and field selection through collection execution.
+ * Pagination metadata belongs to the result; this method sends no HTTP request.
+ * @param {LifecycleArguments<Resource[]>} args
  */
 export default async function queryMethod ({
   params,
-  context,
+  context: callerContext,
   vars,
   helpers,
   scope,
   scopes,
   runHooks,
-  apiOptions,
-  pluginOptions,
-  scopeOptions,
   scopeName,
-  log,
   api
 }) {
-  context.method = 'query'
+  callerContext.method = 'query'
+  // Nested queries only inherit membership when it is explicitly supplied again.
+  callerContext[queryConstraint] = params[queryConstraint]
 
-  // Determine which simplified setting to use based on transport
-  const isTransport = params.isTransport === true
+  rejectRemovedOptions(params)
+  callerContext.format = resolveFormat(params.format, vars.format)
+  callerContext.simplified = callerContext.format === 'plain'
 
-  // Use vars which automatically cascade from scope to global
-  const defaultSimplified = isTransport ? vars.simplifiedTransport : vars.simplifiedApi
+  callerContext.schemaInfo = scope.vars.schemaInfo // This is the object variable created by compileSchemas
+  callerContext.queryParams = params.queryParams || {}
 
-  // Get simplified setting - from params only (per-call override) or use default
-  context.simplified = params.simplified !== undefined ? params.simplified : defaultSimplified
+  callerContext.queryParams.fields = params.queryParams?.fields ?? {}
+  if (callerContext.queryParams.include == null) delete callerContext.queryParams.include
+  callerContext.queryParams.sort = params.queryParams?.sort ?? []
+  callerContext.queryParams.page = params.queryParams?.page ?? {}
 
-  // Assign common context properties
-  context.schemaInfo = scopes[scopeName].vars.schemaInfo // This is the object variable created by compileSchemas
-  context.queryParams = params.queryParams || {}
+  callerContext.transaction = params.transaction
+  callerContext.db = callerContext.transaction || api.knex.instance
 
-  // These only make sense as parameter per query
-  context.queryParams.fields = cascadeConfig('fields', [params.queryParams], {})
-  context.queryParams.include = cascadeConfig('include', [params.queryParams], [])
-  context.queryParams.sort = cascadeConfig('sort', [params.queryParams], [])
-  context.queryParams.page = cascadeConfig('page', [params.queryParams], {})
+  callerContext.scopeName = scopeName
+  const context = /** @type {QueryContext} */ (callerContext)
 
-  context.transaction = params.transaction
-  context.db = context.transaction || api.knex.instance
-
-  context.scopeName = scopeName
-
-  // These are just shortcuts used in this function and will be returned
   const schemaStructure = context.schemaInfo.schemaInstance.structure
   const schemaRelationships = context.schemaInfo.schemaRelationships
 
-  // Sortable fields and sort (mab)
   context.sortableFields = getEffectiveSortableFields(vars)
-  // Apply default sort if no sort specified
   if (context.queryParams.sort.length === 0 && vars.defaultSort) {
     context.queryParams.sort = Array.isArray(vars.defaultSort) ? vars.defaultSort : [vars.defaultSort]
   }
@@ -84,13 +73,13 @@ export default async function queryMethod ({
   )
   context.queryParams = validatedRequest.queryParams || {}
 
-  // Centralised checkPermissions function
   await scope.checkPermissions({
     method: 'query',
     originalContext: context,
   })
 
   await validateRequestedFieldsets(context, scopes)
+  validateRequestedIncludes(context, scopes)
   await runHooks('beforeData')
   await runHooks('beforeDataQuery')
   context.record = await helpers.dataQuery({
@@ -99,32 +88,19 @@ export default async function queryMethod ({
     runHooks
   })
 
-  // Normalize database values (e.g., convert 1/0 to true/false for booleans)
   context.record = normalizeRecordAttributes(context.record, scopes)
 
-  // Make a backup
-  try {
-    context.originalRecord = structuredClone(context.record)
-  } catch (e) {
-    log.error('Failed to clone record:', {
-      error: e.message,
-      recordKeys: Object.keys(context.record || {}),
-      hasHttpRequest: !!context.raw?.req
-    })
-    throw e
-  }
+  context.originalRecord = structuredClone(context.record)
 
-  // This will enhance record, which is the WHOLE JSON:API record
   await runHooks('enrichRecord')
 
-  // Get computed field information for main resource
   const computedFields = scope.vars.schemaInfo?.computed || {}
-  const requestedFields = context.queryParams.fields?.[scopeName]
+  const requestedFields = getResourceFieldset(context.queryParams.fields, scopeName)
   const requestedComputedFields = getRequestedComputedFields(scopeName, requestedFields, computedFields)
 
-  // Run enrichAttributes for every single set of attribute, calling it from the right scope
   for (const entry of context.record.data) {
     entry.attributes = await scope.enrichAttributes({
+      id: entry.id,
       attributes: entry.attributes,
       parentContext: context,
       requestedComputedFields,
@@ -132,40 +108,20 @@ export default async function queryMethod ({
       computedDependencies: context.computedDependencies
     })
   }
-  for (const entry of (context.record.included || [])) {
-    const entryScope = scopes[entry.type]
-    const entryComputed = entryScope.vars.schemaInfo?.computed || {}
-    const entryRequestedFields = context.queryParams.fields?.[entry.type]
-    const entryRequestedComputed = getRequestedComputedFields(
-      entry.type,
-      entryRequestedFields,
-      entryComputed
-    )
-
-    entry.attributes = await entryScope.enrichAttributes({
-      attributes: entry.attributes,
-      parentContext: context,
-      requestedComputedFields: entryRequestedComputed,
-      isMainResource: false,
-      computedDependencies: entry.__$jsonrestapi_computed_deps$__
-    })
-  }
+  await enrichIncludedAttributes(context, scopes)
 
-  // The called hooks should NOT change context.record
   await runHooks('finish')
   await runHooks('finishQuery')
+  await filterToOneResponseLinkage(context, scopes)
 
   // Enrichers and finish hooks run after the database pass and may introduce
   // native values. Reassert the public temporal contract at the return boundary.
   context.record = normalizeRecordAttributes(context.record, scopes, {
     source: 'response'
   })
+  filterResponseFields(context.record, context.queryParams.fields)
 
-  // Transform output if in simplified mode
   if (context.simplified) {
-    // Convert JSON:API response back to simplified format
-    // Example: {data: {type: 'posts', id: '1', attributes: {title: 'My Post'}, relationships: {author: {data: {type: 'users', id: '123'}}}}}
-    // becomes: {id: '1', title: 'My Post', author_id: '123'} - flattens structure and restores foreign keys
     return transformJsonApiToSimplified(
       { record: context.record },
       { context: { schemaStructure, schemaRelationships, scopes } }

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

@@ -1,9 +1,10 @@
+// @ts-check
 /**
  * release
  * Runs the hook that tells plugins to release resources
  */
+/** @param {import('../../../types/runtime.js').RuntimeArguments} args */
 export default async ({ runHooks }) => {
-  // Run the addRoute hook to notify transport plugins
   await runHooks('release')
 
   return { }