millas 0.2.20 → 0.2.23

package/src/orm/query/LookupParser.js

@@ -5,75 +5,51 @@
  *
  * Parses Django-style __ field lookups and applies them to a knex query.
  *
- * Supported lookup types:
+ * Supports unlimited depth traversal — each __ segment is either:
+ *   - A relation name  → auto-JOIN (BelongsTo) or EXISTS subquery (HasMany/M2M)
+ *   - A lookup suffix  → terminal condition (exact, icontains, gte, etc.)
  *
- *   Comparison
- *     field__exact        =    (default, same as no suffix)
- *     field__not          !=
- *     field__gt           >
- *     field__gte          >=
- *     field__lt           <
- *     field__lte          <=
- *
- *   Null checks
- *     field__isnull       IS NULL  (value: true) / IS NOT NULL (value: false)
- *
- *   Range / set
- *     field__in           IN (array)
- *     field__notin        NOT IN (array)
- *     field__between      BETWEEN [min, max]
- *
- *   String matching
- *     field__contains     LIKE %value%       (case-sensitive)
- *     field__icontains    ILIKE %value%      (case-insensitive)
- *     field__startswith   LIKE value%
- *     field__istartswith  ILIKE value%
- *     field__endswith     LIKE %value
- *     field__iendswith    ILIKE %value
- *     field__like         LIKE <raw pattern>  (you supply the %)
- *
- *   Date / time extraction  (SQLite: strftime, PG/MySQL: EXTRACT / DATE_FORMAT)
- *     field__year
- *     field__month
- *     field__day
- *     field__hour
- *     field__minute
- *     field__second
- *
- *   Relationship traversal  (requires Model.fields with references)
- *     profile__city__icontains  → joins profiles, filters on city
- *
- * Usage (internal — called by QueryBuilder):
- *   LookupParser.apply(knexQuery, 'age__gte', 18, ModelClass)
- *   LookupParser.apply(knexQuery, 'profile__city', 'Nairobi', ModelClass)
+ * Examples:
+ *   'age__gte'                          → WHERE age >= 18
+ *   'author__name'                      → JOIN users, WHERE users.name = ?
+ *   'author__profile__city__icontains'  → JOIN users JOIN profiles, WHERE LOWER(city) LIKE ?
+ *   'unit_categories__unit_type__in'    → WHERE EXISTS (SELECT 1 FROM unit_categories WHERE ...)
+ *   'tags__name__icontains'             → WHERE EXISTS (SELECT 1 FROM pivot JOIN tags WHERE ...)
+ *   'pk'                                → WHERE id = ?  (pk shorthand)
  */
 class LookupParser {
 
-  /**
-   * All recognised lookup suffixes, in order from longest to shortest so
-   * that e.g. "icontains" is matched before a hypothetical "contains" variant.
-   */
   static LOOKUPS = [
-    'icontains', 'istartswith', 'iendswith',
-    'contains', 'startswith', 'endswith', 'like',
-    'isnull', 'between', 'notin', 'in',
+    'icontains', 'istartswith', 'iendswith', 'iexact',
+    'contains', 'startswith', 'endswith', 'ilike', 'like',
+    'iregex', 'regex',
+    'isnull', 'between', 'range', 'notin', 'in',
     'exact', 'not',
     'gte', 'lte', 'gt', 'lt',
     'year', 'month', 'day', 'hour', 'minute', 'second',
+    'date', 'time', 'week', 'week_day', 'quarter',
   ];
 
   /**
    * Parse a lookup key and apply the appropriate knex constraint.
    *
    * @param {object}  q          — knex query builder (mutated in place)
-   * @param {string}  key        — e.g. "age__gte", "profile__city__icontains"
+   * @param {string}  key        — e.g. 'age__gte', 'author__profile__city__icontains'
    * @param {*}       value      — the comparison value
-   * @param {class}   ModelClass — the root Model class (for relationship traversal)
+   * @param {class}   ModelClass — the root Model class
    * @param {string}  [method]   — 'where' | 'orWhere' (default: 'where')
-   * @returns {object} the (mutated) knex query
    */
   static apply(q, key, value, ModelClass, method = 'where') {
-    // No __ at all → plain equality, pass straight through
+    // pk shorthand — resolve to actual primary key
+    if (key === 'pk' || key === 'pk__exact') {
+      q[method](ModelClass.primaryKey || 'id', value);
+      return q;
+    }
+    if (key.startsWith('pk__')) {
+      key = (ModelClass.primaryKey || 'id') + '__' + key.slice(4);
+    }
+
+    // No __ at all → plain equality
     if (!key.includes('__')) {
       q[method](key, value);
       return q;
@@ -81,16 +57,208 @@ class LookupParser {
 
     const parts  = key.split('__');
     const lookup = this._extractLookup(parts);
-    // Everything left after stripping the lookup is the field path
     const fieldPath = lookup ? parts.slice(0, -1) : parts;
 
-    // Relationship traversal: more than one segment in the field path
-    if (fieldPath.length > 1) {
-      return this._applyRelational(q, fieldPath, lookup, value, ModelClass, method);
+    // Single field, no relation traversal
+    if (fieldPath.length === 1) {
+      return this._applyLookup(q, fieldPath[0], lookup || 'exact', value, method);
     }
 
-    const column = fieldPath[0];
-    return this._applyLookup(q, column, lookup || 'exact', value, method);
+    // Multi-segment — walk the relation chain
+    return this._applyDeep(q, fieldPath, lookup || 'exact', value, ModelClass, method);
+  }
+
+  // ─── Deep relation traversal ──────────────────────────────────────────────
+
+  /**
+   * Walk a multi-segment field path, resolving each segment as either:
+   *   - A relation → JOIN (BelongsTo/HasOne) or EXISTS subquery (HasMany/M2M)
+   *   - A plain column → apply the lookup
+   *
+   * Matches Django's names_to_path() + setup_joins() behaviour.
+   */
+  static _applyDeep(q, fieldPath, lookup, value, ModelClass, method) {
+    let currentModel = ModelClass;
+    const joinedTables = new Set(); // track already-joined tables to avoid duplicates
+
+    for (let i = 0; i < fieldPath.length; i++) {
+      const segment   = fieldPath[i];
+      const isLast    = i === fieldPath.length - 1;
+      const relations = currentModel._effectiveRelations
+        ? currentModel._effectiveRelations()
+        : (currentModel.relations || {});
+
+      const rel = relations[segment];
+
+      if (!rel) {
+        // Not a relation — treat as a column on the current model
+        const column = currentModel.table
+          ? `${currentModel.table}.${segment}`
+          : segment;
+        return this._applyLookup(q, column, lookup, value, method);
+      }
+
+      const BelongsTo     = require('../relations/BelongsTo');
+      const HasOne        = require('../relations/HasOne');
+      const HasMany       = require('../relations/HasMany');
+      const BelongsToMany = require('../relations/BelongsToMany');
+
+      if (rel instanceof BelongsTo || rel instanceof HasOne) {
+        // Forward FK or HasOne — safe to JOIN
+        const RelatedModel = rel._related;
+        if (!RelatedModel) {
+          // Can't resolve — fall back to flat column
+          return this._applyLookup(q, segment, lookup, value, method);
+        }
+
+        if (rel instanceof BelongsTo) {
+          // FK is on current table: current.fk_col = related.pk
+          const fkCol    = rel._foreignKey;
+          const ownerKey = rel._ownerKey || 'id';
+          const joinKey  = `${currentModel.table}__${RelatedModel.table}`;
+
+          if (!joinedTables.has(joinKey)) {
+            q = q.join(
+              RelatedModel.table,
+              `${currentModel.table}.${fkCol}`,
+              '=',
+              `${RelatedModel.table}.${ownerKey}`
+            );
+            joinedTables.add(joinKey);
+          }
+        } else {
+          // HasOne — FK is on related table: related.fk_col = current.pk
+          const fkCol   = rel._foreignKey;
+          const localKey = rel._localKey || 'id';
+          const joinKey  = `${currentModel.table}__${RelatedModel.table}`;
+
+          if (!joinedTables.has(joinKey)) {
+            q = q.join(
+              RelatedModel.table,
+              `${RelatedModel.table}.${fkCol}`,
+              '=',
+              `${currentModel.table}.${localKey}`
+            );
+            joinedTables.add(joinKey);
+          }
+        }
+
+        if (isLast) {
+          // Last segment is the relation itself — compare its PK
+          const RelatedModel = rel._related;
+          const pkCol = `${RelatedModel.table}.${RelatedModel.primaryKey || 'id'}`;
+          return this._applyLookup(q, pkCol, lookup, value, method);
+        }
+
+        currentModel = rel._related;
+
+      } else if (rel instanceof HasMany || rel instanceof BelongsToMany) {
+        // Reverse relation — use EXISTS subquery to avoid row multiplication
+        // This matches Django's split_exclude / subquery strategy for N-to-many
+        const remainingPath = fieldPath.slice(i + 1);
+        const remainingLookup = lookup;
+
+        return this._applyExistsSubquery(
+          q, rel, remainingPath, remainingLookup, value, currentModel, method,
+          rel instanceof BelongsToMany
+        );
+      }
+    }
+
+    // Reached end of path without hitting a terminal — shouldn't happen
+    return q;
+  }
+
+  /**
+   * Apply an EXISTS subquery for HasMany and BelongsToMany relations.
+   *
+   * Generates:
+   *   WHERE EXISTS (
+   *     SELECT 1 FROM related_table
+   *     WHERE related_table.fk = current_table.pk
+   *     AND related_table.column [lookup] value
+   *   )
+   *
+   * For M2M:
+   *   WHERE EXISTS (
+   *     SELECT 1 FROM pivot_table
+   *     JOIN related_table ON pivot.related_fk = related.pk
+   *     WHERE pivot.owner_fk = current.pk
+   *     AND related_table.column [lookup] value
+   *   )
+   */
+  static _applyExistsSubquery(q, rel, remainingPath, lookup, value, ownerModel, method, isM2M) {
+    const HasMany       = require('../relations/HasMany');
+    const BelongsToMany = require('../relations/BelongsToMany');
+    const DatabaseManager = require('../drivers/DatabaseManager');
+
+    const db = DatabaseManager.connection(ownerModel.connection || null);
+
+    if (isM2M) {
+      const RelatedModel    = rel._related;
+      const pivotTable      = rel._pivotTable;
+      const foreignPivotKey = rel._foreignPivotKey;
+      const relatedPivotKey = rel._relatedPivotKey;
+      const localKey        = rel._localKey || 'id';
+      const relatedKey      = rel._relatedKey || 'id';
+
+      q[method](function () {
+        let sub = db(pivotTable)
+          .select(db.raw('1'))
+          .join(
+            RelatedModel.table,
+            `${RelatedModel.table}.${relatedKey}`,
+            '=',
+            `${pivotTable}.${relatedPivotKey}`
+          )
+          .whereRaw(
+            `${pivotTable}.${foreignPivotKey} = ${ownerModel.table}.${localKey}`
+          );
+
+        if (remainingPath.length > 0) {
+          const colName = `${RelatedModel.table}.${remainingPath.join('__')}`;
+          LookupParser._applyLookup(sub, colName, lookup, value, 'where');
+        }
+
+        this.whereExists(sub);
+      });
+
+    } else {
+      // HasMany
+      const RelatedModel = rel._related;
+      const foreignKey   = rel._foreignKey;
+      const localKey     = rel._localKey || 'id';
+
+      q[method](function () {
+        let sub = db(RelatedModel.table)
+          .select(db.raw('1'))
+          .whereRaw(
+            `${RelatedModel.table}.${foreignKey} = ${ownerModel.table}.${localKey}`
+          );
+
+        if (remainingPath.length > 0) {
+          // Remaining path could be a simple column or another deep lookup
+          // Qualify the column with the table name to avoid ambiguity
+          const remainingKey = remainingPath.join('__');
+          // If it's a simple column (no further relation hops), qualify it
+          const firstSegment = remainingPath[0];
+          const relRelations = RelatedModel._effectiveRelations
+            ? RelatedModel._effectiveRelations()
+            : (RelatedModel.relations || {});
+          const isRelation = !!relRelations[firstSegment];
+          if (!isRelation && remainingPath.length === 1) {
+            // Simple column — qualify with table name
+            LookupParser._applyLookup(sub, `${RelatedModel.table}.${firstSegment}`, lookup, value, 'where');
+          } else {
+            LookupParser.apply(sub, remainingKey, value, RelatedModel, 'where');
+          }
+        }
+
+        this.whereExists(sub);
+      });
+    }
+
+    return q;
   }
 
   // ─── Lookup application ───────────────────────────────────────────────────
@@ -101,6 +269,10 @@ class LookupParser {
         q[method](column, value);
         break;
 
+      case 'iexact':
+        this._applyILike(q, column, value, method);
+        break;
+
       case 'not':
         q[method](column, '!=', value);
         break;
@@ -122,8 +294,13 @@ class LookupParser {
         break;
 
       case 'isnull':
-        if (value) q[`${method}Null`]   ? q[`${method}Null`](column)   : q.whereNull(column);
-        else       q[`${method}NotNull`] ? q[`${method}NotNull`](column) : q.whereNotNull(column);
+        if (value) {
+          if (typeof q.whereNull === 'function') q.whereNull(column);
+          else q[method](column, null);
+        } else {
+          if (typeof q.whereNotNull === 'function') q.whereNotNull(column);
+          else q[method](column, '!=', null);
+        }
         break;
 
       case 'in':
@@ -135,6 +312,7 @@ class LookupParser {
         break;
 
       case 'between':
+      case 'range':
         q[`${method}Between`]
           ? q[`${method}Between`](column, value)
           : q.whereBetween(column, value);
@@ -145,7 +323,7 @@ class LookupParser {
         break;
 
       case 'icontains':
-        q[method](column, 'ilike', `%${value}%`);
+        this._applyILike(q, column, `%${value}%`, method);
         break;
 
       case 'startswith':
@@ -153,7 +331,7 @@ class LookupParser {
         break;
 
       case 'istartswith':
-        q[method](column, 'ilike', `${value}%`);
+        this._applyILike(q, column, `${value}%`, method);
         break;
 
       case 'endswith':
@@ -161,144 +339,125 @@ class LookupParser {
         break;
 
       case 'iendswith':
-        q[method](column, 'ilike', `%${value}`);
+        this._applyILike(q, column, `%${value}`, method);
         break;
 
       case 'like':
         q[method](column, 'like', value);
         break;
 
-      // ── Date/time extractions ──────────────────────────────────────────
+      case 'ilike':
+        this._applyILike(q, column, value, method);
+        break;
+
+      case 'regex':
+        this._applyRegex(q, column, value, method, false);
+        break;
+
+      case 'iregex':
+        this._applyRegex(q, column, value, method, true);
+        break;
+
       case 'year':
       case 'month':
       case 'day':
       case 'hour':
       case 'minute':
       case 'second':
+      case 'date':
+      case 'time':
+      case 'week':
+      case 'week_day':
+      case 'quarter':
         this._applyDatePart(q, column, lookup, value, method);
         break;
 
       default:
-        // Unrecognised suffix — treat whole key as column name, do equality
         q[method](column, value);
     }
 
     return q;
   }
 
-  // ─── Date part extraction — dialect-aware ─────────────────────────────────
+  // ─── Dialect-aware helpers ────────────────────────────────────────────────
+
+  static _applyILike(q, column, pattern, method) {
+    const client = q.client?.config?.client || 'sqlite3';
+    if (client.includes('pg') || client.includes('postgres')) {
+      q[method](column, 'ilike', pattern);
+    } else {
+      // SQLite / MySQL: LOWER() both sides for Unicode safety
+      const col = column.includes('.') ? column : `\`${column}\``;
+      q[method](q.client.raw(`LOWER(${col})`), 'like', pattern.toLowerCase());
+    }
+  }
+
+  static _applyRegex(q, column, pattern, method, caseInsensitive) {
+    const client = q.client?.config?.client || 'sqlite3';
+    if (client.includes('pg') || client.includes('postgres')) {
+      const op = caseInsensitive ? '~*' : '~';
+      q[method](q.client.raw(`"${column}" ${op} ?`, [pattern]));
+    } else if (client.includes('mysql') || client.includes('maria')) {
+      const op = caseInsensitive ? 'REGEXP' : 'REGEXP BINARY';
+      q[method](q.client.raw(`\`${column}\` ${op} ?`, [pattern]));
+    } else {
+      console.warn(`[Millas] regex lookup is not supported on SQLite. Falling back to LIKE.`);
+      q[method](column, 'like', `%${pattern}%`);
+    }
+  }
 
   static _applyDatePart(q, column, part, value, method) {
     const client = q.client?.config?.client || 'sqlite3';
 
     if (client.includes('pg') || client.includes('postgres')) {
-      // PostgreSQL: EXTRACT(YEAR FROM column) = value
-      const pgPart = part.toUpperCase();
-      q[method](q.client.raw(`EXTRACT(${pgPart} FROM "${column}")`, []), value);
+      const pgMap = {
+        year: 'YEAR', month: 'MONTH', day: 'DAY',
+        hour: 'HOUR', minute: 'MINUTE', second: 'SECOND',
+        week: 'WEEK', quarter: 'QUARTER',
+        date: 'DATE', time: 'TIME', week_day: 'DOW',
+      };
+      const pgPart = pgMap[part] || part.toUpperCase();
+      if (part === 'date') {
+        q[method](q.client.raw(`"${column}"::date`), value);
+      } else if (part === 'time') {
+        q[method](q.client.raw(`"${column}"::time`), value);
+      } else {
+        q[method](q.client.raw(`EXTRACT(${pgPart} FROM "${column}")`), value);
+      }
 
     } else if (client.includes('mysql') || client.includes('maria')) {
-      // MySQL: YEAR(column) = value etc.
-      const fn = part.toUpperCase();
-      q[method](q.client.raw(`${fn}(\`${column}\`)`, []), value);
+      const mysqlMap = {
+        year: 'YEAR', month: 'MONTH', day: 'DAY',
+        hour: 'HOUR', minute: 'MINUTE', second: 'SECOND',
+        week: 'WEEK', quarter: 'QUARTER',
+        date: 'DATE', time: 'TIME', week_day: 'DAYOFWEEK',
+      };
+      const fn = mysqlMap[part] || part.toUpperCase();
+      q[method](q.client.raw(`${fn}(\`${column}\`)`), value);
 
     } else {
-      // SQLite: strftime('%Y', column) = value
+      // SQLite
       const fmtMap = {
         year: '%Y', month: '%m', day: '%d',
         hour: '%H', minute: '%M', second: '%S',
+        date: '%Y-%m-%d', time: '%H:%M:%S',
+        week: '%W', week_day: '%w', quarter: null,
       };
       const fmt = fmtMap[part];
-      q[method](q.client.raw(`strftime('${fmt}', "${column}")`, []), String(value).padStart(part === 'year' ? 4 : 2, '0'));
-    }
-  }
-
-  // ─── Relationship traversal ───────────────────────────────────────────────
-
-  /**
-   * Handle multi-segment paths like profile__city or post__author__role.
-   *
-   * Resolves each hop using Model.fields[x].references, auto-joins the
-   * necessary tables, then applies the final lookup on the leaf column.
-   *
-   * @param {object}   q          — knex query
-   * @param {string[]} fieldPath  — e.g. ['profile', 'city']
-   * @param {string}   lookup     — e.g. 'icontains'
-   * @param {*}        value
-   * @param {class}    ModelClass — root model
-   * @param {string}   method     — 'where' | 'orWhere'
-   */
-  static _applyRelational(q, fieldPath, lookup, value, ModelClass, method) {
-    let currentModel = ModelClass;
-    const joinedTables = new Set();
-
-    // Walk all segments except the last — each one is a relationship hop
-    for (let i = 0; i < fieldPath.length - 1; i++) {
-      const segment  = fieldPath[i];
-      const fields   = currentModel.fields || {};
-
-      // Try to find a field whose name matches the segment
-      const fieldDef = fields[segment] || fields[`${segment}_id`];
-
-      if (!fieldDef || !fieldDef.references) {
-        // No references info — fall back to treating the whole path as a
-        // raw column name with underscores (best-effort)
-        const fallbackCol = fieldPath.join('_');
-        return this._applyLookup(q, fallbackCol, lookup || 'exact', value, method);
+      if (!fmt) {
+        q[method](q.client.raw(`CAST((strftime('%m', \`${column}\`) + 2) / 3 AS INTEGER)`), value);
+      } else {
+        const pad = part === 'year' ? 4 : 2;
+        q[method](
+          q.client.raw(`strftime('${fmt}', \`${column}\`)`),
+          String(value).padStart(pad, '0')
+        );
       }
-
-      const { table: relTable, column: relColumn } = fieldDef.references;
-      const localColumn = fieldDef.references.localKey || segment + '_id';
-      const joinKey     = `${currentModel.table}__${relTable}`;
-
-      if (!joinedTables.has(joinKey)) {
-        q.join(relTable, `${currentModel.table}.${localColumn}`, '=', `${relTable}.${relColumn}`);
-        joinedTables.add(joinKey);
-      }
-
-      // Advance — try to resolve the related model for the next hop.
-      // We do a best-effort require() from the models directory.
-      currentModel = this._resolveRelatedModel(relTable) || { table: relTable, fields: {} };
     }
-
-    // The final segment is the leaf column on the last joined table
-    const leafColumn = `${currentModel.table}.${fieldPath[fieldPath.length - 1]}`;
-    return this._applyLookup(q, leafColumn, lookup || 'exact', value, method);
-  }
-
-  /**
-   * Try to resolve a related Model class by table name.
-   * Looks in process.cwd()/app/models/  (best-effort, graceful failure).
-   */
-  static _resolveRelatedModel(tableName) {
-    try {
-      const path     = require('path');
-      const fs       = require('fs');
-      const modelsDir = path.join(process.cwd(), 'app', 'models');
-
-      if (!fs.existsSync(modelsDir)) return null;
-
-      const files = fs.readdirSync(modelsDir).filter(f => f.endsWith('.js'));
-
-      for (const file of files) {
-        try {
-          const cls = require(path.join(modelsDir, file));
-          const ModelClass = typeof cls === 'function' ? cls
-            : Object.values(cls).find(v => typeof v === 'function');
-
-          if (ModelClass && ModelClass.table === tableName) return ModelClass;
-        } catch { /* skip */ }
-      }
-    } catch { /* skip */ }
-
-    return null;
   }
 
   // ─── Helpers ──────────────────────────────────────────────────────────────
 
-  /**
-   * Given the split parts array, return the lookup suffix if the last
-   * element is a known lookup keyword, otherwise return null.
-   */
   static _extractLookup(parts) {
     const last = parts[parts.length - 1];
     return this.LOOKUPS.includes(last) ? last : null;