@simtlix/simfinity-js 2.4.6 → 2.5.0

package/.cursor/rules/simfinity-core-functions.mdc

@@ -55,11 +55,13 @@ Handles: scalars, enums, relation fields (`IdInputType` for refs, nested input f
 `buildQuery(args, gqltype)` translates GraphQL filter arguments into a MongoDB aggregation pipeline:
 
 - `buildQueryTerms()` -- converts scalar/enum filters to `$match`, object/relation filters to `$lookup` + `$unwind` + `$match`
+- `buildFilterGroupMatch()` -- recursively processes `QLFilterGroup` (AND/OR) into nested MongoDB `$and`/`$or` match expressions. Reuses `buildQueryTerms()` for each leaf condition. Deduplicates `$lookup` stages via shared `aggregationsIncluded` dict. Max depth: 5.
 - `buildAggregationsForSort()` -- adds `$lookup`/`$unwind` for sort on related fields
 - Pagination: `$skip` + `$limit` from `QLPagination` input
 - Sort: `$sort` from `QLSortExpression` input
+- AND/OR: optional `AND`/`OR` arguments containing `QLFilterGroup` trees. Flat field filters and scope-injected filters are always ANDed at the top level (cannot be bypassed by user OR).
 
-`buildAggregationQuery()` extends this with `$group` for aggregation operations (SUM, COUNT, AVG, MIN, MAX).
+`buildAggregationQuery()` extends this with `$group` for aggregation operations (SUM, COUNT, AVG, MIN, MAX). Supports the same AND/OR filter pattern.
 
 ## Mutation Pipeline
 

package/README.md

@@ -265,6 +265,208 @@ query {
 - `NIN` - Not in array
 - `BTW` - Between two values
 
+### Logical Filters (AND / OR)
+
+By default, all field-level filters are combined with implicit AND logic. For complex conditions requiring OR logic or nested combinations, use the `AND` and `OR` query arguments.
+
+#### Simple OR
+
+Return books in either the Sci-Fi or Fantasy category:
+
+```graphql
+query {
+  books(
+    OR: [
+      { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+      { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+    ]
+  ) {
+    id
+    title
+    category
+  }
+}
+```
+
+#### Flat Filters Combined with OR
+
+Flat field filters are always ANDed at the top level, making them ideal for scope/security conditions that cannot be bypassed by user OR logic:
+
+```graphql
+query {
+  books(
+    rating: { operator: GTE, value: 7.0 }
+    OR: [
+      { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+      { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+    ]
+  ) {
+    id
+    title
+  }
+}
+```
+
+This translates to: `rating >= 7.0 AND (category = "Sci-Fi" OR category = "Fantasy")`.
+
+#### Nested AND inside OR
+
+```graphql
+query {
+  books(
+    OR: [
+      { AND: [
+        { conditions: [{ field: "rating", operator: GTE, value: 9.0 }] }
+        { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+      ]}
+      { AND: [
+        { conditions: [{ field: "rating", operator: GTE, value: 8.0 }] }
+        { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+      ]}
+    ]
+  ) {
+    id
+    title
+  }
+}
+```
+
+This translates to: `(rating >= 9.0 AND category = "Sci-Fi") OR (rating >= 8.0 AND category = "Fantasy")`.
+
+#### Filtering on Relationships within AND/OR
+
+Use the `path` parameter to filter on related entity fields:
+
+```graphql
+query {
+  books(
+    OR: [
+      { conditions: [{ field: "author", path: "name", operator: LIKE, value: "Adams" }] }
+      { conditions: [{ field: "author", path: "name", operator: LIKE, value: "Pratchett" }] }
+    ]
+  ) {
+    id
+    title
+    author { name }
+  }
+}
+```
+
+#### Mixing Flat Filters with AND/OR
+
+You can freely combine the existing flat filter syntax with AND/OR groups. Flat filters and AND groups are all ANDed together at the top level:
+
+```graphql
+query {
+  books(
+    rating: { operator: GTE, value: 7.0 }
+    author: { terms: [{ path: "country", operator: EQ, value: "UK" }] }
+    OR: [
+      { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+      { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+    ]
+  ) {
+    id
+    title
+    rating
+    category
+    author { name country }
+  }
+}
+```
+
+This translates to: `rating >= 7.0 AND author.country = "UK" AND (category = "Sci-Fi" OR category = "Fantasy")`. The flat field filters (`rating`, `author`) use the existing syntax while the OR group uses the new `QLFilterGroup` syntax.
+
+You can also combine flat filters with explicit AND groups for more complex logic:
+
+```graphql
+query {
+  books(
+    rating: { operator: GTE, value: 5.0 }
+    AND: [
+      {
+        OR: [
+          { conditions: [{ field: "category", operator: EQ, value: "Sci-Fi" }] }
+          { conditions: [{ field: "category", operator: EQ, value: "Fantasy" }] }
+        ]
+      }
+      {
+        OR: [
+          { conditions: [{ field: "author", path: "country", operator: EQ, value: "UK" }] }
+          { conditions: [{ field: "author", path: "country", operator: EQ, value: "US" }] }
+        ]
+      }
+    ]
+  ) {
+    id
+    title
+  }
+}
+```
+
+This translates to: `rating >= 5.0 AND (category = "Sci-Fi" OR category = "Fantasy") AND (author.country = "UK" OR author.country = "US")`.
+
+#### Collection Filtering with AND/OR
+
+AND/OR filters are also available on collection fields (one-to-many relationships). The auto-generated resolvers for collection fields support the same `AND` and `OR` arguments:
+
+```graphql
+query {
+  series {
+    seasons(
+      OR: [
+        { conditions: [{ field: "year", operator: EQ, value: 2020 }] }
+        { conditions: [{ field: "year", operator: EQ, value: 2021 }] }
+      ]
+    ) {
+      number
+      year
+    }
+  }
+}
+```
+
+You can mix flat collection filters with AND/OR:
+
+```graphql
+query {
+  series {
+    seasons(
+      number: { operator: GT, value: 1 }
+      OR: [
+        { conditions: [{ field: "year", operator: EQ, value: 2020 }] }
+        {
+          AND: [
+            { conditions: [{ field: "year", operator: GTE, value: 2022 }] }
+            { conditions: [
+                { field: "episodes", path: "name", operator: LIKE, value: "Final" }
+            ] }
+          ]
+        }
+      ]
+    ) {
+      number
+      year
+      episodes { name }
+    }
+  }
+}
+```
+
+This translates to: `number > 1 AND (year = 2020 OR (year >= 2022 AND episodes.name LIKE "Final"))`.
+
+#### Filter Types Reference
+
+| Type | Fields | Description |
+|------|--------|-------------|
+| `QLFilterGroup` | `AND: [QLFilterGroup]`, `OR: [QLFilterGroup]`, `conditions: [QLFilterCondition]` | Recursive logical group |
+| `QLFilterCondition` | `field: String!`, `operator: QLOperator`, `value: QLValue`, `path: String` | Individual filter condition |
+
+- `field` identifies the entity field by name (e.g., `"title"`, `"author"`)
+- `path` is required for object/relationship fields (e.g., `"name"`, `"country.name"`)
+- Multiple `conditions` in the same group are combined with AND
+- Maximum nesting depth: 5 levels
+
 ### Collection Field Filtering
 
 Simfinity.js now supports filtering collection fields (one-to-many relationships) using the same powerful query format. This allows you to filter related objects directly within your GraphQL queries.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "2.4.6",
+  "version": "2.5.0",
   "description": "",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -167,6 +167,25 @@ const QLTypeFilterExpression = new GraphQLInputObjectType({
   }),
 });
 
