@simtlix/simfinity-js 2.4.1 → 2.4.4

package/README.md

@@ -16,31 +16,20 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
   - [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)
-- [Authorization](#-authorization)
-  - [Quick Start](#quick-start-1)
-  - [Permission Schema](#permission-schema)
-  - [Rule Helpers](#rule-helpers)
-  - [Policy Expressions (JSON AST)](#policy-expressions-json-ast)
-  - [Integration with GraphQL Yoga / Envelop](#integration-with-graphql-yoga--envelop)
-  - [Legacy: Integration with graphql-middleware](#legacy-integration-with-graphql-middleware)
 - [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)
+- [State Machines](#-state-machines)
+- [Controllers & Lifecycle Hooks](#️-controllers--lifecycle-hooks)
+  - [Hook Parameters](#hook-parameters)
 - [Query Scope](#-query-scope)
   - [Overview](#overview)
   - [Defining Scope](#defining-scope)
@@ -48,6 +37,17 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
   - [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)
+- [Authorization](#-authorization)
+  - [Quick Start](#quick-start-1)
+  - [Permission Schema](#permission-schema)
+  - [Rule Helpers](#rule-helpers)
+  - [Policy Expressions (JSON AST)](#policy-expressions-json-ast)
+  - [Integration with GraphQL Yoga / Envelop](#integration-with-graphql-yoga--envelop)
+  - [Legacy: Integration with graphql-middleware](#legacy-integration-with-graphql-middleware)
+- [Middlewares](#-middlewares)
+  - [Adding Middlewares](#adding-middlewares)
+  - [Middleware Parameters](#middleware-parameters)
+  - [Common Use Cases](#common-use-cases)
 - [Advanced Features](#-advanced-features)
   - [Field Extensions](#field-extensions)
   - [Custom Mutations](#custom-mutations)
@@ -58,10 +58,6 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
 - [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
 
@@ -175,6 +171,8 @@ query {
 }
 ```
 
+> For a full working application, see the [Series Sample Project](https://github.com/simtlix/series-sample) -- a complete TV series microservice with types, relationships, state machines, controllers, and authorization.
+
 ## 🔧 Core Concepts
 
 ### Connecting Models
@@ -383,1005 +381,813 @@ query {
 
 **Note**: Collection field filtering uses the exact same format as main query filtering, ensuring consistency across your GraphQL API. All available operators (`EQ`, `NE`, `GT`, `LT`, `GTE`, `LTE`, `LIKE`, `IN`, `NIN`, `BTW`) work with collection fields.
 
-## 🔧 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.
+## 🔗 Relationships
 
-### Adding Middlewares
+### Defining Relationships
 
-Register middlewares using `simfinity.use()`. Middlewares execute in the order they're registered:
+Use the `extensions.relation` field to define relationships between types:
 
 ```javascript
-// Basic logging middleware
-simfinity.use((params, next) => {
-  console.log(`Executing ${params.operation} on ${params.type?.name || 'custom mutation'}`);
-  next();
+const AuthorType = new GraphQLObjectType({
+  name: 'Author',
+  fields: () => ({
+    id: { type: new GraphQLNonNull(GraphQLID) },
+    name: { type: new GraphQLNonNull(GraphQLString) },
+    books: {
+      type: new GraphQLList(BookType),
+      extensions: {
+        relation: {
+          connectionField: 'author',
+          displayField: 'title'
+        },
+      },
+      // resolve method automatically generated! 🎉
+    },
+  }),
 });
-```
-
-### 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();
+const BookType = new GraphQLObjectType({
+  name: 'Book',
+  fields: () => ({
+    id: { type: new GraphQLNonNull(GraphQLID) },
+    title: { type: new GraphQLNonNull(GraphQLString) },
+    author: {
+      type: AuthorType,
+      extensions: {
+        relation: {
+          displayField: 'name'
+        },
+      },
+      // resolve method automatically generated! 🎉
+    },
+  }),
 });
 ```
 
-### Common Use Cases
+### Relationship Configuration
 
-#### 1. Authentication & Authorization
+- `connectionField`: **(Required for collections)** The field storing the related object's ID - only needed for one-to-many relationships (GraphQLList). For single object relationships, the field name is automatically inferred from the GraphQL field name.
+- `displayField`: **(Optional)** Field to use for display in UI components
+- `embedded`: **(Optional)** Whether the relation is embedded (default: false)
 
-```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();
-});
-```
+### Auto-Generated Resolve Methods
 
-#### 2. Request Logging & Monitoring
+🎉 **NEW**: Simfinity.js automatically generates resolve methods for relationship fields when types are connected, eliminating the need for manual resolver boilerplate.
+
+#### Before (Manual Resolvers)
 
 ```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`);
+const BookType = new GraphQLObjectType({
+  name: 'Book',
+  fields: () => ({
+    id: { type: new GraphQLNonNull(GraphQLID) },
+    title: { type: new GraphQLNonNull(GraphQLString) },
+    author: {
+      type: AuthorType,
+      extensions: {
+        relation: {
+          displayField: 'name'
+        },
+      },
+      // You had to manually write this
+      resolve(parent) {
+        return simfinity.getModel(AuthorType).findById(parent.author);
+      }
+    },
+    comments: {
+      type: new GraphQLList(CommentType),
+      extensions: {
+        relation: {
+          connectionField: 'bookId',
+          displayField: 'text'
+        },
+      },
+      // You had to manually write this too
+      resolve(parent) {
+        return simfinity.getModel(CommentType).find({ bookId: parent.id });
+      }
+    }
+  }),
 });
 ```
 
-#### 3. Input Validation & Sanitization
+#### After (Auto-Generated Resolvers)
 
 ```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);
+const BookType = new GraphQLObjectType({
+  name: 'Book',
+  fields: () => ({
+    id: { type: new GraphQLNonNull(GraphQLID) },
+    title: { type: new GraphQLNonNull(GraphQLString) },
+    author: {
+      type: AuthorType,
+      extensions: {
+        relation: {
+          displayField: 'name'
+        },
+      },
+      // resolve method automatically generated! 🎉
+    },
+    comments: {
+      type: new GraphQLList(CommentType),
+      extensions: {
+        relation: {
+          connectionField: 'bookId',
+          displayField: 'text'
+        },
+      },
+      // resolve method automatically generated! 🎉
     }
-  }
-  
-  next();
+  }),
 });
 ```
 
-#### 4. Rate Limiting
+#### How It Works
+
+- **Single Object Relationships**: Automatically generates `findById()` resolvers using the field name or `connectionField`
+- **Collection Relationships**: Automatically generates `find()` resolvers using the `connectionField` to query related objects
+- **Lazy Loading**: Models are looked up at runtime, so types can be connected in any order
+- **Backwards Compatible**: Existing manual resolve methods are preserved and not overwritten
+- **Type Safety**: Clear error messages if related types aren't properly connected
+
+#### Connect Your Types
 
 ```javascript
-const requestCounts = new Map();
+// Connect all your types to Simfinity
+simfinity.connect(null, AuthorType, 'author', 'authors');
+simfinity.connect(null, BookType, 'book', 'books');
+simfinity.connect(null, CommentType, 'comment', 'comments');
 
-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();
-});
+// Or use addNoEndpointType for types that don't need direct queries/mutations
+simfinity.addNoEndpointType(AuthorType);
 ```
 
-#### 5. Audit Trail
+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.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();
-});
+simfinity.addNoEndpointType(TypeName);
 ```
 
-### Multiple Middlewares
+**When to use `addNoEndpointType()` vs `connect()`:**
 
-Middlewares execute in registration order. Each middleware must call `next()` to continue the chain:
+| 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 |
 
-```javascript
-// Middleware 1: Authentication
-simfinity.use((params, next) => {
-  console.log('1. Checking authentication...');
-  // Authentication logic here
-  next(); // Continue to next middleware
-});
+#### Perfect Example: TV Series with Embedded Director
 
-// Middleware 2: Authorization  
-simfinity.use((params, next) => {
-  console.log('2. Checking permissions...');
-  // Authorization logic here
-  next(); // Continue to next middleware
-});
+From the [series-sample](https://github.com/simtlix/series-sample) project:
 
-// Middleware 3: Logging
-simfinity.use((params, next) => {
-  console.log('3. Logging request...');
-  // Logging logic here
-  next(); // Continue to GraphQL operation
+```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 }
+  })
 });
-```
 
-### Error Handling in Middlewares
-
-Middlewares can throw errors to stop the operation:
+// Add to schema WITHOUT creating endpoints
+simfinity.addNoEndpointType(directorType);
 
-```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);
+// 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'
+        }
+      }
     }
-    
-    next(); // Continue only if validation passes
-  } catch (error) {
-    // Error automatically bubbles up to GraphQL error handling
-    throw error;
-  }
+  })
 });
-```
 
-### Conditional Middleware Execution
+// Create full CRUD endpoints for series
+simfinity.connect(null, serieType, 'serie', 'series');
+```
 
-Execute middleware logic conditionally based on operation type or context:
+**Result:**
+- ✅ `addserie`, `updateserie`, `deleteserie` mutations available
+- ✅ `serie`, `series` queries available  
+- ❌ No `adddirector`, `director`, `directors` endpoints (director is embedded)
 
-```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);
+**Usage:**
+```graphql
+mutation {
+  addserie(input: {
+    name: "Breaking Bad"
+    categories: ["crime", "drama", "thriller"]
+    director: { 
+      name: "Vince Gilligan" 
+      country: "United States" 
+    }
+  }) {
+    id
+    name
+    director {
+      name
+      country
     }
   }
-  
-  // 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
+#### When to Use Each Approach
 
-## 🔐 Authorization
+**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
 
-Simfinity.js provides production-grade centralized GraphQL authorization supporting RBAC/ABAC, function-based rules, declarative policy expressions (JSON AST), wildcard permissions, and configurable default policies. It ships as a native Envelop plugin for GraphQL Yoga (recommended) and also supports the legacy graphql-middleware approach.
+**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
 
-### Quick Start
+### Embedded vs Referenced Relationships
 
+**Referenced Relationships** (default):
 ```javascript
-const { auth } = require('@simtlix/simfinity-js');
-const { createYoga } = require('graphql-yoga');
-
-const { createAuthPlugin, requireAuth, requireRole } = auth;
-
-// Define your permission schema
-const permissions = {
-  Query: {
-    users: requireAuth(),
-    adminDashboard: requireRole('ADMIN'),
-  },
-  Mutation: {
-    publishPost: requireRole('EDITOR'),
-  },
-  User: {
-    '*': requireAuth(),           // Wildcard: all fields require auth
-    email: requireRole('ADMIN'),  // Override: email requires ADMIN role
-  },
-  Post: {
-    '*': requireAuth(),
-    content: async (post, _args, ctx) => {
-      // Custom logic: allow if published OR if author
-      if (post.published) return true;
-      if (post.authorId === ctx.user?.id) return true;
-      return false;
-    },
-  },
-};
+// Stores author ID in the book document
+author: {
+  type: AuthorType,
+  extensions: {
+    relation: {
+      // connectionField not needed for single object relationships
+      embedded: false  // This is the default
+    }
+  }
+}
+```
 
-// Create the Envelop auth plugin and pass it to your server
-const authPlugin = createAuthPlugin(permissions, { defaultPolicy: 'DENY' });
-const yoga = createYoga({ schema, plugins: [authPlugin] });
+**Embedded Relationships**:
+```javascript
+// Stores the full publisher object in the book document
+publisher: {
+  type: PublisherType,
+  extensions: {
+    relation: {
+      embedded: true
+    }
+  }
+}
 ```
 
-### Permission Schema
+### Querying Relationships
 
-The permission schema defines authorization rules per type and field:
+Query nested relationships with dot notation:
 
-```javascript
-const permissions = {
-  // Operation types (Query, Mutation, Subscription)
-  Query: {
-    fieldName: ruleOrRules,
-  },
-  
-  // Object types
-  TypeName: {
-    '*': wildcardRule,      // Applies to all fields unless overridden
-    fieldName: specificRule, // Overrides wildcard for this field
-  },
-};
+```graphql
+query {
+  books(author: {
+    terms: [
+      {
+        path: "country.name",
+        operator: EQ,
+        value: "England"
+      }
+    ]
+  }) {
+    id
+    title
+    author {
+      name
+      country {
+        name
+      }
+    }
+  }
+}
 ```
 
-**Resolution Order:**
-1. Check exact field rule: `permissions[TypeName][fieldName]`
-2. Fallback to wildcard: `permissions[TypeName]['*']`
-3. Apply default policy (ALLOW or DENY)
+### Creating Objects with Relationships
 
-**Rule Types:**
-- **Function**: `(parent, args, ctx, info) => boolean | void | Promise<boolean | void>`
-- **Array of functions**: All rules must pass (AND logic)
-- **Policy expression**: JSON AST object (see below)
-
-**Rule Semantics:**
-- `return true` or `return void` → allow
-- `return false` → deny
-- `throw Error` → deny with error
-
-### Rule Helpers
-
-Simfinity.js provides reusable rule builders:
-
-```javascript
-const { auth } = require('@simtlix/simfinity-js');
-
-const {
-  resolvePath,       // Utility to resolve dotted paths in objects
-  requireAuth,       // Requires ctx.user to exist
-  requireRole,       // Requires specific role(s)
-  requirePermission, // Requires specific permission(s)
-  composeRules,      // Combine rules (AND logic)
-  anyRule,           // Combine rules (OR logic)
-  isOwner,           // Check resource ownership
-  allow,             // Always allow
-  deny,              // Always deny
-  createRule,        // Create custom rule
-} = auth;
-```
-
-#### requireAuth(userPath?)
-
-Requires the user to be authenticated. Supports custom user paths in context:
-
-```javascript
-const permissions = {
-  Query: {
-    // Default: checks ctx.user
-    me: requireAuth(),
-    
-    // Custom path: checks ctx.auth.currentUser
-    profile: requireAuth('auth.currentUser'),
-    
-    // Deep path: checks ctx.session.data.user
-    settings: requireAuth('session.data.user'),
-  },
-};
-```
-
-#### requireRole(role, options?)
-
-Requires the user to have a specific role. Supports custom paths:
-
-```javascript
-const permissions = {
-  Query: {
-    // Default: checks ctx.user.role
-    adminDashboard: requireRole('ADMIN'),
-    modTools: requireRole(['ADMIN', 'MODERATOR']), // Any of these roles
-    
-    // Custom paths: checks ctx.auth.user.profile.role
-    superAdmin: requireRole('SUPER_ADMIN', { 
-      userPath: 'auth.user', 
-      rolePath: 'profile.role',
-    }),
-  },
-};
+**Link to existing objects:**
+```graphql
+mutation {
+  addBook(input: {
+    title: "New Book"
+    author: {
+      id: "existing_author_id"
+    }
+  }) {
+    id
+    title
+    author {
+      name
+    }
+  }
+}
 ```
 
-#### requirePermission(permission, options?)
-
-Requires the user to have specific permission(s). Supports custom paths:
-
-```javascript
-const permissions = {
-  Mutation: {
-    // Default: checks ctx.user.permissions
-    deletePost: requirePermission('posts:delete'),
-    manageUsers: requirePermission(['users:read', 'users:write']), // All required
-    
-    // Custom paths: checks ctx.session.user.access.grants
-    admin: requirePermission('admin:all', {
-      userPath: 'session.user',
-      permissionsPath: 'access.grants',
-    }),
-  },
-};
+**Create embedded objects:**
+```graphql
+mutation {
+  addBook(input: {
+    title: "New Book"
+    publisher: {
+      name: "Penguin Books"
+      location: "London"
+    }
+  }) {
+    id
+    title
+    publisher {
+      name
+      location
+    }
+  }
+}
 ```
 
-#### composeRules(...rules)
+### Collection Fields
 
-Combines multiple rules with AND logic (all must pass):
+Work with arrays of related objects:
 
-```javascript
-const permissions = {
-  Mutation: {
-    updatePost: composeRules(
-      requireAuth(),
-      requireRole('EDITOR'),
-      async (post, args, ctx) => post.authorId === ctx.user.id,
-    ),
-  },
-};
+```graphql
+mutation {
+  updateBook(input: {
+    id: "book_id"
+    reviews: {
+      added: [
+        { rating: 5, comment: "Amazing!" }
+        { rating: 4, comment: "Good read" }
+      ]
+      updated: [
+        { id: "review_id", rating: 3 }
+      ]
+      deleted: ["review_id_to_delete"]
+    }
+  }) {
+    id
+    title
+    reviews {
+      rating
+      comment
+    }
+  }
+}
 ```
 
-#### anyRule(...rules)
-
-Combines multiple rules with OR logic (any must pass):
+## ✅ Validations
 
-```javascript
-const permissions = {
-  Post: {
-    content: anyRule(
-      requireRole('ADMIN'),
-      async (post, args, ctx) => post.authorId === ctx.user.id,
-    ),
-  },
-};
-```
+### Declarative Validation Helpers
 
-#### isOwner(ownerField, userIdField)
+Simfinity.js provides built-in validation helpers to simplify common validation patterns, eliminating verbose boilerplate code.
 
-Checks if the authenticated user owns the resource:
+#### Using Validators
 
 ```javascript
-const permissions = {
-  Post: {
-    '*': composeRules(
-      requireAuth(),
-      isOwner('authorId', 'id'), // Compares post.authorId with ctx.user.id
-    ),
-  },
-};
-```
-
-### Policy Expressions (JSON AST)
-
-For declarative rules, use JSON AST policy expressions:
+const { validators } = require('@simtlix/simfinity-js');
 
-```javascript
-const permissions = {
-  Post: {
-    content: {
-      anyOf: [
-        { eq: [{ ref: 'parent.published' }, true] },
-        { eq: [{ ref: 'parent.authorId' }, { ref: 'ctx.user.id' }] },
-      ],
+const PersonType = new GraphQLObjectType({
+  name: 'Person',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.stringLength('Name', 2, 100)
+      }
     },
-  },
-};
-```
-
-**Supported Operators:**
-
-| Operator | Description | Example |
-|----------|-------------|---------|
-| `eq` | Equals | `{ eq: [{ ref: 'parent.status' }, 'active'] }` |
-| `in` | Value in array | `{ in: [{ ref: 'ctx.user.role' }, ['ADMIN', 'MOD']] }` |
-| `allOf` | All must be true (AND) | `{ allOf: [expr1, expr2] }` |
-| `anyOf` | Any must be true (OR) | `{ anyOf: [expr1, expr2] }` |
-| `not` | Negation | `{ not: { eq: [{ ref: 'parent.deleted' }, true] } }` |
-
-**References:**
-
-Use `{ ref: 'path' }` to reference values:
-- `parent.*` - Parent resolver result (the object being resolved)
-- `args.*` - GraphQL arguments
-- `ctx.*` - GraphQL context
-
-**Security:**
-- Only `parent`, `args`, and `ctx` roots are allowed
-- Unknown operators fail closed (deny)
-- No `eval()` or `Function()` - pure object traversal
-
-### Integration with GraphQL Yoga / Envelop
-
-The recommended way to use the auth system is via the Envelop plugin, which works natively with GraphQL Yoga and any Envelop-based server. The plugin wraps resolvers in-place without rebuilding the schema, avoiding compatibility issues.
-
-```javascript
-const { createYoga } = require('graphql-yoga');
-const { createServer } = require('http');
-const simfinity = require('@simtlix/simfinity-js');
-
-const { auth } = simfinity;
-const { createAuthPlugin, requireAuth, requireRole, requirePermission } = auth;
-
-// Define your types and connect them
-simfinity.connect(null, UserType, 'user', 'users');
-simfinity.connect(null, PostType, 'post', 'posts');
-
-// Create base schema
-const schema = simfinity.createSchema();
-
-// Define permissions
-const permissions = {
-  Query: {
-    users: requireAuth(),
-    user: requireAuth(),
-    posts: requireAuth(),
-    post: requireAuth(),
-  },
-  Mutation: {
-    adduser: requireRole('ADMIN'),
-    updateuser: requireRole('ADMIN'),
-    deleteuser: requireRole('ADMIN'),
-    addpost: requireAuth(),
-    updatepost: composeRules(requireAuth(), isOwner('authorId')),
-    deletepost: requireRole('ADMIN'),
-  },
-  User: {
-    '*': requireAuth(),
-    email: requireRole('ADMIN'),
-    password: deny('Password field is not accessible'),
-  },
-  Post: {
-    '*': requireAuth(),
-    content: {
-      anyOf: [
-        { eq: [{ ref: 'parent.published' }, true] },
-        { eq: [{ ref: 'parent.authorId' }, { ref: 'ctx.user.id' }] },
-      ],
+    email: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.email()
+      }
     },
-  },
-};
-
-// Create auth plugin
-const authPlugin = createAuthPlugin(permissions, {
-  defaultPolicy: 'DENY',
-  debug: false,
-});
-
-// Setup Yoga with the auth plugin
-const yoga = createYoga({
-  schema,
-  plugins: [authPlugin],
-  context: (req) => ({
-    user: req.user,  // Set by your authentication layer
-  }),
-});
-
-const server = createServer(yoga);
-server.listen(4000);
-```
-
-### Legacy: Integration with graphql-middleware
-
-> **Deprecated:** `applyMiddleware` from `graphql-middleware` rebuilds the schema via `mapSchema`,
-> which can cause `"Schema must contain uniquely named types"` errors with Simfinity schemas.
-> Use `createAuthPlugin` with GraphQL Yoga / Envelop instead.
-
-```javascript
-const { applyMiddleware } = require('graphql-middleware');
-const simfinity = require('@simtlix/simfinity-js');
-
-const { auth } = simfinity;
-const { createAuthMiddleware, requireAuth, requireRole } = auth;
-
-const baseSchema = simfinity.createSchema();
-
-const authMiddleware = createAuthMiddleware(permissions, {
-  defaultPolicy: 'DENY',
+    website: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.url()
+      }
+    },
+    age: {
+      type: GraphQLInt,
+      extensions: {
+        validations: validators.numberRange('Age', 0, 120)
+      }
+    },
+    price: {
+      type: GraphQLFloat,
+      extensions: {
+        validations: validators.positive('Price')
+      }
+    }
+  })
 });
-
-const schema = applyMiddleware(baseSchema, authMiddleware);
 ```
 
-### Plugin / Middleware Options
-
-```javascript
-const plugin = createAuthPlugin(permissions, {
-  defaultPolicy: 'DENY',  // 'ALLOW' or 'DENY' (default: 'DENY')
-  debug: false,           // Enable debug logging
-});
-```
+#### Available Validators
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `defaultPolicy` | `'ALLOW' \| 'DENY'` | `'DENY'` | Policy when no rule matches |
-| `debug` | `boolean` | `false` | Log authorization decisions |
+**String Validators:**
+- `validators.stringLength(name, min, max)` - Validates string length with min/max bounds (required for CREATE)
+- `validators.maxLength(name, max)` - Validates maximum string length
+- `validators.pattern(name, regex, message)` - Validates against a regex pattern
+- `validators.email()` - Validates email format
+- `validators.url()` - Validates URL format
 
-### Error Handling
+**Number Validators:**
+- `validators.numberRange(name, min, max)` - Validates number range
+- `validators.positive(name)` - Ensures number is positive
 
-The auth middleware uses Simfinity error classes:
+**Array Validators:**
+- `validators.arrayLength(name, maxItems, itemValidator)` - Validates array length and optionally each item
 
-```javascript
-const { auth } = require('@simtlix/simfinity-js');
+**Date Validators:**
+- `validators.dateFormat(name, format)` - Validates date format
+- `validators.futureDate(name)` - Ensures date is in the future
 
-const { UnauthenticatedError, ForbiddenError } = auth;
+#### Validator Features
 
-// UnauthenticatedError: code 'UNAUTHENTICATED', status 401
-// ForbiddenError: code 'FORBIDDEN', status 403
-```
+- **Automatic Operation Handling**: Validators work for both `CREATE` (save) and `UPDATE` operations
+- **Smart Validation**: For CREATE operations, values are required. For UPDATE operations, undefined/null values are allowed (field might not be updated)
+- **Consistent Error Messages**: All validators throw `SimfinityError` with appropriate messages
 
-Custom error handling in rules:
+#### Example: Multiple Validators
 
 ```javascript
-const permissions = {
-  Mutation: {
-    deleteAccount: async (parent, args, ctx) => {
-      if (!ctx.user) {
-        throw new auth.UnauthenticatedError('Please log in');
-      }
-      if (ctx.user.role !== 'ADMIN' && ctx.user.id !== args.id) {
-        throw new auth.ForbiddenError('Cannot delete other users');
+const ProductType = new GraphQLObjectType({
+  name: 'Product',
+  fields: () => ({
+    id: { type: GraphQLID },
+    name: {
+      type: GraphQLString,
+      extensions: {
+        validations: validators.stringLength('Product Name', 3, 200)
       }
-      return true;
     },
-  },
-};
-```
-
-### Best Practices
-
-1. **Default to DENY**: Use `defaultPolicy: 'DENY'` for security
-2. **Use wildcards wisely**: `'*'` rules provide baseline security per type
-3. **Prefer helper rules**: Use `requireAuth()`, `requireRole()` over custom functions
-4. **Fail closed**: Custom rules should deny on unexpected conditions
-5. **Keep rules simple**: Complex logic belongs in controllers, not auth rules
-6. **Test thoroughly**: Auth rules are critical - test all scenarios
-
-## 🔗 Relationships
-
-### Defining Relationships
-
-Use the `extensions.relation` field to define relationships between types:
-
-```javascript
-const AuthorType = new GraphQLObjectType({
-  name: 'Author',
-  fields: () => ({
-    id: { type: new GraphQLNonNull(GraphQLID) },
-    name: { type: new GraphQLNonNull(GraphQLString) },
-    books: {
-      type: new GraphQLList(BookType),
+    sku: {
+      type: GraphQLString,
       extensions: {
-        relation: {
-          connectionField: 'author',
-          displayField: 'title'
-        },
-      },
-      // resolve method automatically generated! 🎉
+        validations: validators.pattern('SKU', /^[A-Z0-9-]+$/, 'SKU must be uppercase alphanumeric with hyphens')
+      }
     },
-  }),
-});
-
-const BookType = new GraphQLObjectType({
-  name: 'Book',
-  fields: () => ({
-    id: { type: new GraphQLNonNull(GraphQLID) },
-    title: { type: new GraphQLNonNull(GraphQLString) },
-    author: {
-      type: AuthorType,
+    price: {
+      type: GraphQLFloat,
       extensions: {
-        relation: {
-          displayField: 'name'
-        },
-      },
-      // resolve method automatically generated! 🎉
+        validations: validators.positive('Price')
+      }
     },
-  }),
+    tags: {
+      type: new GraphQLList(GraphQLString),
+      extensions: {
+        validations: validators.arrayLength('Tags', 10)
+      }
+    }
+  })
 });
 ```
 
-### Relationship Configuration
-
-- `connectionField`: **(Required for collections)** The field storing the related object's ID - only needed for one-to-many relationships (GraphQLList). For single object relationships, the field name is automatically inferred from the GraphQL field name.
-- `displayField`: **(Optional)** Field to use for display in UI components
-- `embedded`: **(Optional)** Whether the relation is embedded (default: false)
+### Field-Level Validations (Manual)
 
-### Auto-Generated Resolve Methods
+For custom validation logic, you can still write manual validators:
 
-🎉 **NEW**: Simfinity.js automatically generates resolve methods for relationship fields when types are connected, eliminating the need for manual resolver boilerplate.
+```javascript
+const { SimfinityError } = require('@simtlix/simfinity-js');
 
-#### Before (Manual Resolvers)
+const validateAge = {
+  validate: async (typeName, fieldName, value, session) => {
+    if (value < 0 || value > 120) {
+      throw new SimfinityError(`Invalid age: ${value}`, 'VALIDATION_ERROR', 400);
+    }
+  }
+};
 
-```javascript
-const BookType = new GraphQLObjectType({
-  name: 'Book',
+const PersonType = new GraphQLObjectType({
+  name: 'Person',
   fields: () => ({
-    id: { type: new GraphQLNonNull(GraphQLID) },
-    title: { type: new GraphQLNonNull(GraphQLString) },
-    author: {
-      type: AuthorType,
+    id: { type: GraphQLID },
+    name: { 
+      type: GraphQLString,
       extensions: {
-        relation: {
-          displayField: 'name'
-        },
-      },
-      // You had to manually write this
-      resolve(parent) {
-        return simfinity.getModel(AuthorType).findById(parent.author);
+        validations: {
+          save: [{
+            validate: async (typeName, fieldName, value, session) => {
+              if (!value || value.length < 2) {
+                throw new SimfinityError('Name must be at least 2 characters', 'VALIDATION_ERROR', 400);
+              }
+            }
+          }],
+          update: [{
+            validate: async (typeName, fieldName, value, session) => {
+              if (value && value.length < 2) {
+                throw new SimfinityError('Name must be at least 2 characters', 'VALIDATION_ERROR', 400);
+              }
+            }
+          }]
+        }
       }
     },
-    comments: {
-      type: new GraphQLList(CommentType),
+    age: {
+      type: GraphQLInt,
       extensions: {
-        relation: {
-          connectionField: 'bookId',
-          displayField: 'text'
-        },
-      },
-      // You had to manually write this too
-      resolve(parent) {
-        return simfinity.getModel(CommentType).find({ bookId: parent.id });
+        validations: {
+          save: [validateAge],
+          update: [validateAge]
+        }
       }
     }
-  }),
+  })
 });
 ```
 
-#### After (Auto-Generated Resolvers)
+### Type-Level Validations
+
+Validate objects as a whole:
 
 ```javascript
-const BookType = new GraphQLObjectType({
-  name: 'Book',
-  fields: () => ({
-    id: { type: new GraphQLNonNull(GraphQLID) },
-    title: { type: new GraphQLNonNull(GraphQLString) },
-    author: {
-      type: AuthorType,
-      extensions: {
-        relation: {
-          displayField: 'name'
-        },
-      },
-      // resolve method automatically generated! 🎉
-    },
-    comments: {
-      type: new GraphQLList(CommentType),
-      extensions: {
-        relation: {
-          connectionField: 'bookId',
-          displayField: 'text'
-        },
-      },
-      // resolve method automatically generated! 🎉
+const orderValidator = {
+  validate: async (typeName, args, modelArgs, session) => {
+    // Cross-field validation
+    if (modelArgs.deliveryDate < modelArgs.orderDate) {
+      throw new SimfinityError('Delivery date cannot be before order date', 'VALIDATION_ERROR', 400);
     }
-  }),
+    
+    // Business rule validation
+    if (modelArgs.items.length === 0) {
+      throw new SimfinityError('Order must contain at least one item', 'BUSINESS_ERROR', 400);
+    }
+  }
+};
+
+const OrderType = new GraphQLObjectType({
+  name: 'Order',
+  extensions: {
+    validations: {
+      save: [orderValidator],
+      update: [orderValidator]
+    }
+  },
+  fields: () => ({
+    // ... fields
+  })
 });
 ```
 
-#### How It Works
+### Custom Validated Scalar Types
 
-- **Single Object Relationships**: Automatically generates `findById()` resolvers using the field name or `connectionField`
-- **Collection Relationships**: Automatically generates `find()` resolvers using the `connectionField` to query related objects
-- **Lazy Loading**: Models are looked up at runtime, so types can be connected in any order
-- **Backwards Compatible**: Existing manual resolve methods are preserved and not overwritten
-- **Type Safety**: Clear error messages if related types aren't properly connected
+Create custom scalar types with built-in validation. The generated type names follow the pattern `{name}_{baseScalarTypeName}`.
 
-#### Connect Your Types
+#### Pre-built Scalars
+
+Simfinity.js provides ready-to-use validated scalars for common patterns:
 
 ```javascript
-// Connect all your types to Simfinity
-simfinity.connect(null, AuthorType, 'author', 'authors');
-simfinity.connect(null, BookType, 'book', 'books');
-simfinity.connect(null, CommentType, 'comment', 'comments');
+const { scalars } = require('@simtlix/simfinity-js');
 
-// Or use addNoEndpointType for types that don't need direct queries/mutations
-simfinity.addNoEndpointType(AuthorType);
+const UserType = new GraphQLObjectType({
+  name: 'User',
+  fields: () => ({
+    id: { type: GraphQLID },
+    email: { type: scalars.EmailScalar },      // Type name: Email_String
+    website: { type: scalars.URLScalar },       // Type name: URL_String
+    age: { type: scalars.PositiveIntScalar },  // Type name: PositiveInt_Int
+    price: { type: scalars.PositiveFloatScalar } // Type name: PositiveFloat_Float
+  }),
+});
 ```
 
-That's it! All relationship resolvers are automatically generated when you connect your types.
+**Available Pre-built Scalars:**
+- `scalars.EmailScalar` - Validates email format (`Email_String`)
+- `scalars.URLScalar` - Validates URL format (`URL_String`)
+- `scalars.PositiveIntScalar` - Validates positive integers (`PositiveInt_Int`)
+- `scalars.PositiveFloatScalar` - Validates positive floats (`PositiveFloat_Float`)
 
-### Adding Types Without Endpoints
+#### Factory Functions for Custom Scalars
 
-Use `addNoEndpointType()` for types that should be included in the GraphQL schema but don't need their own CRUD operations:
+Create custom validated scalars with parameters:
 
 ```javascript
-simfinity.addNoEndpointType(TypeName);
-```
+const { scalars } = require('@simtlix/simfinity-js');
 
-**When to use `addNoEndpointType()` vs `connect()`:**
+// Create a bounded string scalar (name length between 2-100 characters)
+const NameScalar = scalars.createBoundedStringScalar('Name', 2, 100);
 
-| 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 |
+// Create a bounded integer scalar (age between 0-120)
+const AgeScalar = scalars.createBoundedIntScalar('Age', 0, 120);
 
-#### Perfect Example: TV Series with Embedded Director
+// Create a bounded float scalar (rating between 0-10)
+const RatingScalar = scalars.createBoundedFloatScalar('Rating', 0, 10);
 
-From the [series-sample](https://github.com/simtlix/series-sample) project:
+// Create a pattern-based string scalar (phone number format)
+const PhoneScalar = scalars.createPatternStringScalar(
+  'Phone',
+  /^\+?[\d\s\-()]+$/,
+  'Invalid phone number format'
+);
 
-```javascript
-// Director type - Used only as embedded data, no direct API access needed
-const directorType = new GraphQLObjectType({
-  name: 'director',
+// Use in your types
+const PersonType = new GraphQLObjectType({
+  name: 'Person',
   fields: () => ({
     id: { type: GraphQLID },
-    name: { type: new GraphQLNonNull(GraphQLString) },
-    country: { type: GraphQLString }
-  })
+    name: { type: NameScalar },        // Type name: Name_String
+    age: { type: AgeScalar },          // Type name: Age_Int
+    rating: { type: RatingScalar },    // Type name: Rating_Float
+    phone: { type: PhoneScalar }       // Type name: Phone_String
+  }),
 });
+```
 
-// Add to schema WITHOUT creating endpoints
-simfinity.addNoEndpointType(directorType);
+**Available Factory Functions:**
+- `scalars.createBoundedStringScalar(name, min, max)` - String with length bounds
+- `scalars.createBoundedIntScalar(name, min, max)` - Integer with range validation
+- `scalars.createBoundedFloatScalar(name, min, max)` - Float with range validation
+- `scalars.createPatternStringScalar(name, pattern, message)` - String with regex pattern validation
 
-// 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'
-        }
-      }
-    }
-  })
-});
+#### Creating Custom Scalars Manually
 
-// Create full CRUD endpoints for series
-simfinity.connect(null, serieType, 'serie', 'series');
-```
+You can also create custom scalars using `createValidatedScalar` directly:
 
-**Result:**
-- ✅ `addserie`, `updateserie`, `deleteserie` mutations available
-- ✅ `serie`, `series` queries available  
-- ❌ No `adddirector`, `director`, `directors` endpoints (director is embedded)
+```javascript
+const { GraphQLString, GraphQLInt } = require('graphql');
+const { createValidatedScalar } = require('@simtlix/simfinity-js');
 
-**Usage:**
-```graphql
-mutation {
-  addserie(input: {
-    name: "Breaking Bad"
-    categories: ["crime", "drama", "thriller"]
-    director: { 
-      name: "Vince Gilligan" 
-      country: "United States" 
+// Email scalar with validation (generates type name: Email_String)
+const EmailScalar = createValidatedScalar(
+  'Email',
+  'A valid email address',
+  GraphQLString,
+  (value) => {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    if (!emailRegex.test(value)) {
+      throw new Error('Invalid email format');
     }
-  }) {
-    id
-    name
-    director {
-      name
-      country
+  }
+);
+
+// Positive integer scalar (generates type name: PositiveInt_Int)
+const PositiveIntScalar = createValidatedScalar(
+  'PositiveInt',
+  'A positive integer',
+  GraphQLInt,
+  (value) => {
+    if (value <= 0) {
+      throw new Error('Value must be positive');
     }
   }
-}
+);
+
+// Use in your types
+const UserType = new GraphQLObjectType({
+  name: 'User',
+  fields: () => ({
+    id: { type: GraphQLID },
+    email: { type: EmailScalar }, // Type name: Email_String
+    age: { type: PositiveIntScalar }, // Type name: PositiveInt_Int
+  }),
+});
 ```
 
-#### When to Use Each Approach
+### Custom Error Classes
 
-**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
+Create domain-specific error classes:
 
-**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
+```javascript
+const { SimfinityError } = require('@simtlix/simfinity-js');
 
-### Embedded vs Referenced Relationships
+// Business logic error
+class BusinessError extends SimfinityError {
+  constructor(message) {
+    super(message, 'BUSINESS_ERROR', 400);
+  }
+}
 
-**Referenced Relationships** (default):
-```javascript
-// Stores author ID in the book document
-author: {
-  type: AuthorType,
-  extensions: {
-    relation: {
-      // connectionField not needed for single object relationships
-      embedded: false  // This is the default
-    }
+// Authorization error
+class AuthorizationError extends SimfinityError {
+  constructor(message) {
+    super(message, 'UNAUTHORIZED', 401);
   }
 }
-```
 
-**Embedded Relationships**:
-```javascript
-// Stores the full publisher object in the book document
-publisher: {
-  type: PublisherType,
-  extensions: {
-    relation: {
-      embedded: true
-    }
+// Not found error
+class NotFoundError extends SimfinityError {
+  constructor(message) {
+    super(message, 'NOT_FOUND', 404);
   }
 }
 ```
 
-### Querying Relationships
+## 🔄 State Machines
 
-Query nested relationships with dot notation:
+Implement declarative state machine workflows:
 
-```graphql
-query {
-  books(author: {
-    terms: [
-      {
-        path: "country.name",
-        operator: EQ,
-        value: "England"
-      }
-    ]
-  }) {
-    id
-    title
-    author {
-      name
-      country {
-        name
-      }
-    }
+### 1. Define States
+
+```javascript
+const { GraphQLEnumType } = require('graphql');
+
+const OrderState = new GraphQLEnumType({
+  name: 'OrderState',
+  values: {
+    PENDING: { value: 'PENDING' },
+    PROCESSING: { value: 'PROCESSING' },
+    SHIPPED: { value: 'SHIPPED' },
+    DELIVERED: { value: 'DELIVERED' },
+    CANCELLED: { value: 'CANCELLED' }
   }
-}
+});
 ```
 
-### Creating Objects with Relationships
+### 2. Define Type with State Field
 
-**Link to existing objects:**
-```graphql
-mutation {
-  addBook(input: {
-    title: "New Book"
-    author: {
-      id: "existing_author_id"
-    }
-  }) {
-    id
-    title
-    author {
-      name
-    }
-  }
-}
+```javascript
+const OrderType = new GraphQLObjectType({
+  name: 'Order',
+  fields: () => ({
+    id: { type: GraphQLID },
+    customer: { type: GraphQLString },
+    state: { type: OrderState }
+  })
+});
 ```
 
-**Create embedded objects:**
-```graphql
-mutation {
-  addBook(input: {
-    title: "New Book"
-    publisher: {
-      name: "Penguin Books"
-      location: "London"
-    }
-  }) {
-    id
-    title
-    publisher {
-      name
-      location
+### 3. Configure State Machine
+
+```javascript
+const stateMachine = {
+  initialState: { name: 'PENDING', value: 'PENDING' },
+  actions: {
+    process: {
+      from: { name: 'PENDING', value: 'PENDING' },
+      to: { name: 'PROCESSING', value: 'PROCESSING' },
+      description: 'Process the order',
+      action: async (args, session) => {
+        // Business logic for processing
+        console.log(`Processing order ${args.id}`);
+        // You can perform additional operations here
+      }
+    },
+    ship: {
+      from: { name: 'PROCESSING', value: 'PROCESSING' },
+      to: { name: 'SHIPPED', value: 'SHIPPED' },
+      description: 'Ship the order',
+      action: async (args, session) => {
+        // Business logic for shipping
+        console.log(`Shipping order ${args.id}`);
+      }
+    },
+    deliver: {
+      from: { name: 'SHIPPED', value: 'SHIPPED' },
+      to: { name: 'DELIVERED', value: 'DELIVERED' },
+      description: 'Mark as delivered'
+    },
+    cancel: {
+      from: { name: 'PENDING', value: 'PENDING' },
+      to: { name: 'CANCELLED', value: 'CANCELLED' },
+      description: 'Cancel the order'
     }
   }
-}
+};
 ```
 
-### Collection Fields
+### 4. Connect with State Machine
 
-Work with arrays of related objects:
+```javascript
+simfinity.connect(null, OrderType, 'order', 'orders', null, null, stateMachine);
+```
+
+### 5. Use State Machine Mutations
+
+The state machine automatically generates mutations for each action:
 
 ```graphql
 mutation {
-  updateBook(input: {
-    id: "book_id"
-    reviews: {
-      added: [
-        { rating: 5, comment: "Amazing!" }
-        { rating: 4, comment: "Good read" }
-      ]
-      updated: [
-        { id: "review_id", rating: 3 }
-      ]
-      deleted: ["review_id_to_delete"]
-    }
+  process_order(input: {
+    id: "order_id"
   }) {
     id
-    title
-    reviews {
-      rating
-      comment
-    }
+    state
+    customer
   }
 }
 ```
 
+**Important Notes**:
+- The `state` field is automatically read-only and managed by the state machine
+- State transitions are only allowed based on the defined actions
+- Business logic in the `action` function is executed during transitions
+- Invalid transitions throw errors automatically
+
 ## 🎛️ Controllers & Lifecycle Hooks
 
 Controllers provide fine-grained control over operations with lifecycle hooks:
@@ -1482,781 +1288,956 @@ const documentController = {
     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.
+
+## 🔒 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'
+        }
+      }
+    }
+  })
+});
 ```
 
-**Example: Role-Based Authorization**
+### 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 adminOnlyController = {
-  onUpdating: async (id, doc, session, context) => {
-    if (!context || !context.user || context.user.role !== 'admin') {
-      throw new simfinity.SimfinityError('Admin access required', 'FORBIDDEN', 403);
+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
+            }
+          ]
+        };
+      }
     }
   },
-  
-  onDelete: async (doc, session, context) => {
-    if (!context || !context.user || context.user.role !== 'admin') {
-      throw new simfinity.SimfinityError('Admin access required', 'FORBIDDEN', 403);
+  fields: () => ({
+    id: { type: GraphQLID },
+    title: { type: GraphQLString },
+    owner: {
+      type: new GraphQLNonNull(simfinity.getType('user')),
+      extensions: {
+        relation: {
+          connectionField: 'owner',
+          displayField: 'name'
+        }
+      }
     }
-  }
-};
+  })
+});
 ```
 
-**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
-
-Implement declarative state machine workflows:
-
-### 1. Define States
-
-```javascript
-const { GraphQLEnumType } = require('graphql');
+**Result**: All `documents` queries will automatically filter to only return documents where `owner.id` equals `context.user.id`.
 
-const OrderState = new GraphQLEnumType({
-  name: 'OrderState',
-  values: {
-    PENDING: { value: 'PENDING' },
-    PROCESSING: { value: 'PROCESSING' },
-    SHIPPED: { value: 'SHIPPED' },
-    DELIVERED: { value: 'DELIVERED' },
-    CANCELLED: { value: 'CANCELLED' }
-  }
-});
-```
+### Scope for Aggregate Operations
 
-### 2. Define Type with State Field
+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: () => ({
-    id: { type: GraphQLID },
-    customer: { type: GraphQLString },
-    state: { type: OrderState }
+    // ... fields
   })
 });
 ```
 
-### 3. Configure State Machine
+**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 stateMachine = {
-  initialState: { name: 'PENDING', value: 'PENDING' },
-  actions: {
-    process: {
-      from: { name: 'PENDING', value: 'PENDING' },
-      to: { name: 'PROCESSING', value: 'PROCESSING' },
-      description: 'Process the order',
-      action: async (args, session) => {
-        // Business logic for processing
-        console.log(`Processing order ${args.id}`);
-        // You can perform additional operations here
-      }
-    },
-    ship: {
-      from: { name: 'PROCESSING', value: 'PROCESSING' },
-      to: { name: 'SHIPPED', value: 'SHIPPED' },
-      description: 'Ship the order',
-      action: async (args, session) => {
-        // Business logic for shipping
-        console.log(`Shipping order ${args.id}`);
+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
+            }
+          ]
+        };
       }
-    },
-    deliver: {
-      from: { name: 'SHIPPED', value: 'SHIPPED' },
-      to: { name: 'DELIVERED', value: 'DELIVERED' },
-      description: 'Mark as delivered'
-    },
-    cancel: {
-      from: { name: 'PENDING', value: 'PENDING' },
-      to: { name: 'CANCELLED', value: 'CANCELLED' },
-      description: 'Cancel the order'
     }
-  }
-};
+  },
+  fields: () => ({
+    // ... fields
+  })
+});
 ```
 
-### 4. Connect with State Machine
-
-```javascript
-simfinity.connect(null, OrderType, 'order', 'orders', null, null, stateMachine);
-```
+**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
 
-### 5. Use State Machine Mutations
+### Scope Function Parameters
 
-The state machine automatically generates mutations for each action:
+Scope functions receive the same parameters as middleware for consistency:
 
-```graphql
-mutation {
-  process_order(input: {
-    id: "order_id"
-  }) {
-    id
-    state
-    customer
-  }
+```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.)
 }
 ```
 
-**Important Notes**:
-- The `state` field is automatically read-only and managed by the state machine
-- State transitions are only allowed based on the defined actions
-- Business logic in the `action` function is executed during transitions
-- Invalid transitions throw errors automatically
+### Filter Structure
 
-## ✅ Validations
+When modifying `args` in scope functions, use the appropriate filter structure:
 
-### Declarative Validation Helpers
+**For scalar fields:**
+```javascript
+args.fieldName = {
+  operator: 'EQ',
+  value: 'someValue'
+};
+```
 
-Simfinity.js provides built-in validation helpers to simplify common validation patterns, eliminating verbose boilerplate code.
+**For object/relation fields (QLTypeFilterExpression):**
+```javascript
+args.relationField = {
+  terms: [
+    {
+      path: 'fieldName',
+      operator: 'EQ',
+      value: 'someValue'
+    }
+  ]
+};
+```
 
-#### Using Validators
+### Complete Example
 
-```javascript
-const { validators } = require('@simtlix/simfinity-js');
+Here's a complete example showing scope for all query operations:
 
-const PersonType = new GraphQLObjectType({
-  name: 'Person',
+```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 },
-    name: {
-      type: GraphQLString,
-      extensions: {
-        validations: validators.stringLength('Name', 2, 100)
-      }
-    },
-    email: {
-      type: GraphQLString,
-      extensions: {
-        validations: validators.email()
-      }
-    },
-    website: {
-      type: GraphQLString,
-      extensions: {
-        validations: validators.url()
-      }
-    },
-    age: {
-      type: GraphQLInt,
+    number: { type: GraphQLInt },
+    name: { type: GraphQLString },
+    season: {
+      type: new GraphQLNonNull(simfinity.getType('season')),
       extensions: {
-        validations: validators.numberRange('Age', 0, 120)
+        relation: {
+          connectionField: 'season',
+          displayField: 'number'
+        }
       }
     },
-    price: {
-      type: GraphQLFloat,
+    owner: {
+      type: new GraphQLNonNull(simfinity.getType('user')),
       extensions: {
-        validations: validators.positive('Price')
+        relation: {
+          connectionField: 'owner',
+          displayField: 'name'
+        }
       }
     }
   })
 });
 ```
 
-#### Available Validators
+### Important Notes
 
-**String Validators:**
-- `validators.stringLength(name, min, max)` - Validates string length with min/max bounds (required for CREATE)
-- `validators.maxLength(name, max)` - Validates maximum string length
-- `validators.pattern(name, regex, message)` - Validates against a regex pattern
-- `validators.email()` - Validates email format
-- `validators.url()` - Validates URL format
+- **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
 
-**Number Validators:**
-- `validators.numberRange(name, min, max)` - Validates number range
-- `validators.positive(name)` - Ensures number is positive
+### Use Cases
 
-**Array Validators:**
-- `validators.arrayLength(name, maxItems, itemValidator)` - Validates array length and optionally each item
+- **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
 
-**Date Validators:**
-- `validators.dateFormat(name, format)` - Validates date format
-- `validators.futureDate(name)` - Ensures date is in the future
+## 🔐 Authorization
 
-#### Validator Features
+Simfinity.js provides production-grade centralized GraphQL authorization supporting RBAC/ABAC, function-based rules, declarative policy expressions (JSON AST), wildcard permissions, and configurable default policies. It ships as a native Envelop plugin for GraphQL Yoga (recommended) and also supports the legacy graphql-middleware approach.
 
-- **Automatic Operation Handling**: Validators work for both `CREATE` (save) and `UPDATE` operations
-- **Smart Validation**: For CREATE operations, values are required. For UPDATE operations, undefined/null values are allowed (field might not be updated)
-- **Consistent Error Messages**: All validators throw `SimfinityError` with appropriate messages
+### Quick Start
 
-#### Example: Multiple Validators
+```javascript
+const { auth } = require('@simtlix/simfinity-js');
+const { createYoga } = require('graphql-yoga');
+
+const { createAuthPlugin, requireAuth, requireRole } = auth;
+
+// Define your permission schema
+// Query/Mutation names match the ones generated by simfinity.connect()
+const permissions = {
+  Query: {
+    series: requireAuth(),
+    seasons: requireAuth(),
+  },
+  Mutation: {
+    deleteserie: requireRole('admin'),
+    deletestar: requireRole('admin'),
+  },
+  serie: {
+    '*': requireAuth(),           // Wildcard: all fields require auth
+  },
+};
+
+// Create the Envelop auth plugin and pass it to your server
+const authPlugin = createAuthPlugin(permissions, { defaultPolicy: 'ALLOW' });
+const yoga = createYoga({ schema, plugins: [authPlugin] });
+```
+
+### Permission Schema
+
+The permission schema defines authorization rules per type and field:
 
 ```javascript
-const ProductType = new GraphQLObjectType({
-  name: 'Product',
-  fields: () => ({
-    id: { type: GraphQLID },
-    name: {
-      type: GraphQLString,
-      extensions: {
-        validations: validators.stringLength('Product Name', 3, 200)
-      }
-    },
-    sku: {
-      type: GraphQLString,
-      extensions: {
-        validations: validators.pattern('SKU', /^[A-Z0-9-]+$/, 'SKU must be uppercase alphanumeric with hyphens')
-      }
-    },
-    price: {
-      type: GraphQLFloat,
-      extensions: {
-        validations: validators.positive('Price')
-      }
-    },
-    tags: {
-      type: new GraphQLList(GraphQLString),
-      extensions: {
-        validations: validators.arrayLength('Tags', 10)
-      }
-    }
-  })
-});
+const permissions = {
+  // Operation types (Query, Mutation, Subscription)
+  Query: {
+    fieldName: ruleOrRules,
+  },
+  
+  // Object types
+  TypeName: {
+    '*': wildcardRule,      // Applies to all fields unless overridden
+    fieldName: specificRule, // Overrides wildcard for this field
+  },
+};
 ```
 
-### Field-Level Validations (Manual)
+**Resolution Order:**
+1. Check exact field rule: `permissions[TypeName][fieldName]`
+2. Fallback to wildcard: `permissions[TypeName]['*']`
+3. Apply default policy (ALLOW or DENY)
 
-For custom validation logic, you can still write manual validators:
+**Rule Types:**
+- **Function**: `(parent, args, ctx, info) => boolean | void | Promise<boolean | void>`
+- **Array of functions**: All rules must pass (AND logic)
+- **Policy expression**: JSON AST object (see below)
+
+**Rule Semantics:**
+- `return true` or `return void` → allow
+- `return false` → deny
+- `throw Error` → deny with error
+
+### Rule Helpers
+
+Simfinity.js provides reusable rule builders:
 
 ```javascript
-const { SimfinityError } = require('@simtlix/simfinity-js');
+const { auth } = require('@simtlix/simfinity-js');
 
-const validateAge = {
-  validate: async (typeName, fieldName, value, session) => {
-    if (value < 0 || value > 120) {
-      throw new SimfinityError(`Invalid age: ${value}`, 'VALIDATION_ERROR', 400);
-    }
-  }
+const {
+  resolvePath,       // Utility to resolve dotted paths in objects
+  requireAuth,       // Requires ctx.user to exist
+  requireRole,       // Requires specific role(s)
+  requirePermission, // Requires specific permission(s)
+  composeRules,      // Combine rules (AND logic)
+  anyRule,           // Combine rules (OR logic)
+  isOwner,           // Check resource ownership
+  allow,             // Always allow
+  deny,              // Always deny
+  createRule,        // Create custom rule
+} = auth;
+```
+
+#### requireAuth(userPath?)
+
+Requires the user to be authenticated. Supports custom user paths in context:
+
+```javascript
+const permissions = {
+  Query: {
+    // Default: checks ctx.user
+    me: requireAuth(),
+    
+    // Custom path: checks ctx.auth.currentUser
+    profile: requireAuth('auth.currentUser'),
+    
+    // Deep path: checks ctx.session.data.user
+    settings: requireAuth('session.data.user'),
+  },
 };
+```
 
-const PersonType = new GraphQLObjectType({
-  name: 'Person',
-  fields: () => ({
-    id: { type: GraphQLID },
-    name: { 
-      type: GraphQLString,
-      extensions: {
-        validations: {
-          save: [{
-            validate: async (typeName, fieldName, value, session) => {
-              if (!value || value.length < 2) {
-                throw new SimfinityError('Name must be at least 2 characters', 'VALIDATION_ERROR', 400);
-              }
-            }
-          }],
-          update: [{
-            validate: async (typeName, fieldName, value, session) => {
-              if (value && value.length < 2) {
-                throw new SimfinityError('Name must be at least 2 characters', 'VALIDATION_ERROR', 400);
-              }
-            }
-          }]
-        }
-      }
-    },
-    age: {
-      type: GraphQLInt,
-      extensions: {
-        validations: {
-          save: [validateAge],
-          update: [validateAge]
-        }
-      }
-    }
-  })
-});
+#### requireRole(role, options?)
+
+Requires the user to have a specific role. Supports custom paths:
+
+```javascript
+const permissions = {
+  Query: {
+    // Default: checks ctx.user.role
+    adminDashboard: requireRole('ADMIN'),
+    modTools: requireRole(['ADMIN', 'MODERATOR']), // Any of these roles
+    
+    // Custom paths: checks ctx.auth.user.profile.role
+    superAdmin: requireRole('SUPER_ADMIN', { 
+      userPath: 'auth.user', 
+      rolePath: 'profile.role',
+    }),
+  },
+};
 ```
 
-### Type-Level Validations
+#### requirePermission(permission, options?)
 
-Validate objects as a whole:
+Requires the user to have specific permission(s). Supports custom paths:
 
 ```javascript
-const orderValidator = {
-  validate: async (typeName, args, modelArgs, session) => {
-    // Cross-field validation
-    if (modelArgs.deliveryDate < modelArgs.orderDate) {
-      throw new SimfinityError('Delivery date cannot be before order date', 'VALIDATION_ERROR', 400);
-    }
+const permissions = {
+  Mutation: {
+    // Default: checks ctx.user.permissions
+    deletePost: requirePermission('posts:delete'),
+    manageUsers: requirePermission(['users:read', 'users:write']), // All required
     
-    // Business rule validation
-    if (modelArgs.items.length === 0) {
-      throw new SimfinityError('Order must contain at least one item', 'BUSINESS_ERROR', 400);
-    }
-  }
+    // Custom paths: checks ctx.session.user.access.grants
+    admin: requirePermission('admin:all', {
+      userPath: 'session.user',
+      permissionsPath: 'access.grants',
+    }),
+  },
 };
+```
 
-const OrderType = new GraphQLObjectType({
-  name: 'Order',
-  extensions: {
-    validations: {
-      save: [orderValidator],
-      update: [orderValidator]
-    }
+#### composeRules(...rules)
+
+Combines multiple rules with AND logic (all must pass):
+
+```javascript
+const permissions = {
+  Mutation: {
+    updatePost: composeRules(
+      requireAuth(),
+      requireRole('EDITOR'),
+      async (post, args, ctx) => post.authorId === ctx.user.id,
+    ),
   },
-  fields: () => ({
-    // ... fields
-  })
-});
+};
 ```
 
-### Custom Validated Scalar Types
+#### anyRule(...rules)
 
-Create custom scalar types with built-in validation. The generated type names follow the pattern `{name}_{baseScalarTypeName}`.
+Combines multiple rules with OR logic (any must pass):
 
-#### Pre-built Scalars
+```javascript
+const permissions = {
+  Post: {
+    content: anyRule(
+      requireRole('ADMIN'),
+      async (post, args, ctx) => post.authorId === ctx.user.id,
+    ),
+  },
+};
+```
 
-Simfinity.js provides ready-to-use validated scalars for common patterns:
+#### isOwner(ownerField, userIdField)
+
+Checks if the authenticated user owns the resource:
 
 ```javascript
-const { scalars } = require('@simtlix/simfinity-js');
+const permissions = {
+  Post: {
+    '*': composeRules(
+      requireAuth(),
+      isOwner('authorId', 'id'), // Compares post.authorId with ctx.user.id
+    ),
+  },
+};
+```
 
-const UserType = new GraphQLObjectType({
-  name: 'User',
-  fields: () => ({
-    id: { type: GraphQLID },
-    email: { type: scalars.EmailScalar },      // Type name: Email_String
-    website: { type: scalars.URLScalar },       // Type name: URL_String
-    age: { type: scalars.PositiveIntScalar },  // Type name: PositiveInt_Int
-    price: { type: scalars.PositiveFloatScalar } // Type name: PositiveFloat_Float
-  }),
-});
+### Policy Expressions (JSON AST)
+
+For declarative rules, use JSON AST policy expressions:
+
+```javascript
+const permissions = {
+  Post: {
+    content: {
+      anyOf: [
+        { eq: [{ ref: 'parent.published' }, true] },
+        { eq: [{ ref: 'parent.authorId' }, { ref: 'ctx.user.id' }] },
+      ],
+    },
+  },
+};
 ```
 
-**Available Pre-built Scalars:**
-- `scalars.EmailScalar` - Validates email format (`Email_String`)
-- `scalars.URLScalar` - Validates URL format (`URL_String`)
-- `scalars.PositiveIntScalar` - Validates positive integers (`PositiveInt_Int`)
-- `scalars.PositiveFloatScalar` - Validates positive floats (`PositiveFloat_Float`)
+**Supported Operators:**
 
-#### Factory Functions for Custom Scalars
+| Operator | Description | Example |
+|----------|-------------|---------|
+| `eq` | Equals | `{ eq: [{ ref: 'parent.status' }, 'active'] }` |
+| `in` | Value in array | `{ in: [{ ref: 'ctx.user.role' }, ['ADMIN', 'MOD']] }` |
+| `allOf` | All must be true (AND) | `{ allOf: [expr1, expr2] }` |
+| `anyOf` | Any must be true (OR) | `{ anyOf: [expr1, expr2] }` |
+| `not` | Negation | `{ not: { eq: [{ ref: 'parent.deleted' }, true] } }` |
 
-Create custom validated scalars with parameters:
+**References:**
+
+Use `{ ref: 'path' }` to reference values:
+- `parent.*` - Parent resolver result (the object being resolved)
+- `args.*` - GraphQL arguments
+- `ctx.*` - GraphQL context
+
+**Security:**
+- Only `parent`, `args`, and `ctx` roots are allowed
+- Unknown operators fail closed (deny)
+- No `eval()` or `Function()` - pure object traversal
+
+### Integration with GraphQL Yoga / Envelop
+
+The recommended way to use the auth system is via the Envelop plugin, which works natively with GraphQL Yoga and any Envelop-based server. The plugin wraps resolvers in-place without rebuilding the schema, avoiding compatibility issues.
 
 ```javascript
-const { scalars } = require('@simtlix/simfinity-js');
+const { createYoga } = require('graphql-yoga');
+const { createServer } = require('http');
+const simfinity = require('@simtlix/simfinity-js');
 
-// Create a bounded string scalar (name length between 2-100 characters)
-const NameScalar = scalars.createBoundedStringScalar('Name', 2, 100);
+const { auth } = simfinity;
+const { createAuthPlugin, requireAuth, requireRole, composeRules, isOwner, deny } = auth;
 
-// Create a bounded integer scalar (age between 0-120)
-const AgeScalar = scalars.createBoundedIntScalar('Age', 0, 120);
+// Define your types and connect them
+simfinity.connect(null, SerieType, 'serie', 'series');
+simfinity.connect(null, SeasonType, 'season', 'seasons');
+simfinity.connect(null, StarType, 'star', 'stars');
 
-// Create a bounded float scalar (rating between 0-10)
-const RatingScalar = scalars.createBoundedFloatScalar('Rating', 0, 10);
+// Create base schema
+const schema = simfinity.createSchema();
 
-// Create a pattern-based string scalar (phone number format)
-const PhoneScalar = scalars.createPatternStringScalar(
-  'Phone',
-  /^\+?[\d\s\-()]+$/,
-  'Invalid phone number format'
-);
+// Define permissions
+// Query/Mutation names match the ones generated by simfinity.connect()
+const permissions = {
+  Query: {
+    series: requireAuth(),
+    seasons: requireAuth(),
+    stars: requireAuth(),
+  },
+  Mutation: {
+    addserie: requireAuth(),
+    updateserie: composeRules(requireAuth(), isOwner('createdBy')),
+    deleteserie: requireRole('admin'),
+    deletestar: requireRole('admin'),
+  },
+  serie: {
+    '*': requireAuth(),
+  },
+  season: {
+    '*': requireAuth(),
+  },
+};
 
-// Use in your types
-const PersonType = new GraphQLObjectType({
-  name: 'Person',
-  fields: () => ({
-    id: { type: GraphQLID },
-    name: { type: NameScalar },        // Type name: Name_String
-    age: { type: AgeScalar },          // Type name: Age_Int
-    rating: { type: RatingScalar },    // Type name: Rating_Float
-    phone: { type: PhoneScalar }       // Type name: Phone_String
+// Create auth plugin
+const authPlugin = createAuthPlugin(permissions, {
+  defaultPolicy: 'ALLOW',
+  debug: false,
+});
+
+// Setup Yoga with the auth plugin
+const yoga = createYoga({
+  schema,
+  plugins: [authPlugin],
+  context: (req) => ({
+    user: req.user,  // Set by your authentication layer
   }),
 });
-```
 
-**Available Factory Functions:**
-- `scalars.createBoundedStringScalar(name, min, max)` - String with length bounds
-- `scalars.createBoundedIntScalar(name, min, max)` - Integer with range validation
-- `scalars.createBoundedFloatScalar(name, min, max)` - Float with range validation
-- `scalars.createPatternStringScalar(name, pattern, message)` - String with regex pattern validation
+const server = createServer(yoga);
+server.listen(4000);
+```
 
-#### Creating Custom Scalars Manually
+### Legacy: Integration with graphql-middleware
 
-You can also create custom scalars using `createValidatedScalar` directly:
+> **Deprecated:** `applyMiddleware` from `graphql-middleware` rebuilds the schema via `mapSchema`,
+> which can cause `"Schema must contain uniquely named types"` errors with Simfinity schemas.
+> Use `createAuthPlugin` with GraphQL Yoga / Envelop instead.
 
 ```javascript
-const { GraphQLString, GraphQLInt } = require('graphql');
-const { createValidatedScalar } = require('@simtlix/simfinity-js');
+const { applyMiddleware } = require('graphql-middleware');
+const simfinity = require('@simtlix/simfinity-js');
 
-// Email scalar with validation (generates type name: Email_String)
-const EmailScalar = createValidatedScalar(
-  'Email',
-  'A valid email address',
-  GraphQLString,
-  (value) => {
-    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-    if (!emailRegex.test(value)) {
-      throw new Error('Invalid email format');
-    }
-  }
-);
+const { auth } = simfinity;
+const { createAuthMiddleware, requireAuth, requireRole } = auth;
 
-// Positive integer scalar (generates type name: PositiveInt_Int)
-const PositiveIntScalar = createValidatedScalar(
-  'PositiveInt',
-  'A positive integer',
-  GraphQLInt,
-  (value) => {
-    if (value <= 0) {
-      throw new Error('Value must be positive');
-    }
-  }
-);
+const baseSchema = simfinity.createSchema();
 
-// Use in your types
-const UserType = new GraphQLObjectType({
-  name: 'User',
-  fields: () => ({
-    id: { type: GraphQLID },
-    email: { type: EmailScalar }, // Type name: Email_String
-    age: { type: PositiveIntScalar }, // Type name: PositiveInt_Int
-  }),
+const authMiddleware = createAuthMiddleware(permissions, {
+  defaultPolicy: 'DENY',
+});
+
+const schema = applyMiddleware(baseSchema, authMiddleware);
+```
+
+### Plugin / Middleware Options
+
+```javascript
+const plugin = createAuthPlugin(permissions, {
+  defaultPolicy: 'DENY',  // 'ALLOW' or 'DENY' (default: 'DENY')
+  debug: false,           // Enable debug logging
 });
 ```
 
-### Custom Error Classes
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `defaultPolicy` | `'ALLOW' \| 'DENY'` | `'DENY'` | Policy when no rule matches |
+| `debug` | `boolean` | `false` | Log authorization decisions |
 
-Create domain-specific error classes:
+### Error Handling
+
+The auth middleware uses Simfinity error classes:
 
 ```javascript
-const { SimfinityError } = require('@simtlix/simfinity-js');
+const { auth } = require('@simtlix/simfinity-js');
 
-// Business logic error
-class BusinessError extends SimfinityError {
-  constructor(message) {
-    super(message, 'BUSINESS_ERROR', 400);
-  }
-}
+const { UnauthenticatedError, ForbiddenError } = auth;
 
-// Authorization error
-class AuthorizationError extends SimfinityError {
-  constructor(message) {
-    super(message, 'UNAUTHORIZED', 401);
-  }
-}
+// UnauthenticatedError: code 'UNAUTHENTICATED', status 401
+// ForbiddenError: code 'FORBIDDEN', status 403
+```
 
-// Not found error
-class NotFoundError extends SimfinityError {
-  constructor(message) {
-    super(message, 'NOT_FOUND', 404);
-  }
-}
+Custom error handling in rules:
+
+```javascript
+const permissions = {
+  Mutation: {
+    deleteserie: async (parent, args, ctx) => {
+      if (!ctx.user) {
+        throw new auth.UnauthenticatedError('Please log in');
+      }
+      if (ctx.user.role !== 'admin') {
+        throw new auth.ForbiddenError('Only admins can delete series');
+      }
+      return true;
+    },
+  },
+};
 ```
 
-## 🔒 Query Scope
+### Best Practices
 
-### Overview
+1. **Default to DENY**: Use `defaultPolicy: 'DENY'` for security
+2. **Use wildcards wisely**: `'*'` rules provide baseline security per type
+3. **Prefer helper rules**: Use `requireAuth()`, `requireRole()` over custom functions
+4. **Fail closed**: Custom rules should deny on unexpected conditions
+5. **Keep rules simple**: Complex logic belongs in controllers, not auth rules
+6. **Test thoroughly**: Auth rules are critical - test all scenarios
 
-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.
+## 🔧 Middlewares
 
-### Defining Scope
+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.
 
-Define scope in the type extensions, similar to how validations are defined:
+### Adding Middlewares
+
+Register middlewares using `simfinity.use()`. Middlewares execute in the order they're registered:
 
 ```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'
-        }
-      }
-    }
-  })
+// Basic logging middleware
+simfinity.use((params, next) => {
+  console.log(`Executing ${params.operation} on ${params.type?.name || 'custom mutation'}`);
+  next();
 });
 ```
 
-### Scope for Find Operations
+### Middleware Parameters
 
-Scope functions for `find` operations modify the query arguments that are passed to `buildQuery`. The modified arguments are automatically used to filter results:
+Each middleware receives a `params` object containing:
 
 ```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'
-        }
-      }
-    }
-  })
+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();
 });
 ```
 
-**Result**: All `documents` queries will automatically filter to only return documents where `owner.id` equals `context.user.id`.
+### Common Use Cases
 
-### Scope for Aggregate Operations
+#### 1. Authentication & Authorization
 
-Scope functions for `aggregate` operations work the same way, ensuring aggregation queries also respect the scope:
+```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
-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
-            }
-          ]
-        };
+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();
       }
-    }
-  },
-  fields: () => ({
-    // ... fields
-  })
+    });
+    
+    // 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();
 });
 ```
 
-**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:
+#### 4. Rate Limiting
 
 ```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
-            }
-          ]
-        };
-      }
+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);
     }
-  },
-  fields: () => ({
-    // ... fields
-  })
+    
+    recentRequests.push(now);
+    requestCounts.set(userId, recentRequests);
+  }
+  
+  next();
 });
 ```
 
-**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:
+#### 5. Audit Trail
 
 ```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.)
-}
+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();
+});
 ```
 
-### Filter Structure
+### Multiple Middlewares
 
-When modifying `args` in scope functions, use the appropriate filter structure:
+Middlewares execute in registration order. Each middleware must call `next()` to continue the chain:
 
-**For scalar fields:**
 ```javascript
-args.fieldName = {
-  operator: 'EQ',
-  value: 'someValue'
-};
+// 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
+});
 ```
 
-**For object/relation fields (QLTypeFilterExpression):**
+### Error Handling in Middlewares
+
+Middlewares can throw errors to stop the operation:
+
 ```javascript
-args.relationField = {
-  terms: [
-    {
-      path: 'fieldName',
-      operator: 'EQ',
-      value: 'someValue'
+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;
+  }
+});
 ```
 
-### Complete Example
+### Conditional Middleware Execution
 
-Here's a complete example showing scope for all query operations:
+Execute middleware logic conditionally based on operation type or context:
 
 ```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'
-        }
-      }
+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();
 });
 ```
 
-### 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
+### Best Practices
 
-- **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
+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
 
 ## 🔧 Advanced Features
 
@@ -2705,6 +2686,7 @@ app.listen(4000, () => {
 
 ## 🔗 Resources
 
+- **[Series Sample Project](https://github.com/simtlix/series-sample)** - A complete TV series microservice built with Simfinity.js demonstrating types, relationships, state machines, controllers, and authorization
 - **[Samples Repository](https://github.com/simtlix/simfinity.js-samples)** - Complete examples and use cases
 - **[MongoDB Query Language](https://docs.mongodb.com/manual/tutorial/query-documents/)** - Learn about MongoDB querying
 - **[GraphQL Documentation](https://graphql.org/learn/)** - Learn about GraphQL