@simtlix/simfinity-js 1.2.0 → 1.3.0

package/README.md

@@ -1,204 +1,222 @@
 # Simfinity.js
 
-Simfinity.js is a powerful library that automatically generates a GraphQL schema from your Mongoose models. It simplifies the process of creating a GraphQL API for your Node.js application by providing a set of conventions and helpers to handle common CRUD operations, filtering, pagination, and sorting.
+A powerful Node.js framework that automatically generates GraphQL schemas from your data models, bringing all the power and flexibility of MongoDB query language to GraphQL interfaces.
 
-## Installation
+## ✨ Features
 
-To use Simfinity.js in your project, you'll need to have `mongoose` and `graphql` installed as peer dependencies.
+- **Automatic Schema Generation**: Define your object model, and Simfinity.js generates all queries and mutations
+- **MongoDB Integration**: Seamless translation between GraphQL and MongoDB
+- **Powerful Querying**: Any query that can be executed in MongoDB can be executed in GraphQL
+- **Auto-Generated Resolvers**: Automatically generates resolve methods for relationship fields
+- **Business Logic**: Implement business logic and domain validations declaratively
+- **State Machines**: Built-in support for declarative state machine workflows
+- **Lifecycle Hooks**: Controller methods for granular control over operations
+- **Custom Validation**: Field-level and type-level custom validations
+- **Relationship Management**: Support for embedded and referenced relationships
+
+## 📦 Installation
 
 ```bash
 npm install mongoose graphql @simtlix/simfinity-js
 ```
 
-## Core Concepts
-
-The core of Simfinity.js revolves around two main concepts: connecting your Mongoose models to GraphQL types and creating a schema.
+**Prerequisites**: Simfinity.js requires `mongoose` and `graphql` as peer dependencies.
 
-### Connecting Models
+## 🚀 Quick Start
 
-The `simfinity.connect()` method is used to link a Mongoose model to a GraphQLObjectType. This tells Simfinity how to handle the data for that type.
+### 1. Basic Setup
 
 ```javascript
+const express = require('express');
+const { graphqlHTTP } = require('express-graphql');
 const mongoose = require('mongoose');
-const { GraphQLObjectType, GraphQLString, GraphQLNonNull } = require('graphql');
 const simfinity = require('@simtlix/simfinity-js');
 
-// 1. Define your GraphQL Type
+// Connect to MongoDB
+mongoose.connect('mongodb://localhost:27017/bookstore', {
+  useNewUrlParser: true,
+  useUnifiedTopology: true,
+});
+
+const app = express();
+```
+
+### 2. Define Your GraphQL Type
+
+```javascript
+const { GraphQLObjectType, GraphQLString, GraphQLNonNull, GraphQLID } = require('graphql');
+
 const BookType = new GraphQLObjectType({
   name: 'Book',
   fields: () => ({
     id: { type: new GraphQLNonNull(GraphQLID) },
     title: { type: new GraphQLNonNull(GraphQLString) },
+    author: { type: GraphQLString },
   }),
 });
-
-// 2. Connect the type to Simfinity
-simfinity.connect(null, BookType, 'book', 'books');
 ```
 
-### Creating a Schema
-
-Once you've connected your types, you can generate a GraphQL schema using `simfinity.createSchema()`. This will automatically create the queries and mutations for your connected types.
+### 3. Connect to Simfinity
 
 ```javascript
-const schema = simfinity.createSchema();
-```
-
----
-
-# About SimfinityJS
-SimfinityJS is a Node.js framework that allows bringing all the power and flexibility of MongoDB query language to GraphQL interfaces. 
-
-In pure GraphQL, you have to define every query and mutation. With SimfinityJS you define the object model, and the framework itself interprets all queries and mutations. SimfinityJS acts as a glue. It translates GraphQL to MongoDB and viceversa. 
-
-As a result, developers can focus on model structure and object relationships. 
-
-## Features
-- Translation between GraphQL and MongoDB and viceversa
-- Implement business logic in a declarative way
-- Implement domain validations in a declarative way. 
-- Supports declarative state machine. Business logic can be included in each state transition. 
-- Powerful semantic API. Basically, any query that can be executed in mongocli can be executed in GraphQL, thanks to SimfinityJS.
-
-
+// Connect the type to Simfinity
+simfinity.connect(null, BookType, 'book', 'books');
 
-# Quick Start
-## Install
-```bash
-npm install @simtlix/simfinity-js --save
+// Create the GraphQL schema
+const schema = simfinity.createSchema();
 ```
 
