feat: introduce built-in ORM for Nexios

docs/orm/guide/advanced.md

@@ -0,0 +1,24 @@
+---
+title: Advanced Topics
+icon: settings
+description: Explore advanced features and best practices for optimizing Nexios ORM usage, including custom types, connection pooling, and performance considerations.
+head:
+  - - meta
+    - property: og:title
+      content: Advanced Topics
+  - - meta
+    - property: og:description
+      content: Explore advanced features and best practices for optimizing Nexios ORM usage, including custom types, connection pooling, and performance considerations.
+---
+
+# Advanced Topics in Nexios ORM
+
+This section delves into more advanced features and optimization techniques for Nexios ORM, helping you build robust, high-performance, and maintainable database interactions.
+
+
+
+By mastering these advanced topics, you can leverage the full power of Nexios ORM to build highly efficient, scalable, and maintainable database-driven applications.
+
+---
+
+This concludes the Nexios ORM documentation.

docs/orm/guide/index.md

@@ -0,0 +1,61 @@
+---
+title: Nexios ORM Overview
+icon: database
+description: An introduction to Nexios ORM, its features, and core concepts for efficient database interaction.
+head:
+  - - meta
+    - property: og:title
+      content: Nexios ORM Overview
+  - - meta
+    - property: og:description
+      content: An introduction to Nexios ORM, its features, and core concepts for efficient database interaction.
+---
+
+# Nexios ORM Overview
+
+Nexios ORM is a powerful, asynchronous-first Object-Relational Mapper designed to integrate seamlessly with the Nexios framework. It provides an elegant way to interact with your database using Python objects, abstracting away raw SQL queries and offering a more productive development experience.
+
+Built with performance and developer experience in mind, Nexios ORM supports various relational databases and leverages Python's `async/await` syntax for non-blocking database operations, crucial for high-performance web applications.
+
+## Key Features
+
+- **Async-First Design**: Fully embraces Python's `async/await` for efficient, non-blocking I/O operations, making it ideal for concurrent web applications.
+- **Declarative Model Definition**: Define your database schema using Python classes, making your code more readable and maintainable.
+- **Flexible Querying**: A rich query API for performing CRUD (Create, Read, Update, Delete) operations, filtering, sorting, and complex joins.
+- **Session Management**: Robust session handling for managing database transactions and ensuring data integrity.
+- **Relationship Mapping**: Easily define one-to-one, one-to-many, and many-to-many relationships between your models.
+- **Type Hinting Support**: Excellent integration with Python type hints for better IDE support, static analysis, and reduced errors.
+- **Extensible**: Designed to be extensible, allowing for custom data types, query extensions, and integration with other tools.
+- **Migration Support**: Integrates well with database migration tools like Alembic for managing schema changes.
+
+## Why Use an ORM?
+
+Using an ORM like Nexios ORM offers several significant advantages:
+
+- **Abstraction**: You interact with Python objects instead of writing raw SQL, which can be less error-prone and faster to develop.
+- **Maintainability**: Database schema changes are reflected in your models, making it easier to manage and understand your application's data layer.
+- **Security**: ORMs often provide built-in protection against common SQL injection attacks.
+- **Portability**: While not entirely database-agnostic, ORMs can make it easier to switch between different database backends with minimal code changes.
+- **Productivity**: Reduces boilerplate code for common database operations, allowing you to focus on business logic.
+
+## Core Concepts
+
+Before diving into the specifics, it's helpful to understand the fundamental concepts of Nexios ORM:
+
+- **Engine**: The central component that establishes a connection to your database. It's responsible for managing connection pools and dialect-specific configurations.
+- **Model**: A Python class that represents a table in your database. Each attribute of the model typically maps to a column in the table.
+- **Field/Column**: Attributes defined within a model that correspond to columns in the database table, specifying their type, constraints, and default values.
+- **Session**: A temporary workspace for your database operations. It tracks changes to your objects and is responsible for committing (persisting) those changes to the database or rolling them back.
+- **Query**: The mechanism used to retrieve, filter, and manipulate data from the database through your models.
+- **Relationship**: Defines how different models (tables) are linked to each other (e.g., a `User` can have many `Posts`).
+
+## Getting Started
+
+To begin using Nexios ORM, you'll typically follow these steps:
+
+1.  **Engine Setup**: Configure and create an `Engine` instance to connect to your database.
+2.  **Model Definition**: Define your Python classes that map to database tables.
+3.  **Session Management**: Learn how to create and use sessions to perform database operations.
+4.  **Querying Data**: Interact with your database using the ORM's query API.
+
+Let's dive into defining your first models!

docs/orm/guide/migrations.md

