@simtlix/simfinity-js 2.0.2 → 2.1.0

package/README.md

@@ -7,6 +7,7 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
 - **Automatic Schema Generation**: Define your object model, and Simfinity.js generates all queries and mutations
 - **MongoDB Integration**: Seamless translation between GraphQL and MongoDB
 - **Powerful Querying**: Any query that can be executed in MongoDB can be executed in GraphQL
+- **Aggregation Queries**: Built-in support for GROUP BY queries with aggregation operations (SUM, COUNT, AVG, MIN, MAX)
 - **Auto-Generated Resolvers**: Automatically generates resolve methods for relationship fields
 - **Automatic Index Creation**: Automatically creates MongoDB indexes for all ObjectId fields, including nested embedded objects and relationship fields
 - **Business Logic**: Implement business logic and domain validations declaratively
@@ -1358,6 +1359,238 @@ console.log(UserType.getFields()); // Access GraphQL fields
 const BookInput = simfinity.getInputType(BookType);
 ```
 
+## 📊 Aggregation Queries
+
+Simfinity.js now supports powerful GraphQL aggregation queries with GROUP BY functionality, allowing you to perform aggregate operations (SUM, COUNT, AVG, MIN, MAX) on your data.
+
+### Overview
+
+For each entity type registered with `connect()`, an additional aggregation endpoint is automatically generated with the format `{entityname}_aggregate`.
+
+### Features
+
+- **Group By**: Group results by any field (direct or related entity field path)
+- **Aggregation Operations**: SUM, COUNT, AVG, MIN, MAX
+- **Filtering**: Use the same filter parameters as regular queries
+- **Sorting**: Sort by groupId or any calculated fact (metrics), with support for multiple sort fields
+- **Pagination**: Use the same pagination parameters as regular queries
+- **Related Entity Fields**: Group by or aggregate on fields from related entities using dot notation
+
+### GraphQL Types
+
+#### QLAggregationOperation (Enum)
+- `SUM`: Sum of numeric values
+- `COUNT`: Count of records
+- `AVG`: Average of numeric values
+- `MIN`: Minimum value
+- `MAX`: Maximum value
+
+#### QLTypeAggregationFact (Input)
+```graphql
+input QLTypeAggregationFact {
+  operation: QLAggregationOperation!
+  factName: String!
+  path: String!
+}
+```
+
+#### QLTypeAggregationExpression (Input)
+```graphql
+input QLTypeAggregationExpression {
+  groupId: String!
+  facts: [QLTypeAggregationFact!]!
+}
+```
+
+#### QLTypeAggregationResult (Output)
+```graphql
+type QLTypeAggregationResult {
+  groupId: JSON
+  facts: JSON
+}
+```
+
+### Quick Examples
+
+#### Simple Group By
+```graphql
+query {
+  series_aggregate(
+    aggregation: {
+      groupId: "category"
+      facts: [
+        { operation: COUNT, factName: "total", path: "id" }
+      ]
+    }
+  ) {
+    groupId
+    facts
+  }
+}
+```
+
+#### Group By Related Entity
+```graphql
+query {
+  series_aggregate(
+    aggregation: {
+      groupId: "country.name"
+      facts: [
+        { operation: COUNT, factName: "count", path: "id" }
+        { operation: AVG, factName: "avgRating", path: "rating" }
+      ]
+    }
+  ) {
+    groupId
+    facts
+  }
+}
+```
+
+#### Multiple Aggregation Facts
+```graphql
+query {
+  series_aggregate(
+    aggregation: {
+      groupId: "category"
+      facts: [
+        { operation: COUNT, factName: "total", path: "id" }
+        { operation: SUM, factName: "totalEpisodes", path: "episodeCount" }
+        { operation: AVG, factName: "avgRating", path: "rating" }
+        { operation: MIN, factName: "minRating", path: "rating" }
+        { operation: MAX, factName: "maxRating", path: "rating" }
+      ]
+    }
+  ) {
+    groupId
+    facts
+  }
+}
+```
+
+#### With Filtering
+```graphql
+query {
+  series_aggregate(
+    rating: { operator: GTE, value: 8.0 }
+    aggregation: {
+      groupId: "category"
+      facts: [
+        { operation: COUNT, factName: "highRated", path: "id" }
+      ]
+    }
+  ) {
+    groupId
+    facts
+  }
+}
+```
+
+#### Sorting by Multiple Fields
+```graphql
+query {
+  series_aggregate(
+    sort: {
+      terms: [
+        { field: "total", order: "DESC" },       # Sort by count first
+        { field: "groupId", order: "ASC" }       # Then by name
+      ]
+    }
+    aggregation: {
+      groupId: "category"
+      facts: [
+        { operation: COUNT, factName: "total", path: "id" }
+        { operation: AVG, factName: "avgRating", path: "rating" }
+      ]
+    }
+  ) {
+    groupId
+    facts
+  }
+}
+```
+
+#### With Pagination (Top 5)
+```graphql
+query {
+  series_aggregate(
+    sort: {
+      terms: [{ field: "total", order: "DESC" }]
+    }
+    pagination: {
+      page: 1
+      size: 5
+    }
+    aggregation: {
+      groupId: "category"
+      facts: [
+        { operation: COUNT, factName: "total", path: "id" }
+      ]
+    }
+  ) {
+    groupId
+    facts
+  }
+}
+```
+
+### Field Path Resolution
+
+The `groupId` and `path` parameters support:
+
+1. **Direct Fields**: Simple field names from the entity
+   - Example: `"category"`, `"rating"`, `"id"`
+
+2. **Related Entity Fields**: Dot notation for fields in related entities
+   - Example: `"country.name"`, `"studio.foundedYear"`
+   
+3. **Nested Related Entities**: Multiple levels of relationships
+   - Example: `"country.region.name"`
+
+### Sorting Options
+
+- Sort by **groupId** or **any fact name**
+- **Multiple sort fields supported** - results are sorted by the first field, then by the second field for ties, etc.
+- Set the `field` parameter to:
+  - `"groupId"` to sort by the grouping field
+  - Any fact name (e.g., `"avgRating"`, `"total"`) to sort by that calculated metric
+- The `order` parameter (ASC/DESC) determines the sort direction for each field
+- If a field doesn't match groupId or any fact name, it defaults to groupId
+- If no sort is specified, defaults to sorting by groupId ascending
+
+### Pagination Notes
+
+- The `page` and `size` parameters work as expected
+- The `count` parameter is **ignored** for aggregation queries
+- Pagination is applied **after** grouping and sorting
+
+### MongoDB Translation
+
+Aggregation queries are translated to efficient MongoDB aggregation pipelines:
+
+1. **$lookup**: Joins with related entity collections
+2. **$unwind**: Flattens joined arrays
+3. **$match**: Applies filters (before grouping)
+4. **$group**: Groups by the specified field with aggregation operations
+5. **$project**: Formats final output with groupId and facts fields
+6. **$sort**: Sorts results by groupId or facts (with multiple fields support)
+7. **$limit** / **$skip**: Applied for pagination (after sorting)
+
+### Result Structure
+
+Results are returned in a consistent format:
+```json
+{
+  "groupId": <value>,
+  "facts": {
+    "factName1": <calculated_value>,
+    "factName2": <calculated_value>
+  }
+}
+```
+
+For complete documentation with more examples, see [AGGREGATION_EXAMPLE.md](./AGGREGATION_EXAMPLE.md) and [AGGREGATION_CHANGES_SUMMARY.md](./AGGREGATION_CHANGES_SUMMARY.md).
+
 ## 📚 Complete Example
 
 Here's a complete bookstore example with relationships, validations, and state machines:

package/package.json

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

package/src/index.js

@@ -13,6 +13,41 @@ import QLSort from './const/QLSort.js';
 
 mongoose.set('strictQuery', false);
 
+// Custom JSON scalar type for aggregation results
+const GraphQLJSON = new GraphQLScalarType({
+  name: 'JSON',
+  description: 'The `JSON` scalar type represents JSON values as specified by ECMA-404',
+  serialize(value) {
+    return value;
+  },
+  parseValue(value) {
+    return value;
+  },
+  parseLiteral(ast) {
+    switch (ast.kind) {
+      case Kind.STRING:
+      case Kind.BOOLEAN:
+        return ast.value;
+      case Kind.INT:
+      case Kind.FLOAT:
+        return parseFloat(ast.value);
+      case Kind.OBJECT: {
+        const value = Object.create(null);
+        ast.fields.forEach((field) => {
+          value[field.name.value] = GraphQLJSON.parseLiteral(field.value);
+        });
+        return value;
+      }
+      case Kind.LIST:
+        return ast.values.map((n) => GraphQLJSON.parseLiteral(n));
+      case Kind.NULL:
+        return null;
+      default:
+        return undefined;
+    }
+  },
+});
+
 // Adding 'extensions' field into instronspection query
 const RelationType = new GraphQLObjectType({
   name: 'RelationType',
@@ -147,6 +182,42 @@ const QLSortExpression = new GraphQLInputObjectType({
   }),
 });
 
+const QLAggregationOperation = new GraphQLEnumType({
+  name: 'QLAggregationOperation',
+  values: {
+    SUM: { value: 'SUM' },
+    COUNT: { value: 'COUNT' },
+    AVG: { value: 'AVG' },
+    MIN: { value: 'MIN' },
+    MAX: { value: 'MAX' },
+  },
+});
+
+const QLTypeAggregationFact = new GraphQLInputObjectType({
+  name: 'QLTypeAggregationFact',
+  fields: () => ({
+    operation: { type: new GraphQLNonNull(QLAggregationOperation) },
+    factName: { type: new GraphQLNonNull(GraphQLString) },
+    path: { type: new GraphQLNonNull(GraphQLString) },
+  }),
+});
+
+const QLTypeAggregationExpression = new GraphQLInputObjectType({
+  name: 'QLTypeAggregationExpression',
+  fields: () => ({
+    groupId: { type: new GraphQLNonNull(GraphQLString) },
+    facts: { type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(QLTypeAggregationFact))) },
+  }),
+});
+
+const QLTypeAggregationResult = new GraphQLObjectType({
+  name: 'QLTypeAggregationResult',
+  fields: () => ({
+    groupId: { type: GraphQLJSON },
+    facts: { type: GraphQLJSON },
+  }),
+});
+
 const isNonNullOfType = (fieldEntryType, graphQLType) => {
   let isOfType = false;
   if (fieldEntryType instanceof GraphQLNonNull) {
@@ -1482,6 +1553,254 @@ const buildQuery = async (input, gqltype, isCount) => {
   return aggregateClauses;
 };
 
+const buildFieldPath = (gqltype, fieldPath) => {
+  // This function resolves a field path (e.g., "category" or "country.name") 
+  // and returns the MongoDB field path and any necessary lookups
+  const pathParts = fieldPath.split('.');
+  const aggregateClauses = [];
+  let currentPath = '';
+  let currentGQLType = gqltype;
+  
+  for (let i = 0; i < pathParts.length; i++) {
+    const part = pathParts[i];
+    const field = currentGQLType.getFields()[part];
+    
+    if (!field) {
+      throw new Error(`Field ${part} not found in type ${currentGQLType.name}`);
+    }
+    
+    let fieldType = field.type;
+    if (fieldType instanceof GraphQLNonNull || fieldType instanceof GraphQLList) {
+      fieldType = fieldType.ofType;
+    }
+    
+    // If it's an object type with non-embedded relation, we need a lookup
+    if ((fieldType instanceof GraphQLObjectType) && 
+        field.extensions && field.extensions.relation && 
+        !field.extensions.relation.embedded) {
+      
+      const relatedModel = typesDict.types[fieldType.name].model;
+      const collectionName = relatedModel.collection.collectionName;
+      const connectionField = field.extensions.relation.connectionField || part;
+      
+      const lookupAlias = currentPath ? `${currentPath}_${part}` : part;
+      const localField = currentPath ? `${currentPath}.${connectionField}` : connectionField;
+      
+      aggregateClauses.push({
+        $lookup: {
+          from: collectionName,
+          foreignField: '_id',
+          localField,
+          as: lookupAlias,
+        },
+      });
+      
+      aggregateClauses.push({
+        $unwind: { path: `$${lookupAlias}`, preserveNullAndEmptyArrays: true },
+      });
+      
+      currentPath = lookupAlias;
+      currentGQLType = fieldType;
+    } else if (fieldType instanceof GraphQLObjectType && 
+               field.extensions && field.extensions.relation && 
+               field.extensions.relation.embedded) {
+      // Embedded object - just append to path
+      currentPath = currentPath ? `${currentPath}.${part}` : part;
+      currentGQLType = fieldType;
+    } else {
+      // Scalar field - final part of path
+      if (part === 'id') {
+        currentPath = currentPath ? `${currentPath}._id` : '_id';
+      } else {
+        currentPath = currentPath ? `${currentPath}.${part}` : part;
+      }
+    }
+  }
+  
+  return { mongoPath: currentPath, lookups: aggregateClauses };
+};
+
+const buildAggregationQuery = async (input, gqltype, aggregationExpression) => {
+  const aggregateClauses = [];
+  const matchesClauses = { $match: {} };
+  let addMatch = 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') {
+      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;
+              }
+            }
+          }
+        }
+      }
+    } else if (key === 'sort' && filterField && filterField.terms && filterField.terms.length > 0) {
+      // Extract all sort terms
+      filterField.terms.forEach(sortTerm => {
+        sortTerms.push({
+          field: sortTerm.field || 'groupId',
+          direction: sortTerm.order === 'ASC' ? 1 : -1,
+        });
+      });
+    } else if (key === 'pagination' && filterField) {
+      // Handle pagination (ignore count parameter)
+      if (filterField.page && filterField.size) {
+        const skip = filterField.size * (filterField.page - 1);
+        limitClause = { $limit: filterField.size + skip };
+        skipClause = { $skip: skip };
+      }
+    }
+  }
+  
+  if (addMatch) {
+    aggregateClauses.push(matchesClauses);
+  }
+  
+  // Now build the aggregation with $group
+  const { groupId, facts } = aggregationExpression;
+  
+  // Resolve the groupId field path
+  const groupIdPath = buildFieldPath(gqltype, groupId);
+  
+  // Add any lookups needed for the groupId field
+  groupIdPath.lookups.forEach(lookup => {
+    const lookupKey = Object.keys(lookup)[0];
+    const lookupAlias = lookup[lookupKey].as;
+    if (!aggregationsIncluded[lookupAlias]) {
+      aggregateClauses.push(lookup);
+      // Check if next item is an unwind for this lookup
+      const unwindItem = groupIdPath.lookups[groupIdPath.lookups.indexOf(lookup) + 1];
+      if (unwindItem && unwindItem.$unwind) {
+        aggregateClauses.push(unwindItem);
+      }
+      aggregationsIncluded[lookupAlias] = true;
+    }
+  });
+  
+  // Build the $group stage
+  const groupStage = {
+    $group: {
+      _id: `$${groupIdPath.mongoPath}`,
+    },
+  };
+  
+  // Add aggregation operations for each fact
+  facts.forEach(fact => {
+    const { operation, factName, path } = fact;
+    const factPath = buildFieldPath(gqltype, path);
+    
+    // Add any lookups needed for the fact field
+    factPath.lookups.forEach(lookup => {
+      const lookupKey = Object.keys(lookup)[0];
+      const lookupAlias = lookup[lookupKey].as;
+      if (!aggregationsIncluded[lookupAlias]) {
+        aggregateClauses.push(lookup);
+        // Check if next item is an unwind for this lookup
+        const unwindItem = factPath.lookups[factPath.lookups.indexOf(lookup) + 1];
+        if (unwindItem && unwindItem.$unwind) {
+          aggregateClauses.push(unwindItem);
+        }
+        aggregationsIncluded[lookupAlias] = true;
+      }
+    });
+    
+    // Map GraphQL operations to MongoDB aggregation operators
+    let mongoOperation;
+    switch (operation) {
+      case 'SUM':
+        mongoOperation = { $sum: `$${factPath.mongoPath}` };
+        break;
+      case 'COUNT':
+        mongoOperation = { $sum: 1 };
+        break;
+      case 'AVG':
+        mongoOperation = { $avg: `$${factPath.mongoPath}` };
+        break;
+      case 'MIN':
+        mongoOperation = { $min: `$${factPath.mongoPath}` };
+        break;
+      case 'MAX':
+        mongoOperation = { $max: `$${factPath.mongoPath}` };
+        break;
+      default:
+        throw new Error(`Unknown aggregation operation: ${operation}`);
+    }
+    
+    groupStage.$group[factName] = mongoOperation;
+  });
+  
+  aggregateClauses.push(groupStage);
+  
+  // Add a final projection stage to format the output
+  aggregateClauses.push({
+    $project: {
+      _id: 0,
+      groupId: '$_id',
+      facts: Object.fromEntries(facts.map(fact => [fact.factName, `$${fact.factName}`])),
+    },
+  });
+  
+  // Build sort object from multiple sort terms
+  if (sortTerms.length > 0) {
+    const sortObject = {};
+    const factNames = facts.map(fact => fact.factName);
+    
+    sortTerms.forEach(sortTerm => {
+      let sortFieldPath = 'groupId';
+      
+      if (sortTerm.field !== 'groupId') {
+        // Check if the field is one of the fact names
+        if (factNames.includes(sortTerm.field)) {
+          sortFieldPath = `facts.${sortTerm.field}`;
+        }
+        // If not found, default to groupId (already set)
+      }
+      
+      sortObject[sortFieldPath] = sortTerm.direction;
+    });
+    
+    // Add sort stage with all sort fields
+    aggregateClauses.push({
+      $sort: sortObject,
+    });
+  } else {
+    // Default sort by groupId ascending if no sort terms provided
+    aggregateClauses.push({
+      $sort: { groupId: 1 },
+    });
+  }
+  
+  // Add pagination if provided
+  if (limitClause) {
+    aggregateClauses.push(limitClause);
+  }
+  if (skipClause) {
+    aggregateClauses.push(skipClause);
+  }
+  
+  return aggregateClauses;
+};
+
 const buildRootQuery = (name, includedTypes) => {
   const rootQueryArgs = {};
   rootQueryArgs.name = name;
@@ -1545,6 +1864,29 @@ const buildRootQuery = (name, includedTypes) => {
             return result;
           },
         };
+
+        // Add aggregate endpoint
+        const aggregateArgsObject = { ...argsObject };
+        aggregateArgsObject.aggregation = {
+          type: new GraphQLNonNull(QLTypeAggregationExpression),
+        };
+
+        rootQueryArgs.fields[`${type.listEntitiesEndpointName}_aggregate`] = {
+          type: new GraphQLList(QLTypeAggregationResult),
+          args: aggregateArgsObject,
+          async resolve(parent, args, context) {
+            const params = {
+              type,
+              args,
+              operation: 'aggregate',
+              context,
+            };
+            excecuteMiddleware(params);
+            const aggregateClauses = await buildAggregationQuery(args, type.gqltype, args.aggregation);
+            const result = await type.model.aggregate(aggregateClauses);
+            return result;
+          },
+        };
       }
     }
   }

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,10 +0,0 @@
----
-name: Bug report
-about: Create a report to help us improve
-title: "[BUG]"
-labels: bug
-assignees: ''
-
----
-
-**Describe the bug*

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,10 +0,0 @@
----
-name: Feature request
-about: Suggest an idea for this project
-title: "[FEATURE]"
-labels: feature
-assignees: ''
-
----
-
-** Describe the feature **

package/.github/workflows/master.yml

@@ -1,19 +0,0 @@
-name: Build on master
-
-on:
-  push:
-    branches: master
-
-jobs:
-  build:
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v2.3.4
-      - uses: actions/setup-node@v1.4.4
-        with:
-          node-version: 14
-      - run: npm ci
-      - run: npx json -f package.json peerDependencies | npx json -ka | xargs -i{} bash -c 'echo $0@$(npx json -f package.json peerDependencies.$0)' {} | xargs -i{}  npm install --save-optional {}
-      - run: npm run lint
-      - run: npm test
-

package/.github/workflows/publish.yml

@@ -1,45 +0,0 @@
-name: Publish packages
-
-on:
-  create:
-    tags:
-      - 'v*'
-
-jobs:
-  build:
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v2.3.4
-      - uses: actions/setup-node@v1.4.4
-        with:
-          node-version: 14
-      - run: npm ci
-      - run: npx json -f package.json peerDependencies | npx json -ka | xargs -i{} bash -c 'echo $0@$(npx json -f package.json peerDependencies.$0)' {} | xargs -i{}  npm install --save-optional {}
-      - run: npm test
-
-  publish-npm:
-    needs: build
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v2.3.4
-      - uses: actions/setup-node@v1.4.4
-        with:
-          node-version: 14
-          registry-url: https://registry.npmjs.org/
-      - run: npm ci
-      - run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.NPMJS_TOKEN}}
-  publish-gpr:
-    needs: build
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v2.3.4
-      - uses: actions/setup-node@v1.4.4
-        with:
-          node-version: 14
-          registry-url: https://npm.pkg.github.com/
-      - run: npm ci
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}