json-rest-api 1.0.28 → 2.0.0

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

@@ -0,0 +1,43 @@
+import type { ResourceConversionSchema, StorageAdapter, StorageContext, StorageDatabase, StorageFieldDefinition, StorageQuery } from '../storage/storage-types.js'
+import type { CompiledQueryField, ProjectionRuntime } from './query-field-types.js'
+import type { Fieldsets } from './field-utils.js'
+
+export interface SelectionSchema extends Partial<ResourceConversionSchema> {
+  queryFields?: Record<string, CompiledQueryField>
+  outputRelationships?: Record<string, StorageFieldDefinition>
+  readDependencies?: Record<string, readonly string[]>
+}
+
+export interface SelectionScope {
+  vars?: { schemaInfo?: SelectionSchema }
+}
+
+export interface SelectionContext extends StorageContext {
+  scopeName: string
+  queryParams?: { fields?: Fieldsets; sort?: unknown }
+}
+
+export interface FieldSelection {
+  fieldsToSelect: string[]
+  queryFieldsToSelect: string[]
+  requestedFields: readonly string[] | null
+  computedDependencies: string[]
+  idProperty: 'id'
+}
+
+export interface SelectionQueryRequest {
+  query: StorageQuery
+  scope?: SelectionScope | null
+  fieldSelectionInfo?: Partial<FieldSelection> | null
+  tableName: string
+  useTablePrefix?: boolean
+  storageAdapter?: StorageAdapter | null
+  db?: StorageDatabase | null
+  context?: StorageContext | null
+  scopeName?: string
+}
+
+export interface SelectedQuery {
+  query: StorageQuery
+  queryFieldRuntimeByField: Map<string, ProjectionRuntime>
+}

package/plugins/core/lib/querying-writing/field-utils.js

@@ -1,71 +1,122 @@
+// @ts-check
+/** @import { StorageFieldDefinition } from '../storage/storage-types.js' */
+/** @import { JsonApiDocument } from '../../../../types/representations.js' */
+/** @typedef {string | readonly string[] | null | undefined} Fieldset */
+/** @typedef {Record<string, Fieldset>} Fieldsets */
+import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
+import { SERIALIZATION_CAPABILITIES } from './database-capabilities.js'
+
+/** @param {string} name @param {string} location */
+export function assertFieldName (name, location) {
+  if (name === '__proto__') {
+    throw new Error(`Invalid ${location}: '__proto__' cannot be a field, filter or relationship name. Choose another name.`)
+  }
+}
+
+/** @param {unknown} declarations @param {string} location */
+export function assertFieldNameMap (declarations, location) {
+  if (declarations == null) return
+  const prototype = typeof declarations === 'object' ? Object.getPrototypeOf(declarations) : undefined
+  if (typeof declarations !== 'object' || Array.isArray(declarations) || (prototype !== null && prototype !== Object.prototype)) {
+    throw new Error(`Invalid ${location}: Expected an object with own field declarations and a plain or null prototype.`)
+  }
+  for (const name of Object.keys(declarations)) assertFieldName(name, location)
+}
+
+/** @param {StorageFieldDefinition | null | undefined} definition @param {string} fieldName @param {string} operation */
+export function assertScalarQueryField (definition, fieldName, operation) {
+  const type = definition?.type
+  if (type === undefined || !SERIALIZATION_CAPABILITIES.structuredTypes.includes(type)) return
+  const parameter = operation === 'sort' ? 'sort' : `filters.${fieldName}`
+  const message = `Field '${fieldName}' has type '${type}' and cannot be used in whole-document ${operation} operations. Use a scalar field or projection for sorting, or a custom applyFilter function for JSON queries.`
+  throw new RestApiValidationError(message, {
+    fields: [parameter],
+    violations: [{ field: parameter, rule: 'structured_query', message }]
+  })
+}
+
 /**
- * Extracts all foreign key fields from a schema definition
- *
- * @param {Object} schema - The schema definition (Schema object or plain object)
- * @returns {Set<string>} Set of foreign key field names
- *
- * @example
- * // Input: Schema with belongsTo relationships
- * const schema = {
- *   title: { type: 'string' },
- *   content: { type: 'string' },
- *   author_id: { type: 'number', belongsTo: 'users', as: 'author' },
- *   category_id: { type: 'number', belongsTo: 'categories', as: 'category' },
- *   status: { type: 'string' }
- * };
- *
- * const foreignKeys = getForeignKeyFields(schema);
- *
- * // Output: Set containing only foreign key fields
- * // Set(['author_id', 'category_id'])
- *
- * @example
- * // Input: Works with compiled Schema objects too
- * const schemaObject = {
- *   structure: {
- *     post_id: { type: 'id', belongsTo: 'posts', as: 'post' },
- *     user_id: { type: 'id', belongsTo: 'users', as: 'user' }
- *   }
- * };
- *
- * const foreignKeys = getForeignKeyFields(schemaObject);
- *
- * // Output: Handles both formats
- * // Set(['post_id', 'user_id'])
- *
- * @description
- * Used by:
- * - toJsonApi to filter foreign keys from attributes
- * - buildFieldSelection to ensure foreign keys are always selected
- * - knex-json-api-helpers for field filtering
- *
- * Purpose:
- * - Identifies fields that should be relationships, not attributes
- * - Foreign keys are stored in DB but not exposed as JSON:API attributes
- * - Ensures these fields are included in SELECT for relationship building
- * - Helps transform database structure to JSON:API format
- *
- * Data flow:
- * 1. Accepts schema in either format (plain or with structure property)
- * 2. Iterates through all field definitions
- * 3. Collects fields with belongsTo property
- * 4. Returns Set for efficient lookups
+ * Collect logical relationship backing fields from an explicit field map.
+ * @param {Record<string, StorageFieldDefinition> | null | undefined} schemaStructure - Compiled field definitions, not a Schema wrapper.
+ * @param {Record<string, { belongsToPolymorphic?: { typeField: string, idField: string } }>} [relationships] - Includes polymorphic backing fields.
+ * @returns {Set<string>}
  */
