docs: update docs

Author: Abdalrhman Emad Saad

docs/.vuepress/config.js

@@ -26,7 +26,7 @@ export default defineUserConfig({
     selectLanguageName: "ar",
     lastUpdated: true,
     contributors: true,
-    contributorsText: "dasdasd",
+    // contributorsText: "dasdasd",
 
     navbar: ["/", "/installation"],
     sidebar: [
@@ -51,20 +51,20 @@ export default defineUserConfig({
         collapsible: true,
         children: [
           {
-            text: "Dynamic method",
-            link: "engines/dynamic-methods",
+            text: "Invokable",
+            link: "engines/invokable",
           },
           {
-            text: "Tree based",
-            link: "engines/tree-based",
+            text: "Tree",
+            link: "engines/tree",
           },
           {
             text: "Ruleset",
             link: "engines/rule-set",
           },
           {
-            text: "Closure pipeline",
-            link: "engines/closure",
+            text: "Expression",
+            link: "engines/expression",
           },
         ],
       },
@@ -90,10 +90,6 @@ export default defineUserConfig({
         text: "Sanitization",
         link: "sanitization",
       },
-      {
-        text: "Configurations",
-        link: "configurations",
-      },
     ],
   }),
 

docs/README.md

@@ -45,7 +45,7 @@ Filterable::withRequest($request)
     ->useEngine('ruleset')
     ->setAllowedFields(['status', 'title', 'author.name'])
     ->setRelations(['author'])
-    ->run(Post::query());
+    ->filter(Post::query());
 ```
 
 ## 🧪 Tested & Production-Ready

docs/configurations.md

@@ -0,0 +1,87 @@
+# ⚙️ Expression Engine
+
+The **Expression Engine** is a flexible and expressive filtering engine designed to handle both flat and deeply nested filters, including relationships and their attributes.
+
+It is ideal when you want the power of RuleSet-style syntax but also need to filter through relationships and nested relations easily.
+
+---
+
+## 📦 Example Request
+
+```http
+GET /posts?filter[status]=pending&filter[author.profile.name][like]=kettasoft
+```
+
+This will:
+
+- Filter posts where `status` is `pending`
+- AND where the related author's profile `name` contains `kettasoft`
+
+---
+
+## 🛠️ How It Works
+
+- Filters are parsed from the request's `filter` key.
+- Each filter can be a:
+
+  - Simple key-value pair (e.g., `filter[status]=active`)
+  - Operator-based pair (e.g., `filter[name][like]=kettasoft`)
+  - Nested relation filter (e.g., `filter[author.profile.name]=ahmed`)
+
+- The engine determines the filter structure and applies the corresponding query constraints.
+
+---
+
+## 🔧 Default Operator
+
+If a filter doesn't specify an operator, the **default operator** will be used.  
+This default is configurable in the engine settings.
+
+```php
+'default_operator' => '='
+```
+
+---
+
+## ✅ Supported Features
+
+- ✅ Flat and nested filters
+- ✅ Dot notation for relationships (e.g., `author.profile.name`)
+- ✅ Customizable default operator
+- ✅ Whitelisting of allowed fields & relations
+- ✅ Works well with eager loading and relationship validation
+- ✅ Prevents filtering on undefined fields (optional strict mode)
+
+---
+
+## ✅ Allowed Fields & Relations
+
+To avoid unauthorized or unintended access, you can configure the engine to only accept specific fields or relations:
+
+```php
+Filterable::create()->useEngine('expression')
+  ->allowdFields(['status'])
+  ->allowRelations([
+    'author.profile' => ['name'] // specific fields in this relation
+  ])->paginate()
+```
+
+In **strict mode**, unsupported fields will be rejected with a validation error.
+
+---
+
+## 📌 Use Case
+
+```php
+Post::filter($filters, ExpressionEngine::class)->get();
+```
+
+---
+
+## 🧠 Internal Logic (Simplified)
+
+- Parse the `filter` array recursively.
+- Detect relationships via dot notation.
+- Resolve the relation path and apply `whereHas` queries for related models.
+- Build appropriate SQL queries via the Eloquent builder.
+- Use the defined or default operator.

docs/engines/expression.md

@@ -2,9 +2,9 @@
 sidebarDepth: 2
 ---
 
-# Dynamic Method Engine
+# Invokable Engine
 
-The **Dynamic Method Engine** provides a powerful way to dynamically map incomming reuqest parameters to corresponding methods in a filter class. This mechanism enables clean, scalable filtering logic and behavior injection without requiring large **switch** or **if-else** blocks.
+The **Invokable Engine** provides a powerful way to dynamically map incomming reuqest parameters to corresponding methods in a filter class. This mechanism enables clean, scalable filtering logic and behavior injection without requiring large **switch** or **if-else** blocks.
 
 ---