@simtlix/simfinity-js 2.0.2 → 2.2.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
@@ -1100,9 +1101,117 @@ mutation {
 
 ## ✅ Validations
 
-### Field-Level Validations
+### Declarative Validation Helpers
 
-Add validation logic directly to fields:
+Simfinity.js provides built-in validation helpers to simplify common validation patterns, eliminating verbose boilerplate code.
+
+#### Using Validators
+
+```javascript
+const { validators } = require('@simtlix/simfinity-js');
+
+const PersonType = new GraphQLObjectType({
+  name: 'Person',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.stringLength('Name', 2, 100)
+      }
+    },
+    email: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.email()
+      }
+    },
+    website: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.url()
+      }
+    },
+    age: {
+      type: GraphQLInt,
+      extensions: {
+        validations: validators.numberRange('Age', 0, 120)
+      }
+    },
+    price: {
+      type: GraphQLFloat,
+      extensions: {
+        validations: validators.positive('Price')
+      }
+    }
+  })
+});
+```
+
+#### Available Validators
+
+**String Validators:**
+- `validators.stringLength(name, min, max)` - Validates string length with min/max bounds (required for CREATE)
+- `validators.maxLength(name, max)` - Validates maximum string length
+- `validators.pattern(name, regex, message)` - Validates against a regex pattern
+- `validators.email()` - Validates email format
+- `validators.url()` - Validates URL format
+
+**Number Validators:**
+- `validators.numberRange(name, min, max)` - Validates number range
+- `validators.positive(name)` - Ensures number is positive
+
+**Array Validators:**
+- `validators.arrayLength(name, maxItems, itemValidator)` - Validates array length and optionally each item
+
+**Date Validators:**
+- `validators.dateFormat(name, format)` - Validates date format
+- `validators.futureDate(name)` - Ensures date is in the future
+
+#### Validator Features
+
+- **Automatic Operation Handling**: Validators work for both `CREATE` (save) and `UPDATE` operations
+- **Smart Validation**: For CREATE operations, values are required. For UPDATE operations, undefined/null values are allowed (field might not be updated)
+- **Consistent Error Messages**: All validators throw `SimfinityError` with appropriate messages
+
+#### Example: Multiple Validators
+
+```javascript
+const ProductType = new GraphQLObjectType({
+  name: 'Product',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.stringLength('Product Name', 3, 200)
+      }
+    },
+    sku: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.pattern('SKU', /^[A-Z0-9-]+$/, 'SKU must be uppercase alphanumeric with hyphens')
+      }
+    },
+    price: {
+      type: GraphQLFloat,
+      extensions: {
+        validations: validators.positive('Price')
+      }
+    },
+    tags: {
+      type: new GraphQLList(GraphQLString),
+      extensions: {
+        validations: validators.arrayLength('Tags', 10)
+      }
+    }
+  })
+});
+```
+
+### Field-Level Validations (Manual)
+
+For custom validation logic, you can still write manual validators:
 
 ```javascript
 const { SimfinityError } = require('@simtlix/simfinity-js');
@@ -1188,7 +1297,78 @@ const OrderType = new GraphQLObjectType({
 
 ### Custom Validated Scalar Types
 
-Create custom scalar types with built-in validation. The generated type names follow the pattern `{name}_{baseScalarTypeName}`:
+Create custom scalar types with built-in validation. The generated type names follow the pattern `{name}_{baseScalarTypeName}`.
+
+#### Pre-built Scalars
+
+Simfinity.js provides ready-to-use validated scalars for common patterns:
+
+```javascript
+const { scalars } = require('@simtlix/simfinity-js');
+
+const UserType = new GraphQLObjectType({
+  name: 'User',
+  fields: () => ({
+    id: { type: GraphQLID },
+    email: { type: scalars.EmailScalar },      // Type name: Email_String
+    website: { type: scalars.URLScalar },       // Type name: URL_String
+    age: { type: scalars.PositiveIntScalar },  // Type name: PositiveInt_Int
+    price: { type: scalars.PositiveFloatScalar } // Type name: PositiveFloat_Float
+  }),
+});
+```
+
+**Available Pre-built Scalars:**
+- `scalars.EmailScalar` - Validates email format (`Email_String`)
+- `scalars.URLScalar` - Validates URL format (`URL_String`)
+- `scalars.PositiveIntScalar` - Validates positive integers (`PositiveInt_Int`)
+- `scalars.PositiveFloatScalar` - Validates positive floats (`PositiveFloat_Float`)
+
+#### Factory Functions for Custom Scalars
+
+Create custom validated scalars with parameters:
+
+```javascript
+const { scalars } = require('@simtlix/simfinity-js');
+
+// Create a bounded string scalar (name length between 2-100 characters)
+const NameScalar = scalars.createBoundedStringScalar('Name', 2, 100);
+
+// Create a bounded integer scalar (age between 0-120)
+const AgeScalar = scalars.createBoundedIntScalar('Age', 0, 120);
+
+// Create a bounded float scalar (rating between 0-10)
+const RatingScalar = scalars.createBoundedFloatScalar('Rating', 0, 10);
+
+// Create a pattern-based string scalar (phone number format)
+const PhoneScalar = scalars.createPatternStringScalar(
+  'Phone',
+  /^\+?[\d\s\-()]+$/,
+  'Invalid phone number format'
+);
+
+// Use in your types
+const PersonType = new GraphQLObjectType({
+  name: 'Person',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: NameScalar },        // Type name: Name_String
+    age: { type: AgeScalar },          // Type name: Age_Int
+    rating: { type: RatingScalar },    // Type name: Rating_Float
+    phone: { type: PhoneScalar }       // Type name: Phone_String
+  }),
+});
+```
+
+**Available Factory Functions:**
+- `scalars.createBoundedStringScalar(name, min, max)` - String with length bounds
+- `scalars.createBoundedIntScalar(name, min, max)` - Integer with range validation
+- `scalars.createBoundedFloatScalar(name, min, max)` - Float with range validation
+- `scalars.createPatternStringScalar(name, pattern, message)` - String with regex pattern validation
+
+#### Creating Custom Scalars Manually
+
+You can also create custom scalars using `createValidatedScalar` directly:
 
 ```javascript
 const { GraphQLString, GraphQLInt } = require('graphql');
@@ -1358,6 +1538,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.2.0",
   "description": "",
   "main": "src/index.js",
   "type": "module",