@simtlix/simfinity-js 2.2.0 → 2.3.1

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)
+- [Plugins for Count in Extensions](#-plugins-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
 
@@ -1439,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
@@ -2213,28 +2638,30 @@ query {
 - **count**: Optional boolean - if `true`, returns total count of matching records
 
 #### Getting Total Count:
-When `count: true` is specified, the total count is available in the response extensions. You need to configure an Envelop plugin to expose it:
-
-```javascript
-// Envelop plugin for count in extensions
-function useCountPlugin() {
-  return {
-    onExecute() {
-      return {
-        onExecuteDone({ result, args }) {
-          if (args.contextValue?.count) {
-            result.extensions = {
-              ...result.extensions,
-              count: args.contextValue.count,
-            };
-          }
-        }
-      };
-    }
-  };
-}
+When `count: true` is specified, the total count is available in the response extensions. You need to configure a plugin to expose it. Simfinity.js provides utility plugins for both Apollo Server and Envelop:
+
+```javascript
+const simfinity = require('@simtlix/simfinity-js');
+
+// For Envelop
+const getEnveloped = envelop({
+  plugins: [
+    useSchema(schema),
+    simfinity.plugins.envelopCountPlugin(),
+  ],
+});
+
+// For Apollo Server
+const server = new ApolloServer({
+  schema,
+  plugins: [
+    simfinity.plugins.apolloCountPlugin(),
+  ],
+});
 ```
 
+See the [Plugins for Count in Extensions](#-plugins-for-count-in-extensions) section for complete examples.
+
 #### Example Response:
 ```json
 {
@@ -2574,45 +3001,18 @@ mutation {
 ```
 
 
-## 📦 Envelop Plugin for Count in Extensions
-
-To include the total count in the extensions of your GraphQL response, you can use an Envelop plugin. This is particularly useful for pagination and analytics.
-
-### Envelop Plugin Example
-
-Here's how you can implement the plugin:
-
-```javascript
-// Envelop plugin for count in extensions
-function useCountPlugin() {
-  return {
-    onExecute() {
-      return {
-        onExecuteDone({ result, args }) {
-          if (args.contextValue?.count) {
-            result.extensions = {
-              ...result.extensions,
-              count: args.contextValue.count,
-            };
-          }
-        }
-      };
-    }
-  };
-}
-```
+## 📦 Plugins for Count in Extensions
 
-### How to Use
+To include the total count in the extensions of your GraphQL response, Simfinity.js provides utility plugins for both Apollo Server and Envelop. This is particularly useful for pagination and analytics.
 
-1. **Integrate the Plugin**: Add the plugin to your GraphQL server setup.
-2. **Configure Context**: Ensure that your context includes the count value when executing queries.
-3. **Access Count**: The count will be available in the `extensions` field of the GraphQL response.
+### Envelop Plugin
 
-### Example Usage
+Use `simfinity.plugins.envelopCountPlugin()` to add count to extensions when using Envelop:
 
 ```javascript
 const { envelop, useSchema } = require('@envelop/core');
 const { makeExecutableSchema } = require('@graphql-tools/schema');
+const simfinity = require('@simtlix/simfinity-js');
 
 const schema = makeExecutableSchema({
   typeDefs,
@@ -2622,13 +3022,42 @@ const schema = makeExecutableSchema({
 const getEnveloped = envelop({
   plugins: [
     useSchema(schema),
-    useCountPlugin(), // Add the count plugin here
+    simfinity.plugins.envelopCountPlugin(), // Add the count plugin here
   ],
 });
 
 // Use getEnveloped in your server setup
 ```
 
+### Apollo Server Plugin
+
+Use `simfinity.plugins.apolloCountPlugin()` to add count to extensions when using Apollo Server:
+
+```javascript
+const { ApolloServer } = require('apollo-server-express');
+const simfinity = require('@simtlix/simfinity-js');
+
+const server = new ApolloServer({
+  schema,
+  plugins: [
+    simfinity.plugins.apolloCountPlugin(), // Add the count plugin here
+  ],
+  context: ({ req }) => {
+    // Your context setup
+    return {
+      user: req.user,
+      // count will be automatically added to extensions if present in context
+    };
+  },
+});
+```
+
+### How to Use
+
+1. **Import the Plugin**: Use `simfinity.plugins.envelopCountPlugin()` or `simfinity.plugins.apolloCountPlugin()` depending on your GraphQL server.
+2. **Configure Context**: Ensure that your context includes the count value when executing queries (Simfinity.js automatically sets `context.count` when `count: true` is specified in pagination).
+3. **Access Count**: The count will be available in the `extensions` field of the GraphQL response.
+
 ### Example Response
 
 When the plugin is correctly set up, your GraphQL response will include the count in the extensions:
@@ -2881,7 +3310,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.
 
@@ -2889,6 +3318,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
@@ -2896,12 +3326,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.

package/package.json

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

package/src/index.js

@@ -614,53 +614,53 @@ const executeRegisteredMutation = async (args, callback, session) => {
   }
 };
 
-const iterateonCollectionFields = async (materializedModel, gqltype, objectId, session) => {
+const iterateonCollectionFields = async (materializedModel, gqltype, objectId, session, context) => {
   for (const [collectionFieldKey, collectionField] of
     Object.entries(materializedModel.collectionFields)) {
     if (collectionField.added) {
        
       await executeItemFunction(gqltype, collectionFieldKey, objectId, session,
-        collectionField.added, operations.SAVE);
+        collectionField.added, operations.SAVE, context);
     }
     if (collectionField.updated) {
        
       await executeItemFunction(gqltype, collectionFieldKey, objectId, session,
-        collectionField.updated, operations.UPDATE);
+        collectionField.updated, operations.UPDATE, context);
     }
     if (collectionField.deleted) {
        
       await executeItemFunction(gqltype, collectionFieldKey, objectId, session,
-        collectionField.deleted, operations.DELETE);
+        collectionField.deleted, operations.DELETE, context);
     }
   }
 };
 
-const onDeleteObject = async (Model, gqltype, controller, args, session) => {
+const onDeleteObject = async (Model, gqltype, controller, args, session, context) => {
   const deletedObject = await Model.findById({ _id: args }).session(session).lean();
 
   if (controller && controller.onDelete) {
-    await controller.onDelete(deletedObject, session);
+    await controller.onDelete(deletedObject, session, context);
   }
 
   return Model.findByIdAndDelete({ _id: args }).session(session);
 };
 
-const onDeleteSubject = async (Model, controller, id, session) => {
+const onDeleteSubject = async (Model, controller, id, session, context) => {
   const currentObject = await Model.findById({ _id: id }).session(session).lean();
 
   if (controller && controller.onDelete) {
-    await controller.onDelete(currentObject, session);
+    await controller.onDelete(currentObject, session, context);
   }
 
   return Model.findByIdAndDelete({ _id: id }).session(session);
 };
 
-const onUpdateSubject = async (Model, gqltype, controller, args, session, linkToParent) => {
+const onUpdateSubject = async (Model, gqltype, controller, args, session, linkToParent, context) => {
   const materializedModel = await materializeModel(args, gqltype, linkToParent, 'UPDATE', session);
   const objectId = args.id;
 
   if (materializedModel.collectionFields) {
-    await iterateonCollectionFields(materializedModel, gqltype, objectId, session);
+    await iterateonCollectionFields(materializedModel, gqltype, objectId, session, context);
   }
 
   const currentObject = await Model.findById({ _id: objectId }).lean();
@@ -688,7 +688,7 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
   });
 
   if (controller && controller.onUpdating) {
-    await controller.onUpdating(objectId, materializedModel.modelArgs, session);
+    await controller.onUpdating(objectId, materializedModel.modelArgs, session, context);
   }
 
   const result = Model.findByIdAndUpdate(
@@ -696,13 +696,13 @@ const onUpdateSubject = async (Model, gqltype, controller, args, session, linkTo
   ).session(session);
 
   if (controller && controller.onUpdated) {
-    await controller.onUpdated(result, session);
+    await controller.onUpdated(result, session, context);
   }
 
   return result;
 };
 
-const onStateChanged = async (Model, gqltype, controller, args, session, actionField) => {
+const onStateChanged = async (Model, gqltype, controller, args, session, actionField, context) => {
   const storedModel = await Model.findById(args.id);
   if (!storedModel) {
     throw new SimfinityError(`${gqltype.name} ${args.id} is not valid`, 'NOT_VALID_ID', 404);
@@ -713,7 +713,7 @@ const onStateChanged = async (Model, gqltype, controller, args, session, actionF
     }
 
     args.state = actionField.to.name;
-    let result = await onUpdateSubject(Model, gqltype, controller, args, session);
+    let result = await onUpdateSubject(Model, gqltype, controller, args, session, null, context);
     result = result.toObject();
     result.state = actionField.to.value;
     return result;
@@ -721,7 +721,7 @@ const onStateChanged = async (Model, gqltype, controller, args, session, actionF
   throw new SimfinityError(`Action is not allowed from state ${storedModel.state}`, 'BAD_REQUEST', 400);
 };
 
-const onSaveObject = async (Model, gqltype, controller, args, session, linkToParent) => {
+const onSaveObject = async (Model, gqltype, controller, args, session, linkToParent, context) => {
   const materializedModel = await materializeModel(args, gqltype, linkToParent, 'CREATE', session);
   if (typesDict.types[gqltype.name].stateMachine) {
     materializedModel.modelArgs.state = typesDict.types[gqltype.name]
@@ -732,17 +732,17 @@ const onSaveObject = async (Model, gqltype, controller, args, session, linkToPar
   newObject.$session(session);
 
   if (controller && controller.onSaving) {
-    await controller.onSaving(newObject, args, session);
+    await controller.onSaving(newObject, args, session, context);
   }
 
   if (materializedModel.collectionFields) {
-    await iterateonCollectionFields(materializedModel, gqltype, newObject._id, session);
+    await iterateonCollectionFields(materializedModel, gqltype, newObject._id, session, context);
   }
 
   let result = await newObject.save();
   result = result.toObject();
   if (controller && controller.onSaved) {
-    await controller.onSaved(result, args, session);
+    await controller.onSaved(result, args, session, context);
   }
   if (typesDict.types[gqltype.name].stateMachine) {
     result.state = typesDict.types[gqltype.name].stateMachine.initialState.value;
@@ -750,29 +750,29 @@ const onSaveObject = async (Model, gqltype, controller, args, session, linkToPar
   return result;
 };
 
-export const saveObject = async (typeName, args, session) => {
+export const saveObject = async (typeName, args, session, context) => {
   const type = typesDict.types[typeName];
-  return onSaveObject(type.model, type.gqltype, type.controller, args, session);
+  return onSaveObject(type.model, type.gqltype, type.controller, args, session, null, context);
 };
 
 const executeOperation = async (Model, gqltype, controller,
-  args, operation, actionField, session) => {
+  args, operation, actionField, session, context) => {
   const mySession = session || await mongoose.startSession();
   await mySession.startTransaction();
   try {
     let newObject = null;
     switch (operation) {
       case operations.SAVE:
-        newObject = await onSaveObject(Model, gqltype, controller, args, mySession);
+        newObject = await onSaveObject(Model, gqltype, controller, args, mySession, null, context);
         break;
       case operations.UPDATE:
-        newObject = await onUpdateSubject(Model, gqltype, controller, args, mySession);
+        newObject = await onUpdateSubject(Model, gqltype, controller, args, mySession, null, context);
         break;
       case operations.DELETE:
-        newObject = await onDeleteObject(Model, gqltype, controller, args, mySession);
+        newObject = await onDeleteObject(Model, gqltype, controller, args, mySession, context);
         break;
       case operations.STATE_CHANGED:
-        newObject = await onStateChanged(Model, gqltype, controller, args, mySession, actionField);
+        newObject = await onStateChanged(Model, gqltype, controller, args, mySession, actionField, context);
         break;
     }
     await mySession.commitTransaction();
@@ -781,7 +781,7 @@ const executeOperation = async (Model, gqltype, controller,
   } catch (error) {
     await mySession.abortTransaction();
     if (error.errorLabels && error.errorLabels.includes('TransientTransactionError')) {
-      return executeOperation(Model, gqltype, controller, args, operation, actionField, mySession);
+      return executeOperation(Model, gqltype, controller, args, operation, actionField, mySession, context);
     }
     mySession.endSession();
     throw error;
@@ -789,7 +789,7 @@ const executeOperation = async (Model, gqltype, controller,
 };
 
 const executeItemFunction = async (gqltype, collectionField, objectId, session,
-  collectionFieldsList, operationType) => {
+  collectionFieldsList, operationType, context) => {
   const argTypes = gqltype.getFields();
   const collectionGQLType = argTypes[collectionField].type.ofType;
   const { connectionField } = argTypes[collectionField].extensions.relation;
@@ -802,7 +802,7 @@ const executeItemFunction = async (gqltype, collectionField, objectId, session,
         await onSaveObject(typesDict.types[collectionGQLType.name].model, collectionGQLType,
           typesDict.types[collectionGQLType.name].controller, collectionItem, session, (item) => {
             item[connectionField] = objectId;
-          });
+          }, context);
       };
       break;
     case operations.UPDATE:
@@ -810,13 +810,13 @@ const executeItemFunction = async (gqltype, collectionField, objectId, session,
         await onUpdateSubject(typesDict.types[collectionGQLType.name].model, collectionGQLType,
           typesDict.types[collectionGQLType.name].controller, collectionItem, session, (item) => {
             item[connectionField] = objectId;
-          });
+          }, context);
       };
       break;
     case operations.DELETE:
       operationFunction = async (collectionItem) => {
         await onDeleteSubject(typesDict.types[collectionGQLType.name].model,
-          typesDict.types[collectionGQLType.name].controller, collectionItem, session);
+          typesDict.types[collectionGQLType.name].controller, collectionItem, session, context);
       };
   }
 
@@ -846,6 +846,31 @@ const excecuteMiddleware = (context) => {
   middleware();
 };
 
+const executeScope = async (params) => {
+  const { type, args, operation, context } = params;
+  
+  if (!type || !type.gqltype || !type.gqltype.extensions) {
+    return null;
+  }
+
+  const extensions = type.gqltype.extensions;
+  if (!extensions.scope || !extensions.scope[operation]) {
+    return null;
+  }
+
+  const scopeFunction = extensions.scope[operation];
+  if (typeof scopeFunction !== 'function') {
+    return null;
+  }
+
+  // Call the scope function with the same params as middleware
+  const result = await scopeFunction({ type, args, operation, context });
+  
+  // For get_by_id, the scope function returns additional filters to merge
+  // For find and aggregate, it modifies args in place
+  return result;
+};
+
 const buildMutation = (name, includedMutationTypes, includedCustomMutations) => {
   const rootQueryArgs = {};
   rootQueryArgs.name = name;
@@ -872,7 +897,7 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
 
             excecuteMiddleware(params);
             return executeOperation(type.model, type.gqltype, type.controller,
-              args.input, operations.SAVE);
+              args.input, operations.SAVE, null, null, context);
           },
         };
         rootQueryArgs.fields[`delete${type.simpleEntityEndpointName}`] = {
@@ -889,7 +914,7 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
 
             excecuteMiddleware(params);
             return executeOperation(type.model, type.gqltype, type.controller,
-              args.id, operations.DELETE);
+              args.id, operations.DELETE, null, null, context);
           },
         };
       }
@@ -914,7 +939,7 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
 
             excecuteMiddleware(params);
             return executeOperation(type.model, type.gqltype, type.controller,
-              args.input, operations.UPDATE);
+              args.input, operations.UPDATE, null, null, context);
           },
         };
         if (type.stateMachine) {
@@ -936,7 +961,7 @@ const buildMutation = (name, includedMutationTypes, includedCustomMutations) =>
 
                   excecuteMiddleware(params);
                   return executeOperation(type.model, type.gqltype, type.controller,
-                    args.input, operations.STATE_CHANGED, actionField);
+                    args.input, operations.STATE_CHANGED, actionField, null, context);
                 },
               };
             }
@@ -1829,7 +1854,44 @@ const buildRootQuery = (name, includedTypes) => {
               context,
             };
             excecuteMiddleware(params);
-            return await type.model.findById(args.id);
+            
+            // Check if scope is defined for get_by_id
+            const hasScope = type.gqltype.extensions && type.gqltype.extensions.scope && type.gqltype.extensions.scope.get_by_id;
+            
+            if (hasScope) {
+              // Build query args with id filter - scope function will modify this
+              const queryArgs = {
+                id: { operator: 'EQ', value: args.id },
+              };
+              
+              // Create temporary params with queryArgs for scope function
+              const scopeParams = {
+                type,
+                args: queryArgs,
+                operation: 'get_by_id',
+                context,
+              };
+              
+              // Execute scope which will modify queryArgs in place
+              await executeScope(scopeParams);
+              
+              // Build aggregation pipeline from the combined filters
+              const aggregateClauses = await buildQuery(queryArgs, type.gqltype);
+              
+              // Execute the query and get the first result
+              let result;
+              if (aggregateClauses.length === 0) {
+                result = await type.model.findOne({ _id: args.id });
+              } else {
+                const results = await type.model.aggregate(aggregateClauses);
+                result = results.length > 0 ? results[0] : null;
+              }
+              
+              return result;
+            } else {
+              // No scope defined, use the original findById
+              return await type.model.findById(args.id);
+            }
           },
         };
 
@@ -1848,6 +1910,7 @@ const buildRootQuery = (name, includedTypes) => {
               context,
             };
             excecuteMiddleware(params);
+            await executeScope(params);
             const aggregateClauses = await buildQuery(args, type.gqltype);
             if (args.pagination && args.pagination.count) {
               const aggregateClausesForCount = await buildQuery(args, type.gqltype, true);
@@ -1882,6 +1945,7 @@ const buildRootQuery = (name, includedTypes) => {
               context,
             };
             excecuteMiddleware(params);
+            await executeScope(params);
             const aggregateClauses = await buildAggregationQuery(args, type.gqltype, args.aggregation);
             const result = await type.model.aggregate(aggregateClauses);
             return result;
@@ -2077,6 +2141,7 @@ export { createValidatedScalar };
 
 export { default as validators } from './validators.js';
 export { default as scalars } from './scalars.js';
+export { default as plugins } from './plugins.js';
 
 const createArgsForQuery = (argTypes) => {
     const argsObject = {};

package/src/plugins.js

@@ -0,0 +1,50 @@
+/**
+ * Apollo Server plugin to add count to GraphQL response extensions
+ * @returns {Object} Apollo Server plugin
+ */
+export const apolloCountPlugin = () => {
+  return {
+    async requestDidStart() {
+      return {
+        async willSendResponse({ contextValue, response }) {
+          if (response.body.kind === 'single' && contextValue?.count) {
+            response.body.singleResult.extensions = {
+              ...(response.body.singleResult.extensions || {}),
+              count: contextValue.count,
+            };
+          }
+        }
+      };
+    }
+  };
+};
+
+/**
+ * Envelop plugin to add count to GraphQL response extensions
+ * @returns {Object} Envelop plugin
+ */
+export const envelopCountPlugin = () => {
+  return {
+    onExecute() {
+      return {
+        onExecuteDone({ result, args }) {
+          if (args.contextValue?.count) {
+            result.extensions = {
+              ...result.extensions,
+              count: args.contextValue.count
+            };
+          }
+        }
+      };
+    }
+  };
+};
+
+// Export all plugins as an object for convenience
+const plugins = {
+  apolloCountPlugin,
+  envelopCountPlugin,
+};
+
+export default plugins;
+