-export const getForeignKeyFields = (schema) => {
+export const getForeignKeyFields = (schemaStructure, relationships = {}) => {
+  /** @type {Set<string>} */
   const foreignKeys = new Set()
-  if (!schema) return foreignKeys
-
-  // Handle both Schema objects and plain objects
-  const schemaStructure = schema.structure || schema
+  if (!schemaStructure) return foreignKeys
 
   Object.entries(schemaStructure).forEach(([field, def]) => {
     if (def.belongsTo) {
       foreignKeys.add(field)
     }
   })
+  for (const definition of Object.values(relationships)) {
+    if (definition.belongsToPolymorphic) {
+      foreignKeys.add(definition.belongsToPolymorphic.typeField)
+      foreignKeys.add(definition.belongsToPolymorphic.idField)
+    }
+  }
   return foreignKeys
 }
 
+/** @param {Fieldset} requestedFields */
+export const parseFieldset = requestedFields => requestedFields == null
+  ? null
+  : typeof requestedFields === 'string'
+    ? requestedFields.split(',').map(field => field.trim()).filter(Boolean)
+    : requestedFields
+
+/** @param {Fieldsets | null | undefined} fieldsets @param {string} resourceType */
+export const getResourceFieldset = (fieldsets, resourceType) => fieldsets && Object.hasOwn(fieldsets, resourceType)
+  ? fieldsets[resourceType]
+  : undefined
+
+/**
+ * @overload
+ * @param {JsonApiDocument | null | undefined} record
+ * @param {Fieldsets} [fieldsets]
+ * @param {{ simplified?: false, resourceType?: string }} [options]
+ * @returns {void}
+ */
+/**
+ * @overload
+ * @param {Record<string, unknown> | null | undefined} record
+ * @param {Fieldsets | undefined} fieldsets
+ * @param {{ simplified: true, resourceType: string }} options
+ * @returns {void}
+ */
+/**
+ * @param {JsonApiDocument | Record<string, unknown> | null | undefined} record
+ * @param {Fieldsets} [fieldsets]
+ * @param {{ simplified?: boolean, resourceType?: string }} [options]
+ */
+export const filterResponseFields = (record, fieldsets = {}, { simplified = false, resourceType } = {}) => {
+  if (simplified) {
+    const fields = parseFieldset(getResourceFieldset(fieldsets, /** @type {string} */ (resourceType)))
+    if (fields === null || !record || typeof record !== 'object') return
+    const allowed = new Set(['id', '_type', ...fields])
+    for (const name of Object.keys(record)) if (!allowed.has(name)) delete /** @type {Record<string, unknown>} */ (record)[name]
+    return
+  }
+  const selections = new Map(Object.entries(fieldsets).map(([type, fields]) => [type, new Set(parseFieldset(fields))]))
+  // The overload ties the representation to the corresponding record shape.
+  const document = /** @type {JsonApiDocument | null | undefined} */ (record)
+  const primary = Array.isArray(document?.data) ? document.data : [document?.data]
+  for (const resource of [...primary, ...(document?.included || [])]) {
+    if (!resource) continue
+    const allowed = selections.get(resource.type)
+    if (!allowed) continue
+    // Selection inspects keys and passes member values through unchanged.
+    /** @type {Partial<Record<'attributes' | 'relationships', Record<string, unknown>>>} */
+    const members = resource
+    for (const member of /** @type {const} */ (['attributes', 'relationships'])) {
+      if (!members[member]) continue
+      members[member] = Object.fromEntries(Object.entries(members[member]).filter(([name]) => allowed.has(name)))
+    }
+  }
+}
+
 /**
  * Filters hidden fields from attributes based on schema rules.
  *
@@ -73,48 +124,18 @@ export const getForeignKeyFields = (schema) => {
  * based on the schema definition and requested fields. It ensures that
  * sensitive data is never exposed in API responses.
  *
- * @param {Object} attributes - The attributes object to filter
- * @param {Object} schema - The schema object with structure property
- * @param {Array<string>|string} requestedFields - Fields explicitly requested (for normallyHidden)
- * @returns {Object} Filtered attributes object
- *
- * @example <caption>Filtering hidden fields</caption>
- * const attributes = {
- *   name: 'John',
- *   email: 'john@example.com',
- *   password_hash: 'xxx',
- *   internal_id: '123'
- * };
- * const schema = {
- *   structure: {
- *     name: { type: 'string' },
- *     email: { type: 'string' },
- *     password_hash: { type: 'string', hidden: true },
- *     internal_id: { type: 'string', normallyHidden: true }
- *   }
- * };
- * const filtered = filterHiddenFields(attributes, schema, null);
- * // Returns: { name: 'John', email: 'john@example.com' }
- * // password_hash (hidden) and internal_id (normallyHidden) are removed
- *
- * @example <caption>Including normallyHidden fields when requested</caption>
- * const filtered = filterHiddenFields(attributes, schema, 'name,internal_id');
- * // Returns: { name: 'John', internal_id: '123' }
- * // internal_id is included because explicitly requested
- * // password_hash is still filtered (always hidden)
+ * @param {Record<string, unknown>} attributes - The attributes object to filter
+ * @param {{ structure?: Record<string, StorageFieldDefinition> }} schema - The schema object with structure property
+ * @param {Fieldset} requestedFields - Fields explicitly requested (for normallyHidden)
+ * @returns {Record<string, unknown>} Filtered attributes object
  */
 export const filterHiddenFields = (attributes, schema, requestedFields) => {
+  /** @type {Record<string, unknown>} */
   const filtered = {}
 
   // Parse requested fields if it's a string (from query params)
   // Example: "name,price,cost" -> ['name', 'price', 'cost']
-  const requested = requestedFields
-    ? (
-        typeof requestedFields === 'string'
-          ? requestedFields.split(',').map(f => f.trim()).filter(f => f)
-          : requestedFields
-      )
-    : null
+  const requested = parseFieldset(requestedFields)
 
   Object.entries(attributes).forEach(([field, value]) => {
     const fieldDef = schema.structure?.[field]

package/plugins/core/lib/querying-writing/knex-constants.d.ts

@@ -0,0 +1,18 @@
+export declare const RELATIONSHIPS_KEY = '__$jsonrestapi_relationships$__'
+export declare const RELATIONSHIP_METADATA_KEY = '__$jsonrestapi_metadata$__'
+export declare const ROW_NUMBER_KEY = '__$jsonrestapi_rn$__'
+export declare const COMPUTED_DEPENDENCIES_KEY = '__$jsonrestapi_computed_deps$__'
+
+export declare const DEFAULT_QUERY_LIMIT = 20
+export declare const DEFAULT_MAX_QUERY_LIMIT = 100
+export declare const DEFAULT_MAX_INCLUDE_LIMIT = 1000
+export declare const DEFAULT_INCLUDE_DEPTH_LIMIT = 3
+export declare const RELATIONSHIP_WRITE_BATCH_SIZE = 100
+export declare const RELATIONSHIP_READ_BATCH_SIZE = 100
+
+export declare const ERROR_SUBTYPES: {
+  NOT_FOUND: string
+  VALIDATION: string
+  PERMISSION: string
+  CONFLICT: string
+}

package/plugins/core/lib/querying-writing/knex-constants.js

@@ -1,11 +1,3 @@
-/**
- * @module knex-constants
- * @description Shared constants for the REST API Knex plugin
- *
- * This module contains all the magic strings and shared constants used
- * throughout the plugin to avoid repetition and improve maintainability.
- */
-
 // Internal property names - using unique names to avoid collisions with user data
 export const RELATIONSHIPS_KEY = '__$jsonrestapi_relationships$__'
 export const RELATIONSHIP_METADATA_KEY = '__$jsonrestapi_metadata$__'
@@ -17,24 +9,8 @@ export const DEFAULT_QUERY_LIMIT = 20
 export const DEFAULT_MAX_QUERY_LIMIT = 100
 export const DEFAULT_MAX_INCLUDE_LIMIT = 1000
 export const DEFAULT_INCLUDE_DEPTH_LIMIT = 3
-
-// Schema handling helpers
-export const getSchemaStructure = (schema) => schema?.structure || schema || {}
-export const getIdProperty = (schemaInfo) => schemaInfo?.idProperty || 'id'
-
-// Default values
-export const DEFAULT_PAGE_SIZE = 20
-export const DEFAULT_MAX_PAGE_SIZE = 100
-export const DEFAULT_PAGE_NUMBER = 1
-
-// Database clients
-export const DB_CLIENTS = {
-  POSTGRES: 'pg',
-  MYSQL: 'mysql',
-  MYSQL2: 'mysql2',
-  SQLITE: 'sqlite3',
-  MSSQL: 'mssql'
-}
+export const RELATIONSHIP_WRITE_BATCH_SIZE = 100
+export const RELATIONSHIP_READ_BATCH_SIZE = 100
 
 // Error subtypes
 export const ERROR_SUBTYPES = {