json-rest-api 1.0.13 → 1.0.15

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

@@ -1,46 +1,46 @@
 /**
  * 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
@@ -48,85 +48,85 @@
  * 4. Handles MySQL datetime format (no T separator)
  * 5. Forces UTC interpretation to prevent timezone issues
  */
-function normalizeDateValue(value, type) {
+function normalizeDateValue (value, type) {
   // Handle null/undefined
   if (value === null || value === undefined) {
-    return null;
+    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;
+      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
+      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);
+      const d = new Date(value)
       if (!isNaN(d.getTime())) {
-        return d.toISOString().slice(11, 19);
+        return d.toISOString().slice(11, 19)
       }
     }
-    return null;
+    return null
   }
 
   // For date and dateTime: Already a Date object? Return as-is
   if (value instanceof Date) {
-    return value;
+    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' && 
+    const isMySQLDateTime = type === 'dateTime' &&
                            /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}/.test(value) &&
-                           !value.includes('T') && 
+                           !value.includes('T') &&
                            !value.includes('Z') &&
                            !value.includes('+') &&
-                           !value.includes('-', 10); // Don't match date separators
-    
+                           !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');
+      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');
+      return new Date(value + 'T00:00:00Z')
     }
   }
-  
+
   // Handle numeric values (Unix timestamps)
   if (typeof value === 'number') {
-    return new Date(value);
+    return new Date(value)
   }
-  
+
   // Try to parse any other format
-  const dateObj = new Date(value);
-  
+  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
+    console.warn(`Invalid date value for field type '${type}': ${value}`)
+    return null // Return null for invalid dates
   }
