@dreamtree-org/korm-js 1.0.40 → 1.0.41

package/README.md

@@ -500,6 +500,210 @@ POST /api/Users/crud
 }
 ```
 
+## Relational Support with hasRelations
+
+### Understanding hasRelations Structure
+
+The `hasRelations` object in your schema defines relationships between models. Based on your actual schema file (`../borebell.in/schema/sync.json`), relationships use the following structure:
+
+#### One-to-One or Belongs-To Relationship (`type: "one"`)
+
+```json
+{
+  "UserDetail": {
+    "hasRelations": {
+      "User": {
+        "type": "one",
+        "table": "users",
+        "localKey": "user_id",
+        "foreignKey": "id"
+      }
+    }
+  }
+}
+```
+
+#### One-to-Many Relationship (`type: "many"`)
+
+```json
+{
+  "User": {
+    "hasRelations": {
+      "Post": {
+        "type": "many",
+        "table": "posts",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      },
+      "Comment": {
+        "type": "many",
+        "table": "comments",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      }
+    }
+  }
+}
+```
+
+#### Many-to-Many Relationship (using `through`)
+
+For many-to-many relationships, use the `through` key to specify the join/pivot table:
+
+```json
+{
+  "User": {
+    "hasRelations": {
+      "Role": {
+        "type": "many",
+        "table": "roles",
+        "localKey": "id",
+        "foreignKey": "id",
+        "through": "user_roles",
+        "throughLocalKey": "user_id",
+        "throughForeignKey": "role_id"
+      }
+    }
+  }
+}
+```
+
+**Many-to-Many Structure:**
+- `type`: `"many"` (always use "many" for many-to-many)
+- `table`: The related table name (e.g., `"roles"`)
+- `localKey`: The primary key in the current model (e.g., `"id"`)
+- `foreignKey`: The primary key in the related table (e.g., `"id"`)
+- `through`: **Required** - The join/pivot table name (e.g., `"user_roles"`)
+- `throughLocalKey`: The foreign key in the join table pointing to the current model (e.g., `"user_id"`)
+- `throughForeignKey`: The foreign key in the join table pointing to the related model (e.g., `"role_id"`)
+
+### Using Relationships in Queries
+
+#### Eager Loading with `with`
+
+```javascript
+// Load User with related Posts and Comments
+POST /api/User/crud
+{
+  "action": "list",
+  "where": { "id": 1 },
+  "with": ["Post", "Comment"]
+}
+
+// Nested relationships
+POST /api/User/crud
+{
+  "action": "list",
+  "where": { "id": 1 },
+  "with": ["Post.Comment", "Post.Like"]
+}
+
+// Multiple relationships
+POST /api/User/crud
+{
+  "action": "list",
+  "where": { "id": 1 },
+  "with": ["UserDetail", "Post", "Comment", "Like"]
+}
+```
+
+#### Filtering Related Data with Nested Where
+
+```javascript
+// Get users who have posts with specific hashtag
+POST /api/User/crud
+{
+  "action": "list",
+  "where": {
+    "Post.hashtag": "#OrganicFarming"
+  },
+  "with": ["Post"]
+}
+
+// Get posts with comments from specific user
+POST /api/Post/crud
+{
+  "action": "list",
+  "where": {
+    "Comment.user_id": 1
+  },
+  "with": ["Comment"]
+}
+```
+
+### Example: Complete Relationship Structure
+
+Based on your actual schema (`../borebell.in/schema/sync.json`):
+
+```json
+{
+  "User": {
+    "table": "users",
+    "hasRelations": {
+      "UserDetail": {
+        "type": "one",
+        "table": "user_details",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      },
+      "Post": {
+        "type": "many",
+        "table": "posts",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      },
+      "Comment": {
+        "type": "many",
+        "table": "comments",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      },
+      "Like": {
+        "type": "many",
+        "table": "likes",
+        "localKey": "id",
+        "foreignKey": "user_id"
+      }
+    }
+  },
+  "Post": {
+    "table": "posts",
+    "hasRelations": {
+      "User": {
+        "type": "one",
+        "table": "users",
+        "localKey": "user_id",
+        "foreignKey": "id"
+      },
+      "Comment": {
+        "type": "many",
+        "table": "comments",
+        "localKey": "id",
+        "foreignKey": "post_id"
+      },
+      "Like": {
+        "type": "many",
+        "table": "likes",
+        "localKey": "id",
+        "foreignKey": "post_id"
+      }
+    }
+  }
+}
+```
+
+### Important Notes
+
+> **Always refer to your actual schema file** (`../borebell.in/schema/sync.json`) for the exact relationship definitions in your project. The structure shown above matches the format used in your schema.
+
+- `type: "one"` = One-to-One or Belongs-To relationship
+- `type: "many"` = One-to-Many relationship
+- `through` = Required for Many-to-Many relationships (specifies the join table)
+- `localKey` = The key in the current model
+- `foreignKey` = The key in the related table
+- `throughLocalKey` = The key in the join table pointing to current model (for many-to-many)
+- `throughForeignKey` = The key in the join table pointing to related model (for many-to-many)
+
 ## Soft Delete Support
 
 ### Enabling Soft Delete

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamtree-org/korm-js",
-  "version": "1.0.40",
+  "version": "1.0.41",
   "description": "Knowledge Object-Relational Mapping - A powerful, modular ORM system for Node.js with dynamic database operations, complex queries, relationships, and nested requests",
   "author": {
     "name": "Partha Preetham Krishna",