json-rest-api 1.0.28 → 2.0.0

package/plugins/core/lib/querying-writing/knex-json-api-transformers.js

@@ -1,133 +1,48 @@
+// @ts-check
+/** @import { ResourceConversionScope, StorageRow } from '../storage/storage-types.js' */
+/** @import { JsonApiResource, JsonApiRelationship } from '../../../../types/representations.js' */
 import { toJsonApiRecord } from '../querying/knex-json-api-transformers-querying.js'
-import { getSchemaStructure } from './knex-constants.js'
 import { translateRecordFromStorage } from '../storage/storage-mapping.js'
+import { getPolymorphicLinkage } from './relationship-contracts.js'
 
+/** @overload @param {ResourceConversionScope} scope @param {StorageRow} record @param {string} scopeName @returns {JsonApiResource} */
+/** @overload @param {ResourceConversionScope} scope @param {StorageRow | null | undefined} record @param {string} scopeName @returns {JsonApiResource | null} */
 /**
- * Converts database record to JSON:API format with belongsTo relationships
- *
- * @param {Object} scope - Resource scope with schema and relationship info
- * @param {Object} record - Raw database record
- * @param {string} scopeName - Resource type name
- * @returns {Object} JSON:API resource with belongsTo relationships
- *
- * @example
- * // Input: Database record with foreign keys
- * const dbRecord = {
- *   id: 1,
- *   title: 'Hello World',
- *   author_id: 2,
- *   publisher_id: 3,
- *   category_id: null
- * };
- * const result = toJsonApiRecordWithBelongsTo(scope, dbRecord, 'articles');
- *
- * // Output: JSON:API with relationship objects
- * // {
- * //   type: 'articles',
- * //   id: '1',
- * //   attributes: {
- * //     title: 'Hello World'
- * //     // Note: author_id, publisher_id, category_id removed
- * //   },
- * //   relationships: {
- * //     author: {
- * //       data: { type: 'authors', id: '2' }
- * //     },
- * //     publisher: {
- * //       data: { type: 'publishers', id: '3' }
- * //     },
- * //     category: {
- * //       data: null  // Explicit null for empty relationship
- * //     }
- * //   }
- * // }
- *
- * @example
- * // Input: Polymorphic relationships
- * const dbRecord = {
- *   id: 5,
- *   content: 'Great post!',
- *   commentable_type: 'articles',
- *   commentable_id: 10
- * };
- * // With schema defining polymorphic relationship:
- * // relationships: {
- * //   commentable: {
- * //     belongsToPolymorphic: true,
- * //     typeField: 'commentable_type',
- * //     idField: 'commentable_id'
- * //   }
- * // }
- *
- * // Output: Polymorphic relationship in JSON:API
- * // {
- * //   type: 'comments',
- * //   id: '5',
- * //   attributes: { content: 'Great post!' },
- * //   relationships: {
- * //     commentable: {
- * //       data: { type: 'articles', id: '10' }
- * //     }
- * //   }
- * // }
- *
- * @description
- * Used by:
- * - dataGetMinimal for lightweight single record fetches
- * - dataDelete to return deleted record structure
- * - Internal operations needing quick JSON:API conversion
- *
- * Purpose:
- * - Provides JSON:API structure without loading related data
- * - Transforms foreign keys into relationship objects
- * - Handles both regular and polymorphic belongsTo
- * - Maintains explicit nulls for empty relationships
- *
- * Data flow:
- * 1. Calls toJsonApiRecord for basic transformation
- * 2. Scans schema for belongsTo field definitions
- * 3. Converts foreign key values to relationship objects
- * 4. Processes polymorphic relationships separately
- * 5. Returns complete JSON:API resource object
+ * Convert one storage row and its belongs-to linkage without loading targets.
+ * Empty foreign keys become null linkage; backing fields stay out of attributes.
+ * @param {ResourceConversionScope} scope
+ * @param {StorageRow | null | undefined} record
+ * @param {string} scopeName
+ * @returns {JsonApiResource | null}
  */
