json-rest-api 1.0.10 → 1.0.11

package/plugins/core/lib/querying/url-helpers.js

@@ -0,0 +1,119 @@
+/**
+ * URL Helper Functions
+ * 
+ * Centralized functions for URL generation to avoid code duplication
+ * and support flexible URL prefix override capabilities.
+ */
+
+/**
+ * Get the complete URL prefix, handling all calculation and override logic
+ * 
+ * Priority order:
+ * 1. context.urlPrefixOverride - Explicit override (from hooks or middleware)
+ * 2. context.urlPrefix - Pre-calculated URL prefix
+ * 3. Calculate from request if provided
+ * 4. scope.vars.transport?.mountPath - Fallback to mount path
+ * 5. '' - Empty string as final fallback
+ * 
+ * @param {Object} context - Request context (may have urlPrefixOverride or urlPrefix)
+ * @param {Object} scope - Scope/resource object with transport vars
+ * @param {Object} req - Optional Express request object for auto-calculation
+ * @returns {string} The final URL prefix to use
+ * 
+ * @example
+ * // With full context
+ * const urlPrefix = getUrlPrefix(context, scope);
+ * 
+ * @example
+ * // With request object for auto-calculation
+ * const urlPrefix = getUrlPrefix({}, api, req);
+ */
+export function getUrlPrefix(context, scope, req = null) {
+  // Priority 1: Explicit override
+  if (context?.urlPrefixOverride) {
+    return context.urlPrefixOverride;
+  }
+  
+  // Priority 2: Pre-calculated urlPrefix
+  if (context?.urlPrefix) {
+    return context.urlPrefix;
+  }
+  
+  // Priority 3: Calculate from request if provided
+  if (req) {
+    const protocol = req.get?.('x-forwarded-proto') || req.protocol || 'http';
+    const host = req.get?.('x-forwarded-host') || req.get?.('host');
+    const mountPath = scope?.vars?.transport?.mountPath || '';
+    
+    if (host) {
+      return `${protocol}://${host}${mountPath}`;
+    }
+  }
+  
+  // Priority 4: Fallback to mount path
+  return scope?.vars?.transport?.mountPath || '';
+}
+
+/**
+ * Build a complete resource URL
+ * 
+ * @param {Object} context - Request context
+ * @param {Object} scope - Scope containing transport vars
+ * @param {string} scopeName - Resource type name
+ * @param {string} id - Resource ID
+ * @returns {string} Complete resource URL
+ * 
+ * @example
+ * const url = buildResourceUrl(context, scope, 'books', '123');
+ * // Returns: "https://api.example.com/api/books/123"
+ */
+export function buildResourceUrl(context, scope, scopeName, id) {
+  const urlPrefix = getUrlPrefix(context, scope);
+  return `${urlPrefix}/${scopeName}/${id}`;
+}
+
+/**
+ * Build a relationship URL
+ * 
+ * @param {Object} context - Request context
+ * @param {Object} scope - Scope containing transport vars
+ * @param {string} scopeName - Resource type name
+ * @param {string} id - Resource ID
+ * @param {string} relationshipName - Name of the relationship
+ * @param {boolean} isRelationshipEndpoint - If true, builds /relationships/ URL
+ * @returns {string} Complete relationship URL
+ * 
+ * @example
+ * // For relationship linkage endpoint
+ * buildRelationshipUrl(context, scope, 'books', '1', 'author', true);
+ * // Returns: "https://api.example.com/api/books/1/relationships/author"
+ * 
+ * // For related resource endpoint
+ * buildRelationshipUrl(context, scope, 'books', '1', 'author', false);
+ * // Returns: "https://api.example.com/api/books/1/author"
+ */
+export function buildRelationshipUrl(context, scope, scopeName, id, relationshipName, isRelationshipEndpoint = false) {
+  const urlPrefix = getUrlPrefix(context, scope);
+  if (isRelationshipEndpoint) {
+    return `${urlPrefix}/${scopeName}/${id}/relationships/${relationshipName}`;
+  }
+  return `${urlPrefix}/${scopeName}/${id}/${relationshipName}`;
+}
+
+/**
+ * Build a collection URL with optional query string
+ * 
+ * @param {Object} context - Request context
+ * @param {Object} scope - Scope containing transport vars
+ * @param {string} scopeName - Resource type name
+ * @param {string} queryString - Optional query string (with leading ?)
+ * @returns {string} Complete collection URL
+ * 
+ * @example
+ * buildCollectionUrl(context, scope, 'books', '?page[size]=10');
+ * // Returns: "https://api.example.com/api/books?page[size]=10"
+ */
+export function buildCollectionUrl(context, scope, scopeName, queryString = '') {
+  const urlPrefix = getUrlPrefix(context, scope);
+  return `${urlPrefix}/${scopeName}${queryString}`;
+}

