masquerade-orm 0.8.1 → 0.8.3

package/docs/find.md

@@ -1,265 +1,275 @@
-# Find
-
-```js
-await ExampleClass.find(findObj)
-```
-
-The `find` method is the most complex part of the ORM. **Fortunately, it is fully covered by IntelliSense, and you are strongly encouraged to rely on it.**
-
-It accepts a single argument, findObj, which contains three optional fields.
-Because all fields are optional, findObj itself may be an empty object (although this is rarely useful, as it would return all instances of ExampleClass).
-
-The three optional fields are:
-
-- relations
-- where
-- relationalWhere
-
-
-
-## The `relations` Field:
-
-The `relations` field determines which relations are eagerly loaded from the database.
-
-A crucial detail to understand is that relations are never filtered.
-They are either loaded or not. The ORM never displays partial relational data.
-
-```js
-// assume that relationalProp is a property of type SomeClass or SomeClass[]
-await ExampleClass.find(
-    {
-        relations: {relationalProp: true},
-        where: {
-            relationalProp: {
-                id: 57
-            }
-        }
-    }
-)
-```
-
-The example above translates to:   
-**“Fetch all instances of ExampleClass whose relationalProp contains a SomeClass instance with id = 57.”**
-
-In other words, the condition matches when either of the following is true:  
-
-```js
-// 1-to-1 relationship case
-exampleClassInstance.relationalProp === someClassId57 
-```    
-or   
-```js
-// 1-to-many relationship case
-exampleClassInstance.relationalProp.includes(someClassId57)
-```    
-
-### Lazy Loading
-
-```js
-// Assume the 'Chat' class has relational properties 'users' and 'messages'.
-// Initially, we load only the 'messages' relation for a specific chat.
-
-const resultArray = await Chat.find({
-    relations: { messages: true }, // eager load the 'messages' relation
-    where: { id: 123 } // fetch the chat with ID 123
-})
-
-const someChat = resultArray[0]
-
-// At this point, 'someChat.users' is not loaded. 
-// To load the 'users' relation, we need to await it.
-await someChat.users
-```
-
-
-## The `where` Field:
-
-The `where` field is for filtering the root instances, in the following case, Chat instances.
-```js
-await Chat.find({
-    where: {
-        messages: {
-            sender: {
-                id: 12
-            }
-        }
-    }
-})
-```
-Translation: **“Find all chats that contain a message from a user with the id 12, without loading messages.“**     
-
-- **Note:** The scope of the `where` condtions is agnostic to the scope of the `relations` (eager-loading).       
-It is completely safe to filter based on specific relations without having said relations passed into the `relations` field.      
-
-### Introduction to the `sql`, `OR` and `AND`  functions 
-
-```js
-import { sql, AND, OR } from "masquerade"
-
-await Angel.find({
-    where: {
-        // name is either "Micheal" OR "Gabriel"
-        name: OR('Micheal', 'Gabriel'),
-
-        // demonsSentToAbyss is greater than 12,000 AND less than 57,000
-        demonsSentToAbyss: AND(sql`> 12000`, sql`< 57000`)
-    }
-})
-```
-
-### Using the `sql` function with explicit column identifiers   
-In the previous example, the `sql` function implicitly inserted a column identifier (`#`) on the left side of the SQL statement. 
-```js
-// these two statements are equivalent
-sql`> 12000`  
-sql`# > 12000` 
-```
-
-In next example, `#` identifiers must be written explicitly because the SQL string uses `AND` conditional operators directly, rather than using the `AND()` helper function.
-
-```js
-import { sql } from "masquerade"
-
-const twoYearsAgo = new Date().setFullYear(new Date().getFullYear() - 2)
-const oneYearAgo = new Date().setFullYear(new Date().getFullYear() - 1)
-
-await User.find({
-    where: {
-        // donations between 1,200 and 5,700 cents (exclusive)
-        donations: sql`1200 < # AND # < 5700`, 
-
-        // account's age is between one and two years old.
-        createdAt: sql`${twoYearsAgo} <= # AND # <= ${oneYearAgo}` 
-    }
-})
-// The ANDs are written directly inside the 'sql' string instead of 
-// having to rely on helper functions to achieve the same result. 
-// The 'sql' function gives you the ability to write powerful
-// 'where' conditions in an easy-to-read and easy-to-write manner.
-```
-
-### Using the `sql` function to create a `LIKE` `WHERE` condition 
-```js
-import { sql } from "masquerade"
-
-await User.find({
-    where: {
-        // registered using a Gmail email
-        email: sql`LIKE '%@gmail.com%'`
-    }
-})
-```
-
-### Using the `sql` function to create a `WHERE` condition for matching JSON values
-
-```ts
-import { Entity } from "masquerade"
-
-type OrderOverview = {
-  status: "pending" | "completed" | "cancelled"
-  total: number
-  currency: string
-}
-
-class Order extends Entity {
-  // other properties...
-  metadata: UserMetadata
-  // other properties + constructor...
-}
-
-const completedOrders = await Order.find({
-  where:
-    { overview: sql`json_extract(#, '$.status') = 'completed'` }
-})
-```
-
-- **Note:** for SQL-client specific guide for writing `WHERE` conditions involving JSON and array data, go to the bottom of this page or click **[here](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/find.md#array-and-json-where-conditions-guide)**.
-
-
-## The `relationalWhere` Field:
-
-```js
-import { sql } from "masquerade"
-
-// Finds users that have at least one chat that contains at least one message whose sender's username is 'Glory2Christ'.
-await User.find({
-   relationalWhere: (user) => sql`${user.chats.messages.sender.username} = 'Glory2Christ'`
-})
-```
-
-```js
-import { sql } from "masquerade"
-
-// Identical to the previous example, but here the relational where is called from a different scope.
-// note: the field has an underscore, to prevent any (rather impossible) name collisions.
-
-await User.find({
-  where: {
-    chats: {
-      relationalWhere_: (chat) => sql`${chat.messages.sender.username} = 'Glory2Christ'`,
-      // can be combined with regular 'where' conditions - below is valid code
-      // chatName: 'The History of Orthodoxy' 
-    }
-  }
-})
-```
-
-### Array and JSON `WHERE` Conditions Guide
-
-The model we will use for the examples:
-
-```ts
-import { Entity } from "masquerade"
-
-type UserMetadata = {
-  roles: string[]          // e.g., ["admin", "moderator"]
-  lastLogin?: string       // optional, ISO date string
-  preferences?: {
-    theme?: "light" | "dark"
-    notifications?: boolean
-  }
-}
-
-class User extends Entity {
-  // other properties...
-  metadata: UserMetadata
-  sessions: string[]
-  // other properties + constructor...
-}
-```
-
-Assuming we are writing the condition for the property `metadata` or `sessions`  like so:
-```ts
-import { sql } from "masquerade"
-// 'metadata' find
-const users = await User.find({where: {metadata: sql`_OPERATION_STRING_`}})
-
-// 'sessions' find 
-const users2 = await User.find({where: {sessions: sql`_OPERATION_STRING_`}})
-
-// **if not specified, the default is the 'metadata' find
-
-// replace _OPERATION_STRING_ with the appropriate 
-// operation string from the table below
-```
-
-<strong>**Operation String Table**
-
-| Operation    | SQLite      | PostgreSQL   |
-|-------------|---------------|------------|
-Array length <br>(example uses len = 2) | **'metadata' find** <br> `json_array_length(json_extract(#, '$.roles')) > 2` <br> **'sessions' find** <br> `json_array_length(json_extract(#)) > 2` | **'metadata' find** <br> `jsonb_array_length(#->'roles') > 2` <br> **'sessions' find** <br> `jsonb_array_length(#) > 2`|
-| Access index `i` of array   | **'metadata' find** <br>`json_extract(#, '$.roles[i]') = 'admin'`<br> **'sessions' find** <br>`json_extract(#, '$[i]') = 'SOME_SESSION_ID'` | **'metadata' find** <br>`#->'roles'->>i = 'admin''`<br> **'sessions' find** <br>`#->>i = 'admin'` |
-| Check if array contains a value | `json_extract(#, '$.roles') LIKE '%"admin"%'` | `#->'roles' @> '["admin"]'::jsonb` |
-Check nested field | `json_extract(#, '$.preferences.theme') = 'dark'` | `#->'preferences'->>'theme' = 'dark'` |
-</strong>
-
-
-<br>
-<div align="center">
-  <strong>
-    © 2026 
-    <a href="https://github.com/MasqueradeORM">MasqueradeORM </a>
-		-
-    Released under the MIT License
-  </strong>
+# Find
+
+```js
+await ExampleClass.find(findObj)
+```
+
+The `find` method is the most complex part of the ORM. **Fortunately, it is fully covered by IntelliSense, and you are strongly encouraged to rely on it.**
+
+It accepts a single argument, findObj, which contains three optional fields.
+Because all fields are optional, findObj itself may be an empty object (although this is rarely useful, as it would return all instances of ExampleClass).
+
+The three optional fields are:
+
+- relations
+- where
+- templateWhere
+
+
+
+## The `relations` Field:
+
+The `relations` field determines which relations are eagerly loaded from the database.
+
+A crucial detail to understand is that relations are never filtered.
+They are either loaded or not. The ORM never displays partial relational data.
+
+```js
+// assume that relationalProp is a property of type SomeClass or SomeClass[]
+await ExampleClass.find(
+    {
+        relations: {relationalProp: true},
+        where: {
+            relationalProp: {
+                id: 57
+            }
+        }
+    }
+)
+```
+
+The example above translates to:   
+**“Fetch all instances of ExampleClass whose relationalProp contains a SomeClass instance with id = 57.”**
+
+In other words, the condition matches when either of the following is true:  
+
+```js
+// 1-to-1 relationship case
+exampleClassInstance.relationalProp === someClassId57 
+```    
+or   
+```js
+// 1-to-many relationship case
+exampleClassInstance.relationalProp.includes(someClassId57)
+```    
+
+### Lazy Loading
+
+```js
+// Assume the 'Chat' class has relational properties 'users' and 'messages'.
+// Initially, we load only the 'messages' relation for a specific chat.
+
+const resultArray = await Chat.find({
+    relations: { messages: true }, // eager load the 'messages' relation
+    where: { id: 123 } // fetch the chat with ID 123
+})
+
+const someChat = resultArray[0]
+
+// At this point, 'someChat.users' is not loaded. 
+// To load the 'users' relation, we need to await it.
+await someChat.users
+```
+
+
+## The `where` Field:
+
+The `where` field is for filtering the root instances, in the following case, Chat instances.
+```js
+await Chat.find({
+    where: {
+        messages: {
+            sender: {
+                id: 12
+            }
+        }
+    }
+})
+```
+Translation: **“Find all chats that contain a message from a user with the id 12, without loading messages.“**     
+
+- **Note:** The scope of the `where` condtions is agnostic to the scope of the `relations` (eager-loading).       
+It is completely safe to filter based on specific relations without having said relations passed into the `relations` field.      
+
+### Introduction to the `sql`, `OR` and `AND`  functions 
+
+```js
+import { sql, AND, OR } from "masquerade-orm"
+
+await Angel.find({
+    where: {
+        // name is either "Micheal" OR "Gabriel"
+        name: OR('Micheal', 'Gabriel'),
+
+        // demonsSentToAbyss is greater than 12,000 AND less than 57,000
+        demonsSentToAbyss: AND(sql`> 12000`, sql`< 57000`)
+    }
+})
+```
+
+### Using the `sql` function with explicit column identifiers   
+In the previous example, the `sql` function implicitly inserted a column identifier (`#`) on the left side of the SQL statement. 
+```js
+// these two statements are equivalent
+sql`> 12000`  
+sql`# > 12000` 
+```
+
+In next example, `#` identifiers must be written explicitly because the SQL string uses `AND` conditional operators directly, rather than using the `AND()` helper function.
+
+```js
+import { sql } from "masquerade-orm"
+
+const twoYearsAgo = new Date().setFullYear(new Date().getFullYear() - 2)
+const oneYearAgo = new Date().setFullYear(new Date().getFullYear() - 1)
+
+await User.find({
+    where: {
+        // donations between 1,200 and 5,700 cents (exclusive)
+        donations: sql`1200 < # AND # < 5700`, 
+
+        // account's age is between one and two years old.
+        createdAt: sql`${twoYearsAgo} <= # AND # <= ${oneYearAgo}` 
+    }
+})
+// The ANDs are written directly inside the 'sql' string instead of 
+// having to rely on helper functions to achieve the same result. 
+// The 'sql' function gives you the ability to write powerful
+// 'where' conditions in an easy-to-read and easy-to-write manner.
+```
+
+<!-- **Equivalent Alternative Syntax:** 
+```js
+await User.find({
+    where: {
+        donations: (donations) => sql`1200 < ${donations} AND ${donations} < 5700`, 
+        createdAt: (createdAt) => sql`${twoYearsAgo} <= ${createdAt} AND ${createdAt} <= ${oneYearAgo}` 
+    }
+})
+``` -->
+
+### Using the `sql` function to create a `LIKE` `WHERE` condition 
+```js
+import { sql } from "masquerade-orm"
+
+await User.find({
+    where: {
+        // registered using a Gmail email
+        email: sql`LIKE '%@gmail.com%'`
+    }
+})
+```
+
+### Using the `sql` function to create a `WHERE` condition for matching JSON values
+
+```ts
+import { Entity } from "masquerade-orm"
+
+type OrderOverview = {
+  status: "pending" | "completed" | "cancelled"
+  total: number
+  currency: string
+}
+
+class Order extends Entity {
+  // other properties...
+  metadata: UserMetadata
+  // other properties + constructor...
+}
+
+const completedOrders = await Order.find({
+  where:
+    { overview: sql`json_extract(#, '$.status') = 'completed'` }
+})
+```
+
+- **Note:** for SQL-client specific guide for writing `WHERE` conditions involving JSON and array data, go to the bottom of this page or click **[here](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/find.md#array-and-json-where-conditions-guide)**.
+
+
+## The `templateWhere` Field:
+
+```js
+import { sql } from "masquerade-orm"
+
+// Finds users that have at least one chat that contains at least one message whose sender's username is 'Glory2Christ'.
+await User.find({
+   templateWhere: (user) => sql`${user.chats.messages.sender.username} = 'Glory2Christ'`
+})
+```
+
+```js
+import { sql } from "masquerade-orm"
+
+// Identical to the previous example, but here the 'templateWhere' is called from a different scope.
+// note: the field has an underscore, to prevent any (rather impossible) name collisions.
+
+await User.find({
+  where: {
+    chats: {
+      templateWhere_: (chat) => sql`${chat.messages.sender.username} = 'Glory2Christ'`,
+      // can be combined with regular 'where' conditions - below is valid code
+      // chatName: 'The History of Orthodoxy' 
+    }
+  }
+})
+```
+
+### Array and JSON `WHERE` Conditions Guide
+
+The model we will use for the examples:
+
+```ts
+import { Entity } from "masquerade-orm"
+
+type UserMetadata = {
+  roles: string[]          // e.g., ["admin", "moderator"]
+  lastLogin?: string       // optional, ISO date string
+  preferences?: {
+    theme?: "light" | "dark"
+    notifications?: boolean
+  }
+}
+
+class User extends Entity {
+  // other properties...
+  metadata: UserMetadata
+  sessions: string[]
+  // other properties + constructor...
+}
+```
+
+Assuming we are writing the condition for the property `metadata` or `sessions`  like so:
+```ts
+import { sql } from "masquerade-orm"
+// 'metadata' find
+const users = await User.find({where: {metadata: sql`_OPERATION_STRING_`}})
+
+// 'sessions' find 
+const users2 = await User.find({where: {sessions: sql`_OPERATION_STRING_`}})
+
+// **if not specified, the default is the 'metadata' find
+
+// replace _OPERATION_STRING_ with the appropriate 
+// operation string from the table below
+```
+
+<strong>**Operation String Table**
+
+| Operation    | SQLite      | PostgreSQL   |
+|-------------|---------------|------------|
+Array length <br>(example uses len = 2) | **'metadata' find** <br> `json_array_length(json_extract(#, '$.roles')) > 2` <br> **'sessions' find** <br> `json_array_length(json_extract(#)) > 2` | **'metadata' find** <br> `jsonb_array_length(#->'roles') > 2` <br> **'sessions' find** <br> `jsonb_array_length(#) > 2`|
+| Access index `i` of array   | **'metadata' find** <br>`json_extract(#, '$.roles[i]') = 'admin'`<br> **'sessions' find** <br>`json_extract(#, '$[i]') = 'SOME_SESSION_ID'` | **'metadata' find** <br>`#->'roles'->>i = 'admin''`<br> **'sessions' find** <br>`#->>i = 'admin'` |
+| Check if array contains a value | `json_extract(#, '$.roles') LIKE '%"admin"%'` | `#->'roles' @> '["admin"]'::jsonb` |
+Check nested field | `json_extract(#, '$.preferences.theme') = 'dark'` | `#->'preferences'->>'theme' = 'dark'` |
+</strong>
+
+
+<br>
+<div align="center">
+  <strong>
+    © 2026 
+    <a href="https://github.com/MasqueradeORM">MasqueradeORM </a>
+		-
+    Released under the MIT License
+  </strong>
 </div>

package/docs/getting-started-javascript.md

@@ -3,7 +3,7 @@
 
 ## 1) Declaring the Class:
 ```js
-import { Entity } from 'masquerade'
+import { Entity } from 'masquerade-orm'
 
 class YourClass extends Entity {
   // class properties
@@ -18,7 +18,7 @@ The class **MUST** extend `Entity` or a descendent of `Entity`.
 
 ## 3) Making a Table Column Unique:
 ```js
-/**@typedef {import('masquerade').integer} integer */
+/**@typedef {import('masquerade-orm').integer} integer */
 /**@type {string | Unique}*/ propertyName
 ```   
 
@@ -26,7 +26,8 @@ The class **MUST** extend `Entity` or a descendent of `Entity`.
 Assuming we have the following classes extending Entity: `User`, `Chat` and `Message`.    
 
 ```js
-import { Entity } from 'masquerade'
+import { Entity } from 'masquerade-orm'
+import { User, Chat, Message } from './your/entities'
 
 class Example extends Entity {
     // one-to-one relationship with a User instance
@@ -47,6 +48,8 @@ class Example extends Entity {
 Each relational property will create a junction table named `className___propName_jt`.
 
 
+** **For more in-depth documentation regarding class definitions **[click here](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/in-depth-class-definitions.md)**.** **
+
 # Booting Up the ORM
 
 ## 1) Database Connection Driver:
@@ -76,7 +79,7 @@ const yourDbConnection = new Pool({
 
 ## 2) Configuration Object:
 ```js
-/**@typedef {import('masquerade').OrmConfigObj} OrmConfigObj*/
+/**@typedef {import('masquerade-orm').OrmConfigObj} OrmConfigObj*/
 
 /** @type {OrmConfigObj} */ const ormConfig = {
     dbConnection: yourDbConnection,
@@ -101,6 +104,12 @@ await ORM.javascriptBoot(ormConfig, classes, moreClasses, someClass)
 
 <h1 align="center">All done!</h1>
 
+<div align="center">
+
+### **It is HIGHLY recommended to read [JSDoc – UX Tips](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/jsdoc-ux-tips.md)**
+
+</div>
+
 <br>
 <div align="center">
   <strong>

package/docs/getting-started-typescript.md

@@ -3,7 +3,7 @@
 
 ## 1) Declaring the Class:
 ```js
-import { Entity } from 'masquerade'
+import { Entity } from 'masquerade-orm'
 
 class YourClass extends Entity {
   // class properties
@@ -20,7 +20,7 @@ propertyName?: string
 ## 3) Making a Table Column Unique:
 
 ```ts
-import { Unique } from 'masquerade'
+import { Unique } from 'masquerade-orm'
 propertyName: string | Unique
 ```   
 
@@ -28,7 +28,8 @@ propertyName: string | Unique
 Assuming we have the following classes extending Entity: `User`, `Chat` and `Message`.   
 
 ```ts
-import { Entity } from 'masquerade'
+import { Entity } from 'masquerade-orm'
+import { User, Chat, Message } from './your/entities'
 
 class Example extends Entity {
     // one-to-one relationship with a User instance
@@ -48,6 +49,7 @@ class Example extends Entity {
 ```
 Each relational property will create a junction table named `className___propName_jt`.
 
+** **For more in-depth documentation regarding class definitions **[click here](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/in-depth-class-definitions.md)**.** **
 
 # Booting Up the ORM
 
@@ -78,7 +80,7 @@ const yourDbConnection = new Pool({
 
 ## 2) Configuration Object:
 ```ts
-import type { OrmConfigObj } from "masquerade"
+import type { OrmConfigObj } from "masquerade-orm"
 
 const ormConfig: OrmConfigObj = { 
     dbConnection: yourDbConnection,