json-rest-api 1.0.7 → 1.0.8

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

@@ -1,245 +0,0 @@
-/**
- * @module compileSchemas
- * @description Schema compilation and enrichment for REST API resources
- * 
- * This module handles the lazy compilation of JSON schemas for resources,
- * including enrichment through hooks, search schema generation, and caching.
- * It ensures schemas are processed only once per resource for performance.
- * 
- * Why this is useful upstream:
- * - Provides lazy compilation to avoid processing unused schemas
- * - Enables schema enrichment through hooks for dynamic behavior
- * - Automatically generates search schemas from field definitions
- * - Ensures database indexes are created for searchable fields
- * - Caches compiled schemas for performance
- * - Supports both explicit and implicit search field definitions
- */
-
-import { createSchema } from 'json-rest-schema';
-import { ensureSearchFieldsAreIndexed, generateSearchSchemaFromSchema } from './schema-helpers.js';
-
-/**
- * Compiles and enriches schemas for a given scope.
- * This function must be called at the beginning of each REST method to ensure
- * schemas are processed and cached before use.
- * 
- * The compilation process:
- * 1. Clones the raw schema to avoid mutations
- * 2. Adds default type: 'id' to belongsTo fields
- * 3. Runs schema:enrich hooks for custom enrichment
- * 4. Creates schema objects using json-rest-schema
- * 5. Generates and enriches searchSchema if needed
- * 6. Caches all compiled schemas for the scope
- * 
- * @param {Object} scope - The scope object containing vars, runHooks, scopeOptions, etc.
- * @param {Object} deps - Dependencies object
- * @param {Object} deps.context - Request context containing scopeName
- * @returns {Promise<void>} Resolves when schemas are compiled
- * 
- * @example <caption>Basic usage in REST method</caption>
- * // At the beginning of a REST method:
- * import { compileSchemas } from './lib/compile-schemas.js';
- * 
- * addScopeMethod('query', async (scope, params) => {
- *   const deps = { context: { scopeName: 'articles' } };
- *   await compileSchemas(scope, deps);
- *   const schemaInfo = scope.vars.schemaInfo.schema;
- *   // Now schema, searchSchema, and relationships are available
- * });
- * 
- * @example <caption>Schema enrichment through hooks</caption>
- * // A plugin can enrich schemas dynamically:
- * api.on('schema:enrich', ({ schema, scopeName }) => {
- *   if (scopeName === 'articles') {
- *     // Add computed field
- *     schema.wordCount = {
- *       type: 'number',
- *       compute: (article) => article.content.split(' ').length
- *     };
- *     // Make title required
- *     schema.title.required = true;
- *   }
- * });
- * 
- * @example <caption>Search schema generation</caption>
- * // Original schema:
- * const schema = {
- *   title: { type: 'string', search: true },  // Marked searchable
- *   content: { type: 'string' },              // Not searchable
- *   status: { type: 'string' }                // Not searchable by default
- * };
- * 
- * // Explicit searchSchema can override:
- * const searchSchema = {
- *   title: { type: 'string', filterUsing: 'contains' },
- *   status: { type: 'string', filterUsing: '=' },
- *   author_name: {  // Virtual field for joins
- *     type: 'string',
- *     filterUsing: 'contains',
- *     actualTable: 'users',
- *     actualField: 'name'
- *   }
- * };
- * 
- * @example <caption>Why this is useful upstream</caption>
- * // The REST API plugin uses this to:
- * // 1. Lazy-load schemas only when needed (performance optimization)
- * // 2. Allow dynamic schema modifications through hooks
- * // 3. Automatically set up database indexes for searchable fields
- * // 4. Generate search schemas from field definitions (DRY principle)
- * // 5. Cache compiled schemas to avoid reprocessing
- * // 6. Support virtual search fields that join to other tables
- * // 7. Ensure belongsTo fields have proper type definitions
- */
-export async function compileSchemas(scope, deps) {
-  // Extract scopeName from context
-  const { context, runHooks } = deps;
-  const scopeName = context.scopeName;
-
-  // Get raw schema, computed fields, and virtual fields
-  const rawSchema = scope.scopeOptions?.schema || {};
-  const computed = scope.scopeOptions?.computed || {};
-  const virtual = scope.scopeOptions?.virtual || {};
-  
-  // Validate computed fields to ensure they're properly defined
-  // Example: profit_margin: { type: 'number', dependencies: ['price', 'cost'], compute: (ctx) => ... }
-  Object.entries(computed).forEach(([fieldName, fieldDef]) => {
-    // Every computed field must have a type (for JSON:API serialization)
-    if (!fieldDef.type) {
-      throw new Error(`Computed field '${fieldName}' in scope '${scopeName}' must have a type`);
-    }
-    
-    // If a compute function is provided, it must be a function
-    // Note: compute is optional - you might use enrichAttributes hook instead
-    if (fieldDef.compute && typeof fieldDef.compute !== 'function') {
-      throw new Error(`Computed field '${fieldName}' in scope '${scopeName}' has invalid compute function`);
-    }
-    
-    // Dependencies are optional but recommended for automatic fetching
-    // Example: dependencies: ['price', 'cost'] ensures these fields are 
-    // fetched from DB even if not explicitly requested
-  });
-  
-  // Validate virtual fields to ensure they're properly defined
-  // Virtual fields accept input and are returned in output but not stored in DB
-  // Example: passwordConfirmation: { type: 'string', virtual: true }
-  Object.entries(virtual).forEach(([fieldName, fieldDef]) => {
-    // Every virtual field must have a type (for JSON:API serialization)
-    if (!fieldDef.type) {
-      throw new Error(`Virtual field '${fieldName}' in scope '${scopeName}' must have a type`);
-    }
-    
-    // Virtual fields shouldn't have compute functions
-    if (fieldDef.compute) {
-      throw new Error(`Virtual field '${fieldName}' should not have a compute function. Use 'computed' instead.`);
-    }
-  });
-  
-  // Deep clone schema while preserving functions
-  const enrichedSchema = {};
-  for (const [fieldName, fieldDef] of Object.entries(rawSchema)) {
-    enrichedSchema[fieldName] = { ...fieldDef };
-  }
-  
-  // Default enrichment: Add type to belongsTo fields
-  for (const [fieldName, fieldDef] of Object.entries(enrichedSchema)) {
-    if (fieldDef.belongsTo && !fieldDef.type) {
-      fieldDef.type = 'id';
-    }
-  }
-  
-  // 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 belongsToFields = fields.filter(([_, def]) => def.belongsTo);
-  
-  // If 2+ belongsTo fields and they make up 40%+ of non-id fields, likely a pivot table
-  const nonIdFields = fields.filter(([name, _]) => name !== 'id');
-  const isProbablyPivot = belongsToFields.length >= 2 && 
-    (nonIdFields.length === 0 || belongsToFields.length / nonIdFields.length >= 0.4);
-  
-  if (isProbablyPivot) {
-    // Make all belongsTo fields searchable for pivot operations
-    for (const [fieldName, fieldDef] of belongsToFields) {
-      if (!fieldDef.search) {
-        fieldDef.search = true;
-      }
-    }
-  }
-
-
-  // Hook: schema:enrich
-  const schemaContext = {
-    schema: enrichedSchema,    // Mutable
-    originalSchema: rawSchema,  // Read-only
-    scopeName
-  };
-  await runHooks('schema:enrich', schemaContext);
-  
-  // Create schema object
-  const schemaObject = createSchema(schemaContext.schema);
-  
-  // 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.
-  // Example: title: {search: true} auto-generates a searchable field with sensible defaults,
-  // while searchSchema can specify filterUsing: 'contains' or complex join configurations.
-  let rawSearchSchema = scope.scopeOptions.searchSchema ||
-  generateSearchSchemaFromSchema(schemaContext.schema);
-  
-  if (rawSearchSchema) {
-    // 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);
-    
-    // Hook: searchSchema:enrich
-    const searchSchemaContext = {
-      searchSchema: rawSearchSchema,    // Mutable
-      schema: schemaContext.schema,     // Read-only enriched schema
-      scopeName
-    };
-    await runHooks('searchSchema:enrich', searchSchemaContext);
-    
-    // Create searchSchema object
-    var searchSchemaObject = createSchema(searchSchemaContext.searchSchema);
-  } else {
-    var searchSchemaObject = null;
-  }
-
-  // Build schemaRelationships including polymorphic fields from schema
-  const schemaRelationships = { ...(scope.scopeOptions.relationships || {}) };
-  
-  // Extract polymorphic relationships from schema fields and validate belongsTo fields
-  for (const [fieldName, fieldDef] of Object.entries(schemaContext.schema)) {
-    // Validate that belongsTo fields have 'as' property
-    if (fieldDef.belongsTo && !fieldDef.belongsToPolymorphic && !fieldDef.as) {
-      throw new Error(
-        `Field '${fieldName}' in resource '${scopeName}' has belongsTo: '${fieldDef.belongsTo}' but is missing the required 'as' property. ` +
-        `The 'as' property defines the relationship name used in JSON:API payloads. ` +
-        `Example: ${fieldName}: { type: 'number', belongsTo: '${fieldDef.belongsTo}', as: '${fieldName.replace(/_id$/, '')}' }`
-      );
-    }
-    
-    if (fieldDef.belongsToPolymorphic && fieldDef.as) {
-      schemaRelationships[fieldDef.as] = fieldDef;
-    }
-  }
-
-  // Cache everything
-  scope.vars.schemaInfo = {
-    schema: schemaObject,
-    schemaStructure: schemaContext.schema,
-    computed: computed,
-    virtual: virtual,
-    searchSchema: searchSchemaObject,
-    schemaRelationships: schemaRelationships,
-    tableName: scope.scopeOptions.tableName || scopeName,
-    idProperty: scope.scopeOptions.idProperty || scope.vars.idProperty
-  };  
-}

