json-rest-api 1.0.26 → 1.0.27

package/docs/API.md

@@ -2052,6 +2052,11 @@ const result = await api.resources.articles.query({
 // GET /articles?fields[articles]=title,summary&fields[users]=name,avatar
 ```
 
+An unknown field raises `RestApiFieldsetError` with the stable code
+`REST_API_FIELDSET_INVALID` and HTTP status `400`. The same error is preserved
+for primary resources and included relationships, so transports can classify it
+without parsing error messages.
+
 ### Including Related Resources
 
 Load related resources in a single request:

package/index.js

@@ -33,6 +33,7 @@ export { S3Storage } from './plugins/storage/s3-storage.js'
 
 // Error classes for consumers who need them
 export {
+  RestApiFieldsetError,
   RestApiValidationError,
   RestApiResourceError,
   RestApiPayloadError

package/lib/error-context.js

@@ -0,0 +1,21 @@
+import { HookedApiError } from 'hooked-api'
+
+export function isRestApiError (error) {
+  return error instanceof HookedApiError
+}
+
+/**
+ * Add operational context to unexpected failures without erasing typed API
+ * errors that callers and transports need to classify.
+ */
+export function wrapUnexpectedError (error, { message, context } = {}) {
+  if (isRestApiError(error)) {
+    return error
+  }
+
+  const wrappedError = new Error(`${message}: ${error.message}`, {
+    cause: error
+  })
+  wrappedError.context = context
+  return wrappedError
+}

package/lib/rest-api-errors.js

@@ -1,5 +1,7 @@
 import { HookedApiError } from 'hooked-api'
 
+export const REST_API_FIELDSET_ERROR_CODE = 'REST_API_FIELDSET_INVALID'
+
 /**
  * REST API specific error classes that can be mapped to HTTP status codes
  * by the HTTP plugin or other protocol plugins
@@ -90,3 +92,36 @@ export class RestApiPayloadError extends HookedApiError {
     }
   }
 }
+
+/**
+ * Invalid JSON:API sparse fieldset.
+ *
+ * The structured code lets transports distinguish invalid client input from
+ * query or include failures without parsing the human-readable message.
+ */
+export class RestApiFieldsetError extends HookedApiError {
+  constructor ({ field, resourceType } = {}) {
+    super(
+      `Unknown sparse field '${field}' requested for '${resourceType}'`,
+      REST_API_FIELDSET_ERROR_CODE
+    )
+    this.type = 'rest_api_fieldset'
+    this.statusCode = 400
+    this.details = {
+      field,
+      resourceType
+    }
+  }
+
+  toJSON () {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      type: this.type,
+      statusCode: this.statusCode,
+      details: this.details,
+      stack: this.stack
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-rest-api",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "main": "index.js",
   "type": "module",
   "scripts": {

package/plugins/core/connectors/lib/transport-http-helpers.js

@@ -1,3 +1,5 @@
+import { REST_API_FIELDSET_ERROR_CODE } from '../../../../lib/rest-api-errors.js'
+
 const JSON_API_WRITE_CONTENT_TYPES = [
   'application/vnd.api+json',
   'application/json'
@@ -63,6 +65,14 @@ export function mapRestApiErrorToHttp (error) {
       detail: issue.message,
       ...(issue.instancePath ? { source: { pointer: issue.instancePath } } : {})
     }))
+  } else if (error.code === REST_API_FIELDSET_ERROR_CODE) {
+    status = 400
+    errors = [{
+      status: '400',
+      code: error.code,
+      title: 'Invalid Sparse Fieldset',
+      detail: error.message
+    }]
   } else if (error.code === 'REST_API_VALIDATION') {
     status = 422
     if (error.details?.violations?.length) {

package/plugins/core/lib/querying/knex-process-includes.js

@@ -1,4 +1,5 @@
 import { buildIncludedResources } from './knex-relationship-includes.js'
+import { isRestApiError, wrapUnexpectedError } from '../../../../lib/error-context.js'
 
 /**
  * Processes the ?include= parameter to load related resources efficiently
@@ -143,6 +144,8 @@ export const processIncludes = async (scope, records, deps) => {
 
     return includeResult.included
   } catch (error) {
+    if (isRestApiError(error)) throw error
+
     const { log, context } = deps || {}
 
     if (log) {
@@ -157,10 +160,13 @@ export const processIncludes = async (scope, records, deps) => {
       console.error('[PROCESS-INCLUDES] Error processing includes:', error)
     }
 
-    const enhancedError = new Error(
-      `Failed to process includes${context?.scopeName ? ` for scope '${context.scopeName}'` : ''}: ${error.message}`
-    )
-    enhancedError.originalError = error
-    throw enhancedError
+    throw wrapUnexpectedError(error, {
+      message: `Failed to process includes${context?.scopeName ? ` for scope '${context.scopeName}'` : ''}`,
+      context: {
+        scopeName: context?.scopeName,
+        includeParam: context?.queryParams?.include,
+        recordCount: records?.length || 0
+      }
+    })
   }
 }

package/plugins/core/lib/querying/knex-relationship-includes.js

@@ -84,6 +84,7 @@ import {
 import { unwrapQueryBuilderState } from './query-builder-utils.js'
 import { RELATIONSHIPS_KEY, RELATIONSHIP_METADATA_KEY, ROW_NUMBER_KEY, COMPUTED_DEPENDENCIES_KEY, DEFAULT_QUERY_LIMIT } from '../querying-writing/knex-constants.js'
 import { RestApiResourceError } from '../../../../lib/rest-api-errors.js'
+import { isRestApiError, wrapUnexpectedError } from '../../../../lib/error-context.js'
 import {
   getFieldValue as getStorageFieldValue,
   getIdColumn as getStorageIdColumn,
@@ -415,14 +416,18 @@ const loadRelationshipMetadata = async (scopes, records, scopeName) => {
       }
     })
   } catch (error) {
-    // Log error with context and re-throw
+    if (isRestApiError(error)) throw error
+
     const errorContext = {
       scopeName,
       recordCount: records?.length || 0,
       error: error.message
     }
     console.error('[loadRelationshipMetadata] Error loading relationship metadata:', errorContext)
-    throw new Error(`Failed to load relationship metadata for scope '${scopeName}': ${error.message}`)
+    throw wrapUnexpectedError(error, {
+      message: `Failed to load relationship metadata for scope '${scopeName}'`,
+      context: errorContext
+    })
   }
 }
 
@@ -626,6 +631,8 @@ export const loadBelongsTo = async (scope, deps) => {
       }
     }
   } catch (error) {
+    if (isRestApiError(error)) throw error
+
     // Log error with detailed context
     log.error('[INCLUDE] Error loading belongsTo relationship:', {
       fieldName,
@@ -636,13 +643,10 @@ export const loadBelongsTo = async (scope, deps) => {
       stack: error.stack
     })
 
-    // Re-throw with enhanced error message
-    const enhancedError = new Error(
-      `Failed to load belongsTo relationship '${includeName}' for field '${fieldName}': ${error.message}`
-    )
-    enhancedError.originalError = error
-    enhancedError.context = { fieldName, includeName, targetScope: fieldDef.belongsTo }
-    throw enhancedError
+    throw wrapUnexpectedError(error, {
+      message: `Failed to load belongsTo relationship '${includeName}' for field '${fieldName}'`,
+      context: { fieldName, includeName, targetScope: fieldDef.belongsTo }
+    })
   }
 }
 
@@ -1159,6 +1163,8 @@ export const loadHasMany = async (scope, deps) => {
       }
     }
   } catch (error) {
+    if (isRestApiError(error)) throw error
+
     // Log error with detailed context
     log.error('[INCLUDE] Error loading hasMany relationship:', {
       scopeName,
@@ -1169,13 +1175,10 @@ export const loadHasMany = async (scope, deps) => {
       stack: error.stack
     })
 
-    // Re-throw with enhanced error message
-    const enhancedError = new Error(
-      `Failed to load hasMany relationship '${includeName}' for scope '${scopeName}': ${error.message}`
-    )
-    enhancedError.originalError = error
-    enhancedError.context = { scopeName, includeName, hasThrough: !!relDef.through }
-    throw enhancedError
+    throw wrapUnexpectedError(error, {
+      message: `Failed to load hasMany relationship '${includeName}' for scope '${scopeName}'`,
+      context: { scopeName, includeName, hasThrough: !!relDef.through }
+    })
   }
 }
 
@@ -1539,6 +1542,8 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
       }
     })
   } catch (error) {
+    if (isRestApiError(error)) throw error
+
     // Log error with detailed context
     log.error('[INCLUDE] Error loading polymorphic belongsTo relationship:', {
       relName,
@@ -1548,13 +1553,10 @@ export const loadPolymorphicBelongsTo = async (scope, deps) => {
       stack: error.stack
     })
 
-    // Re-throw with enhanced error message
-    const enhancedError = new Error(
-      `Failed to load polymorphic belongsTo relationship '${relName}': ${error.message}`
-    )
-    enhancedError.originalError = error
-    enhancedError.context = { relName, types: relDef?.belongsToPolymorphic?.types }
-    throw enhancedError
+    throw wrapUnexpectedError(error, {
+      message: `Failed to load polymorphic belongsTo relationship '${relName}'`,
+      context: { relName, types: relDef?.belongsToPolymorphic?.types }
+    })
   }
 }
 
@@ -1759,6 +1761,8 @@ export const loadReversePolymorphic = async (scope, deps) => {
       }
     }
   } catch (error) {
+    if (isRestApiError(error)) throw error
+
     // Log error with detailed context
     log.error('[INCLUDE] Error loading reverse polymorphic relationship:', {
       scopeName,
@@ -1770,13 +1774,10 @@ export const loadReversePolymorphic = async (scope, deps) => {
       stack: error.stack
     })
 
-    // Re-throw with enhanced error message
-    const enhancedError = new Error(
-      `Failed to load reverse polymorphic relationship '${includeName}' via '${relDef?.via}' for scope '${scopeName}': ${error.message}`
-    )
-    enhancedError.originalError = error
-    enhancedError.context = { scopeName, includeName, via: relDef?.via, targetScope: relDef?.target }
-    throw enhancedError
+    throw wrapUnexpectedError(error, {
+      message: `Failed to load reverse polymorphic relationship '${includeName}' via '${relDef?.via}' for scope '${scopeName}'`,
+      context: { scopeName, includeName, via: relDef?.via, targetScope: relDef?.target }
+    })
   }
 }
 
@@ -1897,6 +1898,8 @@ export const processIncludes = async (scope, deps) => {
           }
         }
       } catch (includeError) {
+        if (isRestApiError(includeError)) throw includeError
+
         // Log specific include error and continue with other includes
         log.error('[INCLUDE] Error processing include:', {
           scopeName,
@@ -1918,6 +1921,8 @@ export const processIncludes = async (scope, deps) => {
       }
     }
   } catch (error) {
+    if (isRestApiError(error)) throw error
+
     // Log error with full context
     log.error('[INCLUDE] Error in processIncludes:', {
       scopeName,
@@ -2019,6 +2024,8 @@ export const buildIncludedResources = async (scope, deps) => {
       recordsWithRelationships: records
     }
   } catch (error) {
+    if (isRestApiError(error)) throw error
+
     // Log comprehensive error information
     log.error('[INCLUDE] Failed to build included resources:', {
       scopeName,
@@ -2028,15 +2035,14 @@ export const buildIncludedResources = async (scope, deps) => {
       stack: error.stack
     })
 
-    // Re-throw with additional context
-    const enhancedError = new Error(`Failed to build included resources for scope '${scopeName}': ${error.message}`)
-    enhancedError.originalError = error
-    enhancedError.context = {
-      scopeName,
-      includeParam,
-      recordCount: records?.length || 0
-    }
-    throw enhancedError
+    throw wrapUnexpectedError(error, {
+      message: `Failed to build included resources for scope '${scopeName}'`,
+      context: {
+        scopeName,
+        includeParam,
+        recordCount: records?.length || 0
+      }
+    })
   }
 }
 

package/plugins/core/lib/querying-writing/knex-field-helpers.js

@@ -1,6 +1,7 @@
 import { buildQuerySelection } from '../querying/knex-query-helpers-base.js'
 import { createSelectTranslator } from '../storage/storage-adapter.js'
 import { buildQueryFieldRuntimes } from './query-field-helpers.js'
+import { RestApiFieldsetError } from '../../../../lib/rest-api-errors.js'
 
 /**
  * Checks if a field exists only in code, not in the database
@@ -211,7 +212,12 @@ export const buildFieldSelection = async (scope, deps) => {
       if (nonDatabaseFields.has(field)) return
 
       const fieldDef = schemaStructure[field]
-      if (!fieldDef) throw new Error(`Unknown sparse field '${field}' requested for '${scopeName}'`)
+      if (!fieldDef) {
+        throw new RestApiFieldsetError({
+          field,
+          resourceType: scopeName
+        })
+      }
 
       if (fieldDef.belongsToPolymorphic) {
         return

package/tests/computed-fields.test.js

@@ -4,6 +4,23 @@ import knexLib from 'knex'
 import { cleanTables } from './helpers/test-utils.js'
 import { storageMode } from './helpers/storage-mode.js'
 import { createComputedFieldsApi } from './fixtures/api-configs.js'
+import {
+  REST_API_FIELDSET_ERROR_CODE,
+  RestApiFieldsetError
+} from '../index.js'
+import { mapRestApiErrorToHttp } from '../plugins/core/connectors/lib/transport-http-helpers.js'
+
+function assertFieldsetError (error, { field, resourceType }) {
+  assert(error instanceof RestApiFieldsetError)
+  assert.equal(error.code, REST_API_FIELDSET_ERROR_CODE)
+  assert.equal(error.statusCode, 400)
+  assert.deepEqual(error.details, { field, resourceType })
+  assert.equal(
+    error.message,
+    `Unknown sparse field '${field}' requested for '${resourceType}'`
+  )
+  return true
+}
 
 // Create Knex instance for tests
 const knex = knexLib({
@@ -365,7 +382,10 @@ describe('Computed Fields and Sparse Fieldsets', () => {
             fields: { products: 'name,unknown_field' }
           }
         }),
-        /Unknown sparse field 'unknown_field'/
+        (error) => assertFieldsetError(error, {
+          field: 'unknown_field',
+          resourceType: 'products'
+        })
       )
     })
 
@@ -377,9 +397,56 @@ describe('Computed Fields and Sparse Fieldsets', () => {
             fields: { products: 'name,reviews_ids' }
           }
         }),
-        /Unknown sparse field 'reviews_ids'/
+        (error) => assertFieldsetError(error, {
+          field: 'reviews_ids',
+          resourceType: 'products'
+        })
       )
     })
+
+    it('should preserve fieldset errors from empty included relationships', async () => {
+      const productWithoutReviews = await api.resources.products.post({
+        name: 'No Reviews',
+        price: 25,
+        cost: 10
+      })
+
+      await assert.rejects(
+        api.resources.products.get({
+          id: productWithoutReviews.id,
+          queryParams: {
+            include: ['reviews'],
+            fields: {
+              products: 'name',
+              reviews: 'definitelyHidden'
+            }
+          }
+        }),
+        (error) => assertFieldsetError(error, {
+          field: 'definitelyHidden',
+          resourceType: 'reviews'
+        })
+      )
+    })
+
+    it('should map fieldset errors to an HTTP 400 response', () => {
+      const error = new RestApiFieldsetError({
+        field: 'definitelyHidden',
+        resourceType: 'reviews'
+      })
+
+      assert.deepEqual(mapRestApiErrorToHttp(error), {
+        status: 400,
+        body: {
+          errors: [{
+            status: '400',
+            code: REST_API_FIELDSET_ERROR_CODE,
+            title: 'Invalid Sparse Fieldset',
+            detail: "Unknown sparse field 'definitelyHidden' requested for 'reviews'"
+          }]
+        }
+      })
+    })
   })
 
   describe('Async Computed Fields', () => {

package/tests/includes.test.js

@@ -2,6 +2,10 @@ import { describe, it, before, beforeEach, after } from 'node:test'
 import assert from 'node:assert/strict'
 import knexLib from 'knex'
 import { createBasicApi, createExtendedApi } from './fixtures/api-configs.js'
+import {
+  REST_API_FIELDSET_ERROR_CODE,
+  RestApiFieldsetError
+} from '../index.js'
 import {
   validateJsonApiStructure,
   resourceIdentifier,
@@ -165,6 +169,51 @@ describe('Include/Sideloading Operations', () => {
       assert(includedTypes.includes('publishers'))
       assert(includedTypes.includes('countries'))
     })
+
+    it('should preserve typed fieldset errors across included relationships', async () => {
+      const requests = [
+        {
+          resource: basicApi.resources.countries,
+          id: testData.country.id,
+          include: 'books',
+          primaryType: 'countries',
+          includedType: 'books'
+        },
+        {
+          resource: basicApi.resources.books,
+          id: testData.book.id,
+          include: 'publisher',
+          primaryType: 'books',
+          includedType: 'publishers'
+        }
+      ]
+
+      for (const request of requests) {
+        await assert.rejects(
+          request.resource.get({
+            id: request.id,
+            queryParams: {
+              include: [request.include],
+              fields: {
+                [request.primaryType]: 'id',
+                [request.includedType]: 'definitelyHidden'
+              }
+            },
+            simplified: false
+          }),
+          (error) => {
+            assert(error instanceof RestApiFieldsetError)
+            assert.equal(error.code, REST_API_FIELDSET_ERROR_CODE)
+            assert.equal(error.statusCode, 400)
+            assert.deepEqual(error.details, {
+              field: 'definitelyHidden',
+              resourceType: request.includedType
+            })
+            return true
+          }
+        )
+      }
+    })
   })
 
   describe('Nested Includes', () => {