@simtlix/simfinity-js 1.4.0 → 1.6.0

package/README.md

@@ -146,13 +146,6 @@ const schema = simfinity.createSchema(
 ```javascript
 // Prevent automatic MongoDB collection creation (useful for testing)
 simfinity.preventCreatingCollection(true);
-
-// Add middleware for all operations
-simfinity.use((params, next) => {
-  // params contains: type, args, operation, context
-  console.log(`Executing ${params.operation} on ${params.type.name}`);
-  next();
-});
 ```
 
 ## 📋 Basic Usage
@@ -210,6 +203,253 @@ query {
 - `NIN` - Not in array
 - `BTW` - Between two values
 
+## 🔧 Middlewares
+
+Middlewares provide a powerful way to intercept and process all GraphQL operations before they execute. Use them for cross-cutting concerns like authentication, logging, validation, and performance monitoring.
+
+### Adding Middlewares
+
+Register middlewares using `simfinity.use()`. Middlewares execute in the order they're registered:
+
+```javascript
+// Basic logging middleware
+simfinity.use((params, next) => {
+  console.log(`Executing ${params.operation} on ${params.type?.name || 'custom mutation'}`);
+  next();
+});
+```
+
+### Middleware Parameters
+
+Each middleware receives a `params` object containing:
+
+```javascript
+simfinity.use((params, next) => {
+  // params object contains:
+  const {
+    type,        // Type information (model, gqltype, controller, etc.)
+    args,        // GraphQL arguments passed to the operation
+    operation,   // Operation type: 'save', 'update', 'delete', 'get_by_id', 'find', 'state_changed', 'custom_mutation'
+    context,     // GraphQL context object (includes request info, user data, etc.)
+    actionName,  // For state machine actions (only present for state_changed operations)
+    actionField, // State machine action details (only present for state_changed operations)
+    entry        // Custom mutation name (only present for custom_mutation operations)
+  } = params;
+  
+  // Always call next() to continue the middleware chain
+  next();
+});
+```
+
+### Common Use Cases
+
+#### 1. Authentication & Authorization
+
+```javascript
+simfinity.use((params, next) => {
+  const { context, operation, type } = params;
+  
+  // Skip authentication for read operations
+  if (operation === 'get_by_id' || operation === 'find') {
+    return next();
+  }
+  
+  // Check if user is authenticated
+  if (!context.user) {
+    throw new simfinity.SimfinityError('Authentication required', 'UNAUTHORIZED', 401);
+  }
+  
+  // Check permissions for specific types
+  if (type?.name === 'User' && context.user.role !== 'admin') {
+    throw new simfinity.SimfinityError('Admin access required', 'FORBIDDEN', 403);
+  }
+  
+  next();
+});
+```
+
+#### 2. Request Logging & Monitoring
+
+```javascript
+simfinity.use((params, next) => {
+  const { operation, type, args, context } = params;
+  const startTime = Date.now();
+  
+  console.log(`[${new Date().toISOString()}] Starting ${operation}${type ? ` on ${type.name}` : ''}`);
+  
+  // Continue with the operation
+  next();
+  
+  const duration = Date.now() - startTime;
+  console.log(`[${new Date().toISOString()}] Completed ${operation} in ${duration}ms`);
+});
+```
+
+#### 3. Input Validation & Sanitization
+
+```javascript
+simfinity.use((params, next) => {
+  const { operation, args, type } = params;
+  
+  // Validate input for save operations
+  if (operation === 'save' && args.input) {
+    // Trim string fields
+    Object.keys(args.input).forEach(key => {
+      if (typeof args.input[key] === 'string') {
+        args.input[key] = args.input[key].trim();
+      }
+    });
+    
+    // Validate required business rules
+    if (type?.name === 'Book' && args.input.title && args.input.title.length < 3) {
+      throw new simfinity.SimfinityError('Book title must be at least 3 characters', 'VALIDATION_ERROR', 400);
+    }
+  }
+  
+  next();
+});
+```
+
+#### 4. Rate Limiting
+
+```javascript
+const requestCounts = new Map();
+
+simfinity.use((params, next) => {
+  const { context, operation } = params;
+  const userId = context.user?.id || context.ip;
+  const now = Date.now();
+  const windowMs = 60000; // 1 minute
+  const maxRequests = 100;
+  
+  // Only apply rate limiting to mutations
+  if (operation === 'save' || operation === 'update' || operation === 'delete') {
+    const userRequests = requestCounts.get(userId) || [];
+    const recentRequests = userRequests.filter(time => now - time < windowMs);
+    
+    if (recentRequests.length >= maxRequests) {
+      throw new simfinity.SimfinityError('Rate limit exceeded', 'TOO_MANY_REQUESTS', 429);
+    }
+    
+    recentRequests.push(now);
+    requestCounts.set(userId, recentRequests);
+  }
+  
+  next();
+});
+```
+
+#### 5. Audit Trail
+
+```javascript
+simfinity.use((params, next) => {
+  const { operation, type, args, context } = params;
+  
+  // Log all mutations for audit purposes
+  if (operation === 'save' || operation === 'update' || operation === 'delete') {
+    const auditEntry = {
+      timestamp: new Date(),
+      user: context.user?.id,
+      operation,
+      type: type?.name,
+      entityId: args.id || 'new',
+      data: operation === 'delete' ? null : args.input,
+      ip: context.ip,
+      userAgent: context.userAgent
+    };
+    
+    // Save to audit log (could be database, file, or external service)
+    console.log('AUDIT:', JSON.stringify(auditEntry));
+  }
+  
+  next();
+});
+```
+
+### Multiple Middlewares
+
+Middlewares execute in registration order. Each middleware must call `next()` to continue the chain:
+
+```javascript
+// Middleware 1: Authentication
+simfinity.use((params, next) => {
+  console.log('1. Checking authentication...');
+  // Authentication logic here
+  next(); // Continue to next middleware
+});
+
+// Middleware 2: Authorization  
+simfinity.use((params, next) => {
+  console.log('2. Checking permissions...');
+  // Authorization logic here
+  next(); // Continue to next middleware
+});
+
+// Middleware 3: Logging
+simfinity.use((params, next) => {
+  console.log('3. Logging request...');
+  // Logging logic here
+  next(); // Continue to GraphQL operation
+});
+```
+
+### Error Handling in Middlewares
+
+Middlewares can throw errors to stop the operation:
+
+```javascript
+simfinity.use((params, next) => {
+  const { context, operation } = params;
+  
+  try {
+    // Validation logic
+    if (!context.user && operation !== 'find') {
+      throw new simfinity.SimfinityError('Authentication required', 'UNAUTHORIZED', 401);
+    }
+    
+    next(); // Continue only if validation passes
+  } catch (error) {
+    // Error automatically bubbles up to GraphQL error handling
+    throw error;
+  }
+});
+```
+
+### Conditional Middleware Execution
+
+Execute middleware logic conditionally based on operation type or context:
+
+```javascript
+simfinity.use((params, next) => {
+  const { operation, type, context } = params;
+  
+  // Only apply to specific types
+  if (type?.name === 'SensitiveData') {
+    // Special handling for sensitive data
+    if (!context.user?.hasHighSecurity) {
+      throw new simfinity.SimfinityError('High security clearance required', 'FORBIDDEN', 403);
+    }
+  }
+  
+  // Only apply to mutation operations
+  if (['save', 'update', 'delete', 'state_changed'].includes(operation)) {
+    // Mutation-specific logic
+    console.log(`Mutation ${operation} executing...`);
+  }
+  
+  next();
+});
+```
+
+### Best Practices
+
+1. **Always call `next()`**: Failing to call `next()` will hang the request
+2. **Handle errors gracefully**: Use try-catch blocks for error-prone operations
+3. **Keep middlewares focused**: Each middleware should handle one concern
+4. **Order matters**: Register middlewares in logical order (auth → validation → logging)
+5. **Performance consideration**: Middlewares run on every operation, keep them lightweight
+6. **Use context wisely**: Store request-specific data in the GraphQL context object
+
 ## 🔗 Relationships
 
 ### Defining Relationships
@@ -353,6 +593,104 @@ simfinity.addNoEndpointType(AuthorType);
 
 That's it! All relationship resolvers are automatically generated when you connect your types.
 
+### Adding Types Without Endpoints
+
+Use `addNoEndpointType()` for types that should be included in the GraphQL schema but don't need their own CRUD operations:
+
+```javascript
+simfinity.addNoEndpointType(TypeName);
+```
+
+**When to use `addNoEndpointType()` vs `connect()`:**
+
+| Method | Use Case | Creates Endpoints | Use Example |
+|--------|----------|-------------------|-------------|
+| `connect()` | Types that need CRUD operations | ✅ Yes | User, Product, Order |
+| `addNoEndpointType()` | Types only used in relationships | ❌ No | Address, Settings, Director |
+
+#### Perfect Example: TV Series with Embedded Director
+
+From the [series-sample](https://github.com/simtlix/series-sample) project:
+
+```javascript
+// Director type - Used only as embedded data, no direct API access needed
+const directorType = new GraphQLObjectType({
+  name: 'director',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: new GraphQLNonNull(GraphQLString) },
+    country: { type: GraphQLString }
+  })
+});
+
+// Add to schema WITHOUT creating endpoints
+simfinity.addNoEndpointType(directorType);
+
+// Serie type - Has its own endpoints and embeds director data
+const serieType = new GraphQLObjectType({
+  name: 'serie',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: new GraphQLNonNull(GraphQLString) },
+    categories: { type: new GraphQLList(GraphQLString) },
+    director: {
+      type: new GraphQLNonNull(directorType),
+      extensions: {
+        relation: {
+          embedded: true,  // Director data stored within serie document
+          displayField: 'name'
+        }
+      }
+    }
+  })
+});
+
+// Create full CRUD endpoints for series
+simfinity.connect(null, serieType, 'serie', 'series');
+```
+
+**Result:**
+- ✅ `addserie`, `updateserie`, `deleteserie` mutations available
+- ✅ `serie`, `series` queries available  
+- ❌ No `adddirector`, `director`, `directors` endpoints (director is embedded)
+
+**Usage:**
+```graphql
+mutation {
+  addserie(input: {
+    name: "Breaking Bad"
+    categories: ["crime", "drama", "thriller"]
+    director: { 
+      name: "Vince Gilligan" 
+      country: "United States" 
+    }
+  }) {
+    id
+    name
+    director {
+      name
+      country
+    }
+  }
+}
+```
+
+#### When to Use Each Approach
+
+**Use `addNoEndpointType()` for:**
+- Simple data objects with few fields
+- Data that doesn't need CRUD operations  
+- Objects that belong to a single parent (1:1 relationships)
+- Configuration or settings objects
+- **Examples**: Address, Director info, Product specifications
+
+**Use `connect()` for:**
+- Complex entities that need their own endpoints
+- Data that needs CRUD operations
+- Objects shared between multiple parents (many:many relationships)  
+- Objects with business logic (controllers, state machines)
+- **Examples**: User, Product, Order, Season, Episode
+
 ### Embedded vs Referenced Relationships
 
 **Referenced Relationships** (default):
@@ -853,7 +1191,7 @@ simfinity.registerMutation(
 
 ### Adding Types Without Endpoints
 
-Include types in the schema without generating endpoints:
+Include types in the schema without generating endpoints. See the [detailed guide on addNoEndpointType()](#adding-types-without-endpoints) for when and how to use this pattern:
 
 ```javascript
 // This type can be used in relationships but won't have queries/mutations
@@ -1031,3 +1369,757 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 *Built with ❤️ by [Simtlix](https://github.com/simtlix)*
 
 
+## 📚 Query Examples from Series-Sample
+
+Here are some practical GraphQL query examples from the series-sample project, showcasing how to use simfinity.js effectively:
+
+### 1. Series with Directors from a Specific Country
+
+Find all series that have directors from the United States:
+
+```graphql
+query {
+  series(director: {
+    terms: [
+      {
+        path: "country",
+        operator: EQ,
+        value: "United States"
+      }
+    ]
+  }) {
+    id
+    name
+    categories
+    director {
+      name
+      country
+    }
+  }
+}
+```
+
+### 2. Series with a Specific Episode Name
+
+Find series that contain an episode with the name "Pilot":
+
+```graphql
+query {
+  series(
+    seasons: {
+      terms: [
+        {
+          path: "episodes.name",
+          operator: EQ,
+          value: "Pilot"
+        }
+      ]
+    }
+  ) {
+    id
+    name
+    seasons {
+      number
+      episodes {
+        number
+        name
+        date
+      }
+    }
+  }
+}
+```
+
+### 3. Series with a Particular Star
+
+Find series that feature "Bryan Cranston":
+
+```graphql
+query {
+  assignedStarsAndSeries(star: {
+    terms: [
+      {
+        path: "name",
+        operator: EQ,
+        value: "Bryan Cranston"
+      }
+    ]
+  }) {
+    id
+    star {
+      name
+    }
+    serie {
+      id
+      name
+      categories
+      director {
+        name
+        country
+      }
+    }
+  }
+}
+```
+
+### 4. Seasons from Series with Directors from a Given Country
+
+Find all seasons that belong to series directed by someone from the United States:
+
+```graphql
+query {
+  seasons(serie: {
+    terms: [
+      {
+        path: "director.country",
+        operator: EQ,
+        value: "United States"
+      }
+    ]
+  }) {
+    id
+    number
+    year
+    state
+    serie {
+      name
+      categories
+      director {
+        name
+        country
+      }
+    }
+    episodes {
+      number
+      name
+      date
+    }
+  }
+}
+```
+
+### 5. Combining Scalar and ObjectType Filters
+
+Find series named "Breaking Bad" that have at least one season with number 1:
+
+```graphql
+query {
+  series(
+    name: {
+      operator: EQ,
+      value: "Breaking Bad"
+    }
+    seasons: {
+      terms: [
+        {
+          path: "number",
+          operator: EQ,
+          value: 1
+        }
+      ]
+    }
+  ) {
+    id
+    name
+    director {
+      name
+      country
+    }
+    seasons {
+      number
+      episodes {
+        name
+      }
+    }
+  }
+}
+```
+
+### 6. Complex Nested Queries
+
+Get complete information for a specific series:
+
+```graphql
+query {
+  series(name: {
+    operator: EQ,
+    value: "Breaking Bad"
+  }) {
+    id
+    name
+    categories
+    director {
+      name
+      country
+    }
+    seasons {
+      number
+      year
+      state
+      episodes {
+        number
+        name
+        date
+      }
+    }
+  }
+}
+```
+
+### 7. Episodes from a Specific Season and Series
+
+Find all episodes from Season 1 of Breaking Bad:
+
+```graphql
+query {
+  episodes(season: {
+    terms: [
+      {
+        path: "number",
+        operator: EQ,
+        value: 1
+      },
+      {
+        path: "serie.name",
+        operator: EQ,
+        value: "Breaking Bad"
+      }
+    ]
+  }) {
+    id
+    number
+    name
+    date
+    season {
+      number
+      serie {
+        name
+      }
+    }
+  }
+}
+```
+
+### 8. Series by Category
+
+Find all crime series:
+
+```graphql
+query {
+  series(categories: {
+    operator: EQ,
+    value: "Crime"
+  }) {
+    id
+    name
+    categories
+    director {
+      name
+      country
+    }
+  }
+}
+```
+
+### 9. Search by Partial Episode Name
+
+Find episodes containing "Fire" in the name:
+
+```graphql
+query {
+  episodes(name: {
+    operator: LIKE,
+    value: "Fire"
+  }) {
+    id
+    number
+    name
+    date
+    season {
+      number
+      serie {
+        name
+      }
+    }
+  }
+}
+```
+
+### 10. Pagination
+
+Simfinity.js supports built-in pagination with optional total count:
+
+```graphql
+query {
+  series(
+    categories: {
+      operator: EQ,
+      value: "Crime"
+    }
+    pagination: {
+      page: 1,
+      size: 2,
+      count: true
+    }
+  ) {
+    id
+    name
+    categories
+    director {
+      name
+      country
+    }
+  }
+}
+```
+
+#### Pagination Parameters:
+- **page**: Page number (starts at 1, not 0)
+- **size**: Number of items per page
+- **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,
+            };
+          }
+        }
+      };
+    }
+  };
+}
+```
+
+#### Example Response:
+```json
+{
+  "data": {
+    "series": [
+      {
+        "id": "1",
+        "name": "Breaking Bad",
+        "categories": ["Crime", "Drama"],
+        "director": {
+          "name": "Vince Gilligan",
+          "country": "United States"
+        }
+      },
+      {
+        "id": "2", 
+        "name": "Better Call Saul",
+        "categories": ["Crime", "Drama"],
+        "director": {
+          "name": "Vince Gilligan",
+          "country": "United States"
+        }
+      }
+    ]
+  },
+  "extensions": {
+    "count": 15
+  }
+}
+```
+
+### 11. Sorting
+
+Simfinity.js supports sorting with multiple fields and sort orders:
+
+```graphql
+query {
+  series(
+    categories: { operator: EQ, value: "Crime" }
+    pagination: { page: 1, size: 5, count: true }
+    sort: {
+      terms: [
+        {
+          field: "name",
+          order: DESC
+        }
+      ]
+    }
+  ) {
+    id
+    name
+    categories
+    director {
+      name
+      country
+    }
+  }
+}
+```
+
+#### Sorting Parameters:
+- **sort**: Contains sorting configuration
+- **terms**: Array of sort criteria (allows multiple sort fields)
+- **field**: The field name to sort by
+- **order**: Sort order - `ASC` (ascending) or `DESC` (descending)
+
+#### Sorting by Nested Fields:
+You can sort by fields from related/nested objects using dot notation:
+
+```graphql
+query {
+  series(
+    categories: { operator: EQ, value: "Drama" }
+    pagination: { page: 1, size: 5, count: true }
+    sort: {
+      terms: [
+        {
+          field: "director.name",
+          order: DESC
+        }
+      ]
+    }
+  ) {
+    id
+    name
+    categories
+    director {
+      name
+      country
+    }
+  }
+}
+```
+
+#### Multiple Sort Fields:
+You can sort by multiple fields with different orders:
+
+```graphql
+query {
+  series(
+    sort: {
+      terms: [
+        { field: "director.country", order: ASC },
+        { field: "name", order: DESC }
+      ]
+    }
+  ) {
+    id
+    name
+    director {
+      name
+      country
+    }
+  }
+}
+```
+
+#### Combining Features:
+The example above demonstrates combining **filtering**, **pagination**, and **sorting** in a single query - a common pattern for data tables and lists with full functionality.
+
+### 12. Series Released in a Specific Year Range
+
+Find series with seasons released between 2010-2015:
+
+```graphql
+query {
+  seasons(year: {
+    operator: BETWEEN,
+    value: [2010, 2015]
+  }) {
+    id
+    number
+    year
+    serie {
+      name
+      director {
+        name
+        country
+      }
+    }
+  }
+}
+```
+
+
+## 🔄 State Machine Example from Series-Sample
+
+Simfinity.js provides built-in state machine support for managing entity lifecycles. Here's an example of how a state machine is implemented in the Season entity from the series-sample project.
+
+### State Machine Configuration
+
+State machines require **GraphQL Enum Types** to define states and proper state references:
+
+**Step 1: Define the GraphQL Enum Type**
+
+```javascript
+const { GraphQLEnumType } = require('graphql');
+
+const seasonState = new GraphQLEnumType({
+  name: 'seasonState',
+  values: {
+    SCHEDULED: { value: 'SCHEDULED' },
+    ACTIVE: { value: 'ACTIVE' },
+    FINISHED: { value: 'FINISHED' }
+  }
+});
+```
+
+**Step 2: Use Enum in GraphQL Object Type**
+
+```javascript
+const seasonType = new GraphQLObjectType({
+  name: 'season',
+  fields: () => ({
+    id: { type: GraphQLID },
+    number: { type: GraphQLInt },
+    year: { type: GraphQLInt },
+    state: { type: seasonState }, // ← Use the enum type
+    // ... other fields
+  })
+});
+```
+
+**Step 3: Define State Machine with Enum Values**
+
+```javascript
+const stateMachine = {
+  initialState: seasonState.getValue('SCHEDULED'),
+  actions: {
+    activate: {
+      from: seasonState.getValue('SCHEDULED'),
+      to: seasonState.getValue('ACTIVE'),
+      action: async (params) => {
+        console.log('Season activated:', JSON.stringify(params));
+      }
+    },
+    finalize: {
+      from: seasonState.getValue('ACTIVE'),
+      to: seasonState.getValue('FINISHED'),
+      action: async (params) => {
+        console.log('Season finalized:', JSON.stringify(params));
+      }
+    }
+  }
+};
+
+// Connect type with state machine
+simfinity.connect(null, seasonType, 'season', 'seasons', null, null, stateMachine);
+```
+
+### Season States
+
+The Season entity has three states:
+
+1. **SCHEDULED** - Initial state when season is created
+2. **ACTIVE** - Season is currently airing
+3. **FINISHED** - Season has completed airing
+
+### State Transitions
+
+**Available transitions:**
+- `activate`: SCHEDULED → ACTIVE
+- `finalize`: ACTIVE → FINISHED
+
+### State Machine Mutations
+
+Simfinity.js automatically generates state transition mutations:
+
+```graphql
+# Activate a scheduled season
+mutation {
+  activateseason(id: "season_id_here") {
+    id
+    number
+    year
+    state
+    serie {
+      name
+    }
+  }
+}
+```
+
+```graphql
+# Finalize an active season
+mutation {
+  finalizeseason(id: "season_id_here") {
+    id
+    number
+    year
+    state
+    serie {
+      name
+    }
+  }
+}
+```
+
+### State Machine Features
+
+**Validation:**
+- Only valid transitions are allowed
+- Attempting invalid transitions returns an error
+- State field is read-only (managed by state machine)
+
+**Custom Actions:**
+- Each transition can execute custom business logic
+- Actions receive parameters including entity data
+- Actions can perform side effects (logging, notifications, etc.)
+
+**Query by State:**
+```graphql
+query {
+  seasons(state: {
+    operator: EQ,
+    value: ACTIVE
+  }) {
+    id
+    number
+    year
+    state
+    serie {
+      name
+    }
+  }
+}
+```
+
+### State Machine Best Practices
+
+1. **GraphQL Enum Types**: Always define states as GraphQL enums for type safety
+2. **getValue() Method**: Use `enumType.getValue('VALUE')` for state machine configuration
+3. **Initial State**: Define clear initial state using enum values
+4. **Linear Flows**: Design logical progression (SCHEDULED → ACTIVE → FINISHED)
+5. **Type Safety**: GraphQL enums provide validation and autocomplete
+6. **Actions**: Implement side effects in transition actions
+7. **Error Handling**: Handle transition failures gracefully
+
+### Key Implementation Points
+
+- **Enum Definition**: States must be defined as `GraphQLEnumType`
+- **Type Reference**: Use the enum type in your GraphQL object: `state: { type: seasonState }`
+- **State Machine Values**: Reference enum values with `seasonState.getValue('STATE_NAME')`
+- **Automatic Validation**: GraphQL validates state values against the enum
+- **IDE Support**: Enum values provide autocomplete and type checking
+
+### Example Workflow
+
+```graphql
+# 1. Create season (automatically SCHEDULED)
+mutation {
+  addseason(input: {
+    number: 6
+    year: 2024
+    serie: "series_id_here"
+  }) {
+    id
+    state  # Will be "SCHEDULED"
+  }
+}
+
+# 2. Activate season when airing begins
+mutation {
+  activateseason(id: "season_id_here") {
+    id
+    state  # Will be "ACTIVE"
+  }
+}
+
+# 3. Finalize season when completed
+mutation {
+  finalizeseason(id: "season_id_here") {
+    id
+    state  # Will be "FINISHED"
+  }
+}
+```
+
+
+## 📦 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,
+            };
+          }
+        }
+      };
+    }
+  };
+}
+```
+
+### How to Use
+
+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.
+
+### Example Usage
+
+```javascript
+const { envelop, useSchema } = require('@envelop/core');
+const { makeExecutableSchema } = require('@graphql-tools/schema');
+
+const schema = makeExecutableSchema({
+  typeDefs,
+  resolvers,
+});
+
+const getEnveloped = envelop({
+  plugins: [
+    useSchema(schema),
+    useCountPlugin(), // Add the count plugin here
+  ],
+});
+
+// Use getEnveloped in your server setup
+```
+
+### Example Response
+
+When the plugin is correctly set up, your GraphQL response will include the count in the extensions:
+
+```json
+{
+  "data": {
+    "series": [
+      {
+        "id": "1",
+        "name": "Breaking Bad",
+        "categories": ["Crime", "Drama"],
+        "director": {
+          "name": "Vince Gilligan",
+          "country": "United States"
+        }
+      }
+    ]
+  },
+  "extensions": {
+    "count": 15
+  }
+}
+```
+
+This setup allows you to efficiently manage and display pagination information in your GraphQL applications.
+
+