@simtlix/simfinity-js 1.5.0 → 1.7.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
@@ -894,6 +1232,11 @@ const newBook = await simfinity.saveObject('Book', {
 const BookModel = simfinity.getModel(BookType);
 const books = await BookModel.find({ author: 'Douglas Adams' });
 
+// Get the GraphQL type definition by name
+const UserType = simfinity.getType('User');
+console.log(UserType.name); // 'User'
+console.log(UserType.getFields()); // Access GraphQL fields
+
 // Get the input type for a GraphQL type
 const BookInput = simfinity.getInputType(BookType);
 ```
@@ -1031,3 +1374,1023 @@ 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.
+
+## 📖 API Reference
+
+Simfinity.js provides several utility methods for programmatic access to your GraphQL types and data:
+
+### `getType(typeName)`
+
+Retrieves a GraphQL type definition from the internal types registry.
+
+**Parameters:**
+- `typeName` (string | GraphQLObjectType): The name of the type or a GraphQL type object
+
+**Returns:**
+- `GraphQLObjectType | null`: The GraphQL type definition, or null if not found
+
+**Examples:**
+
+```javascript
+import { getType } from '@simtlix/simfinity-js';
+
+// Get type by string name
+const UserType = getType('User');
+if (UserType) {
+  console.log(UserType.name); // 'User'
+  
+  // Access field definitions
+  const fields = UserType.getFields();
+  console.log(Object.keys(fields)); // ['id', 'name', 'email', ...]
+  
+  // Check specific field
+  const nameField = fields.name;
+  console.log(nameField.type); // GraphQLString
+}
+
+// Get type by GraphQL type object
+const BookType = getType(SomeBookType);
+
+// Safe access - returns null if not found
+const nonExistentType = getType('NonExistent');
+console.log(nonExistentType); // null
+```
+
+**Use Cases:**
+- **Type introspection**: Examine type definitions programmatically
+- **Dynamic schema analysis**: Build tools that analyze your GraphQL schema
+- **Runtime type checking**: Validate types exist before operations
+- **Admin interfaces**: Build dynamic forms based on type definitions
+- **Circular reference resolution**: Prevent import cycles when types reference each other
+
+### Preventing Circular References with `getType`
+
+When you have types that reference each other (like User and Group), using `getType` prevents circular import issues:
+
+```javascript
+import { GraphQLObjectType, GraphQLID, GraphQLString, GraphQLList } from 'graphql';
+import { getType } from '@simtlix/simfinity-js';
+
+// User type that references Group
+const UserType = new GraphQLObjectType({
+  name: 'User',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    email: { type: GraphQLString },
+    
+    // Reference Group type by name to avoid circular imports
+    groups: {
+      type: new GraphQLList(() => getType('Group')), // Use getType instead of direct import
+      extensions: {
+        relation: {
+          connectionField: 'members',
+          displayField: 'name'
+        }
+      }
+    },
+    
+    // Single group reference
+    primaryGroup: {
+      type: () => getType('Group'), // Lazy evaluation with getType
+      extensions: {
+        relation: {
+          connectionField: 'primaryGroupId',
+          displayField: 'name'
+        }
+      }
+    }
+  })
+});
+
+// Group type that references User
+const GroupType = new GraphQLObjectType({
+  name: 'Group',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    description: { type: GraphQLString },
+    
+    // Reference User type by name to avoid circular imports
+    members: {
+      type: new GraphQLList(() => getType('User')), // Use getType instead of direct import
+      extensions: {
+        relation: {
+          connectionField: 'groups',
+          displayField: 'name'
+        }
+      }
+    },
+    
+    // Single user reference (admin)
+    admin: {
+      type: () => getType('User'), // Lazy evaluation with getType
+      extensions: {
+        relation: {
+          connectionField: 'adminId',
+          displayField: 'name'
+        }
+      }
+    }
+  })
+});
+
+// Register types with simfinity
+simfinity.connect(null, UserType, 'user', 'users');
+simfinity.connect(null, GroupType, 'group', 'groups');
+
+// Create schema - resolvers will be auto-generated for all relationships
+const schema = simfinity.createSchema();
+```
+
+**Benefits of this approach:**
+
+1. **🔄 No Circular Imports**: Each file can import `getType` without importing other type definitions
+2. **⚡ Lazy Resolution**: Types are resolved at schema creation time when all types are registered
+3. **🛡️ Type Safety**: Still maintains GraphQL type checking and validation
+4. **🧹 Clean Architecture**: Separates type definitions from type relationships
+5. **📦 Better Modularity**: Each type can be in its own file without import dependencies
+
+**File Structure Example:**
+
+```
+types/
+├── User.js          // Defines UserType using getType('Group')
+├── Group.js         // Defines GroupType using getType('User')
+└── index.js         // Registers all types and creates schema
+```
+
+```javascript
+// types/User.js
+import { GraphQLObjectType, GraphQLID, GraphQLString, GraphQLList } from 'graphql';
+import { getType } from '@simtlix/simfinity-js';
+
+export const UserType = new GraphQLObjectType({
+  name: 'User',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    groups: {
+      type: new GraphQLList(() => getType('Group')),
+      extensions: { relation: { connectionField: 'members' } }
+    }
+  })
+});
+
+// types/Group.js  
+import { GraphQLObjectType, GraphQLID, GraphQLString, GraphQLList } from 'graphql';
+import { getType } from '@simtlix/simfinity-js';
+
+export const GroupType = new GraphQLObjectType({
+  name: 'Group', 
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: { type: GraphQLString },
+    members: {
+      type: new GraphQLList(() => getType('User')),
+      extensions: { relation: { connectionField: 'groups' } }
+    }
+  })
+});
+
+// types/index.js
+import { UserType } from './User.js';
+import { GroupType } from './Group.js';
+import simfinity from '@simtlix/simfinity-js';
+
+// Register all types
+simfinity.connect(null, UserType, 'user', 'users');
+simfinity.connect(null, GroupType, 'group', 'groups');
+
+// Create schema with auto-generated resolvers
+export const schema = simfinity.createSchema();
+```
+
+### `getModel(gqltype)`
+
+Retrieves the Mongoose model associated with a GraphQL type.
+
+**Parameters:**
+- `gqltype` (GraphQLObjectType): The GraphQL type object
+
+**Returns:**
+- `MongooseModel`: The associated Mongoose model
+
+**Example:**
+
+```javascript
+const BookModel = simfinity.getModel(BookType);
+const books = await BookModel.find({ author: 'Douglas Adams' });
+```
+
+### `getInputType(type)`
+
+Retrieves the input type for mutations associated with a GraphQL type.
+
+**Parameters:**
+- `type` (GraphQLObjectType): The GraphQL type object
+
+**Returns:**
+- `GraphQLInputObjectType`: The input type for mutations
+
+**Example:**
+
+```javascript
+const BookInput = simfinity.getInputType(BookType);
+console.log(BookInput.getFields()); // Input fields for mutations
+```
+
+### `saveObject(typeName, args, session?)`
+
+Programmatically save an object outside of GraphQL mutations.
+
+**Parameters:**
+- `typeName` (string): The name of the GraphQL type
+- `args` (object): The data to save
+- `session` (MongooseSession, optional): Database session for transactions
+
+**Returns:**
+- `Promise<object>`: The saved object
+
+**Example:**
+
+```javascript
+const newBook = await simfinity.saveObject('Book', {
+  title: 'New Book',
+  author: 'Author Name'
+}, session);
+```
+
+### `createSchema(includedQueryTypes?, includedMutationTypes?, includedCustomMutations?)`
+
+Creates the final GraphQL schema with all connected types.
+
+**Parameters:**
+- `includedQueryTypes` (array, optional): Limit query types to include
+- `includedMutationTypes` (array, optional): Limit mutation types to include  
+- `includedCustomMutations` (array, optional): Limit custom mutations to include
+
+**Returns:**
+- `GraphQLSchema`: The complete GraphQL schema
+
+**Example:**
+
+```javascript
+const schema = simfinity.createSchema();
+```
+
+*Built with ❤️ by [Simtlix](https://github.com/simtlix)*
+
+