package/plugins/core/lib/database-value-normalizers.js

@@ -1,192 +0,0 @@
-/**
- * Helper functions to normalize values returned from the database.
- * 
- * Handles:
- * - Boolean values: Converts 1/0 to true/false (some databases don't have native boolean support)
- * - Date values: Ensures JavaScript Date objects are properly handled
- *   - date: Already Date objects from Knex, no conversion needed
- *   - dateTime: Already Date objects from Knex, no conversion needed  
- *   - time: Returned as HH:MM:SS strings from the database
- * 
- * Note: With the updated json-rest-schema, dates are stored as Date objects in the database,
- * and Knex returns them as Date objects when fetching. We mainly need to handle edge cases
- * and ensure consistency.
- */
-
-/**
- * Normalizes a date value to a JavaScript Date object.
- * Handles various input formats from different databases and fixes timezone issues.
- * 
- * @param {*} value - The date value from the database (could be Date, string, or number)
- * @param {string} type - The field type ('date', 'dateTime', or 'time')
- * @returns {Date|string|null} Date object for date/dateTime, string for time, or null
- */
-function normalizeDateValue(value, type) {
-  // Handle null/undefined
-  if (value === null || value === undefined) {
-    return null;
-  }
-
-  // Handle time type specially - always return as string
-  if (type === 'time') {
-    // If it's already a properly formatted time string, return as-is
-    if (typeof value === 'string' && /^\d{2}:\d{2}:\d{2}/.test(value)) {
-      return value;
-    }
-    // If we got a Date object for a time field, extract the time portion
-    if (value instanceof Date) {
-      return value.toISOString().slice(11, 19); // Extract HH:MM:SS
-    }
-    // Try to parse and extract time
-    if (typeof value === 'string' || typeof value === 'number') {
-      const d = new Date(value);
-      if (!isNaN(d.getTime())) {
-        return d.toISOString().slice(11, 19);
-      }
-    }
-    return null;
-  }
-
-  // For date and dateTime: Already a Date object? Return as-is
-  if (value instanceof Date) {
-    return value;
-  }
-  
-  // Handle string values
-  if (typeof value === 'string') {
-    // Detect MySQL datetime format: 'YYYY-MM-DD HH:MM:SS'
-    // These have no T separator and no timezone indicator
-    const isMySQLDateTime = type === 'dateTime' && 
-                           /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/.test(value) &&
-                           !value.includes('T') && 
-                           !value.includes('Z') &&
-                           !value.includes('+') &&
-                           !value.includes('-', 10); // Don't match date separators
-    
-    if (isMySQLDateTime) {
-      // Convert to ISO format and force UTC interpretation
-      // '2024-01-15 10:30:00' becomes '2024-01-15T10:30:00Z'
-      return new Date(value.replace(' ', 'T') + 'Z');
-    }
-    
-    // For date-only fields, ensure parsing at UTC midnight
-    // This prevents timezone shifts when parsing dates
-    if (type === 'date' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
-      return new Date(value + 'T00:00:00Z');
-    }
-  }
-  
-  // Handle numeric values (Unix timestamps)
-  if (typeof value === 'number') {
-    return new Date(value);
-  }
-  
-  // Try to parse any other format
-  const dateObj = new Date(value);
-  
-  // Check if date is valid
-  if (isNaN(dateObj.getTime())) {
-    console.warn(`Invalid date value for field type '${type}': ${value}`);
-    return null; // Return null for invalid dates
-  }
-  
-  return dateObj;
-}
-
-/**
- * Normalizes database values in an attributes object.
- * Handles:
- * - Boolean normalization (1/0 to true/false)
- * - Date/dateTime/time normalization to Date objects with proper timezone handling
- * 
- * @param {Object} attributes - The attributes object to normalize
- * @param {Object} schemaStructure - The schema structure defining field types
- * @returns {Object} The normalized attributes object with Date objects for date fields
- */
-export function normalizeAttributes(attributes, schemaStructure) {
-  if (!attributes || !schemaStructure) {
-    return attributes;
-  }
-
-  const normalized = { ...attributes };
-
-  // Iterate through each attribute
-  for (const [fieldName, value] of Object.entries(attributes)) {
-    const fieldDef = schemaStructure[fieldName];
-    
-    // Skip if no field definition found
-    if (!fieldDef) continue;
-
-    // Normalize boolean values
-    if (fieldDef.type === 'boolean') {
-      if (value === 1 || value === '1') {
-        normalized[fieldName] = true;
-      } else if (value === 0 || value === '0') {
-        normalized[fieldName] = false;
-      }
-      // null/undefined remain as-is
-    }
-    
-    // Normalize date/dateTime/time values
-    if (fieldDef.type === 'date' || fieldDef.type === 'dateTime' || fieldDef.type === 'time') {
-      normalized[fieldName] = normalizeDateValue(value, fieldDef.type);
-    }
-  }
-
-  return normalized;
-}
-
-/**
- * Normalizes all records in a JSON:API response.
- * Handles both main data records and included records.
- * 
- * @param {Object} record - The JSON:API record object with data and optional included arrays
- * @param {Object} scopes - All available scopes for looking up schema structures
- * @returns {Object} The record with normalized attribute values
- */
-export function normalizeRecordAttributes(record, scopes) {
-  if (!record || !scopes) {
-    return record;
-  }
-
-  // Normalize main data records
-  if (record.data) {
-    if (Array.isArray(record.data)) {
-      // Handle array of records (query result)
-      for (const entry of record.data) {
-        const scope = scopes[entry.type];
-        if (scope?.vars?.schemaInfo?.schemaStructure && entry.attributes) {
-          entry.attributes = normalizeAttributes(
-            entry.attributes,
-            scope.vars.schemaInfo.schemaStructure
-          );
-        }
-      }
-    } else {
-      // Handle single record (get result)
-      const entry = record.data;
-      const scope = scopes[entry.type];
-      if (scope?.vars?.schemaInfo?.schemaStructure && entry.attributes) {
-        entry.attributes = normalizeAttributes(
-          entry.attributes,
-          scope.vars.schemaInfo.schemaStructure
-        );
-      }
-    }
-  }
-
-  // Normalize included records
-  if (record.included && Array.isArray(record.included)) {
-    for (const entry of record.included) {
-      const scope = scopes[entry.type];
-      if (scope?.vars?.schemaInfo?.schemaStructure && entry.attributes) {
-        entry.attributes = normalizeAttributes(
-          entry.attributes,
-          scope.vars.schemaInfo.schemaStructure
-        );
-      }
-    }
-  }
-
-  return record;
-}

