json-rest-api 1.0.10 → 1.0.11

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

@@ -1,6 +1,6 @@
 import { requirePackage } from 'hooked-api';
-import { createSchema, createKnexTable } from 'json-rest-schema';
-import { createCrossTableSearchHelpers } from './lib/querying/knex-cross-table-search.js';
+import { createSchema }  from 'json-rest-schema';
+import { createKnexTable, addKnexFields, alterKnexFields } from './lib/dbTablesOperations.js';
 import { buildFieldSelection, isNonDatabaseField } from './lib/querying-writing/knex-field-helpers.js';
 import { getForeignKeyFields } from './lib/querying-writing/field-utils.js';
 import { buildQuerySelection } from './lib/querying/knex-query-helpers-base.js';
@@ -24,6 +24,8 @@ import {
   buildCursorMeta,
   parseCursor
 } from './lib/querying/knex-pagination-helpers.js';
+import { getUrlPrefix } from './lib/querying/url-helpers.js';
+import { createStorageAdapter } from './lib/storage/storage-adapter.js';
 
 /**
  * Strips non-database fields (computed and virtual) from attributes before database operations
@@ -55,7 +57,6 @@ export const RestApiKnexPlugin = {
   dependencies: ['rest-api'],
 
   async install({ helpers, vars, pluginOptions, api, log, scopes, addHook, addScopeMethod }) {
-    
     // Try to import knex dynamically
     let knexLib;
     try {
@@ -75,6 +76,48 @@ export const RestApiKnexPlugin = {
       helpers: {}
     };
 
+    const storageAdapters = new Map();
+
+    const getScopeStorageAdapter = (scopeName) => {
+      if (!scopeName) return null;
+      const resource = api.resources?.[scopeName] || scopes?.[scopeName];
+      const schemaInfo = resource?.vars?.schemaInfo;
+      if (!schemaInfo) return null;
+
+      const cached = storageAdapters.get(scopeName);
+      if (cached && cached.schemaInfo === schemaInfo) {
+        return cached.adapter;
+      }
+
+      const adapter = createStorageAdapter({ knex, schemaInfo });
+      storageAdapters.set(scopeName, { adapter, schemaInfo });
+      if (resource?.vars) {
+        resource.vars.storageAdapter = adapter;
+      }
+      return adapter;
+    };
+
+    api.knex.helpers.getStorageAdapter = getScopeStorageAdapter;
+    helpers.getStorageAdapter = getScopeStorageAdapter;
+
+    const createSelectTranslator = (adapter) => {
+      if (!adapter) return null;
+      return (field, alias) => {
+        if (field === '*') {
+          return alias ? `${alias}.*` : '*';
+        }
+        const translated = adapter.translateColumn(field);
+        const result = translated || field;
+        if (!alias) {
+          return result;
+        }
+        if (result.includes('.')) {
+          return result;
+        }
+        return `${alias}.${result}`;
+      };
+    };
+
     // Check database capabilities
     const hasWindowFunctions = await supportsWindowFunctions(knex);
     const dbInfo = await getDatabaseInfo(knex);
@@ -91,8 +134,7 @@ export const RestApiKnexPlugin = {
       windowFunctions: hasWindowFunctions
     });
 
-    // Initialize cross-table search helpers
-    const crossTableSearchHelpers = createCrossTableSearchHelpers(scopes, log);
+    // Cross-table search functions are now imported directly and used with full signatures
     
     /* ╔═════════════════════════════════════════════════════════════════════╗
      * ║                  MAIN QUERY FILTERING HOOK                              ║
@@ -102,7 +144,7 @@ export const RestApiKnexPlugin = {
     
     // Register the three separate filter hooks
     // Dependencies object for the hooks
-    const polymorphicFiltersHookParams  = { log, scopes, knex, crossTableSearchHelpers };
+    const polymorphicFiltersHookParams  = { log, scopes, knex, getStorageAdapter: getScopeStorageAdapter };
     
     // Register in specific order: polymorphic → cross-table → basic
     // This ensures proper field qualification when JOINs are present
@@ -121,32 +163,61 @@ export const RestApiKnexPlugin = {
     addHook('knexQueryFiltering', 'basicFiltersHook', {}, 
       async (hookParams) => basicFiltersHook(hookParams, polymorphicFiltersHookParams)
     );
-    
-    // Expose helpers under api.knex.helpers
-    api.knex.helpers.crossTableSearch = crossTableSearchHelpers;
+
+        // 3. Basic filters (processes simple main table filters)
+    addHook('release', 'releaseHook', {}, 
+       async ({ api }) => api.knex.instance.destroy() 
+    );
+
 
     // Helper scope method to get all schema-related information
-      addScopeMethod('createKnexTable', async ({ vars, scope, scopeName, scopeOptions, runHooks }) => {
-        // Create a filtered schema that excludes virtual fields
-        const schemaStructure = vars.schemaInfo.schemaStructure || {};
-        const filteredSchema = {};
-        
-        // Copy only non-virtual fields to the filtered schema
-        Object.entries(schemaStructure).forEach(([fieldName, fieldDef]) => {
-          if (!fieldDef.virtual) {
-            filteredSchema[fieldName] = fieldDef;
-          }
-        });
-        
-        // Create schema object from filtered fields
-        const tableSchema = createSchema(filteredSchema);
-        
-        await createKnexTable(api.knex.instance, vars.schemaInfo.tableName, tableSchema, vars.schemaInfo.idProperty)
-      })
+    addScopeMethod('createKnexTable', async ({ vars, scope, scopeName, scopeOptions, runHooks }) => {
+      // Create a filtered schema that excludes virtual fields
+      const schemaStructure = vars.schemaInfo.schemaStructure || {};
+      const filteredSchema = {};
+      
+      // Copy only non-virtual fields to the filtered schema
+      Object.entries(schemaStructure).forEach(([fieldName, fieldDef]) => {
+        if (!fieldDef.virtual) {
+          filteredSchema[fieldName] = fieldDef;
+        }
+      });
+      
+      // Create schema object from filtered fields
+      const tableSchemaInstance = createSchema(filteredSchema);
+      
+      await createKnexTable(api.knex.instance, vars.schemaInfo, tableSchemaInstance, scopeOptions)
+    })
+
+
+      // Helper scope method to alter existing fields in a table
+  addScopeMethod('alterKnexFields', async ({ vars, scope, scopeName, scopeOptions, runHooks, params }) => {
+    // Validate required parameters
+    if (!params.fields || typeof params.fields !== 'object') {
+      throw new Error('fields parameter is required for alterKnexFields');
+    }
+
+    await alterKnexFields(
+      api.knex.instance,
+      vars.schemaInfo.tableName,
+      params.fields,
+      params.options // Pass through any additional options
+    );
+  });
+
     
-      helpers.newTransaction = async () => {
-        return knex.transaction()
-      }
+    // Helper scope method to add a field to an existing table
+    addScopeMethod('addKnexFields', async ({ vars, scope, scopeName, scopeOptions, runHooks, params }) => {
+      
+      // Create schema object from filtered fields
+      const partialTableSchema = createSchema(params.fields);
+      
+      await addKnexFields(api.knex.instance, vars.schemaInfo.tableName, partialTableSchema)
+    })
+
+    helpers.newTransaction = async () => {
+      return knex.transaction()
+    }
 
     /* ╔═════════════════════════════════════════════════════════════════════╗
      * ║                    DATA OPERATION METHODS                           ║
@@ -167,16 +238,19 @@ export const RestApiKnexPlugin = {
      * @returns {Promise<boolean>} True if the resource exists, false otherwise
      */
     helpers.dataExists = async ({ scopeName, context }) => {
+      const storageAdapter = getScopeStorageAdapter(scopeName);
+      if (storageAdapter) {
+        context.storageAdapter = storageAdapter;
+      }
+
       const id = context.id;
-      const scope = api.resources[scopeName];
 
-      const tableName = context.schemaInfo.tableName
-      const idProperty = context.schemaInfo.idProperty
-      const db = context.db;
+      const tableName = storageAdapter?.getTableName?.() || context.schemaInfo.tableName;
+      const idProperty = storageAdapter?.getIdColumn?.() || context.schemaInfo.idProperty;
+      const db = context.db || api.knex.instance;
       
       log.debug(`[Knex] EXISTS ${tableName}/${id}`);
       
-      // Select with alias if idProperty is not 'id'
       const selectClause = idProperty !== 'id' ? `${idProperty} as id` : 'id';
       
       const record = await db(tableName)
@@ -197,7 +271,7 @@ export const RestApiKnexPlugin = {
      * @param {Object} params.context.schemaInfo - Schema information for the resource
      * @param {string} params.context.schemaInfo.tableName - The database table name (e.g., 'basic_books')
      * @param {string} params.context.schemaInfo.idProperty - The primary key field name (e.g., 'id')
-     * @param {Object} params.context.schemaInfo.schema - The full schema definition for the resource
+     * @param {Object} params.context.schemaInfo.schemaInstance - The full schema definition for the resource
      * @param {Object} params.context.db - Database connection (knex instance or transaction)
      * @param {Object} [params.context.queryParams] - Query parameters for sparse fieldsets and includes
      * @param {Object} [params.context.queryParams.fields] - Sparse fieldset selections
@@ -207,6 +281,10 @@ export const RestApiKnexPlugin = {
      * @throws {RestApiResourceError} When the resource is not found
      */
     helpers.dataGet = async ({ scopeName, context, runHooks }) => {
+      const storageAdapter = getScopeStorageAdapter(scopeName);
+      if (storageAdapter) {
+        context.storageAdapter = storageAdapter;
+      }
       const scope = api.resources[scopeName];
       if (!scope) {
         log.error('[DATA-GET] scope is undefined!', { scopeName, availableScopes: Object.keys(api.resources || {}) });
@@ -220,11 +298,10 @@ export const RestApiKnexPlugin = {
           varKeys: scope.vars ? Object.keys(scope.vars) : []
         });
       }
-      const id = context.id;      
-      const tableName = context.schemaInfo.tableName;
-      const idProperty = context.schemaInfo.idProperty
-      const schema =  context.schemaInfo.schema;
-      const db = context.db;
+      const id = context.id;
+      const tableName = storageAdapter?.getTableName?.() || context.schemaInfo.tableName;
+      const idProperty = storageAdapter?.getIdColumn?.() || context.schemaInfo.idProperty;
+      const db = context.db || api.knex.instance;
       
       log.debug(`[Knex] GET ${tableName}/${id}`);
       
@@ -246,7 +323,14 @@ export const RestApiKnexPlugin = {
       let query = db(tableName).where(idProperty, id);
       
       // Apply field selection
-      query = buildQuerySelection(query, tableName, fieldSelectionInfo.fieldsToSelect, false);
+      const selectTranslator = createSelectTranslator(storageAdapter);
+      query = buildQuerySelection(
+        query,
+        tableName,
+        fieldSelectionInfo.fieldsToSelect,
+        false,
+        selectTranslator ? { translateColumn: selectTranslator } : undefined,
+      );
       
       const record = await query.first();
       
@@ -291,11 +375,15 @@ export const RestApiKnexPlugin = {
      * @returns {Promise<Object|null>} JSON:API formatted resource with belongsTo relationships, or null if not found
      */
     helpers.dataGetMinimal = async ({ scopeName, context }) => {
+      const storageAdapter = getScopeStorageAdapter(scopeName);
+      if (storageAdapter) {
+        context.storageAdapter = storageAdapter;
+      }
       const scope = api.resources[scopeName];
       const id = context.id;
-      const tableName = context.schemaInfo.tableName;
-      const idProperty = context.schemaInfo.idProperty;
-      const db = context.db;
+      const tableName = storageAdapter?.getTableName?.() || context.schemaInfo.tableName;
+      const idProperty = storageAdapter?.getIdColumn?.() || context.schemaInfo.idProperty;
+      const db = context.db || api.knex.instance;
       
       log.debug(`[Knex] GET_MINIMAL ${tableName}/${id}`);
       
@@ -327,8 +415,8 @@ export const RestApiKnexPlugin = {
      * @param {Object} params.context - The context object containing request-specific data
      * @param {Object} params.context.schemaInfo - Schema information for the resource
      * @param {string} params.context.schemaInfo.tableName - The database table name (e.g., 'basic_books')
-     * @param {Object} params.context.schemaInfo.schema - The full schema definition for the resource
-     * @param {Object} params.context.schemaInfo.searchSchema - Search schema for filtering capabilities
+     * @param {Object} params.context.schemaInfo.schemaInstance - The full schema definition for the resource
+     * @param {Object} params.context.schemaInfo.searchSchemaInstance - Search schema for filtering capabilities
      * @param {string} params.context.schemaInfo.idProperty - The primary key field name (e.g., 'id')
      * @param {Object} params.context.queryParams - Query parameters object
      * @param {Object} [params.context.queryParams.filters] - Filter conditions
@@ -347,17 +435,19 @@ export const RestApiKnexPlugin = {
      * @param {Function} params.runHooks - Function to run hooks (e.g., 'knexQueryFiltering')
      * @returns {Promise<Object>} JSON:API formatted response with data array, optional included resources, and pagination meta/links
      */
-    helpers.dataQuery = async ({ scopeName, context, runHooks }) => {    
+    helpers.dataQuery = async ({ scopeName, context, runHooks }) => {
+      const storageAdapter = getScopeStorageAdapter(scopeName);
+      if (storageAdapter) {
+        context.storageAdapter = storageAdapter;
+      }
       const scope = api.resources[scopeName];
-      const tableName = context.schemaInfo.tableName;
-      const schema =  context.schemaInfo.schema;
-      const searchSchema =  context.schemaInfo.searchSchema;
-      const queryParams = context.queryParams
-      const db = context.db;
-      const sortableFields = context.sortableFields
-      const idProperty = context.schemaInfo.idProperty
-
-      log.trace('[DATA-QUERY] Starting dataQuery', { scopeName, hasSearchSchema: !!searchSchema });
+      const tableName = storageAdapter?.getTableName?.() || context.schemaInfo.tableName;
+      const schemaInfo = context.schemaInfo;
+      const queryParams = context.queryParams;
+      const db = context.db || api.knex.instance;
+      const sortableFields = context.sortableFields;
+
+      log.trace('[DATA-QUERY] Starting dataQuery', { scopeName });
       log.debug(`[Knex] QUERY ${tableName}`, queryParams);
       
       // Build field selection for sparse fieldsets
@@ -376,7 +466,14 @@ export const RestApiKnexPlugin = {
       // Start building query with table prefix (for JOIN support)
       let query = db(tableName);
 
-      query = buildQuerySelection(query, tableName, fieldSelectionInfo.fieldsToSelect, true);
+      const selectTranslator = createSelectTranslator(storageAdapter);
+      query = buildQuerySelection(
+        query,
+        tableName,
+        fieldSelectionInfo.fieldsToSelect,
+        true,
+        selectTranslator ? { translateColumn: selectTranslator } : undefined,
+      );
       
       /* ═══════════════════════════════════════════════════════════════════
        * FILTERING HOOKS
@@ -394,10 +491,20 @@ export const RestApiKnexPlugin = {
       
       log.trace('[DATA-QUERY] Storing query data in context before calling runHooks');
       
+      // YOU ARE HERE: pass 'sesrchSchemaInstance' in the context below
+
       // Store the query data in context where hooks can access it
       // This is the proper way to share data between methods and hooks
       if (context) {
-        context.knexQuery = { query, filters: queryParams.filters, searchSchema, scopeName, tableName, db };
+        context.knexQuery = {
+          query,
+          filters: queryParams.filters,
+          schemaInfo,
+          scopeName,
+          tableName,
+          db,
+          adapter: storageAdapter,
+        };
         
         log.trace('[DATA-QUERY] Stored data in context', { hasStoredData: !!context.knexQuery, filters: queryParams.filters });
       }
@@ -423,7 +530,19 @@ export const RestApiKnexPlugin = {
             return; // Skip non-sortable fields
           }
           
-          query.orderBy(field, desc ? 'desc' : 'asc');
+          // Map relationship names to actual database columns for sorting
+          // Check if this is a relationship field that needs to be mapped
+          let dbField = field;
+          const searchField = schemaInfo.searchSchemaStructure?.[field];
+          if (searchField?.actualField) {
+            // This is a relationship field, use the actual database column
+            dbField = searchField.actualField;
+          }
+          const translatedField = storageAdapter?.translateColumn
+            ? storageAdapter.translateColumn(dbField)
+            : dbField;
+
+          query.orderBy(translatedField, desc ? 'desc' : 'asc');
         });
       }
       
@@ -672,7 +791,14 @@ export const RestApiKnexPlugin = {
           if (queryParams.filters && Object.keys(queryParams.filters).length > 0) {
             // Store query data in context for hooks
             if (context) {
-              context.knexQuery = { query: countQuery, filters: queryParams.filters, searchSchema, scopeName, tableName, db };
+              context.knexQuery = {
+                query: countQuery,
+                filters: queryParams.filters,
+                scopeName,
+                tableName,
+                schemaInfo,
+                db
+              };
             }
             
             // Run the same filtering hooks
@@ -700,7 +826,7 @@ export const RestApiKnexPlugin = {
         }
         
         // Generate links 
-        const urlPrefix = scope.vars.publicBaseUrl || scope.vars.transport?.mountPath || '';
+        const urlPrefix = getUrlPrefix(context, scope);
         context.returnMeta.paginationLinks = generatePaginationLinks(
           urlPrefix,
           scopeName,
@@ -732,7 +858,7 @@ export const RestApiKnexPlugin = {
         }
         
         context.returnMeta.paginationMeta = buildCursorMeta(records, pageSize, hasMore, sortFields);
-        const urlPrefix = scope.vars.publicBaseUrl || scope.vars.transport?.mountPath || '';
+        const urlPrefix = getUrlPrefix(context, scope);
         context.returnMeta.paginationLinks = generateCursorPaginationLinks(
           urlPrefix,
           scopeName,
@@ -770,7 +896,7 @@ export const RestApiKnexPlugin = {
      * @param {Object} params.context.schemaInfo - Schema information for the resource
      * @param {string} params.context.schemaInfo.tableName - The database table name (e.g., 'basic_books')
      * @param {string} params.context.schemaInfo.idProperty - The primary key field name (e.g., 'id')
-     * @param {Object} params.context.schemaInfo.schema - The full schema definition for the resource
+     * @param {Object} params.context.schemaInfo.schemaInstance - The full schema definition for the resource
      * @param {Object} params.context.db - Database connection (knex instance or transaction)
      * @param {Object} params.context.inputRecord - JSON:API formatted input record
      * @param {Object} params.context.inputRecord.data - The resource data
@@ -778,12 +904,15 @@ export const RestApiKnexPlugin = {
      * @returns {Promise<string|number>} The ID of the newly created resource
      */
     helpers.dataPost = async ({ scopeName, context }) => {
+      const storageAdapter = getScopeStorageAdapter(scopeName);
+      if (storageAdapter) {
+        context.storageAdapter = storageAdapter;
+      }
       const scope = api.resources[scopeName];
-      const tableName = context.schemaInfo.tableName;
-      const idProperty = context.schemaInfo.idProperty
-      const schema =  context.schemaInfo.schema;
-      const db = context.db;
-      const inputRecord = context.inputRecord      
+      const tableName = storageAdapter?.getTableName?.() || context.schemaInfo.tableName;
+      const idProperty = storageAdapter?.getIdColumn?.() || context.schemaInfo.idProperty;
+      const db = context.db || api.knex.instance;
+      const inputRecord = context.inputRecord;
       
       log.debug(`[Knex] POST ${tableName}`, inputRecord);
       
@@ -811,7 +940,7 @@ export const RestApiKnexPlugin = {
      * @param {Object} params.context.schemaInfo - Schema information for the resource
      * @param {string} params.context.schemaInfo.tableName - The database table name (e.g., 'basic_books')
      * @param {string} params.context.schemaInfo.idProperty - The primary key field name (e.g., 'id')
-     * @param {Object} params.context.schemaInfo.schema - The full schema definition for the resource
+     * @param {Object} params.context.schemaInfo.schemaInstance - The full schema definition for the resource
      * @param {Object} params.context.db - Database connection (knex instance or transaction)
      * @param {Object} params.context.inputRecord - JSON:API formatted input record
      * @param {Object} params.context.inputRecord.data - The resource data
@@ -822,14 +951,17 @@ export const RestApiKnexPlugin = {
      * @throws {RestApiResourceError} When updating and the resource is not found
      */
     helpers.dataPut = async ({ scopeName, context }) => {
+      const storageAdapter = getScopeStorageAdapter(scopeName);
+      if (storageAdapter) {
+        context.storageAdapter = storageAdapter;
+      }
       const scope = api.resources[scopeName];
       const id = context.id;
-      const tableName = context.schemaInfo.tableName;
-      const idProperty = context.schemaInfo.idProperty
-      const schema =  context.schemaInfo.schema;
-      const db = context.db;
-      const inputRecord = context.inputRecord      
-      const isCreate = context.isCreate
+      const tableName = storageAdapter?.getTableName?.() || context.schemaInfo.tableName;
+      const idProperty = storageAdapter?.getIdColumn?.() || context.schemaInfo.idProperty;
+      const db = context.db || api.knex.instance;
+      const inputRecord = context.inputRecord;
+      const isCreate = context.isCreate;
     
       log.debug(`[Knex] PUT ${tableName}/${id} (isCreate: ${context.isCreate})`);
       
@@ -895,7 +1027,7 @@ export const RestApiKnexPlugin = {
      * @param {Object} params.context.schemaInfo - Schema information for the resource
      * @param {string} params.context.schemaInfo.tableName - The database table name (e.g., 'basic_books')
      * @param {string} params.context.schemaInfo.idProperty - The primary key field name (e.g., 'id')
-     * @param {Object} params.context.schemaInfo.schema - The full schema definition for the resource
+     * @param {Object} params.context.schemaInfo.schemaInstance - The full schema definition for the resource
      * @param {Object} params.context.db - Database connection (knex instance or transaction)
      * @param {Object} params.context.inputRecord - JSON:API formatted input record with partial updates
      * @param {Object} params.context.inputRecord.data - The resource data
@@ -904,14 +1036,17 @@ export const RestApiKnexPlugin = {
      * @returns {Promise<void>} Resolves when the update is complete
      * @throws {RestApiResourceError} When the resource is not found
      */
-    helpers.dataPatch = async ({ scopeName, context  }) => {
+    helpers.dataPatch = async ({ scopeName, context }) => {
+      const storageAdapter = getScopeStorageAdapter(scopeName);
+      if (storageAdapter) {
+        context.storageAdapter = storageAdapter;
+      }
       const scope = api.resources[scopeName];
       const id = context.id;
-      const tableName = context.schemaInfo.tableName;
-      const idProperty = context.schemaInfo.idProperty
-      const schema =  context.schemaInfo.schema;
-      const db = context.db;
-      const inputRecord = context.inputRecord      
+      const tableName = storageAdapter?.getTableName?.() || context.schemaInfo.tableName;
+      const idProperty = storageAdapter?.getIdColumn?.() || context.schemaInfo.idProperty;
+      const db = context.db || api.knex.instance;
+      const inputRecord = context.inputRecord;
       
       log.debug(`[Knex] PATCH ${tableName}/${id}`);
       
@@ -938,7 +1073,7 @@ export const RestApiKnexPlugin = {
       
       // Strip non-database fields (computed and virtual) before database operation
       const finalAttributes = stripNonDatabaseFields(mergedAttributes, context.schemaInfo);
-      
+
       log.debug(`[Knex] PATCH finalAttributes:`, finalAttributes);
       
       // Remove the idProperty from attributes to prevent updating the primary key
@@ -969,12 +1104,16 @@ export const RestApiKnexPlugin = {
      * @throws {RestApiResourceError} When the resource is not found
      */
     helpers.dataDelete = async ({ scopeName, context }) => {
+      const storageAdapter = getScopeStorageAdapter(scopeName);
+      if (storageAdapter) {
+        context.storageAdapter = storageAdapter;
+      }
       const scope = api.resources[scopeName];
       const id = context.id;
 
-      const tableName = context.schemaInfo.tableName;
-      const idProperty = context.schemaInfo.idProperty
-      const db = context.db;
+      const tableName = storageAdapter?.getTableName?.() || context.schemaInfo.tableName;
+      const idProperty = storageAdapter?.getIdColumn?.() || context.schemaInfo.idProperty;
+      const db = context.db || api.knex.instance;
       
       log.debug(`[Knex] DELETE ${tableName}/${id}`);
       
@@ -1004,4 +1143,4 @@ export const RestApiKnexPlugin = {
     
     log.info('RestApiKnexPlugin installed - basic CRUD operations ready');
   }
-}
+}