-export const toJsonApiRecordWithBelongsTo = (scope, record, scopeName) => {
+export function toJsonApiRecordWithBelongsTo (scope, record, scopeName) {
   if (!record) return null
 
   const schemaInfo = scope.vars.schemaInfo
   const logicalRecord = translateRecordFromStorage(record, schemaInfo)
 
   // Get the basic JSON:API structure (without relationships)
-  const jsonApiRecord = toJsonApiRecord(scope, logicalRecord, scopeName)
+  const jsonApiRecord = toJsonApiRecord(scope, record, scopeName)
 
   // Extract schema info from scope
   const {
-    schemaInstance,
+    schemaStructure,
     schemaRelationships: relationships
   } = schemaInfo
 
-  // Get schema structure
-  const schemaStructure = getSchemaStructure(schemaInstance)
-
   // Initialize relationships object
-  jsonApiRecord.relationships = {}
+  /** @type {Record<string, JsonApiRelationship>} */
+  const relationshipData = jsonApiRecord.relationships = {}
 
   // Process regular belongsTo relationships from schema
   for (const [fieldName, fieldDef] of Object.entries(schemaStructure)) {
     if (fieldDef.belongsTo && fieldDef.as) {
       const fieldValue = logicalRecord[fieldName]
 
-      if (fieldValue !== null && fieldValue !== undefined) {
-        jsonApiRecord.relationships[fieldDef.as] = {
-          data: {
-            type: fieldDef.belongsTo,
-            id: String(fieldValue)
-          }
-        }
-      } else {
-        // Explicitly null relationship
-        jsonApiRecord.relationships[fieldDef.as] = {
-          data: null
-        }
+      relationshipData[fieldDef.as] = {
+        data: fieldValue === null || fieldValue === undefined
+          ? null
+          : { type: fieldDef.belongsTo, id: String(fieldValue) }
       }
     }
   }
@@ -135,21 +50,17 @@ export const toJsonApiRecordWithBelongsTo = (scope, record, scopeName) => {
   // Process polymorphic belongsTo relationships
   Object.entries(relationships || {}).forEach(([relName, relDef]) => {
     if (relDef.belongsToPolymorphic) {
-      const typeValue = logicalRecord[relDef.typeField]
-      const idValue = logicalRecord[relDef.idField]
+      const typeValue = logicalRecord[relDef.belongsToPolymorphic.typeField]
+      const idValue = logicalRecord[relDef.belongsToPolymorphic.idField]
 
-      if (typeValue && idValue) {
-        jsonApiRecord.relationships[relName] = {
-          data: {
-            type: typeValue,
-            id: String(idValue)
-          }
-        }
-      } else {
-        // Explicitly null relationship
-        jsonApiRecord.relationships[relName] = {
-          data: null
-        }
+      relationshipData[relName] = {
+        data: getPolymorphicLinkage({
+          type: typeValue,
+          id: idValue,
+          types: relDef.belongsToPolymorphic.types,
+          scopeName,
+          relationshipName: relName
+        })
       }
     }
   })

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

@@ -1,5 +1,67 @@
+// @ts-check
+/** @import { StorageDatabase, StorageFieldDefinition } from '../storage/storage-types.js' */
+/** @import { CompiledQueryField, ProjectionExpression, ProjectionRequest, ProjectionRuntime, QueryFieldCompilation, QueryFieldDeclaration } from './query-field-types.js' */
 import { getStorageColumn } from '../storage/storage-mapping.js'
+import { wrapUnexpectedError } from '../../../../lib/error-context.js'
 
+// PostgreSQL json has no equality operator for DISTINCT parent selections.
+/** @template {string | ProjectionExpression} T @param {T} expression @param {StorageFieldDefinition | undefined} definition @param {StorageDatabase | null} db @returns {T | import('knex').Knex.Raw<unknown>} */
+export function normalizeStructuredSelect (expression, definition, db) {
+  if (!db || !['pg', 'postgresql'].includes(db.client.config.client) || !['object', 'array'].includes(definition?.type || '')) return expression
+  return typeof expression === 'string'
+    ? db.raw('to_jsonb(??)', [expression])
+    : db.raw('to_jsonb((?))', [expression])
+}
+
+/** Compile projection declarations against the final resource namespace.
+ * @param {Record<string, QueryFieldDeclaration>} rawQueryFields
+ * @param {QueryFieldCompilation} options
+ * @returns {Record<string, CompiledQueryField>}
+ */
+export function compileQueryFields (rawQueryFields, { scopeName, schemaStructure, computed, schemaRelationships, idProperty }) {
+  if (!rawQueryFields || typeof rawQueryFields !== 'object' || Array.isArray(rawQueryFields)) {
+    throw new Error(`Invalid queryFields configuration for scope '${scopeName}'. Expected an object.`)
+  }
+  const reservedNames = new Set([
+    'id', idProperty,
+    ...Object.keys(schemaStructure),
+    ...Object.keys(computed),
+    ...Object.keys(schemaRelationships)
+  ])
+  for (const definition of Object.values(schemaStructure)) {
+    if (definition.belongsTo && definition.as) reservedNames.add(definition.as)
+  }
+  /** @type {Array<[string, CompiledQueryField]>} */
+  const normalized = []
+  for (const [fieldName, fieldDef] of Object.entries(rawQueryFields)) {
+    if (!fieldDef || typeof fieldDef !== 'object' || Array.isArray(fieldDef)) {
+      throw new Error(`Query field '${fieldName}' in scope '${scopeName}' must be an object.`)
+    }
+    if (reservedNames.has(fieldName)) {
+      throw new Error(`Query field '${fieldName}' in scope '${scopeName}' conflicts with an existing schema, computed, or relationship name.`)
+    }
+    if (!fieldDef.type) {
+      throw new Error(`Query field '${fieldName}' in scope '${scopeName}' must have a type.`)
+    }
+    if (fieldDef.storage !== undefined) {
+      throw new Error(`Query field '${fieldName}' in scope '${scopeName}' cannot declare storage. Projections select SQL values directly; put storage serializers on stored fields and use getters for public formatting.`)
+    }
+    const select = fieldDef.select || fieldDef.project
+    if (typeof select !== 'function') {
+      throw new Error(`Query field '${fieldName}' in scope '${scopeName}' must define a select() function.`)
+    }
+    normalized.push([fieldName, {
+      ...fieldDef,
+      select,
+      sortable: fieldDef.sortable === true,
+      hidden: fieldDef.hidden === true,
+      normallyHidden: fieldDef.normallyHidden === true
+    }])
+  }
+  return Object.fromEntries(normalized)
+}
+
+/** @param {string} columnName @param {string} tableName */
 function qualifyColumnReference (columnName, tableName) {
   if (!tableName || !columnName || columnName === '*' || String(columnName).includes('.')) {
     return columnName
@@ -8,6 +70,7 @@ function qualifyColumnReference (columnName, tableName) {
   return `${tableName}.${columnName}`
 }
 
+/** @param {ProjectionExpression} expression */
 function normalizeQueryFieldSql (expression) {
   if (expression && typeof expression.toSQL === 'function') {
     const compiled = expression.toSQL()
@@ -20,6 +83,12 @@ function normalizeQueryFieldSql (expression) {
   throw new Error('Query field expressions must return knex raw, knex ref, or a knex query builder.')
 }
 
+/** @param {unknown} value @returns {value is ProjectionExpression} */
+export function isImmediateExpression (value) {
+  return value !== null && typeof value === 'object' && typeof Reflect.get(value, 'toSQL') === 'function'
+}
+
+/** @param {ProjectionRequest} [options] @returns {Promise<Map<string, ProjectionRuntime>>} */
 export async function buildQueryFieldRuntimes ({
   queryFieldNames = [],
   queryFields = {},
@@ -30,6 +99,7 @@ export async function buildQueryFieldRuntimes ({
   context = null,
   scopeName = ''
 } = {}) {
+  /** @type {Map<string, ProjectionRuntime>} */
   const runtimes = new Map()
   const seen = new Set()
 
@@ -44,44 +114,50 @@ export async function buildQueryFieldRuntimes ({
       throw new Error(`Unknown query field '${fieldName}' requested for '${scopeName}'.`)
     }
 
+    /** @param {string} logicalField */
     const column = (logicalField) => {
       const translated = storageAdapter?.translateColumn?.(logicalField) || getStorageColumn(schemaInfo, logicalField)
       return qualifyColumnReference(translated, tableName)
     }
 
-    const selectResult = fieldDef.select({
-      knex: db,
-      db,
-      context,
-      scopeName,
-      tableName,
-      fieldName,
-      schemaInfo,
-      adapter: storageAdapter,
-      column,
-      ref: (logicalField) => db?.ref ? db.ref(column(logicalField)) : column(logicalField)
-    })
-
-    const expression = (
-      selectResult &&
-      typeof selectResult === 'object' &&
-      typeof selectResult.toSQL === 'function'
-    )
-      ? selectResult
-      : await selectResult
-
-    if (expression === undefined || expression === null) {
-      throw new Error(`Query field '${fieldName}' in scope '${scopeName}' returned an empty select expression.`)
-    }
+    try {
+      const selectResult = fieldDef.select({
+        knex: db,
+        db,
+        context,
+        scopeName,
+        tableName,
+        fieldName,
+        schemaInfo,
+        adapter: storageAdapter,
+        column,
+        ref: (logicalField) => db?.ref ? db.ref(column(logicalField)) : column(logicalField)
+      })
+
+      const expression = isImmediateExpression(selectResult)
+        ? selectResult
+        : await selectResult
 
-    const { sql, bindings } = normalizeQueryFieldSql(expression)
-    runtimes.set(fieldName, {
-      fieldName,
-      definition: fieldDef,
-      expression,
-      sql,
-      bindings
-    })
+      if (expression === undefined || expression === null) {
+        throw new Error(`Query field '${fieldName}' in scope '${scopeName}' returned an empty select expression.`)
+      }
+
+      const selectedExpression = normalizeStructuredSelect(expression, fieldDef, db)
+      const { sql, bindings } = normalizeQueryFieldSql(selectedExpression)
+      runtimes.set(fieldName, {
+        fieldName,
+        definition: fieldDef,
+        schemaInfo,
+        expression: selectedExpression,
+        sql,
+        bindings
+      })
+    } catch (error) {
+      throw wrapUnexpectedError(error, {
+        message: `Failed to select query field '${fieldName}' for scope '${scopeName}'`,
+        context: { scopeName, fieldName, phase: 'projection' }
+      })
+    }
   }
 
   return runtimes

package/plugins/core/lib/querying-writing/query-field-types.d.ts

@@ -0,0 +1,60 @@
+import type { Knex } from 'knex'
+import type { StorageAdapter, StorageContext, StorageDatabase, StorageFieldDefinition, StorageRow, StorageSchemaInfo } from '../storage/storage-types.js'
+
+export type ProjectionExpression = Knex.Raw<unknown> | Knex.QueryBuilder<StorageRow, unknown>
+
+export interface ProjectionContext {
+  knex: StorageDatabase | null
+  db: StorageDatabase | null
+  context: StorageContext | null
+  scopeName: string
+  tableName: string
+  fieldName: string
+  schemaInfo: Partial<StorageSchemaInfo>
+  adapter: StorageAdapter | null
+  column: (logicalField: string) => string
+  ref: (logicalField: string) => string | Knex.Ref<string, Record<string, string>>
+}
+
+export type ProjectionSelector = (context: ProjectionContext) => ProjectionExpression
+
+export interface QueryFieldDeclaration extends StorageFieldDefinition {
+  select?: ProjectionSelector
+  project?: ProjectionSelector
+  sortable?: boolean
+}
+
+export interface CompiledQueryField extends QueryFieldDeclaration {
+  select: ProjectionSelector
+  sortable: boolean
+  hidden: boolean
+  normallyHidden: boolean
+}
+
+export interface QueryFieldCompilation {
+  scopeName: string
+  schemaStructure: Record<string, StorageFieldDefinition>
+  computed: Record<string, StorageFieldDefinition>
+  schemaRelationships: Record<string, unknown>
+  idProperty: string
+}
+
+export interface ProjectionRequest {
+  queryFieldNames?: readonly string[]
+  queryFields?: Record<string, CompiledQueryField>
+  schemaInfo?: Partial<StorageSchemaInfo>
+  tableName?: string
+  storageAdapter?: StorageAdapter | null
+  db?: StorageDatabase | null
+  context?: StorageContext | null
+  scopeName?: string
+}
+
+export interface ProjectionRuntime {
+  fieldName: string
+  definition: CompiledQueryField
+  schemaInfo: Partial<StorageSchemaInfo>
+  expression: ProjectionExpression
+  sql: string
+  bindings: readonly unknown[]
+}

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

@@ -1,23 +1,43 @@
+// @ts-check
+/** @import { StorageFieldDefinition } from '../storage/storage-types.js' */
 import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { wrapUnexpectedError } from '../../../../lib/error-context.js'
+import { RELATIONSHIP_CAPABILITIES } from './database-capabilities.js'
 
-export function getRelationshipCardinality (relDef) {
-  if (!relDef) return null
-
-  if (
-    relDef.belongsTo ||
-    relDef.belongsToPolymorphic ||
-    relDef.type === 'hasOne'
-  ) {
-    return 'one'
+/** @param {{ type: unknown, id: unknown, types?: readonly string[] | null, scopeName?: string, relationshipName: string }} options */
+export function getPolymorphicLinkage ({ type, id, types, scopeName, relationshipName }) {
+  if (type == null || id == null) return null
+  if (typeof type !== 'string' || !Array.isArray(types) || !types.includes(type)) {
+    throw wrapUnexpectedError(new Error(`Undeclared target type '${type}'`), {
+      message: `Invalid stored relationship '${scopeName}.${relationshipName}'`,
+      context: { scopeName, relationshipName, phase: 'relationshipData' }
+    })
   }
+  return { type, id: String(id) }
+}
 
-  if (relDef.type === 'hasMany' || relDef.type === 'manyToMany') {
-    return 'many'
-  }
+/**
+ * @template {StorageFieldDefinition} Definition
+ * @param {{ outputRelationships?: Record<string, Definition> }} schemaInfo
+ * @param {string} relationshipName
+ */
+export const findRelationshipDefinition = (schemaInfo, relationshipName) => {
+  const relationships = schemaInfo.outputRelationships || {}
+  return Object.hasOwn(relationships, relationshipName) ? relationships[relationshipName] || null : null
+}
+
+/** @param {StorageFieldDefinition | null} [relDef] */
+export function getRelationshipCardinality (relDef) {
+  if (!relDef) return null
 
-  return null
+  if (RELATIONSHIP_CAPABILITIES.attributeKinds.some(kind => relDef[kind])) return 'one'
+  const cardinalities = RELATIONSHIP_CAPABILITIES.declaredCardinalities
+  return typeof relDef.type === 'string' && Object.hasOwn(cardinalities, relDef.type)
+    ? cardinalities[/** @type {keyof typeof cardinalities} */ (relDef.type)]
+    : null
 }
 
+/** @param {{ relationshipName: string, relDef?: StorageFieldDefinition | null, data: unknown, fieldPath?: string }} options */
 export function validateRelationshipDataCardinality ({
   relationshipName,
   relDef,