json-rest-api 1.0.28 → 2.0.0

package/plugins/core/lib/querying-writing/request-contracts.js

@@ -1,5 +1,6 @@
 import { addType, addValidator, createSchema } from 'json-rest-schema'
 import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { requireDocumentResourceId, requireExistingResourceId } from './resource-id-normalization.js'
 import { getRelationshipCardinality } from './relationship-contracts.js'
 
 function isPlainObject (value) {
@@ -76,12 +77,12 @@ function buildFieldMapJsonSchemaFragment () {
 
 function buildKnownPageSchema () {
   return createSchema({
-    number: { type: 'number' },
-    size: { type: 'number' },
-    limit: { type: 'number' },
-    offset: { type: 'number' },
-    after: { type: 'string' },
-    before: { type: 'string' },
+    number: { type: 'integer', min: 1 },
+    size: { type: 'integer', min: 1 },
+    limit: { type: 'integer', min: 1 },
+    offset: { type: 'integer', min: 0 },
+    after: { type: 'string', min: 1 },
+    before: { type: 'string', min: 1 },
     cursor: { type: 'string' }
   })
 }
@@ -313,6 +314,16 @@ function installRequestContractSupport () {
       const firstError = pickFirstError(errors)
       context.throwParamError(firstError?.code || 'INVALID_PAGE', firstError?.message || 'Invalid page parameters.')
     }
+    for (const direction of ['after', 'before']) {
+      if (Object.hasOwn(knownPageParams, direction) && !validatedObject[direction]?.trim()) {
+        context.throwParamError('INVALID_PAGE', `page[${direction}] must contain a cursor.`)
+      }
+    }
+
+    if ((validatedObject.after !== undefined && validatedObject.before !== undefined) ||
+        (validatedObject.number !== undefined && (validatedObject.after !== undefined || validatedObject.before !== undefined))) {
+      context.throwParamError('INVALID_PAGE', 'Use either page[number], page[after], or page[before].')
+    }
 
     return {
       ...context.value,
@@ -335,18 +346,9 @@ function installRequestContractSupport () {
 
 function buildWritableAttributesStructure (schemaInfo = {}) {
   const schemaStructure = schemaInfo.schemaStructure || {}
-  const schemaRelationships = schemaInfo.schemaRelationships || {}
   const idProperty = schemaInfo.idProperty || 'id'
   const attributesStructure = {}
-  const excludedFieldNames = new Set()
-
-  for (const relDef of Object.values(schemaRelationships)) {
-    if (!relDef?.belongsToPolymorphic) continue
-
-    const { typeField, idField } = relDef.belongsToPolymorphic
-    if (typeField) excludedFieldNames.add(typeField)
-    if (idField) excludedFieldNames.add(idField)
-  }
+  const excludedFieldNames = schemaInfo.foreignKeyFields
 
   for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
     if (!fieldDef) continue
@@ -354,7 +356,6 @@ function buildWritableAttributesStructure (schemaInfo = {}) {
     if (excludedFieldNames.has(fieldName)) continue
     if (fieldDef.computed === true) continue
     if (fieldDef.type === undefined) continue
-    if (fieldDef.belongsTo && fieldDef.as) continue
     attributesStructure[fieldName] = { ...fieldDef }
   }
 
@@ -376,14 +377,14 @@ function resolveRelationshipAllowedTypes (relName, relDef) {
     return relDef.belongsToPolymorphic.types
   }
 
-  if (relDef?.target) {
-    return [relDef.target]
-  }
-
   if (relDef?.belongsTo) {
     return [relDef.belongsTo]
   }
 
+  if (relDef?.target) {
+    return [relDef.target]
+  }
+
   if (relDef?.type === 'manyToMany' || relDef?.type === 'hasMany' || relDef?.type === 'hasOne') {
     return [relDef.target || relName]
   }
@@ -392,28 +393,9 @@ function resolveRelationshipAllowedTypes (relName, relDef) {
 }
 
 function buildRelationshipStructure (schemaInfo = {}) {
-  const schemaStructure = schemaInfo.schemaStructure || {}
-  const schemaRelationships = schemaInfo.schemaRelationships || {}
   const relationshipStructure = {}
 
-  for (const [, fieldDef] of Object.entries(schemaStructure)) {
-    if (!fieldDef?.belongsTo || !fieldDef?.as) continue
-
-    relationshipStructure[fieldDef.as] = {
-      type: 'object',
-      schema: createSchema({
-        data: {
-          type: 'jsonApiRelationshipData',
-          required: true,
-          nullable: true,
-          cardinality: 'one',
-          allowedTypes: [fieldDef.belongsTo]
-        }
-      })
-    }
-  }
-
-  for (const [relName, relDef] of Object.entries(schemaRelationships)) {
+  for (const [relName, relDef] of Object.entries(schemaInfo.outputRelationships || {})) {
     const cardinality = getRelationshipCardinality(relDef)
     relationshipStructure[relName] = {
       type: 'object',
@@ -473,7 +455,10 @@ function buildWriteDocumentContract (scopeName, schemaInfo, mode) {
   }
 
   const schema = createSchema({
-    data: dataFieldDefinition
+    data: dataFieldDefinition,
+    meta: { type: 'object', additionalProperties: true },
+    links: { type: 'object', additionalProperties: true },
+    jsonapi: { type: 'object', additionalProperties: true }
   })
 
   return {
@@ -583,17 +568,19 @@ function buildRequestContracts ({ scopeName, schemaInfo, includeDepthLimit, sort
   }
 }
 
-function buildContractCacheKey ({ includeDepthLimit, sortableFields }) {
+function buildContractCacheKey ({ scopeName, includeDepthLimit, sortableFields }) {
   return JSON.stringify({
+    scopeName,
     includeDepthLimit,
     sortableFields: Array.isArray(sortableFields) ? [...sortableFields].sort() : []
   })
 }
 
+/** @param {{ scopeName: string, schemaInfo: object, includeDepthLimit?: number, sortableFields?: string[] }} options */
 export function getRequestContracts ({ scopeName, schemaInfo, includeDepthLimit = 3, sortableFields = [] }) {
   installRequestContractSupport()
 
-  const cacheKey = buildContractCacheKey({ includeDepthLimit, sortableFields })
+  const cacheKey = buildContractCacheKey({ scopeName, includeDepthLimit, sortableFields })
   if (schemaInfo.requestContracts && schemaInfo.requestContractsCacheKey === cacheKey) {
     return schemaInfo.requestContracts
   }
@@ -619,6 +606,10 @@ export function validateRequestContractOrThrow (contract, payload, message = 'Re
     throw new Error('Invalid request contract.')
   }
 
+  if (!isPlainObject(payload)) {
+    throw new RestApiValidationError('document must be an object', { fields: ['document'] })
+  }
+
   const { validatedObject, errors } = schema[mode](payload)
   if (Object.keys(errors).length === 0) {
     return validatedObject
@@ -637,3 +628,77 @@ export function validateRequestContractOrThrow (contract, payload, message = 'Re
     violations
   })
 }
+
+/** Select input by argument name, independently of the response format. */
+export function selectWriteInput (params) {
+  const hasData = Object.hasOwn(params, 'data')
+  const hasDocument = Object.hasOwn(params, 'document')
+  if (hasData === hasDocument) {
+    throw new RestApiValidationError('Supply exactly one of data or document', { fields: ['data', 'document'] })
+  }
+  if (hasDocument) {
+    if (!isPlainObject(params.document)) {
+      throw new RestApiValidationError('document must be an object', { fields: ['document'] })
+    }
+    const unsupported = ['errors', 'included'].filter(key => Object.hasOwn(params.document, key))
+    if (unsupported.length) {
+      throw new RestApiValidationError('Write documents do not support errors or included resources', {
+        fields: unsupported.map(key => `document.${key}`)
+      })
+    }
+  }
+  return hasDocument ? 'document' : 'data'
+}
+
+/** Validate PUT/PATCH identity and body, then store the normalized document and ID on context. */
+export function validateUpdateRequest ({ method, params, context, vars, scopeOptions, scopeName }) {
+  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 === undefined) {
+    context.inputRecord = {
+      ...context.inputRecord,
+      data: {
+        ...(context.inputRecord?.data || {}),
+        id: normalizedPathId
+      }
+    }
+  }
+
+  context.inputRecord = validateRequestContractOrThrow(
+    requestContracts[method],
+    context.inputRecord,
+    `${method.toUpperCase()} 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
+}

package/plugins/core/lib/querying-writing/resource-id-normalization.js

@@ -1,8 +1,17 @@
+// @ts-check
+
+/** @import { RestApiPluginOptions } from '../../../../types/plugin-options.js' */
+/** @typedef {Pick<RestApiPluginOptions, 'normalizeId'>} NormalizerConfig */
+/** @typedef {{ scopeOptions?: NormalizerConfig | null, vars?: NormalizerConfig | null, scopeName?: string }} NormalizationOptions */
+/** @typedef {{ resources?: Record<string, { scopeOptions?: NormalizerConfig | null, _scopeOptions?: NormalizerConfig | null, vars?: NormalizerConfig | null }> }} NormalizationApi */
+/** @typedef {{ api?: NormalizationApi }} ReferenceOptions */
+
 import {
   RestApiResourceError,
   RestApiValidationError
 } from '../../../../lib/rest-api-errors.js'
 
+/** @param {unknown} value @returns {string | null} */
 export function defaultNormalizeResourceId (value) {
   if (value === null || value === undefined) {
     return null
@@ -21,10 +30,10 @@ export function defaultNormalizeResourceId (value) {
     return String(value)
   }
 
-  const normalized = String(value).trim()
-  return normalized || null
+  return null
 }
 
+/** @param {NormalizationOptions} [options] @returns {NonNullable<RestApiPluginOptions["normalizeId"]>} */
 export function resolveResourceIdNormalizer ({ scopeOptions = null, vars = null } = {}) {
   if (typeof scopeOptions?.normalizeId === 'function') {
     return scopeOptions.normalizeId
@@ -37,11 +46,13 @@ export function resolveResourceIdNormalizer ({ scopeOptions = null, vars = null
   return defaultNormalizeResourceId
 }
 
+/** @param {unknown} value @param {NormalizationOptions} [options] @returns {string | null} */
 export function normalizeResourceId (value, options = {}) {
   const normalizer = resolveResourceIdNormalizer(options)
   return defaultNormalizeResourceId(normalizer(value))
 }
 
+/** @param {unknown} value @param {NormalizationOptions} [options] @returns {string} */
 export function requireExistingResourceId (value, {
   scopeOptions = null,
   vars = null,
@@ -57,11 +68,12 @@ export function requireExistingResourceId (value, {
     {
       subtype: 'not_found',
       resourceType: scopeName,
-      resourceId: value == null ? null : String(value)
+      resourceId: typeof value === 'string' ? value : defaultNormalizeResourceId(value)
     }
   )
 }
 
+/** @param {unknown} value @param {NormalizationOptions} [options] @returns {string} */
 export function requireDocumentResourceId (value, {
   scopeOptions = null,
   vars = null
@@ -84,6 +96,7 @@ export function requireDocumentResourceId (value, {
   )
 }
 
+/** @param {string} resourceType @param {ReferenceOptions} [options] @returns {NormalizationOptions} */
 function resolveResourceNormalizationOptions (resourceType, { api } = {}) {
   const scope = api?.resources?.[resourceType]
   return {
@@ -93,6 +106,7 @@ function resolveResourceNormalizationOptions (resourceType, { api } = {}) {
   }
 }
 
+/** @param {string} resourceType @param {unknown} value @param {ReferenceOptions} [options] @returns {string} */
 export function requireReferencedResourceId (resourceType, value, { api } = {}) {
   return requireExistingResourceId(
     value,
@@ -100,12 +114,15 @@ export function requireReferencedResourceId (resourceType, value, { api } = {})
   )
 }
 
+/** @param {unknown} identifier @param {ReferenceOptions} [options] @returns {unknown} */
 function normalizeRelationshipIdentifier (identifier, { api } = {}) {
   if (!identifier || typeof identifier !== 'object' || Array.isArray(identifier)) {
     return identifier
   }
 
-  const type = typeof identifier.type === 'string' ? identifier.type : ''
+  // Object shape is known here; its property values remain unvalidated.
+  const record = /** @type {Record<string, unknown>} */ (identifier)
+  const type = typeof record.type === 'string' ? record.type : ''
   if (!type || !Object.hasOwn(identifier, 'id')) {
     return {
       ...identifier
@@ -114,10 +131,11 @@ function normalizeRelationshipIdentifier (identifier, { api } = {}) {
 
   return {
     ...identifier,
-    id: requireReferencedResourceId(type, identifier.id, { api })
+    id: requireReferencedResourceId(type, record.id, { api })
   }
 }
 
+/** @param {unknown} relationshipData @param {ReferenceOptions} [options] @returns {unknown} */
 export function normalizeRelationshipIdentifiers (relationshipData, { api } = {}) {
   if (Array.isArray(relationshipData)) {
     return relationshipData.map((identifier) => normalizeRelationshipIdentifier(identifier, { api }))

package/plugins/core/lib/querying-writing/response-options.js

@@ -0,0 +1,35 @@
+// @ts-check
+import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+
+/** @import { ResourceFormat, WriteReturning } from '../../../../types/representations.js' */
+
+/** @param {unknown} [value] @param {unknown} [fallback] @returns {ResourceFormat} */
+export function resolveFormat (value, fallback = 'plain') {
+  const format = value === undefined ? fallback : value
+  if (format !== 'plain' && format !== 'jsonapi') {
+    throw new RestApiValidationError("format must be 'plain' or 'jsonapi'", { fields: ['format'] })
+  }
+  return format
+}
+
+/** @param {unknown} [value] @param {unknown} [fallback] @returns {WriteReturning} */
+export function resolveReturning (value, fallback = 'full') {
+  const returning = value === undefined ? fallback : value
+  if (returning !== 'none' && returning !== 'minimal' && returning !== 'full') {
+    throw new RestApiValidationError("returning must be 'none', 'minimal', or 'full'", { fields: ['returning'] })
+  }
+  return returning
+}
+
+/** @param {object} options @returns {void} */
+export function rejectRemovedOptions (options) {
+  const removedInput = ['inputRecord', 'inputRecords'].filter(name => Object.hasOwn(options, name))
+  if (removedInput.length) {
+    throw new RestApiValidationError(`Removed input options: ${removedInput.join(', ')}. Use data or document.`, { fields: removedInput })
+  }
+  const fields = ['simplified', 'simplifiedApi', 'simplifiedTransport', 'returnFullRecord', 'returnRecordApi', 'returnRecordTransport', 'isTransport']
+    .filter(name => Object.hasOwn(options, name))
+  if (fields.length) {
+    throw new RestApiValidationError(`Removed options: ${fields.join(', ')}. Use format and returning.`, { fields })
+  }
+}