-  
-  return dateObj;
+
+  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 = {
@@ -136,16 +136,16 @@ function normalizeDateValue(value, type) {
  *   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,
@@ -154,7 +154,7 @@ function normalizeDateValue(value, type) {
  * //   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 = {
@@ -163,14 +163,14 @@ function normalizeDateValue(value, type) {
  *   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
@@ -178,18 +178,18 @@ function normalizeDateValue(value, type) {
  * //   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
@@ -197,46 +197,46 @@ function normalizeDateValue(value, type) {
  * 4. Normalizes dates using normalizeDateValue
  * 5. Returns new object with normalized values
  */
-export function normalizeAttributes(attributes, schemaStructure) {
+export function normalizeAttributes (attributes, schemaStructure) {
   if (!attributes || !schemaStructure) {
-    return attributes;
+    return attributes
   }
 
-  const normalized = { ...attributes };
+  const normalized = { ...attributes }
 
   // Iterate through each attribute
   for (const [fieldName, value] of Object.entries(attributes)) {
-    const fieldDef = schemaStructure[fieldName];
-    
+    const fieldDef = schemaStructure[fieldName]
+
     // Skip if no field definition found
-    if (!fieldDef) continue;
+    if (!fieldDef) continue
 
     // Normalize boolean values
     if (fieldDef.type === 'boolean') {
       if (value === 1 || value === '1') {
-        normalized[fieldName] = true;
+        normalized[fieldName] = true
       } else if (value === 0 || value === '0') {
-        normalized[fieldName] = false;
+        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);
+      normalized[fieldName] = normalizeDateValue(value, fieldDef.type)
     }
   }
 
-  return normalized;
+  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 = {
@@ -259,9 +259,9 @@ export function normalizeAttributes(attributes, schemaStructure) {
  *     }
  *   }]
  * };
- * 
+ *
  * const normalized = normalizeRecordAttributes(response, scopes);
- * 
+ *
  * // Output: All booleans and dates normalized
  * // {
  * //   data: {
@@ -283,7 +283,7 @@ export function normalizeAttributes(attributes, schemaStructure) {
  * //     }
  * //   }]
  * // }
- * 
+ *
  * @example
  * // Input: Collection response (array of records)
  * const response = {
@@ -300,20 +300,20 @@ export function normalizeAttributes(attributes, schemaStructure) {
  *     }
  *   ]
  * };
- * 
+ *
  * // 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
@@ -321,9 +321,9 @@ export function normalizeAttributes(attributes, schemaStructure) {
  * 4. Processes included array the same way
  * 5. Returns complete response with normalized values
  */
-export function normalizeRecordAttributes(record, scopes) {
+export function normalizeRecordAttributes (record, scopes) {
   if (!record || !scopes) {
-    return record;
+    return record
   }
 
   // Normalize main data records
@@ -331,23 +331,23 @@ export function normalizeRecordAttributes(record, scopes) {
     if (Array.isArray(record.data)) {
       // Handle array of records (query result)
       for (const entry of record.data) {
-        const scope = scopes[entry.type];
+        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];
+      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
-        );
+        )
       }
     }
   }
@@ -355,15 +355,15 @@ export function normalizeRecordAttributes(record, scopes) {
   // Normalize included records
   if (record.included && Array.isArray(record.included)) {
     for (const entry of record.included) {
-      const scope = scopes[entry.type];
+      const scope = scopes[entry.type]
       if (scope?.vars?.schemaInfo?.schemaStructure && entry.attributes) {
         entry.attributes = normalizeAttributes(
           entry.attributes,
           scope.vars.schemaInfo.schemaStructure
-        );
+        )
       }
     }
   }
 
-  return record;
-}
+  return record
+}

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

@@ -1,11 +1,11 @@
 /**
  * Default data helper implementations that instruct users to install a storage plugin
- * 
+ *
  * @description
  * These default implementations ensure the REST API plugin fails gracefully
  * when no storage plugin is installed. Each method throws a descriptive error
  * guiding users to install a storage implementation.
- * 
+ *
  * @example
  * // When no storage plugin is installed:
  * try {
@@ -14,23 +14,23 @@
  *   console.log(error.message);
  *   // "No storage implementation for get. Install a storage plugin."
  * }
- * 
+ *
  * @example
  * // After installing rest-api-knex-plugin:
  * api.use(RestApiKnexPlugin, { knex });
  * // Now data helpers are replaced with actual implementations
  * const article = await api.resources.articles.get({ id: 1 });
  * // Works! Returns article from database
- * 
+ *
  * Used by:
  * - rest-api-plugin sets these as initial data helpers
  * - Storage plugins replace these with actual implementations
- * 
+ *
  * Purpose:
  * - Provides clear error messages when storage is missing
  * - Ensures REST API plugin can be installed independently
  * - Allows storage plugins to be swapped without changing API
- * 
+ *
  * Data flow:
  * 1. REST API plugin initializes with these defaults
  * 2. User tries to use API without storage plugin
@@ -38,35 +38,35 @@
  * 4. Storage plugin replaces these with real implementations
  */
 export const defaultDataHelpers = {
-  dataExists: async function(scope, deps) {
-    throw new Error(`No storage implementation for exists. Install a storage plugin.`);
+  dataExists: async function (scope, deps) {
+    throw new Error('No storage implementation for exists. Install a storage plugin.')
   },
 
-  dataGet: async function(scope, deps) {
-    throw new Error(`No storage implementation for get. Install a storage plugin.`);
+  dataGet: async function (scope, deps) {
+    throw new Error('No storage implementation for get. Install a storage plugin.')
   },
 
-  dataGetMinimal: async function(scope, deps) {
-    throw new Error(`No storage implementation for getMinimal. Install a storage plugin.`);
+  dataGetMinimal: async function (scope, deps) {
+    throw new Error('No storage implementation for getMinimal. Install a storage plugin.')
   },
-  
-  dataQuery: async function(scope, deps) {
-    throw new Error(`No storage implementation for query. Install a storage plugin.`);
+
+  dataQuery: async function (scope, deps) {
+    throw new Error('No storage implementation for query. Install a storage plugin.')
   },
-  
-  dataPost: async function(scope, deps) {
-    throw new Error(`No storage implementation for post. Install a storage plugin.`);
+
+  dataPost: async function (scope, deps) {
+    throw new Error('No storage implementation for post. Install a storage plugin.')
   },
 
-  dataPatch: async function(scope, deps) {
-    throw new Error(`No storage implementation for patch. Install a storage plugin.`);
+  dataPatch: async function (scope, deps) {
+    throw new Error('No storage implementation for patch. Install a storage plugin.')
   },
-  
-  dataPut: async function(scope, deps) {
-    throw new Error(`No storage implementation for put. Install a storage plugin.`);
+
+  dataPut: async function (scope, deps) {
+    throw new Error('No storage implementation for put. Install a storage plugin.')
   },
-  
-  dataDelete: async function(scope, deps) {
-    throw new Error(`No storage implementation for delete. Install a storage plugin.`);
+
+  dataDelete: async function (scope, deps) {
+    throw new Error('No storage implementation for delete. Install a storage plugin.')
   }
-};
+}

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

@@ -1,9 +1,9 @@
 /**
  * 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 = {
@@ -13,12 +13,12 @@
  *   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 = {
@@ -27,24 +27,24 @@
  *     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
@@ -52,32 +52,32 @@
  * 4. Returns Set for efficient lookups
  */
 export const getForeignKeyFields = (schema) => {
-  const foreignKeys = new Set();
-  if (!schema) return foreignKeys;
-  
+  const foreignKeys = new Set()
+  if (!schema) return foreignKeys
+
   // Handle both Schema objects and plain objects
-  const schemaStructure = schema.structure || schema;
-  
+  const schemaStructure = schema.structure || schema
+
   Object.entries(schemaStructure).forEach(([field, def]) => {
     if (def.belongsTo) {
-      foreignKeys.add(field);
+      foreignKeys.add(field)
     }
-  });
-  return foreignKeys;
-};
+  })
+  return foreignKeys
+}
 
 /**
  * Filters hidden fields from attributes based on schema rules.
- * 
+ *
  * This pure function removes fields marked as hidden or normallyHidden
  * 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',
@@ -96,7 +96,7 @@ export const getForeignKeyFields = (schema) => {
  * 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' }
@@ -104,34 +104,36 @@ export const getForeignKeyFields = (schema) => {
  * // password_hash is still filtered (always hidden)
  */
 export const filterHiddenFields = (attributes, schema, requestedFields) => {
-  const filtered = {};
-  
+  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 = requestedFields
+    ? (
+        typeof requestedFields === 'string'
+          ? requestedFields.split(',').map(f => f.trim()).filter(f => f)
+          : requestedFields
+      )
+    : null
+
   Object.entries(attributes).forEach(([field, value]) => {
-    const fieldDef = schema.structure?.[field];
-    
+    const fieldDef = schema.structure?.[field]
+
     // Never include hidden fields - these are completely invisible
     // Example: password_hash with hidden:true is always filtered out
-    if (fieldDef?.hidden === true) return;
-    
+    if (fieldDef?.hidden === true) return
+
     // Include normallyHidden fields only if explicitly requested
     // Example: 'cost' with normallyHidden:true is only included if user requests it
     // via sparse fieldsets like ?fields[products]=name,cost
     if (fieldDef?.normallyHidden === true) {
       if (!requested || !requested.includes(field)) {
-        return; // Filter out normallyHidden field
+        return // Filter out normallyHidden field
       }
     }
-    
-    filtered[field] = value;
-  });
-  
-  return filtered;
-};
+
+    filtered[field] = value
+  })
+
+  return filtered
+}