-## Adding Simfinity to your application
+### 4. Setup GraphQL Endpoint
 
 ```javascript
-const express = require('express')
-const graphqlHTTP = require('express-graphql')
-const simfinity = require('@simtlix/simfinity-js')
-const app = express()
-const mongoose = require('mongoose')
-
-//Replace with your Mongo DB connection string
-mongoose.connect('mongodb://localhost:27017,localhost:27018,localhost:27019/example2', { replicaSet: 'rs', useNewUrlParser: true, useUnifiedTopology: true })
-
-mongoose.connection.once('open', () => {
-  console.log('connected to database')
-})
-
-mongoose.set('debug', true);
-
-const type = require('./types')
-const includedTypes = [type.Book]
-
-const schema = simfinity.createSchema(includedTypes)
-
 app.use('/graphql', graphqlHTTP({
-  // Directing express-graphql to use this schema to map out the graph
   schema,
-  /* Directing express-graphql to use graphiql when goto '/graphql' address in the browser
-  which provides an interface to make GraphQl queries */
   graphiql: true,
   formatError: simfinity.buildErrorFormatter((err) => {
-    console.log(err)
+    console.log(err);
   })
+}));
 
-}))
-
-app.listen(3000, () => {
-  console.log('Listening on port 3000')
-})
+app.listen(4000, () => {
+  console.log('Server is running on port 4000');
+});
 ```
 
+### 5. Try It Out
 