@@ -0,0 +1,17 @@
+---
+title: Database Migrations
+icon: code-branch
+description: Learn how to manage database schema changes over time using migration tools with Nexios ORM.
+head:
+  - - meta
+    - property: og:title
+      content: Database Migrations
+  - - meta
+    - property: og:description
+      content: Learn how to manage database schema changes over time using migration tools with Nexios ORM.
+---
+
+# Database Migrations
+
+As your application evolves, your database schema will inevitably change. You'll add new tables, modify existing columns, or introduce new relationships. Database migrations are a systematic way to manage these schema changes in a version-controlled, reproducible manner.
+

docs/orm/guide/models.md

@@ -0,0 +1,22 @@
+---
+title: Defining Models
+icon: code
+description: Learn how to define database models in Nexios ORM, including fields, types, and table configurations.
+head:
+  - - meta
+    - property: og:title
+      content: Defining Models
+  - - meta
+    - property: og:description
+      content: Learn how to define database models in Nexios ORM, including fields, types, and table configurations.
+---
+
+# Defining Models
+
+In Nexios ORM, models are Python classes that represent tables in your database. Each attribute of a model class typically corresponds to a column in the database table. Defining models is the first step to interacting with your database using the ORM.
+
+
+
+With your models defined and the database initialized, you're ready to start performing queries.
+
+Next: Querying Data

docs/orm/guide/queries.md

@@ -0,0 +1,76 @@
+---
+title: Querying Data
+icon: search
+description: Learn how to perform CRUD operations, filter, sort, and join data using Nexios ORM's query API.
+head:
+  - - meta
+    - property: og:title
+      content: Querying Data
+  - - meta
+    - property: og:description
+      content: Learn how to perform CRUD operations, filter, sort, and join data using Nexios ORM's query API.
+---
+
+# Querying Data
+
+Once you have defined your models and set up your database engine, the next step is to interact with your data. Nexios ORM provides a powerful and intuitive query API to perform common database operations like creating, reading, updating, and deleting (CRUD) records, as well as more complex filtering, sorting, and joining.
+
+All query operations are performed through a `Session` object. Remember to use `AsyncSession` for asynchronous contexts (like Nexios route handlers) and `Session` for synchronous contexts.
+
+The query system is:
+
+- **Composable** → chain methods to build queries  
+- **Typed** → model-aware results  
+- **Dialect-aware** → generates correct SQL for PostgreSQL, MySQL, SQLite  
+- **Async-first** → works seamlessly with `AsyncSession`  
+
+---
+
+## Setup for Examples
+
+Let's assume you have the following models and an `AsyncSession` dependency set up:
+
+```python
+# my_app/models.py
+from nexios_orm import NexiosModel, Field
+from datetime import datetime
+
+class User(NexiosModel):
+    __tablename__ = "users"
+    id: int = Field(primary_key=True, index=True)
+    username: str
+    email: str
+    is_active: bool = False
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+class Post(BaseModel):
+    __tablename__ = "posts"
+    id: int = Field(primary_key=True, index=True)
+    title: str
+    content: str
+    user_id: int = Field(foreign_key="User.id")
+    created_at: datetime = Field(DateTime, default_factory=datetime.utcnow)
+```
+
+```python
+# my_app/database.py (or similar)
+from nexios_orm import create_engine, AsyncSession, BaseModel
+from nexios import Depend
+
+DATABASE_URL = "postgresql+asyncpg://user:pass@localhost/dbname"
+engine = create_engine(DATABASE_URL, is_async=True)
+
+async def get_db():
+    async with AsyncSession(engine) as session:
+        yield session
+
+async def init_db():
+    async with engine.begin() as conn:
+        await conn.run_sync(BaseModel.metadata.create_all)
+```
+
+## Advanced Querying (Joins, Relationships, etc.)
+
+For more complex scenarios involving multiple tables, you'll use relationships and joins. These are covered in detail in the Defining Relationships guide.
+
+Next: Defining Relationships

docs/orm/guide/relationships.md

@@ -0,0 +1,23 @@
+---
+title: Defining Relationships
+icon: link
+description: Understand how to define and manage one-to-one, one-to-many, and many-to-many relationships between models in Nexios ORM.
+head:
+  - - meta
+    - property: og:title
+      content: Defining Relationships
+  - - meta
+    - property: og:description
+      content: Understand how to define and manage one-to-one, one-to-many, and many-to-many relationships between models in Nexios ORM.
+---
+
+# Defining Relationships
+
+Relational databases are built on the concept of relationships between tables. Nexios ORM provides powerful tools to define and manage these relationships between your models, allowing you to navigate and query related data effortlessly.
+
+
+
+
+Understanding and effectively using relationships is crucial for building robust and efficient database-driven applications with Nexios ORM.
+
+Next: Database Migrations