@simtlix/simfinity-js 2.1.0 → 2.3.0

package/README.md

@@ -2,6 +2,60 @@
 
 A powerful Node.js framework that automatically generates GraphQL schemas from your data models, bringing all the power and flexibility of MongoDB query language to GraphQL interfaces.
 
+## 📑 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Core Concepts](#-core-concepts)
+  - [Connecting Models](#connecting-models)
+  - [Creating Schemas](#creating-schemas)
+  - [Global Configuration](#global-configuration)
+- [Basic Usage](#-basic-usage)
+  - [Automatic Query Generation](#automatic-query-generation)
+  - [Automatic Mutation Generation](#automatic-mutation-generation)
+  - [Filtering and Querying](#filtering-and-querying)
+  - [Collection Field Filtering](#collection-field-filtering)
+- [Middlewares](#-middlewares)
+  - [Adding Middlewares](#adding-middlewares)
+  - [Middleware Parameters](#middleware-parameters)
+  - [Common Use Cases](#common-use-cases)
+- [Relationships](#-relationships)
+  - [Defining Relationships](#defining-relationships)
+  - [Auto-Generated Resolve Methods](#auto-generated-resolve-methods)
+  - [Adding Types Without Endpoints](#adding-types-without-endpoints)
+  - [Embedded vs Referenced Relationships](#embedded-vs-referenced-relationships)
+  - [Querying Relationships](#querying-relationships)
+- [Controllers & Lifecycle Hooks](#️-controllers--lifecycle-hooks)
+  - [Hook Parameters](#hook-parameters)
+- [State Machines](#-state-machines)
+- [Validations](#-validations)
+  - [Field-Level Validations](#field-level-validations)
+  - [Type-Level Validations](#type-level-validations)
+  - [Custom Validated Scalar Types](#custom-validated-scalar-types)
+  - [Custom Error Classes](#custom-error-classes)
+- [Query Scope](#-query-scope)
+  - [Overview](#overview)
+  - [Defining Scope](#defining-scope)
+  - [Scope for Find Operations](#scope-for-find-operations)
+  - [Scope for Aggregate Operations](#scope-for-aggregate-operations)
+  - [Scope for Get By ID Operations](#scope-for-get-by-id-operations)
+  - [Scope Function Parameters](#scope-function-parameters)
+- [Advanced Features](#-advanced-features)
+  - [Field Extensions](#field-extensions)
+  - [Custom Mutations](#custom-mutations)
+  - [Working with Existing Mongoose Models](#working-with-existing-mongoose-models)
+  - [Programmatic Data Access](#programmatic-data-access)
+- [Aggregation Queries](#-aggregation-queries)
+- [Complete Example](#-complete-example)
+- [Resources](#-resources)
+- [License](#-license)
+- [Contributing](#-contributing)
+- [Query Examples from Series-Sample](#-query-examples-from-series-sample)
+- [State Machine Example from Series-Sample](#-state-machine-example-from-series-sample)
+- [Envelop Plugin for Count in Extensions](#-envelop-plugin-for-count-in-extensions)
+- [API Reference](#-api-reference)
+
 ## ✨ Features
 
 - **Automatic Schema Generation**: Define your object model, and Simfinity.js generates all queries and mutations
@@ -940,31 +994,44 @@ Controllers provide fine-grained control over operations with lifecycle hooks:
 
 ```javascript
 const bookController = {
-  onSaving: async (doc, args, session) => {
+  onSaving: async (doc, args, session, context) => {
     // Before saving - doc is a Mongoose document
     if (!doc.title || doc.title.trim().length === 0) {
       throw new Error('Book title cannot be empty');
     }
+    // Access user from context to set owner
+    if (context && context.user) {
+      doc.owner = context.user.id;
+    }
     console.log(`Creating book: ${doc.title}`);
   },
 
-  onSaved: async (doc, args, session) => {
+  onSaved: async (doc, args, session, context) => {
     // After saving - doc is a plain object
     console.log(`Book saved: ${doc._id}`);
+    // Can access context.user for post-save operations like notifications
   },
 
-  onUpdating: async (id, doc, session) => {
+  onUpdating: async (id, doc, session, context) => {
     // Before updating - doc contains only changed fields
+    // Validate user has permission to update
+    if (context && context.user && context.user.role !== 'admin') {
+      throw new simfinity.SimfinityError('Only admins can update books', 'FORBIDDEN', 403);
+    }
     console.log(`Updating book ${id}`);
   },
 
-  onUpdated: async (doc, session) => {
+  onUpdated: async (doc, session, context) => {
     // After updating - doc is the updated document
     console.log(`Book updated: ${doc.title}`);
   },
 
-  onDelete: async (doc, session) => {
+  onDelete: async (doc, session, context) => {
     // Before deleting - doc is the document to be deleted
+    // Validate user has permission to delete
+    if (context && context.user && context.user.role !== 'admin') {
+      throw new simfinity.SimfinityError('Only admins can delete books', 'FORBIDDEN', 403);
+    }
     console.log(`Deleting book: ${doc.title}`);
   }
 };
@@ -975,28 +1042,75 @@ simfinity.connect(null, BookType, 'book', 'books', bookController);
 
 ### Hook Parameters
 
-**`onSaving(doc, args, session)`**:
+**`onSaving(doc, args, session, context)`**:
 - `doc`: Mongoose Document instance (not yet saved)
 - `args`: Raw GraphQL mutation input
 - `session`: Mongoose session for transaction
+- `context`: GraphQL context object (includes request info, user data, etc.)
 
-**`onSaved(doc, args, session)`**:
+**`onSaved(doc, args, session, context)`**:
 - `doc`: Plain object of saved document
 - `args`: Raw GraphQL mutation input
 - `session`: Mongoose session for transaction
+- `context`: GraphQL context object (includes request info, user data, etc.)
 
-**`onUpdating(id, doc, session)`**:
+**`onUpdating(id, doc, session, context)`**:
 - `id`: Document ID being updated
 - `doc`: Plain object with only changed fields
 - `session`: Mongoose session for transaction
+- `context`: GraphQL context object (includes request info, user data, etc.)
 
-**`onUpdated(doc, session)`**:
+**`onUpdated(doc, session, context)`**:
 - `doc`: Full updated Mongoose document
 - `session`: Mongoose session for transaction
+- `context`: GraphQL context object (includes request info, user data, etc.)
 
-**`onDelete(doc, session)`**:
+**`onDelete(doc, session, context)`**:
 - `doc`: Plain object of document to be deleted
 - `session`: Mongoose session for transaction
+- `context`: GraphQL context object (includes request info, user data, etc.)
+
+### Using Context in Controllers
+
+The `context` parameter provides access to the GraphQL request context, which typically includes user information, request metadata, and other application-specific data. This is particularly useful for:
+
+- **Setting ownership**: Automatically assign the current user as the owner of new entities
+- **Authorization checks**: Validate user permissions before allowing operations
+- **Audit logging**: Track who performed which operations
+- **User-specific business logic**: Apply different logic based on user roles or attributes
+
+**Example: Setting Owner on Creation**
+
+```javascript
+const documentController = {
+  onSaving: async (doc, args, session, context) => {
+    // Automatically set the owner to the current user
+    if (context && context.user) {
+      doc.owner = context.user.id;
+    }
+  }
+};
+```
+
+**Example: Role-Based Authorization**
+
+```javascript
+const adminOnlyController = {
+  onUpdating: async (id, doc, session, context) => {
+    if (!context || !context.user || context.user.role !== 'admin') {
+      throw new simfinity.SimfinityError('Admin access required', 'FORBIDDEN', 403);
+    }
+  },
+  
+  onDelete: async (doc, session, context) => {
+    if (!context || !context.user || context.user.role !== 'admin') {
+      throw new simfinity.SimfinityError('Admin access required', 'FORBIDDEN', 403);
+    }
+  }
+};
+```
+
+**Note**: When using `saveObject` programmatically (outside of GraphQL), the `context` parameter is optional and may be `undefined`. Always check for context existence before accessing its properties.
 
 ## 🔄 State Machines
 
@@ -1101,9 +1215,117 @@ mutation {
 
 ## ✅ Validations
 
-### Field-Level Validations
+### Declarative Validation Helpers
+
+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
 
-Add validation logic directly to fields:
+#### 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');
@@ -1189,7 +1411,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');
@@ -1260,6 +1553,317 @@ class NotFoundError extends SimfinityError {
 }
 ```
 
+## 🔒 Query Scope
+
+### Overview
+
+Query scope allows you to automatically modify query arguments based on context (e.g., user permissions). This enables automatic filtering so that users can only see documents they're authorized to access. Scope functions are executed after middleware and before query execution, allowing you to append filter conditions to queries and aggregations.
+
+### Defining Scope
+
+Define scope in the type extensions, similar to how validations are defined:
+
+```javascript
+const EpisodeType = new GraphQLObjectType({
+  name: 'episode',
+  extensions: {
+    validations: {
+      create: [validateEpisodeFields],
+      update: [validateEpisodeBusinessRules]
+    },
+    scope: {
+      find: async ({ type, args, operation, context }) => {
+        // Modify args in place to add filter conditions
+        args.owner = {
+          terms: [
+            {
+              path: 'id',
+              operator: 'EQ',
+              value: context.user.id
+            }
+          ]
+        };
+      },
+      aggregate: async ({ type, args, operation, context }) => {
+        // Apply same scope to aggregate queries
+        args.owner = {
+          terms: [
+            {
+              path: 'id',
+              operator: 'EQ',
+              value: context.user.id
+            }
+          ]
+        };
+      },
+      get_by_id: async ({ type, args, operation, context }) => {
+        // For get_by_id, scope is automatically merged with id filter
+        args.owner = {
+          terms: [
+            {
+              path: 'id',
+              operator: 'EQ',
+              value: context.user.id
+            }
+          ]
+        };
+      }
+    }
+  },
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    owner: {
+      type: new GraphQLNonNull(simfinity.getType('user')),
+      extensions: {
+        relation: {
+          connectionField: 'owner',
+          displayField: 'name'
+        }
+      }
+    }
+  })
+});
+```
+
+### Scope for Find Operations
+
+Scope functions for `find` operations modify the query arguments that are passed to `buildQuery`. The modified arguments are automatically used to filter results:
+
+```javascript
+const DocumentType = new GraphQLObjectType({
+  name: 'Document',
+  extensions: {
+    scope: {
+      find: async ({ type, args, operation, context }) => {
+        // Only show documents owned by the current user
+        args.owner = {
+          terms: [
+            {
+              path: 'id',
+              operator: 'EQ',
+              value: context.user.id
+            }
+          ]
+        };
+      }
+    }
+  },
+  fields: () => ({
+    id: { type: GraphQLID },
+    title: { type: GraphQLString },
+    owner: {
+      type: new GraphQLNonNull(simfinity.getType('user')),
+      extensions: {
+        relation: {
+          connectionField: 'owner',
+          displayField: 'name'
+        }
+      }
+    }
+  })
+});
+```
+
+**Result**: All `documents` queries will automatically filter to only return documents where `owner.id` equals `context.user.id`.
+
+### Scope for Aggregate Operations
+
+Scope functions for `aggregate` operations work the same way, ensuring aggregation queries also respect the scope:
+
+```javascript
+const OrderType = new GraphQLObjectType({
+  name: 'Order',
+  extensions: {
+    scope: {
+      aggregate: async ({ type, args, operation, context }) => {
+        // Only aggregate orders for the current user's organization
+        args.organization = {
+          terms: [
+            {
+              path: 'id',
+              operator: 'EQ',
+              value: context.user.organizationId
+            }
+          ]
+        };
+      }
+    }
+  },
+  fields: () => ({
+    // ... fields
+  })
+});
+```
+
+**Result**: All `orders_aggregate` queries will automatically filter to only aggregate orders from the user's organization.
+
+### Scope for Get By ID Operations
+
+For `get_by_id` operations, scope functions modify a temporary query arguments object that includes the id filter. The system automatically combines the id filter with scope filters:
+
+```javascript
+const PrivateDocumentType = new GraphQLObjectType({
+  name: 'PrivateDocument',
+  extensions: {
+    scope: {
+      get_by_id: async ({ type, args, operation, context }) => {
+        // Ensure user can only access their own documents
+        args.owner = {
+          terms: [
+            {
+              path: 'id',
+              operator: 'EQ',
+              value: context.user.id
+            }
+          ]
+        };
+      }
+    }
+  },
+  fields: () => ({
+    // ... fields
+  })
+});
+```
+
+**Result**: When querying `privatedocument(id: "some_id")`, the system will:
+1. Create a query that includes both the id filter and the owner scope filter
+2. Only return the document if it matches both conditions
+3. Return `null` if the document exists but doesn't match the scope
+
+### Scope Function Parameters
+
+Scope functions receive the same parameters as middleware for consistency:
+
+```javascript
+{
+  type,        // Type information (model, gqltype, controller, etc.)
+  args,        // GraphQL arguments passed to the operation (modify this object)
+  operation,   // Operation type: 'find', 'aggregate', or 'get_by_id'
+  context      // GraphQL context object (includes request info, user data, etc.)
+}
+```
+
+### Filter Structure
+
+When modifying `args` in scope functions, use the appropriate filter structure:
+
+**For scalar fields:**
+```javascript
+args.fieldName = {
+  operator: 'EQ',
+  value: 'someValue'
+};
+```
+
+**For object/relation fields (QLTypeFilterExpression):**
+```javascript
+args.relationField = {
+  terms: [
+    {
+      path: 'fieldName',
+      operator: 'EQ',
+      value: 'someValue'
+    }
+  ]
+};
+```
+
+### Complete Example
+
+Here's a complete example showing scope for all query operations:
+
+```javascript
+const EpisodeType = new GraphQLObjectType({
+  name: 'episode',
+  extensions: {
+    validations: {
+      save: [validateEpisodeFields],
+      update: [validateEpisodeBusinessRules]
+    },
+    scope: {
+      find: async ({ type, args, operation, context }) => {
+        // Only show episodes from seasons the user has access to
+        args.season = {
+          terms: [
+            {
+              path: 'owner.id',
+              operator: 'EQ',
+              value: context.user.id
+            }
+          ]
+        };
+      },
+      aggregate: async ({ type, args, operation, context }) => {
+        // Apply same scope to aggregations
+        args.season = {
+          terms: [
+            {
+              path: 'owner.id',
+              operator: 'EQ',
+              value: context.user.id
+            }
+          ]
+        };
+      },
+      get_by_id: async ({ type, args, operation, context }) => {
+        // Ensure user can only access their own episodes
+        args.owner = {
+          terms: [
+            {
+              path: 'id',
+              operator: 'EQ',
+              value: context.user.id
+            }
+          ]
+        };
+      }
+    }
+  },
+  fields: () => ({
+    id: { type: GraphQLID },
+    number: { type: GraphQLInt },
+    name: { type: GraphQLString },
+    season: {
+      type: new GraphQLNonNull(simfinity.getType('season')),
+      extensions: {
+        relation: {
+          connectionField: 'season',
+          displayField: 'number'
+        }
+      }
+    },
+    owner: {
+      type: new GraphQLNonNull(simfinity.getType('user')),
+      extensions: {
+        relation: {
+          connectionField: 'owner',
+          displayField: 'name'
+        }
+      }
+    }
+  })
+});
+```
+
+### Important Notes
+
+- **Execution Order**: Scope functions are executed **after** middleware, so middleware can set up context (e.g., user info) that scope functions can use
+- **Modify Args In Place**: Scope functions should modify the `args` object directly
+- **Filter Structure**: Use the correct filter structure (`QLFilter` for scalars, `QLTypeFilterExpression` for relations)
+- **All Query Operations**: Scope applies to `find`, `aggregate`, and `get_by_id` operations
+- **Automatic Merging**: For `get_by_id`, the id filter is automatically combined with scope filters
+- **Context Access**: Use `context.user`, `context.ip`, or other context properties to determine scope
+
+### Use Cases
+
+- **Multi-tenancy**: Filter documents by organization or tenant
+- **User-specific data**: Only show documents owned by the current user
+- **Role-based access**: Filter based on user roles or permissions
+- **Department/Team scoping**: Show only data relevant to user's department
+- **Geographic scoping**: Filter by user's location or region
+
 ## 🔧 Advanced Features
 
 ### Field Extensions
@@ -2702,7 +3306,7 @@ const BookInput = simfinity.getInputType(BookType);
 console.log(BookInput.getFields()); // Input fields for mutations
 ```
 
-### `saveObject(typeName, args, session?)`
+### `saveObject(typeName, args, session?, context?)`
 
 Programmatically save an object outside of GraphQL mutations.
 
@@ -2710,6 +3314,7 @@ Programmatically save an object outside of GraphQL mutations.
 - `typeName` (string): The name of the GraphQL type
 - `args` (object): The data to save
 - `session` (MongooseSession, optional): Database session for transactions
+- `context` (object, optional): GraphQL context object (includes request info, user data, etc.)
 
 **Returns:**
 - `Promise<object>`: The saved object
@@ -2717,12 +3322,20 @@ Programmatically save an object outside of GraphQL mutations.
 **Example:**
 
 ```javascript
+const newBook = await simfinity.saveObject('Book', {
+  title: 'New Book',
+  author: 'Author Name'
+}, session, context);
+
+// Without context (context will be undefined in controller hooks)
 const newBook = await simfinity.saveObject('Book', {
   title: 'New Book',
   author: 'Author Name'
 }, session);
 ```
 
+**Note**: When `context` is not provided, it will be `undefined` in controller hooks. This is acceptable for programmatic usage where context may not be available.
+
 ### `createSchema(includedQueryTypes?, includedMutationTypes?, includedCustomMutations?)`
 
 Creates the final GraphQL schema with all connected types.