-### Defining the model
+Open [http://localhost:4000/graphql](http://localhost:4000/graphql) and try these queries:
 
-```javascript
-const graphql = require('graphql')
-const simfinity = require('@simtlix/simfinity-js')
+**Create a book:**
+```graphql
+mutation {
+  addBook(input: {
+    title: "The Hitchhiker's Guide to the Galaxy"
+    author: "Douglas Adams"
+  }) {
+    id
+    title
+    author
+  }
+}
+```
 
-const {
-  GraphQLObjectType,GraphQLString,
-  GraphQLID, GraphQLInt
-} = graphql
+**List all books:**
+```graphql
+query {
+  books {
+    id
+    title
+    author
+  }
+}
+```
 
+## 🔧 Core Concepts
 
-const BookType = new GraphQLObjectType({
-  name: 'Book',
-  fields: () => ({
-    id: {
-      type: GraphQLID
-    },
-    name: { type: GraphQLString },
-    pages: { type: GraphQLInt }
-  })
-})
+### Connecting Models
 
-module.exports = BookType
+The `simfinity.connect()` method links your GraphQL types to Simfinity's automatic schema generation:
 
-simfinity.connect(null, BookType, 'book', 'books', null, null, null)
+```javascript
+simfinity.connect(
+  mongooseModel,           // Optional: Custom Mongoose model (null for auto-generation)
+  graphQLType,            // Required: Your GraphQLObjectType
+  singularEndpointName,   // Required: Singular name for mutations (e.g., 'book')
+  pluralEndpointName,     // Required: Plural name for queries (e.g., 'books')
+  controller,             // Optional: Controller with lifecycle hooks
+  onModelCreated,         // Optional: Callback when Mongoose model is created
+  stateMachine            // Optional: State machine configuration
+);
 ```
 
+### Creating Schemas
 
-# Run 
-Start replica set
+Generate your complete GraphQL schema with optional type filtering:
 
-`run-rs`
+```javascript
+const schema = simfinity.createSchema(
+  includedQueryTypes,     // Optional: Array of types to include in queries
+  includedMutationTypes,  // Optional: Array of types to include in mutations
+  includedCustomMutations // Optional: Array of custom mutations to include
+);
+```
 
-Run the application
+### Global Configuration
 
-`node app.js`
+```javascript
+// Prevent automatic MongoDB collection creation (useful for testing)
+simfinity.preventCreatingCollection(true);
+
+// Add middleware for all operations
+simfinity.use((params, next) => {
+  // params contains: type, args, operation, context
+  console.log(`Executing ${params.operation} on ${params.type.name}`);
+  next();
+});
+```
 
+## 📋 Basic Usage
 
+### Automatic Query Generation
 
-# Try it
+Simfinity automatically generates queries for each connected type:
 
-Open http://localhost:3000/graphql endpoint defined on app.js
+```javascript
+// For a BookType, you get:
+// - book(id: ID): Book          - Get single book by ID
+// - books(...filters): [Book]   - Get filtered list of books
+```
 
+### Automatic Mutation Generation
 
-Create a book
-```graphql
-mutation {
-  addbook (	
-    input:{
-      name: "Hello World Book",
-      pages: 333
-    }
-  ) 
-}
+Simfinity automatically generates mutations for each connected type:
+
+```javascript
+// For a BookType, you get:
+// - addBook(input: BookInput): Book
+// - updateBook(input: BookInputForUpdate): Book  
+// - deleteBook(id: ID): Book
 ```
 
+### Filtering and Querying
+
+Query with powerful filtering options:
 
-List all books
 ```graphql
 query {
-  books {
-    id, name, pages
+  books(
+    title: { operator: LIKE, value: "Galaxy" }
+    author: { operator: EQ, value: "Douglas Adams" }
+    pagination: { page: 1, size: 10, count: true }
+    sort: { terms: [{ field: "title", order: ASC }] }
+  ) {
+    id
+    title
+    author
   }
 }
 ```
 
+#### Available Operators
 
-# Want to know more! 
-Visit the [samples site](https://github.com/simtlix/simfinity.js-samples) and learn about SimfinityJS through different use cases
-
+- `EQ` - Equal
+- `NE` - Not equal
+- `GT` - Greater than
+- `LT` - Less than
+- `GTE` - Greater than or equal
+- `LTE` - Less than or equal
+- `LIKE` - Pattern matching
+- `IN` - In array
+- `NIN` - Not in array
+- `BTW` - Between two values
 
+## 🔗 Relationships
 
-## Bookstore Example
+### Defining Relationships
 
-Let's explore how to use Simfinity.js with a simple bookstore example. We'll have two main types: `Author` and `Book`.
-
-### 1. Define Your GraphQL Types
-
-First, we'll define the `GraphQLObjectType` for our `Author` and `Book` models. Notice the `extensions` field on the `author` field of the `BookType`. This is how you define relationships in Simfinity.
+Use the `extensions.relation` field to define relationships between types:
 
 ```javascript
-const {
-  GraphQLObjectType,
-  GraphQLString,
-  GraphQLNonNull,
-  GraphQLID,
-  GraphQLList,
-} = require('graphql');
-
 const AuthorType = new GraphQLObjectType({
   name: 'Author',
   fields: () => ({
@@ -208,9 +226,11 @@ const AuthorType = new GraphQLObjectType({
       type: new GraphQLList(BookType),
       extensions: {
         relation: {
-          connectionField: 'authorId',
+          connectionField: 'author',
+          displayField: 'title'
         },
       },
+      // resolve method automatically generated! 🎉
     },
   }),
 });
@@ -224,487 +244,790 @@ const BookType = new GraphQLObjectType({
       type: AuthorType,
       extensions: {
         relation: {
-          connectionField: 'authorId',
+          displayField: 'name'
         },
       },
+      // resolve method automatically generated! 🎉
     },
   }),
 });
 ```
 
-### Advanced Relationship Definition
+### Relationship Configuration
 
-For more control over your relationships, you can provide additional options in the `extensions.relation` object and add a custom `resolve` function.
+- `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)
 
-*   `connectionField`: (Required) The name of the field on the current model that stores the ID of the related object (e.g., `authorId` on the `Book` model).
-*   `displayField`: (Optional) The name of the field on the related object that should be used as its display value. This can be useful for auto-generated UI components.
-*   `resolve`: (Optional) A custom resolver function to fetch the related data. This gives you full control over how the relationship is resolved. If not provided, Simfinity.js will handle it automatically based on the `connectionField`.
+### Auto-Generated Resolve Methods
 
-Here's an example of an `Episode` type with a relationship to a `Season` type, using these advanced options. This demonstrates how to define which field to display from the related object and how to write a custom resolver.
+🎉 **NEW**: Simfinity.js automatically generates resolve methods for relationship fields when types are connected, eliminating the need for manual resolver boilerplate.
 
-```javascript
-const { GraphQLID, GraphQLObjectType, GraphQLString, GraphQLInt } = require('graphql');
-const GraphQLDateTime = require('graphql-iso-date').GraphQLDateTime;
-const simfinity = require('@simtlix/simfinity-js');
-const seasonType = require('./season'); // Assuming seasonType is defined elsewhere
+#### Before (Manual Resolvers)
 
-const episodeType = new GraphQLObjectType({
-  name: 'episode',
+```javascript
+const BookType = new GraphQLObjectType({
+  name: 'Book',
   fields: () => ({
-    id: { type: GraphQLID },
-    number: { type: GraphQLInt },
-    name: { type: GraphQLString },
-    date: { type: GraphQLDateTime },
-    season: {
-      type: seasonType,
+    id: { type: new GraphQLNonNull(GraphQLID) },
+    title: { type: new GraphQLNonNull(GraphQLString) },
+    author: {
+      type: AuthorType,
       extensions: {
         relation: {
-          connectionField: 'seasonID',
-          displayField: 'number'
-        }
+          displayField: 'name'
+        },
       },
+      // You had to manually write this
       resolve(parent) {
-        // Use simfinity.getModel() to get the Mongoose model for a GraphQL type
-        return simfinity.getModel(seasonType).findById(parent.seasonID);
+        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 });
+      }
+    }
+  }),
 });
 ```
 
-In this example:
-- The `season` field on `episodeType` is linked to `seasonType`.
-- `connectionField: 'seasonID'` tells Simfinity that the `seasonID` field in the episode document holds the ID of the related season.
-- `displayField: 'number'` suggests that the `number` field of a season (e.g., season 1, season 2) should be used to represent it.
-- The `resolve` function manually fetches the season document using its ID from the parent episode. This is useful for custom logic, but often not necessary, as Simfinity can resolve it automatically.
-
-### 2. Connect Your Types
-
-Next, we'll connect these types to Simfinity. This will automatically generate the Mongoose models and the necessary queries and mutations.
+#### After (Auto-Generated Resolvers)
 
 ```javascript
-const simfinity = require('@simtlix/simfinity-js');
-
-simfinity.connect(null, AuthorType, 'author', 'authors');
-simfinity.connect(null, BookType, 'book', 'books');
+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! 🎉
+    }
+  }),
+});
 ```
 
-### 3. Create the Server
+#### How It Works
 
-Finally, we'll create a simple Express server with `express-graphql` to serve our schema.
+- **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
 
-```javascript
-const express = require('express');
-const { graphqlHTTP } = require('express-graphql');
-const mongoose = require('mongoose');
-const simfinity = require('@simtlix/simfinity-js');
+#### Connect Your Types
 
-// ... (AuthorType and BookType definitions)
+```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');
 
-// Connect to MongoDB
-mongoose.connect('mongodb://localhost/bookstore', {
-  useNewUrlParser: true,
-  useUnifiedTopology: true,
-});
+// Or use addNoEndpointType for types that don't need direct queries/mutations
+simfinity.addNoEndpointType(AuthorType);
+```
 
-const app = express();
+That's it! All relationship resolvers are automatically generated when you connect your types.
 
-app.use('/graphql', graphqlHTTP({
-  schema: simfinity.createSchema(),
-  graphiql: true,
-}));
+### Embedded vs Referenced Relationships
 
-app.listen(4000, () => {
-  console.log('Server is running on port 4000');
-});
+**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
+    }
+  }
+}
 ```
 
-## Creating Complex Objects
-
-Simfinity.js makes it easy to create and connect objects in a single mutation. When you define a relationship, the input type for the parent object will automatically include a field for the child's ID.
-
-For our bookstore example, the `addBook` mutation will accept an `author` field, which is an object containing the `id` of the author.
+**Embedded Relationships**:
+```javascript
+// Stores the full publisher object in the book document
+publisher: {
+  type: PublisherType,
+  extensions: {
+    relation: {
+      embedded: true
+    }
+  }
+}
+```
 
-### Creating a Book for an Existing Author
+### Querying Relationships
 
-To create a new book and link it to an author that already exists, you can use the `addBook` mutation and provide the author's ID.
+Query nested relationships with dot notation:
 
 ```graphql
-mutation {
-  addBook(input: {
-    title: "The Hitchhiker's Guide to the Galaxy",
-    author: {
-      id: "author_id_here"
-    }
+query {
+  books(author: {
+    terms: [
+      {
+        path: "country.name",
+        operator: EQ,
+        value: "England"
+      }
+    ]
   }) {
     id
     title
     author {
-      id
       name
+      country {
+        name
+      }
     }
   }
 }
 ```
 
-This will create a new book and set its `authorId` field to the provided author ID.
-
----
-
-## Querying Data
-
-Simfinity.js provides a rich set of querying capabilities that are automatically added to your schema. You can filter, paginate, and sort your data with ease.
-
-### Basic Queries
-
-To get a list of all books, you can use the `books` query:
+### Creating Objects with Relationships
 
+**Link to existing objects:**
 ```graphql
-query {
-  books {
+mutation {
+  addBook(input: {
+    title: "New Book"
+    author: {
+      id: "existing_author_id"
+    }
+  }) {
     id
     title
+    author {
+      name
+    }
   }
 }
 ```
 
-To get a single book by its ID, you can use the `book` query:
-
+**Create embedded objects:**
 ```graphql
-query {
-  book(id: "book_id_here") {
+mutation {
+  addBook(input: {
+    title: "New Book"
+    publisher: {
+      name: "Penguin Books"
+      location: "London"
+    }
+  }) {
     id
     title
-    author {
-      id
+    publisher {
       name
+      location
     }
   }
 }
 ```
 
-### Filtering
-
-You can filter your queries using the `filter` argument. The filter object takes an `operator` and a `value`.
-
-#### Simple Equality Filter
+### Collection Fields
 
-To find all books with a specific title:
+Work with arrays of related objects:
 
 ```graphql
-query {
-  books(title: {
-    operator: EQ,
-    value: "The Hitchhiker's Guide to the Galaxy"
+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
+    }
   }
 }
 ```
 
-#### Using Other Operators
+## 🎛️ Controllers & Lifecycle Hooks
 
-Simfinity.js supports a variety of operators: `EQ`, `NE`, `GT`, `GTE`, `LT`, `LTE`, `LIKE`, `IN`, `NIN`, and `BTW`.
+Controllers provide fine-grained control over operations with lifecycle hooks:
 
-To find all books with "Guide" in the title:
+```javascript
+const bookController = {
+  onSaving: async (doc, args, session) => {
+    // Before saving - doc is a Mongoose document
+    if (!doc.title || doc.title.trim().length === 0) {
+      throw new Error('Book title cannot be empty');
+    }
+    console.log(`Creating book: ${doc.title}`);
+  },
 
-```graphql
-query {
-  books(title: {
-    operator: LIKE,
-    value: "Guide"
-  }) {
-    id
-    title
+  onSaved: async (doc, args, session) => {
+    // After saving - doc is a plain object
+    console.log(`Book saved: ${doc._id}`);
+  },
+
+  onUpdating: async (id, doc, session) => {
+    // Before updating - doc contains only changed fields
+    console.log(`Updating book ${id}`);
+  },
+
+  onUpdated: async (doc, session) => {
+    // After updating - doc is the updated document
+    console.log(`Book updated: ${doc.title}`);
+  },
+
+  onDelete: async (doc, session) => {
+    // Before deleting - doc is the document to be deleted
+    console.log(`Deleting book: ${doc.title}`);
   }
-}
+};
+
+// Connect with controller
+simfinity.connect(null, BookType, 'book', 'books', bookController);
 ```
 
-### Filtering on Nested Objects
+### Hook Parameters
 
-You can also filter based on the fields of a related object. To do this, you provide a `terms` array to the filter argument, where each term specifies a `path` to the nested field.
+**`onSaving(doc, args, session)`**:
+- `doc`: Mongoose Document instance (not yet saved)
+- `args`: Raw GraphQL mutation input
+- `session`: Mongoose session for transaction
 
-To find all books by a specific author:
+**`onSaved(doc, args, session)`**:
+- `doc`: Plain object of saved document
+- `args`: Raw GraphQL mutation input
+- `session`: Mongoose session for transaction
 
-```graphql
-query {
-  books(author: {
-    terms: [
-      {
-        path: "name",
-        operator: EQ,
-        value: "Douglas Adams"
-      }
-    ]
-  }) {
-    id
-    title
-    author {
-      name
-    }
+**`onUpdating(id, doc, session)`**:
+- `id`: Document ID being updated
+- `doc`: Plain object with only changed fields
+- `session`: Mongoose session for transaction
+
+**`onUpdated(doc, session)`**:
+- `doc`: Full updated Mongoose document
+- `session`: Mongoose session for transaction
+
+**`onDelete(doc, session)`**:
+- `doc`: Plain object of document to be deleted
+- `session`: Mongoose session for transaction
+
+## 🔄 State Machines
+
+Implement declarative state machine workflows:
+
+### 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' }
   }
-}
+});
 ```
 
-You can also use a deeper path to filter on nested relations. For example, if our `Author` type had a `country` relation, we could find all books by authors from a specific country:
+### 2. Define Type with State Field
 
-```graphql
-query {
-  books(author: {
-    terms: [
-      {
-        path: "country.name",
-        operator: EQ,
-        value: "England"
+```javascript
+const OrderType = new GraphQLObjectType({
+  name: 'Order',
+  fields: () => ({
+    id: { type: GraphQLID },
+    customer: { type: GraphQLString },
+    state: { type: OrderState }
+  })
+});
+```
+
+### 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
       }
-    ]
-  }) {
-    id
-    title
-    author {
-      name
-      country {
-        name
+    },
+    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'
     }
   }
-}
+};
 ```
 
-### Pagination
+### 4. Connect with State Machine
 
-To paginate your results, you can use the `pagination` argument. You can also get a `count` of the total number of documents that match the query.
-
-```graphql
-query {
-  books(pagination: {
-    page: 1,
-    size: 10,
-    count: true
-  }) {
-    id
-    title
-  }
-}
+```javascript
+simfinity.connect(null, OrderType, 'order', 'orders', null, null, stateMachine);
 ```
 
-### Sorting
+### 5. Use State Machine Mutations
 
-To sort your results, you can use the `sort` argument.
+The state machine automatically generates mutations for each action:
 
 ```graphql
-query {
-  books(sort: {
-    terms: [
-      {
-        field: "title",
-        order: ASC
-      }
-    ]
+mutation {
+  process_order(input: {
+    id: "order_id"
   }) {
     id
-    title
+    state
+    customer
   }
 }
 ```
 
-## Mutations
+**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
 
-Simfinity.js automatically generates `add`, `update`, and `delete` mutations for each type you connect.
+## ✅ Validations
 
-### Add Mutation
+### Field-Level Validations
 
-To create a new author:
+Add validation logic directly to fields:
 
-```graphql
-mutation {
-  addAuthor(input: {
-    name: "J.R.R. Tolkien"
-  }) {
-    id
-    name
+```javascript
+const { SimfinityError } = 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 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]
+        }
+      }
+    }
+  })
+});
 ```
 
-### Update Mutation
+### Type-Level Validations
 
-To update an existing author's name:
+Validate objects as a whole:
 
-```graphql
-mutation {
-  updateAuthor(input: {
-    id: "author_id_here",
-    name: "John Ronald Reuel Tolkien"
-  }) {
-    id
-    name
+```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);
+    }
+    
+    // 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
+  })
+});
 ```
 
-### Delete Mutation
+### Custom Validated Scalar Types
 
-To delete an author:
+Create custom scalar types with built-in validation:
 
-```graphql
-mutation {
-  deleteAuthor(id: "author_id_here") {
-    id
+```javascript
+const { GraphQLString, GraphQLInt } = require('graphql');
+const { createValidatedScalar } = require('@simtlix/simfinity-js');
+
+// Email scalar with validation
+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');
+    }
   }