+const QLFilterCondition = new GraphQLInputObjectType({
+  name: 'QLFilterCondition',
+  fields: () => ({
+    field: { type: new GraphQLNonNull(GraphQLString) },
+    operator: { type: QLOperator },
+    value: { type: QLValue },
+    path: { type: GraphQLString },
+  }),
+});
+
+const QLFilterGroup = new GraphQLInputObjectType({
+  name: 'QLFilterGroup',
+  fields: () => ({
+    AND: { type: new GraphQLList(QLFilterGroup) },
+    OR: { type: new GraphQLList(QLFilterGroup) },
+    conditions: { type: new GraphQLList(QLFilterCondition) },
+  }),
+});
+
 const QLPagination = new GraphQLInputObjectType({
   name: 'QLPagination',
   fields: () => ({
@@ -1492,10 +1511,122 @@ const buildQueryTerms = async (filterField, qlField, fieldName) => {
   return { aggregateClauses, matchesClauses };
 };
 
+const MAX_FILTER_GROUP_DEPTH = 5;
+
+const buildFilterGroupMatch = async (filterGroup, gqltype, aggregateClauses, aggregationsIncluded, depth = 0) => {
+  if (depth > MAX_FILTER_GROUP_DEPTH) {
+    throw new SimfinityError('Filter nesting too deep', 'FILTER_DEPTH_EXCEEDED', 400);
+  }
+
+  const parts = [];
+  const fields = gqltype.getFields();
+
+  // Process leaf conditions
+  if (filterGroup.conditions && filterGroup.conditions.length > 0) {
+    for (const condition of filterGroup.conditions) {
+      const qlField = fields[condition.field];
+      if (!qlField) {
+        throw new SimfinityError(
+          `Unknown filter field: ${condition.field}`,
+          'INVALID_FILTER_FIELD',
+          400,
+        );
+      }
+
+      let filterInput;
+      let fieldType = qlField.type;
+      if (fieldType instanceof GraphQLList || fieldType instanceof GraphQLNonNull) {
+        fieldType = fieldType.ofType;
+      }
+
+      if (fieldType instanceof GraphQLObjectType
+        || isNonNullOfType(fieldType, GraphQLObjectType)) {
+        // Object/relation field — wrap as QLTypeFilterExpression shape
+        if (!condition.path) {
+          throw new SimfinityError(
+            `Filter on object field "${condition.field}" requires a path`,
+            'MISSING_FILTER_PATH',
+            400,
+          );
+        }
+        filterInput = {
+          terms: [{
+            path: condition.path,
+            operator: condition.operator,
+            value: condition.value,
+          }],
+        };
+      } else {
+        // Scalar/enum field
+        filterInput = {
+          operator: condition.operator,
+          value: condition.value,
+        };
+      }
+
+      const result = await buildQueryTerms(filterInput, qlField, condition.field);
+
+      if (result) {
+        // Collect lookups (deduplicated)
+        for (const [prop, aggregate] of Object.entries(result.aggregateClauses)) {
+          if (!aggregationsIncluded[prop]) {
+            aggregateClauses.push(aggregate.lookup);
+            aggregateClauses.push(aggregate.unwind);
+            aggregationsIncluded[prop] = true;
+          }
+        }
+
+        // Collect match conditions
+        for (const matchClause of Object.values(result.matchesClauses)) {
+          for (const [matchKey, match] of Object.entries(matchClause)) {
+            parts.push({ [matchKey]: match });
+          }
+        }
+      }
+    }
+  }
+
+  // Process AND sub-groups
+  if (filterGroup.AND && filterGroup.AND.length > 0) {
+    for (const subGroup of filterGroup.AND) {
+      const subMatch = await buildFilterGroupMatch(
+        subGroup, gqltype, aggregateClauses, aggregationsIncluded, depth + 1,
+      );
+      if (subMatch) {
+        parts.push(subMatch);
+      }
+    }
+  }
+
+  // Process OR sub-groups
+  if (filterGroup.OR && filterGroup.OR.length > 0) {
+    const orParts = [];
+    for (const subGroup of filterGroup.OR) {
+      const subMatch = await buildFilterGroupMatch(
+        subGroup, gqltype, aggregateClauses, aggregationsIncluded, depth + 1,
+      );
+      if (subMatch) {
+        orParts.push(subMatch);
+      }
+    }
+    if (orParts.length === 1) {
+      parts.push(orParts[0]);
+    } else if (orParts.length > 1) {
+      parts.push({ $or: orParts });
+    }
+  }
+
+  if (parts.length === 0) return null;
+  if (parts.length === 1) return parts[0];
+  return { $and: parts };
+};
+
+const RESERVED_QUERY_KEYS = new Set(['pagination', 'sort', 'AND', 'OR', 'aggregation']);
+
 const buildQuery = async (input, gqltype, isCount) => {
   const aggregateClauses = [];
-  const matchesClauses = { $match: {} };
-  let addMatch = false;
+  const flatMatchConditions = {};
+  let hasFlat = false;
   let limitClause = { $limit: 100 };
   let skipClause = { $skip: 0 };
   let sortClause = {};
@@ -1503,7 +1634,7 @@ const buildQuery = async (input, gqltype, isCount) => {
   const aggregationsIncluded = {};
 
   for (const [key, filterField] of Object.entries(input)) {
-    if (Object.prototype.hasOwnProperty.call(input, key) && key !== 'pagination' && key !== 'sort') {
+    if (Object.prototype.hasOwnProperty.call(input, key) && !RESERVED_QUERY_KEYS.has(key)) {
       const qlField = gqltype.getFields()[key];
 
       const result = await buildQueryTerms(filterField, qlField, key);
@@ -1519,8 +1650,8 @@ const buildQuery = async (input, gqltype, isCount) => {
           if (Object.prototype.hasOwnProperty.call(result.matchesClauses, matchClauseKey)) {
             for (const [matchKey, match] of Object.entries(matchClause)) {
               if (Object.prototype.hasOwnProperty.call(matchClause, matchKey)) {
-                matchesClauses.$match[matchKey] = match;
-                addMatch = true;
+                flatMatchConditions[matchKey] = match;
+                hasFlat = true;
               }
             }
           }
@@ -1539,9 +1670,9 @@ const buildQuery = async (input, gqltype, isCount) => {
 
         if (sort.field.indexOf('.') >= 0) {
           const sortParts = sort.field.split('.');
-           
+
           fixedSortField = sortParts[0];
-           
+
           for (let i = 1; i < sortParts.length - 1; i++) {
             fixedSortField += `_${sortParts[i]}`;
           }
@@ -1564,8 +1695,45 @@ const buildQuery = async (input, gqltype, isCount) => {
     }
   }
 
-  if (addMatch) {
-    aggregateClauses.push(matchesClauses);
+  // Combine flat conditions with AND/OR groups
+  const topLevelAndParts = [];
+
+  if (hasFlat) {
+    topLevelAndParts.push(flatMatchConditions);
+  }
+
+  if (input.AND && input.AND.length > 0) {
+    for (const group of input.AND) {
+      const groupMatch = await buildFilterGroupMatch(
+        group, gqltype, aggregateClauses, aggregationsIncluded,
+      );
+      if (groupMatch) {
+        topLevelAndParts.push(groupMatch);
+      }
+    }
+  }
+
+  if (input.OR && input.OR.length > 0) {
+    const orParts = [];
+    for (const group of input.OR) {
+      const groupMatch = await buildFilterGroupMatch(
+        group, gqltype, aggregateClauses, aggregationsIncluded,
+      );
+      if (groupMatch) {
+        orParts.push(groupMatch);
+      }
+    }
+    if (orParts.length === 1) {
+      topLevelAndParts.push(orParts[0]);
+    } else if (orParts.length > 1) {
+      topLevelAndParts.push({ $or: orParts });
+    }
+  }
+
+  if (topLevelAndParts.length === 1) {
+    aggregateClauses.push({ $match: topLevelAndParts[0] });
+  } else if (topLevelAndParts.length > 1) {
+    aggregateClauses.push({ $match: { $and: topLevelAndParts } });
   }
 
   if (addSort && !isCount) {
@@ -1653,33 +1821,33 @@ const buildFieldPath = (gqltype, fieldPath) => {
 
 const buildAggregationQuery = async (input, gqltype, aggregationExpression) => {
   const aggregateClauses = [];
-  const matchesClauses = { $match: {} };
-  let addMatch = false;
+  const flatMatchConditions = {};
+  let hasFlat = false;
   const aggregationsIncluded = {};
   const sortTerms = []; // Store multiple sort terms
   let limitClause = null;
   let skipClause = null;
-  
+
   // Build filter and lookup clauses (similar to buildQuery)
   for (const [key, filterField] of Object.entries(input)) {
-    if (Object.prototype.hasOwnProperty.call(input, key) && key !== 'pagination' && key !== 'sort' && key !== 'aggregation') {
+    if (Object.prototype.hasOwnProperty.call(input, key) && !RESERVED_QUERY_KEYS.has(key)) {
       const qlField = gqltype.getFields()[key];
-      
+
       const result = await buildQueryTerms(filterField, qlField, key);
-      
+
       if (result) {
         for (const [prop, aggregate] of Object.entries(result.aggregateClauses)) {
           aggregateClauses.push(aggregate.lookup);
           aggregateClauses.push(aggregate.unwind);
           aggregationsIncluded[prop] = true;
         }
-        
+
         for (const [matchClauseKey, matchClause] of Object.entries(result.matchesClauses)) {
           if (Object.prototype.hasOwnProperty.call(result.matchesClauses, matchClauseKey)) {
             for (const [matchKey, match] of Object.entries(matchClause)) {
               if (Object.prototype.hasOwnProperty.call(matchClause, matchKey)) {
-                matchesClauses.$match[matchKey] = match;
-                addMatch = true;
+                flatMatchConditions[matchKey] = match;
+                hasFlat = true;
               }
             }
           }
@@ -1702,9 +1870,46 @@ const buildAggregationQuery = async (input, gqltype, aggregationExpression) => {
       }
     }
   }
-  
-  if (addMatch) {
-    aggregateClauses.push(matchesClauses);
+
+  // Combine flat conditions with AND/OR groups
+  const topLevelAndParts = [];
+
+  if (hasFlat) {
+    topLevelAndParts.push(flatMatchConditions);
+  }
+
+  if (input.AND && input.AND.length > 0) {
+    for (const group of input.AND) {
+      const groupMatch = await buildFilterGroupMatch(
+        group, gqltype, aggregateClauses, aggregationsIncluded,
+      );
+      if (groupMatch) {
+        topLevelAndParts.push(groupMatch);
+      }
+    }
+  }
+
+  if (input.OR && input.OR.length > 0) {
+    const orParts = [];
+    for (const group of input.OR) {
+      const groupMatch = await buildFilterGroupMatch(
+        group, gqltype, aggregateClauses, aggregationsIncluded,
+      );
+      if (groupMatch) {
+        orParts.push(groupMatch);
+      }
+    }
+    if (orParts.length === 1) {
+      topLevelAndParts.push(orParts[0]);
+    } else if (orParts.length > 1) {
+      topLevelAndParts.push({ $or: orParts });
+    }
+  }
+
+  if (topLevelAndParts.length === 1) {
+    aggregateClauses.push({ $match: topLevelAndParts[0] });
+  } else if (topLevelAndParts.length > 1) {
+    aggregateClauses.push({ $match: { $and: topLevelAndParts } });
   }
   
   // Now build the aggregation with $group
@@ -2150,6 +2355,8 @@ export { default as scalars } from './scalars.js';
 export { default as plugins } from './plugins.js';
 export { default as auth } from './auth/index.js';
 
+export { buildQuery, buildFilterGroupMatch };
+
 const createArgsForQuery = (argTypes) => {
     const argsObject = {};
 
@@ -2182,6 +2389,13 @@ const createArgsForQuery = (argTypes) => {
 
     argsObject.sort = {};
     argsObject.sort.type = QLSortExpression;
+
+    argsObject.AND = {};
+    argsObject.AND.type = new GraphQLList(QLFilterGroup);
+
+    argsObject.OR = {};
+    argsObject.OR.type = new GraphQLList(QLFilterGroup);
+
     return argsObject;
 };