masquerade-orm 0.8.1 → 0.8.3

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/index.d.ts

@@ -1,7 +1,7 @@
-
-export {ORM} from "./src/ORM/ORM.js"
-export {Entity} from './src/entity/entity'
-export {DbManager} from "./src/ORM/DbManager"
-export {sql, AND, OR} from "./src/entity/find/where/whereArgsFunctions"
-export {MasqueradePlugin} from "./src/webpack/plugin"
-export {Unique, integer, OrmConfigObj} from './src/misc/types'
+
+export {ORM} from "./src/ORM/ORM"
+export {Entity} from './src/entity/entity'
+export {DbManager} from "./src/ORM/DbManager"
+export {sql, AND, OR} from "./src/entity/find/where/whereArgsFunctions"
+export {MasqueradePlugin} from "./src/webpack/plugin"
+export {Unique, integer, OrmConfigObj} from './src/misc/types'

package/package.json

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

package/src/changeLogger/changeLogger.js

@@ -20,8 +20,8 @@ export class ChangeLogger {
     static async save() {
         const dbChanges = OrmStore.store.dbChangesObj
         if (!Object.keys(dbChanges).length || ChangeLogger.currentlySaving) return
-        // ChangeLogger.currentlySaving = true
-
+        
+        ChangeLogger.currentlySaving = true
         let paramIndex = 1
         const { sqlClient, dbConnection } = OrmStore.store
         const deletedInstancesArr = dbChanges.deletedInstancesArr

package/src/entity/entity.js

@@ -11,7 +11,7 @@ import { aliasedFindWiki2QueryRes, parseFindWiki, destructureAndValidateArg } fr
 import { deproxifyScopeProxy, classWiki2ScopeProxy } from "./find/scopeProxies.js"
 import { postgresCreateProxyArray } from "./find/sqlClients/postgresFuncs.js"
 import { sqliteCreateProxyArray } from "./find/sqlClients/sqliteFuncs.js"
-import { mergeRelationalWhereScope } from "./find/where/relationalWhere.js"
+import { mergeTemplateWhereScope } from "./find/where/templateWhere.js"
 import { mergeWhereScope } from "./find/where/where.js"
 
 /**
@@ -68,11 +68,11 @@ export class Entity {
 
     let classWiki = classWikiDict[this.name]
     if (!classWiki) throw new Error(`The class '${this.name}' has not been included in the ORM boot method.`)
-    const [relationsArg, whereArg, relationalWhereArg] = destructureAndValidateArg(findObj)
+    const [relationsArg, whereArg, templateWhereArg] = destructureAndValidateArg(findObj)
     let findWiki
     const baseProxyMap = classWiki2ScopeProxy(classWiki)
     if (whereArg) mergeWhereScope(baseProxyMap, whereArg)
-    if (relationalWhereArg) findWiki = mergeRelationalWhereScope(baseProxyMap, relationalWhereArg)
+    if (templateWhereArg) findWiki = mergeTemplateWhereScope(baseProxyMap, templateWhereArg)
     findWiki = deproxifyScopeProxy(baseProxyMap)
 
     const [aliasedFindMap, joinStatements, whereObj] = parseFindWiki(findWiki)

package/src/entity/find/find.js

@@ -4,14 +4,14 @@ import { rowObj2InstanceProxy } from "../../proxies/instanceProxy.js"
 import { createRelationalArrayProxy } from "../../proxies/relationalArrayProxy.js"
 import { generateQueryStrWithCTEs } from "./queryBuilder.js"
 import { junctionJoin, parentJoin } from "./joins.js"
-import { relationalWhereFuncs2Statements } from "./where/relationalWhere.js"
+import { relationalWhereFuncs2Statements } from "./where/templateWhere.js"
 import { whereValues2Statements } from "./where/where.js"
 import { OrmStore } from "../../misc/ormStore.js"
 
 export const proxyType = Symbol('proxyType')
 
 export function destructureAndValidateArg(findObj) {
-    let { relations: eagerLoad, where, relationalWhere } = findObj
+    let { relations: eagerLoad, where, templateWhere } = findObj
 
     if (eagerLoad) {
         const type = getType(eagerLoad)
@@ -25,11 +25,11 @@ export function destructureAndValidateArg(findObj) {
         else if (Object.keys(where).length === 0) where = undefined
     }
 
-    if (relationalWhere) {
-        const type = getType(relationalWhere)
-        if (type !== "function") throw new Error(`\nInvalid value in the 'relationalWhere' field of the 'find' function's argument. Expected a function.`)
+    if (templateWhere) {
+        const type = getType(templateWhere)
+        if (type !== "function") throw new Error(`\nInvalid value in the 'templateWhere' field of the 'find' function's argument. Expected a function.`)
     }
-    return [eagerLoad, where, relationalWhere]
+    return [eagerLoad, where, templateWhere]
 }
 
 export function removeRelationFromUnusedRelations(classMap, key) {
@@ -63,7 +63,7 @@ export function parseFindWiki(findWiki, aliasBase = 'a', aliasArr = [], joinStat
             returnedWiki.junctions[key] = parseFindWiki(joinedTable, aliasBase, aliasArr, joinStatements, whereObj, selectArr)[0]
         }
     }
-    if (returnedWiki.relationalWhere) relationalWhereFuncs2Statements(returnedWiki, whereObj)
+    if (returnedWiki.templateWhere) relationalWhereFuncs2Statements(returnedWiki, whereObj)
     if (returnedWiki.where) whereValues2Statements(returnedWiki, whereObj)
     return [returnedWiki, joinStatements, whereObj, selectArr]
 }

package/src/entity/find/scopeProxies.js

@@ -40,7 +40,7 @@ export function classWiki2ScopeProxy(classWiki) {
                 || key === "uncalledJunctions_"
                 || key === "junctions_"
                 || key === "where_"
-                || key === "relationalWhere_"
+                || key === "templateWhere_"
                 || key === "isArray_"
             ) return target[key]
             else if (key === proxyType) return 'categorizingProxy'
@@ -56,5 +56,5 @@ export function findPropOnScopeProxy(scopeProxy, key, rootClassName) {
     else if (scopeProxy.uncalledJunctions_ && scopeProxy.uncalledJunctions_[key]) return [scopeProxy.uncalledJunctions_[key], scopeProxy, "uncalledJunctions_"]
     else if (scopeProxy.junctions_ && scopeProxy.junctions_[key]) return [scopeProxy.junctions_[key], scopeProxy, "junctions_"]
     else if (scopeProxy.parent_) return findPropOnScopeProxy(scopeProxy.parent_, key, rootClassName)
-    else throw new Error(`\n'${key}' is not a valid property of class ${rootClassName}. Please fix the find function's argument. \nhint: use intellisense by pressing CNTRL + space to see all viable options.`)
+    else throw new Error(`\n'${key}' is not a valid property of class ${rootClassName}. Please fix the find function's argument. \nhint: use IntelliSense.`)
 }

package/src/entity/find/where/{relationalWhere.js → templateWhere.js}

@@ -5,7 +5,7 @@ import { proxyType, removeRelationFromUnusedRelations } from "../find.js"
 import { deproxifyScopeProxy, findPropOnScopeProxy, classWiki2ScopeObj } from "../scopeProxies.js"
 
 export function relationalWhereFuncs2Statements(mapObj, whereObj, queryStr = ``) {
-    const relationalWhereFunc = mapObj.relationalWhere
+    const relationalWhereFunc = mapObj.templateWhere
     let AliasObj4func = createFullAndFlatAliasObj(mapObj)
     const sqlWhereObj = relationalWhereFunc(AliasObj4func)
     while (sqlWhereObj.params.length + sqlWhereObj.strings.length > 0) {
@@ -49,24 +49,24 @@ function createFullAndFlatAliasObj(mapObj, fullFlatAliasObj = {}) {
     return fullFlatAliasObj
 }
 
-export function mergeRelationalWhereScope(proxyMap, relationalWhereFunc) {
+export function mergeTemplateWhereScope(proxyMap, relationalWhereFunc) {
     if (typeof relationalWhereFunc !== "function") throw new Error(`Relational where expects a function.`)
     let mapObj = deproxifyScopeProxy(proxyMap)
     const classWiki = OrmStore.store.classWikiDict[mapObj.className_]
-    const relationalWhereMapProxy = createRelationalWhereProxy(mapObj, classWiki)
+    const relationalWhereMapProxy = createTemplateWhereProxy(mapObj, classWiki)
     relationalWhereFunc(relationalWhereMapProxy)
     mapObj = deproxifyScopeProxy(relationalWhereMapProxy)
-    mapObj.relationalWhere_ = relationalWhereFunc
-    return reproxyMapObjPostRelationalWhere(mapObj, classWiki)
+    mapObj.templateWhere_ = relationalWhereFunc
+    return reproxyWikiPostTemplateWhere(mapObj, classWiki)
 }
 
-function reproxyMapObjPostRelationalWhere(mapObj, classWiki) {
-    if (mapObj.parent_) mapObj.parent_ = reproxyMapObjPostRelationalWhere(mapObj.parent_, classWiki.parent)
+function reproxyWikiPostTemplateWhere(mapObj, classWiki) {
+    if (mapObj.parent_) mapObj.parent_ = reproxyWikiPostTemplateWhere(mapObj.parent_, classWiki.parent)
 
     if (mapObj.junctions_) {
         const mapRelations = mapObj.junctions_
         for (const key of Object.keys(mapRelations))
-            mapRelations[key] = reproxyMapObjPostRelationalWhere(mapRelations[key], classWiki.junctions[key])
+            mapRelations[key] = reproxyWikiPostTemplateWhere(mapRelations[key], classWiki.junctions[key])
     }
 
     const proxy = new Proxy(mapObj, {
@@ -78,7 +78,7 @@ function reproxyMapObjPostRelationalWhere(mapObj, classWiki) {
                 || key === "uncalledJunctions_"
                 || key === "junctions_"
                 || key === "where_"
-                || key === "relationalWhere_"
+                || key === "templateWhere_"
                 || key === "isArray_"
             ) return target[key]
             else if (key === "raw_") return target
@@ -89,20 +89,20 @@ function reproxyMapObjPostRelationalWhere(mapObj, classWiki) {
     return proxy
 }
 
-export function createRelationalWhereProxy(mapObj, classWiki) {
+export function createTemplateWhereProxy(mapObj, classWiki) {
     if (classWiki.parent) {
         let parent
         if (!mapObj.parent_) parent = classWiki2ScopeObj(classWiki)
         else parent = mapObj.parent_
         const parentOrmMap = classWiki.parent
-        mapObj.parent_ = createRelationalWhereProxy(parent, parentOrmMap)
+        mapObj.parent_ = createTemplateWhereProxy(parent, parentOrmMap)
     }
 
     if (mapObj.junctions_) {
         const mapRelations = mapObj.junctions_
         for (const key of Object.keys(mapRelations)) {
             const relationOrmMap = classWiki.junctions[key]
-            mapRelations[key] = createRelationalWhereProxy(mapRelations[key], relationOrmMap)
+            mapRelations[key] = createTemplateWhereProxy(mapRelations[key], relationOrmMap)
         }
     }
 
@@ -115,28 +115,28 @@ export function createRelationalWhereProxy(mapObj, classWiki) {
                 || key === "uncalledJunctions_"
                 || key === "junctions_"
                 || key === "where_"
-                || key === "relationalWhere_"
+                || key === "templateWhere_"
                 || key === "isArray_"
             ) return target[key]
             else if (key === "raw_") return target
             else if (key === proxyType) return 'relationalWhereProxy'
-            else return findPropOnRelationalWhereMapProxy(target, key, classWiki)
+            else return findPropOnTemplateWhereProxy(target, key, classWiki)
         }
     })
     return proxy
 }
 
-export function findPropOnRelationalWhereMapProxy(mapObj, key, classWiki) {
+export function findPropOnTemplateWhereProxy(mapObj, key, classWiki) {
     if (mapObj.uncalledJunctions_[key]) {
         const relation = mapObj.uncalledJunctions_[key]
         const formattedRelationObj = classWiki2ScopeObj(relation)
         removeRelationFromUnusedRelations(mapObj, key)
         const proxyRelations = mapObj.junctions_ ??= {}
-        proxyRelations[key] = createRelationalWhereProxy(formattedRelationObj, classWiki.junctions[key])
+        proxyRelations[key] = createTemplateWhereProxy(formattedRelationObj, classWiki.junctions[key])
         return proxyRelations[key]
     }
     else if (mapObj.columns_[key]) return mapObj.columns_[key]
     else if (mapObj.junctions_[key]) return mapObj.junctions_[key]
-    else if (mapObj.parent_) return findPropOnRelationalWhereMapProxy(mapObj.parent_, key, classWiki.parent)
-    else throw new Error(`\n'${key}' is not a valid property of class ${classWiki.className}. Please fix the find function's relationalWhere. \nhint: use intellisense by pressing CNTRL + space to see all viable options.`)
+    else if (mapObj.parent_) return findPropOnTemplateWhereProxy(mapObj.parent_, key, classWiki.parent)
+    else throw new Error(`\n'${key}' is not a valid property of class ${classWiki.className}. Please fix the find function's templateWhere. \nhint: use intellisense by pressing CNTRL + space to see all viable options.`)
 }

package/src/entity/find/where/where.js

@@ -4,7 +4,7 @@ import { array2String, getType, nonSnake2Snake } from "../../../misc/miscFunctio
 import { OrmStore } from "../../../misc/ormStore.js"
 import { removeRelationFromUnusedRelations } from "../find.js"
 import { classWiki2ScopeProxy } from "../scopeProxies.js"
-import { mergeRelationalWhereScope } from "./relationalWhere.js"
+import { mergeTemplateWhereScope } from "./templateWhere.js"
 /**@typedef {import('../../../misc/classes').AndArray} AndArray */
 /**@typedef {import('../../../misc/classes').AndArray} OrArray */
 
@@ -209,7 +209,7 @@ export function mergeWhereScope(proxyMap, whereObj) {
     for (const [key, whereVal] of entries) {
 
         if (key === "_relationalWhere") {
-            proxyMap = mergeRelationalWhereScope(proxyMap, whereVal)
+            proxyMap = mergeTemplateWhereScope(proxyMap, whereVal)
             continue
         }
 
@@ -236,8 +236,8 @@ export function mergeWhereScope(proxyMap, whereObj) {
             }
 
             const passedMap = classMap.junctions_[key]
-            if (whereValType === "function") passedMap.relationalWhere_ = [whereVal]
-            else if (whereValType === "array") passedMap.relationalWhere_ = whereVal
+            if (whereValType === "function") passedMap.templateWhere_ = [whereVal]
+            else if (whereValType === "array") passedMap.templateWhere_ = whereVal
             else mergeWhereScope(passedMap, whereVal)
         }
     }

package/src/misc/classes.js

@@ -1,5 +1,7 @@
 /**@typedef {import('./types').PrimitivesNoNull} PrimitivesNoNull*/
 
+import { OrmStore } from './ormStore.js'
+
 
 /**
  * @template T
@@ -51,13 +53,65 @@ export class Alias {
 
 
 export class LazyPromise {
-  constructor(className) {
-    this.promise =
-      className
+  constructor(instance, property, promiseType, executor) {
+    // if (typeof executor !== 'function') {
+    //   throw new TypeError(
+    //     `LazyPromise executor must be a function, got ${typeof executor}`
+    //   )
+    // }
+    this.instanceContext = {
+      instanceId: instance.id,
+      instanceClass: instance.constructor.name,
+      property,
+      promiseType
+    }
+    this._executor = executor
+    this._promise = null
+  }
+
+  _getPromise() {
+    if (!this._promise) {
+      this._promise = new Promise((resolve, reject) => {
+        try {
+          this._executor(resolve, reject)
+        } catch (err) {
+          reject(err)
+        }
+      })
+    }
+    return this._promise
+  }
 
+  then(onFulfilled, onRejected) {
+    return this._getPromise().then(onFulfilled, onRejected)
+  }
+
+  catch(onRejected) {
+    return this._getPromise().catch(onRejected)
+  }
+
+  finally(onFinally) {
+    return this._getPromise().finally(onFinally)
   }
 
   toString() {
-    return `Promise<${this.promise}>`
+    return `Promise<${this.instanceContext.promiseType}>`
+  }
+
+  push(...items) {
+    const { instanceClass, instanceId, property, promiseType } = this.instanceContext
+    const cleanedType = promiseType.endsWith('[]') ? promiseType.slice(0, -2) : promiseType
+    const addedIds = []
+    for (const item of items) {
+      if (item.constructor.name !== cleanedType) throw new Error(`${item} is of type ${item.constructor.name} but must be of type ${cleanedType}.`)
+      addedIds.push(item.id)
+    }
+
+    const changesObj = OrmStore.store.dbChangesObj
+    changesObj[instanceClass] ??= {}
+    const instanceChangeObj = changesObj[instanceClass][instanceId] ??= {}
+    const relationsLogger = instanceChangeObj[property] ??= { added: [], removed: [] }
+    relationsLogger.added.push(...addedIds)
   }
-}
+
+}