-}
+);
+
+// Positive integer scalar
+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 },
+    age: { type: PositiveIntScalar },
+  }),
+});
 ```
 
-## Lifecycle Hooks with Controllers
+### Custom Error Classes
 
-For more granular control over the automatically generated mutations (`add`, `update`, `delete`), you can provide a controller object to Simfinity.js. This controller can contain methods that are executed as lifecycle hooks during these operations, allowing you to run validation, perform modifications, or trigger side effects.
+Create domain-specific error classes:
 
-The controller is passed as the fifth argument to the `simfinity.connect()` method.
+```javascript
+const { SimfinityError } = require('@simtlix/simfinity-js');
+
+// Business logic error
+class BusinessError extends SimfinityError {
+  constructor(message) {
+    super(message, 'BUSINESS_ERROR', 400);
+  }
+}
 
-### Controller Methods
+// Authorization error
+class AuthorizationError extends SimfinityError {
+  constructor(message) {
+    super(message, 'UNAUTHORIZED', 401);
+  }
+}
+
+// Not found error
+class NotFoundError extends SimfinityError {
+  constructor(message) {
+    super(message, 'NOT_FOUND', 404);
+  }
+}
+```
 
-*   `onCreating({ doc })`: Executed just before a new document is created. You can modify the `doc` or throw an error to prevent creation.
-*   `onUpdating({ doc, originalDoc })`: Executed before a document is updated. It receives the new `doc` with the pending changes and the `originalDoc` as it exists in the database.
-*   `onDeleting({ doc })`: Executed before a document is deleted. It receives the document that is about to be removed.
+## 🔧 Advanced Features
 
-### Example
+### Field Extensions
 
-Here's how you can define a controller for our `Book` type to add custom validation and logging:
+Control field behavior with extensions:
 
 ```javascript
