masquerade-orm 0.8.1 → 0.8.2

package/README.md

@@ -134,13 +134,12 @@ user.friendList.pop()
 
 - **[Getting Started - Javascript](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/getting-started-javascript.md#class-definitions)**
 - **[Getting Started - Typescript](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/getting-started-typescript.md#class-definitions)**
+- **[Defining Classes: In-Depth](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/in-depth-class-definitions.md)** **(important read)**
 - **[Find Method](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/find.md#find)**
 - **[Saving to Database](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/saving-to-database.md#saving-to-the-database)**
 - **[Deleting Instances from the Database](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/deletion.md)**
 - **[Managing Database Tables](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/managing-the-database.md)**
-- **[Defining Classes: In-Depth](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/in-depth-class-definitions.md)** **(important read)**
-
-
+- **[JSDoc – UX Tips](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/jsdoc-ux-tips.md)**
 
 <br>
 <div align="center">

package/docs/deletion.md

@@ -72,7 +72,7 @@ const softDelUser = new SoftDeletableUser('JohnDoe', 'JohnDoe@gmail.com', 'hashe
 ### Hard Deletion
 
 ```ts
-import { sql } from "masquerade"
+import { sql } from "masquerade-orm"
 const twoYearsAgo = new Date().setFullYear(new Date().getFullYear() - 2)
 
 // finds all instances that haven't been mutated in over two years

package/docs/find.md

@@ -1,265 +1,265 @@
-# 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
+- 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-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.
+```
+
+### 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 `relationalWhere` 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({
+   relationalWhere: (user) => sql`${user.chats.messages.sender.username} = 'Glory2Christ'`
+})
+```
+
+```js
+import { sql } from "masquerade-orm"
+
+// 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-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,

package/docs/in-depth-class-definitions.md

@@ -5,7 +5,7 @@
 
 **TypseScript**
 ```ts
-import { Entity, integer } from 'masquerade'
+import { Entity, integer } from 'masquerade-orm'
 
 type MyJSON = {
     booleanField: boolean
@@ -45,8 +45,8 @@ class ExampleClass extends Entity {
 ```
 **JavaScript**
 ```js
-import { Entity } from 'masquerade'
-/**@typedef {import('masquerade').integer} integer */
+import { Entity } from 'masquerade-orm'
+/**@typedef {import('masquerade-orm').integer} integer */
 
 /**
  * @typedef {Object} MyJSON
@@ -63,7 +63,7 @@ class ExampleClass extends Entity {
     /**@type {number}*/ float = 15.7
 
     // Allowed
-    /**@type {(string | undefined)[]}*/ stringArrWithUndefineds = [
+    /**@type { (string | undefined)[] }*/ stringArrWithUndefineds = [
         'hello', 'world' , undefined
         ]
 
@@ -117,7 +117,7 @@ Both approaches will allow for proper detection and persisting of such changes.
 ## 2) Overriding the Default Id-Type
 
 ```js
-import { Entity } from 'masquerade'
+import { Entity } from 'masquerade-orm'
 
 class ClassA extends Entity {
     // to avoid bugs put 'ormClassSettings_' as the first property.
@@ -131,7 +131,7 @@ The above code lets you override the default id-type that is assigned to all Ent
 Setting the `idType` is only possible on a **direct child of Entity**.    
 
 ```ts
-import { Entity } from 'masquerade'
+import { Entity } from 'masquerade-orm'
 
 class ClassA extends Entity {
     // properties and constructor...
@@ -152,7 +152,7 @@ At the moment, this is the only class setting supported, but it may evolve in th
 ### How to create an `abstract class` when using JSDoc?
 Put the decorator `/**@abstract*/` right above the constructor of the class.   
 ```js
-import { Entity } from 'masquerade'
+import { Entity } from 'masquerade-orm'
 
 class User extends Entity {
     // properties...

package/docs/jsdoc-ux-tips.md

@@ -1,17 +1,252 @@
-# Miscellaneous
-- **Importing types from package**
-
-```js
-/**@typedef {import('masquerade').OrmConfigObj} OrmConfigObj*/
-```
-
-
-<br>
-<div align="center">
-  <strong>
-    © 2026 
-    <a href="https://github.com/MasqueradeORM">MasqueradeORM </a>
-		-
-    Released under the MIT License
-  </strong>
+# JSDoc - UX Tips
+
+#### ** Note: The following guide is for Visual Studio Code users **
+
+This guide will instruct you on how to adjust your VS Code settings to vastly improve your experience with JSDoc annotation.
+
+Here is how your code will look like after applying the settings:
+
+ 
+![img](https://github.com/MasqueradeORM/MasqueradeORM/releases/download/0.1.0/jsdoc-class-example.png)
+
+
+
+### 1) Install the [`Inline fold`](https://marketplace.visualstudio.com/items?itemName=moalamri.inline-fold) Extension
+
+Either click the link in the title or run the following command in the terminal:
+```bash
+code --install-extension moalamri.inline-fold
+```
+
+### 2) Modify `User Settings (JSON)`
+**First Step**
+- Windows / Linux: Ctrl + Shift + P
+- macOS: Cmd + Shift + P
+
+**Second Step**
+
+Type `Preferences: Open User Settings (JSON)` and press Enter.
+
+**Third Step**
+
+Copy the lines below into the JSON and save.
+```JSON
+{    
+	"inlineFold.regex": "(\\/\\*\\*@\\w+\\s+\\{|(?<=\\/\\*\\*@\\w+\\s+\\{.*)\\}\\s*\\w*\\*\\/)",
+    "inlineFold.regexGroup": "1",
+    "inlineFold.maskChar": "",
+    "inlineFold.after": "",
+    "inlineFold.unfoldOnLineSelect": true,
+    "inlineFold.unfoldedOpacity": 1
+}
+```
+
+### 3) Create Snippet File
+**First Step**
+- Windows / Linux: Ctrl + Shift + P
+- macOS: Cmd + Shift + P
+
+**Second Step**
+
+Type `Snippets: Configure Snippets` and press Enter.
+
+**Third Step**
+
+Choose the `New Global Snippets file...` option and press Enter.
+
+**Fourth Step**
+
+Name you snippet file, for example, `JSDoc_UX`.
+
+
+**Fifth Step**
+
+Copy the JSON below and save.
+```JSON
+{
+	"@type let": {
+		"scope": "javascript,typescript",
+		"prefix": "let",
+		"body": [
+			"/**@type {${1}}*/ let $0"
+		]
+	},
+	"@type const": {
+		"scope": "javascript,typescript",
+		"prefix": "const",
+		"body": [
+			"/**@type {${1}}*/ const $0"
+		]
+	},
+	"@type string": {
+		"scope": "javascript,typescript",
+		"prefix": "string",
+		"body": [
+			"/**@type {string${1}}*/$0"
+		]
+	},
+	"@type number": {
+		"scope": "javascript,typescript",
+		"prefix": "number",
+		"body": [
+			"/**@type {number${1}}*/$0"
+		]
+	},
+	"@type boolean": {
+		"scope": "javascript,typescript",
+		"prefix": "boolean",
+		"body": [
+			"/**@type {boolean${1}}*/$0"
+		]
+	},
+	"@type any": {
+		"scope": "javascript,typescript",
+		"prefix": "any",
+		"body": [
+			"/**@type {any${1}}*/$0"
+		]
+	},
+	"@type Map": {
+		"scope": "javascript,typescript",
+		"prefix": "Map",
+		"body": [
+			"/**@type {Map<${1}>}*/$0"
+		]
+	},
+	"@type Function": {
+		"scope": "javascript,typescript",
+		"prefix": "Function",
+		"body": [
+			"/**@type {Function${1}}*/$0"
+		]
+	},
+	"@type": {
+		"scope": "javascript,typescript",
+		"prefix": "type",
+		"body": [
+			"/**@type {${1}}*/$0"
+		]
+	},
+	"@return": {
+		"scope": "javascript,typescript",
+		"prefix": "return",
+		"body": [
+			"/**@return {${1}}*/$0"
+		]
+	},
+	"@typedef import": {
+		"scope": "javascript,typescript",
+		"prefix": "importTypedef",
+		"body": [
+			"/**@typedef {import('${1}').$2} $3*/$0"
+		]
+	},
+	"@typedef": {
+		"scope": "javascript,typescript",
+		"prefix": "typedef",
+		"body": [
+			"/**",
+			"* @typedef {Object} ${1:MyObject}",
+			"* @property {${2:boolean}} ${3:booleanField}",
+			"* @property {${4:object}} ${5:nestedObj}",
+			"*/"
+		],
+		"description": "JSDoc typedef for an object"
+	}
+}
+```
+**Note:** You can change the `prefix` fields if you do not like the shortcut names.
+
+
+### 4) Configure the `jsconfig.json` file
+
+Add the following lines to your `jsconfig.json` (or `tsconfig.json`) file:
+```JSON
+"allowJs": true,
+"checkJs": true
+```
+
+
+## Using the Shortcuts
+
+
+### Importing Types
+
+- **Use `importTypedef`**
+```js
+// importing from a package
+/**@typedef {import('masquerade-orm').OrmConfigObj} OrmConfigObjAlias*/
+// importing from some file
+/**@typedef {import('./path/to/file').YourImportedType} YourImportedTypeAlias*/
+```
+
+![gif](https://github.com/MasqueradeORM/MasqueradeORM/releases/download/0.1.0/import-typedef.gif)
+
+
+### Typing Variables
+- **Use `type` / `string` / `number` / `boolean` (etc)**
+```js
+/**@type {string}*/ someString = '123'
+/**@type {number}*/ someNumber = 567
+```
+![gif](https://github.com/MasqueradeORM/MasqueradeORM/releases/download/0.1.0/type-declarations.gif)
+
+
+### `Object` Type Deinition Template
+- **Use `typedef`**
+```js
+/**
+* @typedef {Object} YourObject
+* @property {string} someString
+* @property {number} someNum
+*/
+```
+
+![gif](https://github.com/MasqueradeORM/MasqueradeORM/releases/download/0.1.0/typedef.gif)
+
+### Defining Classes
+
+```js
+import { Entity } from 'masquerade-orm'
+/**@typedef {import('masquerade-orm').Unique} Unique*/
+
+class User extends Entity {
+    /**@type {string | Unique}*/ username
+    /**@type {string | Unique}*/ email
+    /**@type {string}*/ password
+    /**@type {boolean}*/ isBanned = false
+    /**@satisfies {UserMetadata}*/ metadata = {
+        twoFactorAuth: false,
+        createdAt: new Date()
+    }
+
+    constructor(
+	/**@type {string}*/ username, 
+	/**@type {string}*/ email, 
+	/**@type {string}*/ password) {
+        super()
+        this.username = username
+        this.email = email
+        this.password = password
+    }
+}
+
+/**
+* @typedef {Object} UserMetadata
+* @property {boolean} twoFactorAuth
+* @property {Date} createdAt
+*/
+```
+
+<h1 align="center">All done!</h1>
+
+
+<br>
+<div align="center">
+  <strong>
+    © 2026 
+    <a href="https://github.com/MasqueradeORM">MasqueradeORM </a>
+		-
+    Released under the MIT License
+  </strong>
 </div>

package/docs/managing-the-database.md

@@ -9,7 +9,7 @@ We offer a simple way to clean up your database using the `DbManager` class and
 
 
 ```js
-import { DbManager } from 'masquerade'
+import { DbManager } from 'masquerade-orm'
 // will drop all unused columns in the database
 await DbManager.dropUnusedColumns() 
 // will drop all unused columns in entity_table

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "masquerade-orm",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Lightweight ORM compatible with SQLite and Postgresql in Node.js",
   "keywords": [
     "orm",

package/src/webpack/masquerade-loader.js

@@ -1,4 +1,4 @@
-import { store } from "./store"
+import { store } from "./store.js"
 import { createSourceFile, SyntaxKind, ScriptKind, ScriptTarget } from "typescript"
 
 

package/testing/postgres.test.js

@@ -3,7 +3,7 @@ import test from 'node:test'
 import assert from "node:assert"
 import * as classes from './testing-classes.js'
 import { resetPostgresDb, initORM, createConfigObj } from "./testInit.js"
-import { sql } from '..//src/entity/find/where/whereArgsFunctions.js'
+import { sql } from '../src/entity/find/where/whereArgsFunctions.js'
 import { generateFamiliesAndHouses } from "./generationFuncs.js"
 import { validateUpdatedAt } from "./miscFunctions.js"
 import { OrmStore } from '../src/misc/ormStore.js'

package/testing/sqlite.test.js

@@ -3,7 +3,7 @@ import test from 'node:test'
 import assert from "node:assert"
 import * as classes from './testing-classes.js'
 import { initORM, createConfigObj } from "./testInit.js"
-import { sql } from '..//src/entity/find/where/whereArgsFunctions.js'
+import { sql } from '../src/entity/find/where/whereArgsFunctions.js'
 import { generateFamiliesAndHouses } from "./generationFuncs.js"
 import { validateUpdatedAt } from "./miscFunctions.js"
 import { OrmStore } from '../src/misc/ormStore.js'
@@ -254,4 +254,3 @@ test.after(async () => {
     await fs.rm("./test", { force: true })
     console.log('db reset')
 })
-

package/testing/testing-classes.js

@@ -1,6 +1,6 @@
-import { Entity } from 'masquerade'
+import { Entity } from '../index.js'
 import { jsonGenerator } from './miscFunctions.js'
-/**@typedef {import('masquerade').integer} integer */
+/**@typedef {import('../index.js').integer} integer */
 
 
 export class House extends Entity {