json-rest-api 1.0.28 → 2.0.0

package/plugins/core/rest-api-label-plugin.js

@@ -1,3 +1,5 @@
+import { getForeignKeyFields } from './lib/querying-writing/field-utils.js'
+
 export const LabelPlugin = {
   name: 'rest-api-label',
   dependencies: ['rest-api'],
@@ -15,57 +17,42 @@ export const LabelPlugin = {
       ...pluginOptions
     }
 
-    function pickLabelFieldFromFields (fields, searchSchema) {
-      const byGlobal = Object.keys(searchSchema || {}).find(k => searchSchema[k]?.globalSearch)
-      if (byGlobal) return byGlobal
-      for (const key of opts.preferNameFields) {
-        if (fields?.[key]?.type === 'string') return key
+    function labelFields (fields, searchSchema, idProperty, relationships) {
+      const relationshipFields = getForeignKeyFields(fields, relationships)
+      const publicField = name => {
+        const field = fields[name]
+        return Object.hasOwn(fields, name) && name !== idProperty && !relationshipFields.has(name) && !field.hidden && !field.normallyHidden && !field.virtual
       }
-      const firstString = Object.entries(fields || {}).find(([_, def]) => def?.type === 'string')?.[0]
-      if (firstString) return firstString
-      return null
+      const byGlobal = Object.entries(searchSchema || {})
+        .filter(([, field]) => field.globalSearch)
+        .map(([name, field]) => field.actualField || name)
+        .find(publicField)
+      const strings = Object.keys(fields).filter(name => publicField(name) && fields[name].type === 'string')
+      return [...new Set([byGlobal, ...opts.preferNameFields.filter(name => strings.includes(name)), strings[0]].filter(Boolean))]
     }
 
-    // Inject as a computed field AFTER schemas are compiled,
-    // so it lives in schemaInfo.computed and not in schemaStructure
     addHook(
-      'scope:added',
+      'computedSchema:enrich',
       'rest-api-label:inject-computed',
-      { afterFunction: 'compileResourceSchemas' },
-      ({ context, scopes }) => {
+      {},
+      ({ context }) => {
         if (opts.disable) return
-        const { scopeName } = context
-        const scope = scopes?.[scopeName]
-        const schemaInfo = scope?.vars?.schemaInfo
-        if (!schemaInfo) return
+        const { fields, schemaStructure, searchSchemaStructure, schemaRelationships, idProperty } = context
 
         // Respect explicit label already defined by resource
-        if (schemaInfo.computed?.label || schemaInfo.schemaStructure?.label) {
-          // If label accidentally made it into schemaStructure, remove it
-          if (schemaInfo.schemaStructure?.label) delete schemaInfo.schemaStructure.label
-          return
-        }
+        if (Object.hasOwn(fields, 'label') || Object.hasOwn(schemaStructure, 'label')) return
 
-        const structure = schemaInfo.schemaStructure || {}
-        const searchStruct = schemaInfo.searchSchemaStructure || {}
-        const idProp = schemaInfo.idProperty || 'id'
+        const candidates = labelFields(schemaStructure, searchSchemaStructure, idProperty, schemaRelationships)
 
-        const pick = pickLabelFieldFromFields(structure, searchStruct)
-
-        schemaInfo.computed = schemaInfo.computed || {}
-        schemaInfo.computed.label = {
+        fields.label = {
           type: 'string',
           computed: true,
-          ...(pick ? { dependencies: [pick] } : {}),
-          compute: ({ attributes }) => {
-            if (pick) {
-              const v = attributes?.[pick]
-              if (v != null) return String(v)
-            }
-            for (const k of opts.preferNameFields) {
-              if (attributes?.[k] != null) return String(attributes[k])
+          dependencies: candidates,
+          compute: ({ attributes, id }) => {
+            for (const field of candidates) {
+              if (attributes?.[field] != null) return String(attributes[field])
             }
-            return String(attributes?.[idProp] ?? '')
+            return String(id ?? '')
           }
         }
       }

package/plugins/core/rest-api-plugin-hooks/register-relationship-routes.js

@@ -2,18 +2,18 @@ import { parseJsonApiQuery } from '../lib/querying-writing/connectors-query-pars
 
 export default async function registerRelationshipRoutes ({ context, api, log }) {
   const { scopeName } = context
-  const basePath = api.scopes[scopeName].vars.transport?.mountPath || ''
+  const basePath = api.resources[scopeName].vars.transport?.mountPath || ''
   const scopePath = `${basePath}/${scopeName}`
 
   // Helper to create route handlers
   const createRouteHandler = (methodName) => {
-    return async ({ params, body, queryString }) => {
-      const scope = api.scopes[scopeName]
+    return async ({ params, body, queryString, context }) => {
+      const scope = api.resources[scopeName]
 
       const methodParams = {
         id: params.id,
         relationshipName: params.relationshipName,
-        isTransport: true
+        format: 'jsonapi'
       }
 
       // Add query params for getRelated
@@ -26,7 +26,7 @@ export default async function registerRelationshipRoutes ({ context, api, log })
         methodParams.relationshipData = body.data
       }
 
-      return await scope[methodName](methodParams)
+      return await scope[methodName](methodParams, context)
     }
   }
 

package/plugins/core/rest-api-plugin-hooks/register-scope-routes.js

@@ -1,5 +1,6 @@
 import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
 import { parseJsonApiQuery } from '../lib/querying-writing/connectors-query-parser.js'
+import { writePrecondition } from '../rest-api-plugin-methods/common.js'
 
 export default async function registerScopeRoutes ({ context, api, vars, log }) {
   const { scopeName } = context
@@ -7,8 +8,8 @@ export default async function registerScopeRoutes ({ context, api, vars, log })
 
   // Helper to create route handlers
   const createRouteHandler = (scopeName, methodName) => {
-    return async ({ queryString, headers, params, body, context }) => {
-      const scope = api.scopes[scopeName]
+    return async ({ queryString, headers, params, body, context, transaction, precondition }) => {
+      const scope = api.resources[scopeName]
       if (!scope) {
         throw new RestApiResourceError(
           `Scope '${scopeName}' not found`,
@@ -21,7 +22,10 @@ export default async function registerScopeRoutes ({ context, api, vars, log })
       }
 
       // Build parameters for the scope method
-      const methodParams = {}
+      const methodParams = { format: 'jsonapi' }
+      // Only the connector supplies this handle; HTTP input cannot select an owner.
+      if (transaction !== undefined) methodParams.transaction = transaction
+      if (precondition !== undefined) methodParams[writePrecondition] = precondition
 
       // Add ID for single-resource operations
       if (['get', 'put', 'patch', 'delete'].includes(methodName)) {
@@ -31,13 +35,12 @@ export default async function registerScopeRoutes ({ context, api, vars, log })
       // Parse query parameters for read operations
       if (['query', 'get'].includes(methodName)) {
         methodParams.queryParams = parseJsonApiQuery(queryString)
-        methodParams.isTransport = true
       }
 
       // Add body for write operations
       if (['post', 'put', 'patch'].includes(methodName)) {
-        methodParams.inputRecord = body
-        methodParams.isTransport = true
+        methodParams.document = body
+        methodParams.returning = 'full'
 
         // Add query params for includes/fields on write operations
         if (queryString) {

package/plugins/core/rest-api-plugin-hooks/turn-scope-init-into-vars.js

@@ -1,4 +1,5 @@
-import { normalizeReturnRecordSetting } from '../lib/querying-writing/return-record-settings.js'
+import { snapshotResourceConfiguration } from '../lib/querying-writing/schema-helpers.js'
+import { rejectRemovedOptions, resolveFormat, resolveReturning } from '../lib/querying-writing/response-options.js'
 
 export default async function turnScopeInitIntoVars ({ context, scopes, vars: apiVars }) {
   // Refer to the scope's vars
@@ -7,8 +8,8 @@ export default async function turnScopeInitIntoVars ({ context, scopes, vars: ap
   const vars = scope?.vars || apiVars
 
   // The scope-specific ones
-  vars.sortableFields = scopeOptions.sortableFields || []
-  vars.defaultSort = scopeOptions.defaultSort || null
+  vars.sortableFields = snapshotResourceConfiguration(scopeOptions.sortableFields || [])
+  vars.defaultSort = snapshotResourceConfiguration(scopeOptions.defaultSort || null)
 
   // The general ones that are also set at api level, but overrideable
   if (typeof scopeOptions.queryDefaultLimit !== 'undefined') vars.queryDefaultLimit = scopeOptions.queryDefaultLimit
@@ -16,17 +17,9 @@ export default async function turnScopeInitIntoVars ({ context, scopes, vars: ap
   if (typeof scopeOptions.includeDepthLimit !== 'undefined') vars.includeDepthLimit = scopeOptions.includeDepthLimit
   if (typeof scopeOptions.enablePaginationCounts !== 'undefined') vars.enablePaginationCounts = scopeOptions.enablePaginationCounts
 
-  // Set simplified settings as scope vars
-  if (typeof scopeOptions.simplifiedApi !== 'undefined') vars.simplifiedApi = scopeOptions.simplifiedApi
-  if (typeof scopeOptions.simplifiedTransport !== 'undefined') vars.simplifiedTransport = scopeOptions.simplifiedTransport
-
-  // Set returnRecord settings as scope vars
-  if (typeof scopeOptions.returnRecordApi !== 'undefined') {
-    vars.returnRecordApi = normalizeReturnRecordSetting(scopeOptions.returnRecordApi, vars.returnRecordApi || 'full')
-  }
-  if (typeof scopeOptions.returnRecordTransport !== 'undefined') {
-    vars.returnRecordTransport = normalizeReturnRecordSetting(scopeOptions.returnRecordTransport, vars.returnRecordTransport || 'no')
-  }
+  rejectRemovedOptions(scopeOptions)
+  if (scopeOptions.format !== undefined) vars.format = resolveFormat(scopeOptions.format)
+  if (scopeOptions.returning !== undefined) vars.returning = resolveReturning(scopeOptions.returning)
 
   // Set idProperty as scope var
   if (typeof scopeOptions.idProperty !== 'undefined') vars.idProperty = scopeOptions.idProperty
@@ -41,16 +34,4 @@ export default async function turnScopeInitIntoVars ({ context, scopes, vars: ap
       )
     }
   }
-
-  // Validate relationship include limits at scope creation time
-  Object.entries(scopeOptions.relationships || {}).forEach(([relName, relDef]) => {
-    if (relDef.include?.limit && vars.queryMaxLimit) {
-      if (relDef.include.limit > vars.queryMaxLimit) {
-        throw new Error(
-          `Invalid relationship '${context.scopeName}.${relName}' configuration: ` +
-          `include.limit (${relDef.include.limit}) cannot exceed queryMaxLimit (${vars.queryMaxLimit})`
-        )
-      }
-    }
-  })
 }

package/plugins/core/rest-api-plugin-hooks/validate-include-configurations.js

@@ -1,39 +1,33 @@
-export default async function validateIncludeConfigurations ({ context, scopes, log }) {
-  const { scopeName } = context
-  const scope = scopes[scopeName]
-  const relationships = scope.vars.schemaInfo?.schemaRelationships
+import { buildEffectiveSortList } from '../lib/querying/query-field-sort-helpers.js'
 
-  if (!relationships) return
+export function validateIncludeConfigurations ({ context, scopes, log }) {
+  const { scopeName, scopeOptions, schemaInfo } = context
+  const maxLimit = scopeOptions.queryMaxLimit !== undefined
+    ? scopeOptions.queryMaxLimit
+    : scopes[scopeName]?.vars?.queryMaxLimit
 
-  // Check each relationship for include configuration
-  for (const [relName, relDef] of Object.entries(relationships)) {
+  for (const [relName, relDef] of Object.entries(schemaInfo.outputRelationships)) {
     if (relDef.include?.strategy === 'window') {
-      // This relationship requires window functions
-      // We'll validate this at query time since the database might not be connected yet
+      // Database support is checked when the include query is prepared.
       log.debug(`Relationship ${scopeName}.${relName} configured for window function includes`)
     }
 
-    // Validate include configuration
-    if (relDef.include?.limit) {
-      if (typeof relDef.include.limit !== 'number') {
-        throw new Error(
-          `Invalid include limit for ${scopeName}.${relName}: limit must be a number`
-        )
+    const limit = relDef.include?.limit
+    if (limit !== undefined && limit !== null && limit !== false) {
+      if (!Number.isInteger(limit) || limit < 0) {
+        throw new Error(`Invalid include limit for ${scopeName}.${relName}: expected a non-negative integer, null or false`)
       }
-      // Check against queryMaxLimit if available
-      const maxLimit = scope.vars?.queryMaxLimit
-      if (maxLimit && relDef.include.limit > maxLimit) {
-        throw new Error(
-          `Invalid include limit for ${scopeName}.${relName}: ` +
-          `limit (${relDef.include.limit}) exceeds queryMaxLimit (${maxLimit})`
-        )
+      if (maxLimit && limit > maxLimit) {
+        throw new Error(`Invalid include limit for ${scopeName}.${relName}: limit (${limit}) exceeds queryMaxLimit (${maxLimit})`)
       }
     }
 
-    if (relDef.include?.orderBy && !Array.isArray(relDef.include.orderBy)) {
-      throw new Error(
-        `Invalid include orderBy for ${scopeName}.${relName}: orderBy must be an array`
-      )
+    const orderBy = relDef.include?.orderBy
+    if (orderBy !== undefined && orderBy !== null) {
+      if (!Array.isArray(orderBy)) {
+        throw new Error(`Invalid include orderBy for ${scopeName}.${relName}: orderBy must be an array`)
+      }
+      buildEffectiveSortList(orderBy)
     }
   }
 }

package/plugins/core/rest-api-plugin-methods/add-route.js

@@ -1,22 +1,20 @@
-import { ValidationError } from 'hooked-api'
+// @ts-check
+import { RestApiValidationError } from '../../../lib/rest-api-errors.js'
 
 /**
  * addRoute
  * Registers a new route with the transport layer
  */
+/** @param {import('../../../types/runtime.js').RuntimeArguments} args */
 export default async ({ params, context, runHooks }) => {
   const { method, path, handler } = params
 
-  // Validate route configuration
   if (!method || !path || !handler) {
-    throw new ValidationError('Route requires method, path, and handler')
+    throw new RestApiValidationError('Route requires method, path, and handler')
   }
 
-  // debugger
-  // Create context for enrichAttributes hooks
   Object.assign(context, params)
 
-  // Run the addRoute hook to notify transport plugins
   await runHooks('addRoute')
 
   return { registered: true, method, path }

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

@@ -1,14 +1,37 @@
-export default async function applyQueryFiltersMethod ({ context, params = {}, runHooks }) {
+// @ts-check
+/** @import { QueryFilteringState, StorageAdapter, StorageSchemaInfo } from '../lib/storage/storage-types.js' */
+
+/**
+ * @typedef {object} FilteringContext
+ * @property {QueryFilteringState | null} [knexQuery]
+ * @property {StorageAdapter} [storageAdapter]
+ * @property {Record<string, unknown>} [queryParams]
+ */
+
+import { withQueryFilteringContext } from '../lib/querying/query-builder-utils.js'
+
+/**
+ * @param {object} request
+ * @param {FilteringContext} request.context
+ * @param {QueryFilteringState} [request.params]
+ * @param {(name: 'knexQueryFiltering') => unknown | Promise<unknown>} request.runHooks
+ * @param {{ vars: { schemaInfo: StorageSchemaInfo }, checkPermissions: (request: {
+ *   method: 'query', originalContext: FilteringContext & {
+ *     method: 'query', scopeName: string, schemaInfo: StorageSchemaInfo, id: undefined
+ *   }
+ * }) => unknown | Promise<unknown> }} request.scope
+ * @param {string} request.scopeName
+ */
+export default async function applyQueryFiltersMethod ({ context, params = {}, runHooks, scope, scopeName }) {
   const { query, filters, storageAdapter, ...knexQuery } = params
 
   if (!query) {
     return query
   }
 
-  const previousKnexQuery = context.knexQuery
   const previousStorageAdapter = context.storageAdapter
 
-  context.knexQuery = {
+  const queryState = {
     query,
     filters,
     storageAdapter,
@@ -21,17 +44,23 @@ export default async function applyQueryFiltersMethod ({ context, params = {}, r
   }
 
   try {
-    await runHooks('knexQueryFiltering')
-    return {
-      query: context.knexQuery?.query || query
-    }
+    return await withQueryFilteringContext(context, queryState, async () => {
+      if (['include', 'relationship-identifiers', 'search-join'].includes(params.queryPurpose || '')) {
+        await scope.checkPermissions({
+          method: 'query',
+          originalContext: {
+            ...context,
+            method: 'query',
+            scopeName,
+            schemaInfo: scope.vars.schemaInfo,
+            id: undefined,
+            queryParams: { ...context.queryParams, filters: filters || {} }
+          }
+        })
+      }
+      await runHooks('knexQueryFiltering')
+    })
   } finally {
-    if (previousKnexQuery === undefined) {
-      delete context.knexQuery
-    } else {
-      context.knexQuery = previousKnexQuery
-    }
-
     if (previousStorageAdapter === undefined) {
       delete context.storageAdapter
     } else {

package/plugins/core/rest-api-plugin-methods/check-permissions.js

@@ -1,13 +1,19 @@
+// @ts-check
+/** @import { HookContext, PermissionHookContext } from '../../../types/hook-context.js' */
+
 /**
- * checkPermissions
- * Check if ther are permissions to access a resource.
- *
+ * Run the resource permission hook with the originating operation context.
+ * @param {object} request
+ * @param {Record<string, unknown>} request.context
+ * @param {{ method: string, originalContext: HookContext }} request.params
+ * @param {(name: 'checkPermissions') => unknown} request.runHooks
  */
-export default async function checkPermissionsMethod ({ context, params, runHooks, scopeName, scopes, helpers }) {
-  Object.assign(context, {
+export default async function checkPermissionsMethod ({ context, params, runHooks }) {
+  const permissionContext = /** @satisfies {PermissionHookContext} */ ({
     method: params.method,
     originalContext: params.originalContext,
   })
+  Object.assign(context, permissionContext)
 
   await runHooks('checkPermissions')
 }