package/plugins/core/lib/default-data-helpers.js

@@ -1,100 +0,0 @@
-/**
- * @module defaultDataHelpers
- * @description Default data helper implementations that throw errors
- * 
- * This module provides default implementations of data helpers that throw
- * errors instructing users to install a storage plugin. These are used
- * when no storage plugin has been installed.
- */
-
-export const createDefaultDataHelpers = (api) => {
-  return {
-    /**
-     * Default implementation of dataExists that throws an error
-     * @param {Object} scope - The scope object
-     * @param {Object} deps - Dependencies object
-     * @param {Object} deps.context - Request context with id, transaction, etc
-     * @throws {Error} Always throws error about missing storage plugin
-     */
-    dataExists: async function(scope, deps) {
-      throw new Error(`No storage implementation for exists. Install a storage plugin.`);
-    },
-
-    /**
-     * Default implementation of dataGet that throws an error
-     * @param {Object} scope - The scope object
-     * @param {Object} deps - Dependencies object
-     * @param {Object} deps.context - Request context with id, queryParams, transaction, etc
-     * @throws {Error} Always throws error about missing storage plugin
-     */
-    dataGet: async function(scope, deps) {
-      throw new Error(`No storage implementation for get. Install a storage plugin.`);
-    },
-
-    /**
-     * Default implementation of dataGetMinimal that throws an error
-     * @param {Object} scope - The scope object
-     * @param {Object} deps - Dependencies object
-     * @param {Object} deps.context - Request context with id, transaction, etc
-     * @throws {Error} Always throws error about missing storage plugin
-     */
-    dataGetMinimal: async function(scope, deps) {
-      throw new Error(`No storage implementation for getMinimal. Install a storage plugin.`);
-    },
-    
-    /**
-     * Default implementation of dataQuery that throws an error
-     * @param {Object} scope - The scope object
-     * @param {Object} deps - Dependencies object
-     * @param {Object} deps.context - Request context with queryParams, transaction, etc
-     * @param {Function} deps.runHooks - Hook runner function
-     * @throws {Error} Always throws error about missing storage plugin
-     */
-    dataQuery: async function(scope, deps) {
-      throw new Error(`No storage implementation for query. Install a storage plugin.`);
-    },
-    
-    /**
-     * Default implementation of dataPost that throws an error
-     * @param {Object} scope - The scope object
-     * @param {Object} deps - Dependencies object
-     * @param {Object} deps.context - Request context with inputRecord, transaction, etc
-     * @throws {Error} Always throws error about missing storage plugin
-     */
-    dataPost: async function(scope, deps) {
-      throw new Error(`No storage implementation for post. Install a storage plugin.`);
-    },
-
-    /**
-     * Default implementation of dataPatch that throws an error
-     * @param {Object} scope - The scope object
-     * @param {Object} deps - Dependencies object
-     * @param {Object} deps.context - Request context with id, inputRecord, queryParams, transaction, etc
-     * @throws {Error} Always throws error about missing storage plugin
-     */
-    dataPatch: async function(scope, deps) {
-      throw new Error(`No storage implementation for patch. Install a storage plugin.`);
-    },
-    /**
-     * Default implementation of dataPut that throws an error
-     * @param {Object} scope - The scope object
-     * @param {Object} deps - Dependencies object
-     * @param {Object} deps.context - Request context with id, inputRecord, isCreate, transaction, etc
-     * @throws {Error} Always throws error about missing storage plugin
-     */
-    dataPut: async function(scope, deps) {
-      throw new Error(`No storage implementation for put. Install a storage plugin.`);
-    },
-    
-    /**
-     * Default implementation of dataDelete that throws an error
-     * @param {Object} scope - The scope object
-     * @param {Object} deps - Dependencies object
-     * @param {Object} deps.context - Request context with id, transaction, etc
-     * @throws {Error} Always throws error about missing storage plugin
-     */
-    dataDelete: async function(scope, deps) {
-      throw new Error(`No storage implementation for delete. Install a storage plugin.`);
-    }
-  };
-};