-const bookController = {
-  onCreating: async ({ doc }) => {
-    // Validate that a book has a title before saving.
-    if (!doc.title || doc.title.trim().length === 0) {
-      throw new Error('Book title cannot be empty.');
+const BookType = new GraphQLObjectType({
+  name: 'Book',
+  fields: () => ({
+    id: { type: GraphQLID },
+    title: { 
+      type: GraphQLString,
+      extensions: {
+        unique: true,        // Creates unique index in MongoDB
+        readOnly: true       // Excludes from input types
+      }
+    },
+    isbn: {
+      type: GraphQLString,
+      extensions: {
+        unique: true
+      }
     }
-    console.log(`A new book titled "${doc.title}" is being created.`);
-    // You can also modify the document before it's saved, e.g., to add a timestamp.
-  },
+  })
+});
+```
 
-  onUpdating: async ({ doc, originalDoc }) => {
-    // Log the update operation.
-    console.log(`The book "${originalDoc.title}" is being updated.`);
-    // 'doc' contains the new values, while 'originalDoc' has the old ones.
-  },
+### Custom Mutations
 
-  onDeleting: async ({ doc }) => {
-    // Perform a final check or logging before deletion.
-    console.log(`The book "${doc.title}" is being deleted.`);
-    // This is a good place to perform related cleanup operations.
-  }
-};
+Register custom mutations beyond the automatic CRUD operations:
 
-// Connect the BookType with its controller
-simfinity.connect(
-  null,          // mongooseModel
-  BookType,      // graphQLType
-  'book',        // singularName
-  'books',       // pluralName
-  bookController // controller
+```javascript
+simfinity.registerMutation(
+  'sendBookNotification',
+  'Send notification about a book',
+  BookNotificationInput,    // Input type
+  NotificationResult,       // Output type
+  async (args, session) => {
+    // Custom business logic
+    const book = await BookModel.findById(args.bookId);
+    // Send notification logic here
+    return { success: true, message: 'Notification sent' };
+  }
 );
 ```
 
-When you now use the `addBook`, `updateBook`, or `deleteBook` mutations, the corresponding controller methods will be executed. For example, trying to create a book with an empty title would now fail with the custom error message.
+### Adding Types Without Endpoints
 
-## State Machines
+Include types in the schema without generating endpoints:
 
-Simfinity.js has built-in support for state machines, allowing you to manage the lifecycle of your objects in a declarative way. You can define states and actions that transition an object from one state to another. For each action, you can also specify business logic that gets executed during the transition.
+```javascript
+// This type can be used in relationships but won't have queries/mutations
+simfinity.addNoEndpointType(AddressType);
+```
+
+### Working with Existing Mongoose Models
+
+Use your existing Mongoose models:
 
-### Defining a State Machine
+```javascript
+const mongoose = require('mongoose');
 
-Let's look at an example of a `Season` type that has a lifecycle managed by a state machine. The process involves four main steps:
+const BookSchema = new mongoose.Schema({
+  title: String,
+  author: String,
+  publishedDate: Date
+});
 
-1.  **Define States**: Create a `GraphQLEnumType` to represent the possible states.
-2.  **Define Type**: Create the `GraphQLObjectType` that will have a state field.
-3.  **Configure State Machine**: Define an object with the `initialState` and the `actions` that govern transitions.
-4.  **Connect**: Use `simfinity.connect()` to link the type with its state machine.
+const BookModel = mongoose.model('Book', BookSchema);
 
-Here is the complete example:
+// Use existing model
+simfinity.connect(BookModel, BookType, 'book', 'books');
+```
+
+### Programmatic Data Access
+
+Access data programmatically outside of GraphQL:
 
 ```javascript
-const graphql = require('graphql');
-const simfinity = require('@simtlix/simfinity-js');
+// Save an object programmatically
+const newBook = await simfinity.saveObject('Book', {
+  title: 'New Book',
+  author: 'Author Name'
+}, session);
+
+// Get the Mongoose model for a type
+const BookModel = simfinity.getModel(BookType);
+const books = await BookModel.find({ author: 'Douglas Adams' });
+
+// Get the input type for a GraphQL type
+const BookInput = simfinity.getInputType(BookType);
+```
 
-const { GraphQLObjectType, GraphQLID, GraphQLInt, GraphQLEnumType } = graphql;
+## 📚 Complete Example
 
-// 1. Define the states using a GraphQLEnumType
-const seasonState = new GraphQLEnumType({
-  name: 'seasonState',
-  values: {
-    SCHEDULED: { value: 'SCHEDULED' },
-    ACTIVE: { value: 'ACTIVE' },
-    FINISHED: { value: 'FINISHED' }
-  }
+Here's a complete bookstore example with relationships, validations, and state machines:
+
+```javascript
+const express = require('express');
+const { graphqlHTTP } = require('express-graphql');
+const mongoose = require('mongoose');
+const { 
+  GraphQLObjectType, 
+  GraphQLString, 
+  GraphQLNonNull, 
+  GraphQLID, 
+  GraphQLList,
+  GraphQLInt,
+  GraphQLEnumType
+} = require('graphql');
+const simfinity = require('@simtlix/simfinity-js');
+
+// Connect to MongoDB
+mongoose.connect('mongodb://localhost:27017/bookstore', {
+  useNewUrlParser: true,
+  useUnifiedTopology: true,
 });
 
-// 2. Define the GraphQLObjectType
-const seasonType = new GraphQLObjectType({
-  name: 'season',
+// Define Types
+const AuthorType = new GraphQLObjectType({
+  name: 'Author',
   fields: () => ({
-    id: { type: GraphQLID },
-    number: { type: GraphQLInt },
-    year: { type: GraphQLInt },
-    state: { type: seasonState }
-  })
+    id: { type: new GraphQLNonNull(GraphQLID) },
+    name: { type: new GraphQLNonNull(GraphQLString) },
+    email: { type: GraphQLString },
+    books: {
+      type: new GraphQLList(BookType),
+      extensions: {
+        relation: {
+          connectionField: 'author',
+          displayField: 'title'
+        },
+      },
+      resolve(parent) {
+        return simfinity.getModel(BookType).find({ author: parent.id });
+      }
+    },
+  }),
 });
 
-// 3. Define the state machine configuration
-const stateMachine = {
-  initialState: 'SCHEDULED', // The value of the initial state
-  actions: {
-    activate: {
-      from: 'SCHEDULED',
-      to: 'ACTIVE',
-      action: async ({ doc }) => {
-        // Business logic to run on activation
-        // The 'doc' parameter contains the document being transitioned
-        console.log(`Activating season ${doc._id} of year ${doc.year}`);
+const BookType = new GraphQLObjectType({
+  name: 'Book',
+  fields: () => ({
+    id: { type: new GraphQLNonNull(GraphQLID) },
+    title: { 
+      type: new GraphQLNonNull(GraphQLString),
+      extensions: {
+        validations: {
+          save: [{
+            validate: async (typeName, fieldName, value, session) => {
+              if (!value || value.length < 2) {
+                throw new simfinity.SimfinityError('Title must be at least 2 characters', 'VALIDATION_ERROR', 400);
+              }
+            }
+          }]
+        }
       }
     },
-    finalize: {
-      from: 'ACTIVE',
-      to: 'FINISHED',
-      action: async ({ doc }) => {
-        // Business logic to run on finalization
-        console.log(`Finalizing season ${doc._id} of year ${doc.year}`);
+    pages: { type: GraphQLInt },
+    author: {
+      type: AuthorType,
+      extensions: {
+        relation: {
+          displayField: 'name'
+        },
+      },
+      resolve(parent) {
+        return simfinity.getModel(AuthorType).findById(parent.author);
       }
-    }
+    },
+  }),
+});
+
+// Define Controllers
+const bookController = {
+  onSaving: async (doc, args, session) => {
+    console.log(`Creating book: ${doc.title}`);
+  },
+  
+  onSaved: async (doc, args, session) => {
+    console.log(`Book saved: ${doc.title}`);
   }
 };
 
-// 4. Connect the type and its state machine to Simfinity
-simfinity.connect(
-  null,
-  seasonType,
-  'season',
-  'seasons',
-  null,
-  null,
-  stateMachine
-);
+// Connect Types
+simfinity.connect(null, AuthorType, 'author', 'authors');
+simfinity.connect(null, BookType, 'book', 'books', bookController);
+
+// Create Schema
+const schema = simfinity.createSchema();
+
+// Setup Express Server
+const app = express();
+
+app.use('/graphql', graphqlHTTP({
+  schema,
+  graphiql: true,
+  formatError: simfinity.buildErrorFormatter((err) => {
+    console.log(err);
+  })
+}));
+
+app.listen(4000, () => {
+  console.log('Bookstore API running on http://localhost:4000/graphql');
+});
 ```
 
-When a new `season` is created, its `state` field will automatically be set to `SCHEDULED`.
+## 🔗 Resources
 
-### Triggering State Transitions
+- **[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
 
-When you connect a type with a state machine, Simfinity.js automatically creates a GraphQL mutation for each action. The mutation name is a combination of the action name and the type name (e.g., `actionName` + `TypeName`).
+## 📄 License
 
-For our `season` example, Simfinity.js will generate `activateSeason` and `finalizeSeason` mutations.
+Apache-2.0 License - see the [LICENSE](LICENSE) file for details.
 
-To activate a season, you would call the `activateSeason` mutation with the ID of the season:
+## 🤝 Contributing
 
-```graphql
-mutation {
-  activateSeason(id: "season_id_here") {
-    id
-    state
-  }
-}
-```
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+---
 
-This will change the season's state from `SCHEDULED` to `ACTIVE` and execute the `action` function defined for the `activate` transition.
+*Built with ❤️ by [Simtlix](https://github.com/simtlix)*