package/plugins/core/lib/querying-writing/compile-schemas.js

@@ -10,7 +10,7 @@ import { ensureSearchFieldsAreIndexed, generateSearchSchemaFromSchema, sortField
  * 
  * @example
  * // Input: Raw schema with computed field
- * const rawSchema = {
+ * const rawFields = {
  *   title: { type: 'string', required: true },
  *   content: { type: 'string' },
  *   author_id: { belongsTo: 'users', as: 'author' },  // Missing type
@@ -39,7 +39,7 @@ import { ensureSearchFieldsAreIndexed, generateSearchSchemaFromSchema, sortField
  * 
  * @example
  * // Input: Schema with search fields
- * const rawSchema = {
+ * const rawFields = {
  *   title: { type: 'string', search: true },    // Searchable
  *   status: { type: 'string' },                 // Not searchable
  *   author_id: { belongsTo: 'users', as: 'author' }
@@ -127,13 +127,13 @@ export async function compileSchemas(scope, deps) {
   const scopeName = context.scopeName;
 
   // Get raw schema
-  const rawSchema = scope.scopeOptions?.schema || {};
+  const rawFields = scope.scopeOptions?.schema || {};
   
   // Extract computed fields from schema and build enriched schema
   const computedFields = {};
-  const enrichedSchema = {};
+  const enrichedFields = {};
   
-  for (const [fieldName, fieldDef] of Object.entries(rawSchema)) {
+  for (const [fieldName, fieldDef] of Object.entries(rawFields)) {
     if (fieldDef.computed === true) {
       // Extract computed field - copy entire definition
       computedFields[fieldName] = { ...fieldDef };
@@ -149,12 +149,12 @@ export async function compileSchemas(scope, deps) {
       
       // Don't include computed fields in the validation schema
     } else {
-      enrichedSchema[fieldName] = { ...fieldDef };
+      enrichedFields[fieldName] = { ...fieldDef };
     }
   }
   
   // Default enrichment: Add type to belongsTo fields
-  for (const [fieldName, fieldDef] of Object.entries(enrichedSchema)) {
+  for (const [fieldName, fieldDef] of Object.entries(enrichedFields)) {
     if (fieldDef.belongsTo && !fieldDef.type) {
       fieldDef.type = 'id';
     }
@@ -163,7 +163,7 @@ export async function compileSchemas(scope, deps) {
   // ADD LOGIC TO MAKE FIELDS SEARCHABLE HERE
   // Auto-detect pivot tables and make their foreign key fields searchable
   // This is critical for many-to-many relationship operations which need to filter pivot records
-  const fields = Object.entries(enrichedSchema);
+  const fields = Object.entries(enrichedFields);
   const belongsToFields = fields.filter(([_, def]) => def.belongsTo);
   
   // If 2+ belongsTo fields and they make up 40%+ of non-id fields, likely a pivot table
@@ -183,52 +183,56 @@ export async function compileSchemas(scope, deps) {
 
   // Hook: schema:enrich
   const schemaContext = {
-    schema: enrichedSchema,    // Mutable
-    originalSchema: rawSchema,  // Read-only
+    fields: enrichedFields,    // Mutable
+    originalFields: rawFields,  // Read-only
     scopeName
   };
   await runHooks('schema:enrich', schemaContext);
   
   // Create schema object
-  const schemaObject = createSchema(schemaContext.schema);
+  const schemaObject = createSchema(schemaContext.fields);
   
   // Generate searchSchema by merging explicit searchSchema with fields marked search:true.
   // This allows two ways to define searchable fields: either mark fields with search:true
   // in the main schema, or provide an explicit searchSchema with more control over filtering.
-  // The explicit searchSchema takes precedence and can define virtual fields for joins.
+  // The explicit searchSchema takes precedence when there are conflicts - it can override
+  // fields marked with search:true. Fields with search:true that are NOT in the explicit
+  // searchSchema will be added automatically.
   // Example: title: {search: true} auto-generates a searchable field with sensible defaults,
   // while searchSchema can specify filterOperator: 'contains' or complex join configurations.
-  let rawSearchSchema = scope.scopeOptions.searchSchema ||
-  generateSearchSchemaFromSchema(schemaContext.schema);
+  let rawSearchFields = generateSearchSchemaFromSchema(
+    schemaContext.fields,
+    scope.scopeOptions.searchSchema
+  );
   
-  if (rawSearchSchema) {
+  if (rawSearchFields) {
     // Mark all search fields as indexed for database optimization.
     // This ensures that any field used for filtering will have a database index created,
     // dramatically improving query performance. Without indexes, filtering large tables
     // would require full table scans. The storage plugin uses these hints to create indexes.
     // Example: A status field marked for search gets indexed: true, enabling efficient
     // WHERE status = 'published' queries that can use index lookups instead of scanning all rows.
-    ensureSearchFieldsAreIndexed(rawSearchSchema);
+    ensureSearchFieldsAreIndexed(rawSearchFields);
     
     // Hook: searchSchema:enrich
     const searchSchemaContext = {
-      searchSchema: rawSearchSchema,    // Mutable
-      schema: schemaContext.schema,     // Read-only enriched schema
+      fields: schemaContext.fields,       // Mutable
+      originalFields: rawSearchFields,    // Read-only enriched schema
       scopeName
     };
     await runHooks('searchSchema:enrich', searchSchemaContext);
     
     // Create searchSchema object
-    var searchSchemaObject = createSchema(searchSchemaContext.searchSchema);
+    var searchSchemaObject = createSchema(rawSearchFields);
   } else {
-    var searchSchemaObject = null;
+    var searchSchemaObject = createSchema({});
   }
 
   // Build schemaRelationships including polymorphic fields from schema
   const schemaRelationships = { ...(scope.scopeOptions.relationships || {}) };
   
   // Validate belongsTo fields
-  for (const [fieldName, fieldDef] of Object.entries(schemaContext.schema)) {
+  for (const [fieldName, fieldDef] of Object.entries(schemaContext.fields)) {
     // Validate that belongsTo fields have 'as' property
     if (fieldDef.belongsTo && !fieldDef.as) {
       throw new Error(
@@ -243,7 +247,7 @@ export async function compileSchemas(scope, deps) {
   const fieldGetters = {};
   const getterFields = [];
   
-  for (const [fieldName, fieldDef] of Object.entries(schemaContext.schema)) {
+  for (const [fieldName, fieldDef] of Object.entries(schemaContext.fields)) {
     if (fieldDef.getter && typeof fieldDef.getter === 'function') {
       fieldGetters[fieldName] = {
         getter: fieldDef.getter,
@@ -255,7 +259,7 @@ export async function compileSchemas(scope, deps) {
       // Validate dependencies exist
       if (fieldDef.runGetterAfter && Array.isArray(fieldDef.runGetterAfter)) {
         for (const dep of fieldDef.runGetterAfter) {
-          if (!schemaContext.schema[dep]) {
+          if (!schemaContext.fields[dep]) {
             throw new Error(
               `Field '${fieldName}' in resource '${scopeName}' has getter dependency '${dep}' that does not exist in schema`
             );
@@ -279,7 +283,7 @@ export async function compileSchemas(scope, deps) {
   const fieldSetters = {};
   const setterFields = [];
   
-  for (const [fieldName, fieldDef] of Object.entries(schemaContext.schema)) {
+  for (const [fieldName, fieldDef] of Object.entries(schemaContext.fields)) {
     if (fieldDef.setter && typeof fieldDef.setter === 'function') {
       fieldSetters[fieldName] = {
         setter: fieldDef.setter,
@@ -291,7 +295,7 @@ export async function compileSchemas(scope, deps) {
       // Validate dependencies exist
       if (fieldDef.runSetterAfter && Array.isArray(fieldDef.runSetterAfter)) {
         for (const dep of fieldDef.runSetterAfter) {
-          if (!schemaContext.schema[dep]) {
+          if (!schemaContext.fields[dep]) {
             throw new Error(
               `Field '${fieldName}' in resource '${scopeName}' has setter dependency '${dep}' that does not exist in schema`
             );
@@ -313,10 +317,14 @@ export async function compileSchemas(scope, deps) {
 
   // Cache everything
   scope.vars.schemaInfo = {
-    schema: schemaObject,
-    schemaStructure: schemaContext.schema,
+
+    schemaInstance: schemaObject,
+    schemaStructure: schemaObject.structure,
+
+    searchSchemaInstance: searchSchemaObject,
+    searchSchemaStructure: searchSchemaObject.structure,
+       
     computed: computedFields,
-    searchSchema: searchSchemaObject,
     schemaRelationships: schemaRelationships,
     tableName: scope.scopeOptions.tableName || scopeName,
     idProperty: scope.scopeOptions.idProperty || scope.vars.idProperty,

package/plugins/core/lib/querying-writing/database-capabilities.js

@@ -101,8 +101,9 @@ export const supportsWindowFunctions = async (knex) => {
       case 'mysql':
       case 'mysql2':
         try {
-          versionString = await knex.raw('SELECT VERSION() as version');
-          const mysqlVersion = parseVersion(versionString[0].version);
+          const row = await knex.first(knex.raw('VERSION() as version'));
+          const mysqlVersion = parseVersion(row.version);
+
           return mysqlVersion && mysqlVersion.major >= 8;
         } catch (dbError) {
           console.warn(`[supportsWindowFunctions] Failed to get MySQL version: ${dbError.message}`);
@@ -216,13 +217,13 @@ export const getDatabaseInfo = async (knex) => {
     switch (client) {
       case 'mysql':
       case 'mysql2':
-        try {
-          versionString = await knex.raw('SELECT VERSION() as version');
-          return { client: 'MySQL', version: versionString[0].version };
-        } catch (dbError) {
-          console.warn(`[getDatabaseInfo] Failed to get MySQL version: ${dbError.message}`);
-          return { client: 'MySQL', version: 'unknown', error: dbError.message };
-        }
+      try {
+        const row = await knex.first(knex.raw('VERSION() as version'));
+        return { client: 'MySQL', version: row.version };
+      } catch (dbError) {
+        console.warn(`[getDatabaseInfo] Failed to get MySQL version: ${dbError.message}`);
+        return { client: 'MySQL', version: 'unknown', error: dbError.message };
+      }
         
       case 'sqlite3':
       case 'better-sqlite3':

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

@@ -145,7 +145,7 @@ export const buildFieldSelection = async (scope, deps) => {
   // Extract values from scope
   const { 
     vars: { 
-      schemaInfo: { schema, computed: computedFields = {}, schemaStructure }
+      schemaInfo: { schemaInstance: schemaInstance, computed: computedFields = {}, schemaStructure }
     }
   } = scope;
   
@@ -165,7 +165,7 @@ export const buildFieldSelection = async (scope, deps) => {
   
   // Handle both Schema objects and plain objects
   if (!schemaStructure) {
-    schemaStructure = schema?.structure || schema || {};
+    schemaStructure = schemaInstance?.structure || schemaInstance || {};
   }
   
   // Get computed fields and virtual fields from schema
@@ -199,6 +199,10 @@ export const buildFieldSelection = async (scope, deps) => {
       
       const fieldDef = schemaStructure[field];
       if (!fieldDef) throw new Error(`Unknown sparse field '${field}' requested for '${scopeName}'`);
+
+      if (fieldDef.belongsToPolymorphic) {
+        return;
+      }
       
       // NEVER include hidden fields, even if explicitly requested
       // Example: password_hash with hidden:true is never returned
@@ -254,6 +258,9 @@ export const buildFieldSelection = async (scope, deps) => {
       // Example: password_hash with hidden:true
       if (fieldDef.hidden === true) return;
       
+      // Skip polymorphic placeholder fields - handled via type/id columns
+      if (fieldDef.belongsToPolymorphic) return;
+
       // Skip normallyHidden fields - these are hidden by default
       // Example: cost with normallyHidden:true (only returned when explicitly requested)
       if (fieldDef.normallyHidden === true) return;
@@ -385,4 +392,3 @@ export const getRequestedComputedFields = (scopeName, requestedFields, computedF
   // Return only requested computed fields that exist
   return requested.filter(field => allComputedFields.includes(field));
 };
-

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

@@ -98,14 +98,14 @@ export const toJsonApiRecordWithBelongsTo = (scope, record, scopeName) => {
   // Extract schema info from scope
   const { 
     vars: { 
-      schemaInfo: { schema, schemaRelationships: relationships, idProperty }
+      schemaInfo: { schemaInstance: schemaInstance, schemaRelationships: relationships, idProperty }
     }
   } = scope;
   
   const idField = idProperty || 'id';
   
   // Get schema structure
-  const schemaStructure = getSchemaStructure(schema);
+  const schemaStructure = getSchemaStructure(schemaInstance);
   
   // Initialize relationships object
   jsonApiRecord.relationships = {};

package/plugins/core/lib/querying-writing/payload-validators.js

@@ -5,13 +5,13 @@ import { RestApiValidationError, RestApiPayloadError } from '../../../../lib/res
  * 
  * @param {string[]} includes - Array of include paths to validate
  * @param {number} maxDepth - Maximum allowed depth
- * @returns {boolean} True if valid
+ * @returns {void}
  * @throws {RestApiValidationError} If depth is exceeded
  * 
  * @example
  * // Input: Valid include paths
  * validateIncludeDepth(['author', 'comments.author'], 3);
- * // Output: true (depths are 1 and 2, both under limit)
+ * // Output: Validation succeeds (no error thrown)
  * 
  * @example
  * // Input: Path exceeding depth limit
@@ -23,7 +23,7 @@ import { RestApiValidationError, RestApiPayloadError } from '../../../../lib/res
  */
 function validateIncludeDepth(includes, maxDepth) {
   if (!includes || !Array.isArray(includes)) {
-    return true;
+    return;
   }
   
   for (const includePath of includes) {
@@ -46,8 +46,6 @@ function validateIncludeDepth(includes, maxDepth) {
       );
     }
   }
-  
-  return true;
 }
 
 /**
@@ -140,8 +138,6 @@ function validateResourceIdentifier(identifier, context, scopes = null) {
       { path: `${context}.id`, expected: 'string, number, or null', received: typeof identifier.id }
     );
   }
-  
-  return true;
 }
 
 /**
@@ -150,7 +146,7 @@ function validateResourceIdentifier(identifier, context, scopes = null) {
  * @param {Object} relationship - Relationship object to validate
  * @param {string} relationshipName - Name for error context
  * @param {Object} scopes - Scopes proxy to verify resource types
- * @returns {boolean} True if valid
+ * @returns {void}
  * @throws {RestApiPayloadError} If validation fails
  * 
  * @example
@@ -160,7 +156,7 @@ function validateResourceIdentifier(identifier, context, scopes = null) {
  *   'author',
  *   scopes
  * );
- * // Output: true
+ * // Output: Validation succeeds (no error thrown)
  * 
  * @example
  * // Input: To-many relationship  
@@ -174,7 +170,7 @@ function validateResourceIdentifier(identifier, context, scopes = null) {
  *   'tags',
  *   scopes
  * );
- * // Output: true
+ * // Output: Validation succeeds (no error thrown)
  * 
  * @example
  * // Input: Null relationship (remove association)
@@ -183,7 +179,7 @@ function validateResourceIdentifier(identifier, context, scopes = null) {
  *   'featuredImage',
  *   scopes
  * );
- * // Output: true (null is valid for clearing)
+ * // Output: Validation succeeds (null is valid for clearing)
  * 
  * @example
  * // Input: Missing data property
@@ -228,25 +224,23 @@ function validateRelationship(relationship, relationshipName, scopes = null) {
   
   // data can be null (empty to-one relationship)
   if (data === null) {
-    return true;
+    return;
   }
   
   // data can be a single resource identifier (to-one)
   if (!Array.isArray(data)) {
     validateResourceIdentifier(data, `Relationship '${relationshipName}'`, scopes);
-    return true;
+    return;
   }
   
   // data can be an array of resource identifiers (to-many)
   if (data.length === 0) {
-    return true; // Empty to-many relationship is valid
+    return; // Empty to-many relationship is valid
   }
   
   data.forEach((identifier, index) => {
     validateResourceIdentifier(identifier, `Relationship '${relationshipName}[${index}]'`, scopes);
   });
-  
-  return true;
 }
 
 /**