json-rest-api 1.0.7 → 1.0.8

package/plugins/core/{utils → lib/querying-writing}/connectors-query-parser.js

@@ -1,109 +1,114 @@
 /**
- * @module connectors-query-parser
- * @description Shared JSON:API query parameter parser for connector plugins
- * 
- * This module provides utilities for parsing URL query strings into JSON:API
- * compliant parameter objects. It handles the standard JSON:API query parameter
- * patterns including bracket notation for filters, fields, and pagination.
- * This parser is shared between HTTP, Express, and WebSocket connectors to
- * ensure consistent query parameter handling across all transport layers.
- * 
- * Why this is useful upstream:
- * - Ensures consistent JSON:API query parsing across all connectors
- * - Handles bracket notation parsing (e.g., filter[status]=published)
- * - Converts comma-separated values to arrays for include/sort
- * - Maintains fields as strings for REST API validation
- * - Automatically converts numeric page values
- * - Ignores non-JSON:API parameters safely
- */
-
-/**
- * Parses URL query strings into JSON:API compliant parameter objects.
- * 
- * This function takes a raw query string and converts it into a structured
- * object following JSON:API conventions. It handles all standard JSON:API
- * query parameter patterns including filters with bracket notation, sparse
- * fieldsets, sorting, pagination, and relationship inclusion.
+ * Parses URL query strings into JSON:API compliant parameter objects
  * 
  * @param {string} queryString - The query string part of URL (without ?)
  * @returns {object} Parsed query parameters in JSON:API format
  * 
- * @example <caption>Basic query parsing</caption>
+ * @example
+ * // Input: Basic include and sort
  * const query = parseJsonApiQuery('include=author&sort=-created_at');
- * // Returns:
+ * 
+ * // Output: Parsed into arrays
  * // {
- * //   include: ['author'],
+ * //   include: ['author'],      // Split by comma
  * //   fields: {},
  * //   filters: {},
- * //   sort: ['-created_at'],
+ * //   sort: ['-created_at'],    // Split by comma
  * //   page: {}
  * // }
  * 
- * @example <caption>Filter parameters with bracket notation</caption>
+ * @example
+ * // Input: Filters with bracket notation
  * const query = parseJsonApiQuery('filter[status]=published&filter[author_id]=123');
- * // Returns:
+ * 
+ * // Output: Extracted filter keys
  * // {
  * //   include: [],
  * //   fields: {},
  * //   filters: {
- * //     status: 'published',
- * //     author_id: '123'
+ * //     status: 'published',   // filter[status] → filters.status
+ * //     author_id: '123'       // Values kept as strings
  * //   },
  * //   sort: [],
  * //   page: {}
  * // }
  * 
- * @example <caption>Sparse fieldsets</caption>
+ * @example
+ * // Input: Sparse fieldsets  
  * const query = parseJsonApiQuery('fields[articles]=title,body&fields[users]=name');
- * // Returns:
+ * 
+ * // Output: Fields kept as comma-separated strings
  * // {
  * //   include: [],
  * //   fields: {
- * //     articles: 'title,body',  // Kept as string for validation
- * //     users: 'name'
+ * //     articles: 'title,body',  // NOT split into array
+ * //     users: 'name'            // Validation expects strings
  * //   },
  * //   filters: {},
  * //   sort: [],
  * //   page: {}
  * // }
  * 
- * @example <caption>Pagination parameters</caption>
- * const query = parseJsonApiQuery('page[size]=20&page[number]=3');
- * // Returns:
+ * @example
+ * // Input: Pagination with numeric conversion
+ * const query = parseJsonApiQuery('page[size]=20&page[number]=3&page[cursor]=abc123');
+ * 
+ * // Output: Numbers converted, strings preserved
  * // {
  * //   include: [],
  * //   fields: {},
  * //   filters: {},
  * //   sort: [],
  * //   page: {
- * //     size: 20,     // Converted to number
- * //     number: 3     // Converted to number
+ * //     size: 20,        // "20" → 20 (numeric)
+ * //     number: 3,       // "3" → 3 (numeric)
+ * //     cursor: 'abc123' // Non-numeric stays string
  * //   }
  * // }
  * 
- * @example <caption>Complex query with all parameter types</caption>
+ * @example
+ * // Input: Complex real-world query
  * const query = parseJsonApiQuery(
  *   'include=author,comments.user&' +
  *   'filter[status]=published&' +
- *   'filter[created_after]=2024-01-01&' +
+ *   'filter[created_after]=2024-01-01&' + 
  *   'fields[articles]=title,summary&' +
  *   'sort=-created_at,title&' +
- *   'page[size]=10&page[number]=1'
+ *   'page[size]=10'
  * );
- * // Returns complete parsed structure with all parameters
  * 
- * @example <caption>Empty or invalid input</caption>
- * parseJsonApiQuery('');        // Returns default structure with empty values
- * parseJsonApiQuery(null);      // Returns default structure with empty values
- * parseJsonApiQuery('foo=bar'); // Ignores non-JSON:API parameters
+ * // Output: All parameters properly categorized
+ * // {
+ * //   include: ['author', 'comments.user'],
+ * //   fields: { articles: 'title,summary' },
+ * //   filters: { 
+ * //     status: 'published',
+ * //     created_after: '2024-01-01'
+ * //   },
+ * //   sort: ['-created_at', 'title'],
+ * //   page: { size: 10 }
+ * // }
+ * 
+ * @description
+ * Used by:
+ * - express-plugin parses req.query with this
+ * - http-plugin parses URL query strings with this
+ * - websocket-plugin parses message query parameters with this
+ * 
+ * Purpose:
+ * - Provides uniform JSON:API query parsing across all transports
+ * - Handles bracket notation without regex complexity
+ * - Converts data types appropriately (numbers for pagination)
+ * - Ignores non-JSON:API parameters gracefully
+ * - Returns consistent structure even for empty input
  * 
- * @example <caption>Why this is useful upstream</caption>
- * // Connector plugins use this to:
- * // 1. Convert raw URL queries to structured JSON:API format
- * // 2. Handle bracket notation without custom regex parsing
- * // 3. Ensure consistent behavior across HTTP/Express/WebSocket
- * // 4. Prepare query parameters for REST API validation
- * // 5. Support all JSON:API query features uniformly
+ * Data flow:
+ * 1. Uses URLSearchParams for reliable parsing
+ * 2. Categorizes parameters by their prefix pattern
+ * 3. Extracts bracketed keys (filter[x] → x)
+ * 4. Splits comma-separated values for include/sort
+ * 5. Converts numeric strings for pagination
+ * 6. Returns normalized structure for REST API
  */
 export function parseJsonApiQuery(queryString) {
   if (!queryString) {

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

@@ -1,9 +1,23 @@
 /**
- * Detects database capabilities based on client type and version
- */
-
-/**
- * Parse version string to comparable format
+ * Parses database version string to comparable format
+ * 
+ * @param {string} versionString - Raw version string from database
+ * @returns {Object|null} Parsed version with major, minor, patch
+ * 
+ * @example
+ * // Input: MySQL version
+ * parseVersion("8.0.33");
+ * // Output: { major: 8, minor: 0, patch: 33 }
+ * 
+ * @example
+ * // Input: PostgreSQL version with extra info
+ * parseVersion("14.5 (Ubuntu 14.5-1.pgdg20.04+1)");
+ * // Output: { major: 14, minor: 5, patch: 0 }
+ * 
+ * @example
+ * // Input: MariaDB version
+ * parseVersion("10.6.12-MariaDB");
+ * // Output: { major: 10, minor: 6, patch: 12 }
  */
 const parseVersion = (versionString) => {
   // MySQL: "8.0.33"
@@ -22,7 +36,55 @@ const parseVersion = (versionString) => {
 };
 
 /**
- * Check if database supports window functions
+ * Checks if the database supports window functions based on version
+ * 
+ * @param {Object} knex - Knex instance
+ * @returns {Promise<boolean>} True if window functions are supported
+ * 
+ * @example
+ * // Input: MySQL 8.0.33
+ * const supports = await supportsWindowFunctions(knex);
+ * // Output: true (MySQL 8.0+ supports window functions)
+ * 
+ * @example
+ * // Input: MySQL 5.7.42  
+ * const supports = await supportsWindowFunctions(knex);
+ * // Output: false (MySQL < 8.0 doesn't support window functions)
+ * 
+ * @example
+ * // Input: PostgreSQL (any modern version)
+ * const supports = await supportsWindowFunctions(knex);
+ * // Output: true (PostgreSQL 8.4+ supports window functions)
+ * 
+ * @example
+ * // Input: SQLite 3.24.0
+ * const supports = await supportsWindowFunctions(knex);
+ * // Output: false (SQLite needs 3.25.0+)
+ * 
+ * @description
+ * Used by:
+ * - buildWindowedIncludeQuery to validate before using window functions
+ * - rest-api-knex-plugin to determine query strategies
+ * 
+ * Purpose:
+ * - Prevents runtime errors by checking feature support
+ * - Enables fallback strategies for older databases
+ * - Provides clear error messages about version requirements
+ * 
+ * Data flow:
+ * 1. Identifies database client type from Knex config
+ * 2. For version-dependent databases, queries version string
+ * 3. Parses version and compares against known thresholds
+ * 4. Returns boolean indicating support
+ * 5. Falls back to false if version can't be determined
+ * 
+ * Version requirements:
+ * - PostgreSQL: 8.4+ (all modern versions)
+ * - MySQL: 8.0+
+ * - MariaDB: 10.2+
+ * - SQLite: 3.25.0+
+ * - SQL Server: 2005+ (all versions)
+ * - Oracle: Supported (long-standing feature)
  */
 export const supportsWindowFunctions = async (knex) => {
   try {
@@ -100,7 +162,51 @@ export const supportsWindowFunctions = async (knex) => {
 };
 
 /**
- * Get database info for error messages
+ * Gets database info for error messages and capability checks
+ * 
+ * @param {Object} knex - Knex instance
+ * @returns {Promise<Object>} Database info with client and version
+ * 
+ * @example
+ * // Input: MySQL connection
+ * const info = await getDatabaseInfo(knex);
+ * // Output: { client: 'MySQL', version: '8.0.33' }
+ * 
+ * @example
+ * // Input: PostgreSQL connection
+ * const info = await getDatabaseInfo(knex);
+ * // Output: { 
+ * //   client: 'PostgreSQL', 
+ * //   version: 'PostgreSQL 14.5 (Ubuntu 14.5-1.pgdg20.04+1)'
+ * // }
+ * 
+ * @example
+ * // Input: Connection error case
+ * const info = await getDatabaseInfo(knexWithError);
+ * // Output: { 
+ * //   client: 'MySQL', 
+ * //   version: 'unknown',
+ * //   error: 'Connection refused'
+ * // }
+ * 
+ * @description
+ * Used by:
+ * - Error messages to show which database/version lacks a feature
+ * - Capability detection for feature flags
+ * - Debugging connection issues
+ * 
+ * Purpose:
+ * - Provides human-readable database identification
+ * - Helps users understand version requirements
+ * - Enables detailed error messages
+ * - Gracefully handles query failures
+ * 
+ * Data flow:
+ * 1. Identifies client type from Knex config
+ * 2. Runs version query specific to each database
+ * 3. Returns formatted info object
+ * 4. Includes error details if version query fails
+ * 5. Falls back to 'unknown' for unsupported databases
  */
 export const getDatabaseInfo = async (knex) => {
   try {

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

@@ -0,0 +1,369 @@
+/**
+ * Normalizes a date value to appropriate format based on field type
+ * 
+ * @param {*} value - The date value from the database
+ * @param {string} type - The field type ('date', 'dateTime', or 'time')
+ * @returns {Date|string|null} Date object for date/dateTime, string for time, or null
+ * 
+ * @example
+ * // Input: Already a Date object
+ * normalizeDateValue(new Date('2024-01-15T10:30:00Z'), 'dateTime');
+ * // Output: Date object (unchanged)
+ * 
+ * @example
+ * // Input: MySQL datetime string without timezone
+ * normalizeDateValue('2024-01-15 10:30:00', 'dateTime');
+ * // Output: Date object parsed as UTC (2024-01-15T10:30:00Z)
+ * 
+ * @example
+ * // Input: Date-only string
+ * normalizeDateValue('2024-01-15', 'date');
+ * // Output: Date object at UTC midnight (2024-01-15T00:00:00Z)
+ * 
+ * @example
+ * // Input: Time field (always returns string)
+ * normalizeDateValue('14:30:45', 'time');
+ * // Output: "14:30:45" (string)
+ * 
+ * @example
+ * // Input: Date object for time field
+ * normalizeDateValue(new Date('2024-01-15T14:30:45Z'), 'time');
+ * // Output: "14:30:45" (extracts time portion)
+ * 
+ * @description
+ * Used by:
+ * - normalizeAttributes to process individual field values
+ * - Applied to all date/time fields fetched from database
+ * 
+ * Purpose:
+ * - Handles database-specific date formats (especially MySQL)
+ * - Prevents timezone shifts for date-only fields
+ * - Ensures consistent Date objects across databases
+ * - Keeps time fields as HH:MM:SS strings
+ * 
+ * Data flow:
+ * 1. Checks for null/undefined (returns null)
+ * 2. For time fields: ensures HH:MM:SS string format
+ * 3. For date/dateTime: converts to Date objects
+ * 4. Handles MySQL datetime format (no T separator)
+ * 5. Forces UTC interpretation to prevent timezone issues
+ */
+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
+ * 
+ * @param {Object} attributes - The attributes object to normalize
+ * @param {Object} schemaStructure - The schema structure defining field types
+ * @returns {Object} The normalized attributes object
+ * 
+ * @example
+ * // Input: Raw database values
+ * const attributes = {
+ *   id: 1,
+ *   is_active: 1,              // Boolean as 0/1
+ *   created_at: '2024-01-15 10:30:00',  // MySQL datetime
+ *   birth_date: '1990-05-20',           // Date string
+ *   shift_time: '09:00:00'              // Time string
+ * };
+ * 
+ * const schema = {
+ *   is_active: { type: 'boolean' },
+ *   created_at: { type: 'dateTime' },
+ *   birth_date: { type: 'date' },
+ *   shift_time: { type: 'time' }
+ * };
+ * 
+ * const normalized = normalizeAttributes(attributes, schema);
+ * 
+ * // Output: Properly typed values
+ * // {
+ * //   id: 1,
+ * //   is_active: true,                    // 1 → true
+ * //   created_at: Date('2024-01-15T10:30:00Z'),  // Date object
+ * //   birth_date: Date('1990-05-20T00:00:00Z'),  // Date at midnight UTC
+ * //   shift_time: '09:00:00'                     // String unchanged
+ * // }
+ * 
+ * @example
+ * // Input: Boolean edge cases
+ * const attributes = {
+ *   flag1: 0,      // Number 0
+ *   flag2: '1',    // String '1'
+ *   flag3: true,   // Already boolean
+ *   flag4: null    // Null value
+ * };
+ * 
+ * const normalized = normalizeAttributes(attributes, {
+ *   flag1: { type: 'boolean' },
+ *   flag2: { type: 'boolean' },
+ *   flag3: { type: 'boolean' },
+ *   flag4: { type: 'boolean' }
+ * });
+ * 
+ * // Output:
+ * // {
+ * //   flag1: false,  // 0 → false
+ * //   flag2: true,   // '1' → true
+ * //   flag3: true,   // unchanged
+ * //   flag4: null    // null preserved
+ * // }
+ * 
+ * @description
+ * Used by:
+ * - normalizeRecordAttributes for each record's attributes
+ * - Applied after fetching data from database
+ * 
+ * Purpose:
+ * - Handles databases without native boolean support (SQLite, older MySQL)
+ * - Normalizes date formats from different databases
+ * - Ensures consistent data types in API responses
+ * - Preserves null values appropriately
+ * 
+ * Data flow:
+ * 1. Creates copy of attributes to avoid mutation
+ * 2. Iterates through each field with schema definition
+ * 3. Normalizes booleans: 1/0 or '1'/'0' to true/false
+ * 4. Normalizes dates using normalizeDateValue
+ * 5. Returns new object with normalized values
+ */
+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
+ * 
+ * @param {Object} record - The JSON:API response object
+ * @param {Object} scopes - All available scopes for schema lookup
+ * @returns {Object} The response with normalized values
+ * 
+ * @example
+ * // Input: JSON:API response with various data types
+ * const response = {
+ *   data: {
+ *     type: 'articles',
+ *     id: '1',
+ *     attributes: {
+ *       title: 'My Article',
+ *       is_published: 1,                    // Boolean as number
+ *       published_at: '2024-01-15 10:00:00' // MySQL datetime
+ *     }
+ *   },
+ *   included: [{
+ *     type: 'users',
+ *     id: '10',
+ *     attributes: {
+ *       name: 'John',
+ *       is_admin: 0,         // Boolean as number
+ *       last_login: '2024-01-14 15:30:00'
+ *     }
+ *   }]
+ * };
+ * 
+ * const normalized = normalizeRecordAttributes(response, scopes);
+ * 
+ * // Output: All booleans and dates normalized
+ * // {
+ * //   data: {
+ * //     type: 'articles',
+ * //     id: '1',
+ * //     attributes: {
+ * //       title: 'My Article',
+ * //       is_published: true,                        // 1 → true
+ * //       published_at: Date('2024-01-15T10:00:00Z') // Date object
+ * //     }
+ * //   },
+ * //   included: [{
+ * //     type: 'users',
+ * //     id: '10',
+ * //     attributes: {
+ * //       name: 'John',
+ * //       is_admin: false,                          // 0 → false
+ * //       last_login: Date('2024-01-14T15:30:00Z')  // Date object
+ * //     }
+ * //   }]
+ * // }
+ * 
+ * @example
+ * // Input: Collection response (array of records)
+ * const response = {
+ *   data: [
+ *     {
+ *       type: 'comments',
+ *       id: '1',
+ *       attributes: { approved: 1, created_at: '2024-01-01 09:00:00' }
+ *     },
+ *     {
+ *       type: 'comments',
+ *       id: '2',
+ *       attributes: { approved: 0, created_at: '2024-01-02 10:00:00' }
+ *     }
+ *   ]
+ * };
+ * 
+ * // Each record in the array is normalized
+ * 
+ * @description
+ * Used by:
+ * - rest-api-knex-plugin after fetching data, before sending response
+ * - Applied to both GET (single) and QUERY (collection) responses
+ * 
+ * Purpose:
+ * - Ensures consistent data types in API responses
+ * - Handles both primary data and included resources
+ * - Works with single records and collections
+ * - Uses schema definitions to determine field types
+ * 
+ * Data flow:
+ * 1. Checks if data is array (collection) or object (single)
+ * 2. For each record, looks up its schema by type
+ * 3. Calls normalizeAttributes with schema structure
+ * 4. Processes included array the same way
+ * 5. Returns complete response with normalized 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;
+}