masquerade-orm 0.8.2 → 0.8.3

package/README.md

@@ -37,21 +37,22 @@ npm install masquerade-orm
 ```
 
 # Features
-- **Effortless setup** - no ORM-specific structures; just use your classes.
-- **Zero schema planning** - tables and schema are generated automatically.
-- **Powerful IntelliSense** - confidently build complex queries with real-time IDE feedback when something’s wrong.
-- **Minimal memory usage** - one class instance per database row, minimizing memory usage and avoiding duplicates through smart state management.
-- **Optimized querying** - fewer queries through intelligent transaction grouping without sacrificing data integrity.
-- **Relational WHERE clauses** - easily write conditions that compare two columns within the same table or columns across different tables.
-- **Write complex WHERE conditions using a template-literal helper** - enabling expressive comparisons like >=, LIKE, object-property access, and even array element matching, all without cluttering your query code.
-- **SQL injection protection** - all queries are parameterized.
-- **Lightweight** - minimal dependencies.
-- **Strong typing even in JavaScript** - powered by JSDoc, no compile step required.
-- **Reduced data transfer size** - improves performance in client-server setups (not applicable for embedded databases like SQLite).
-- **Abstract and non-abstract inheritance** - enables the use of abstract classes, even in JavaScript.
+- **Effortless setup** - No ORM-specific structures; just use your classes.
+- **Zero schema planning** - Tables and schema are generated automatically.
+- **Powerful IntelliSense** - Confidently build complex queries with real-time IDE guidance and warnings when something’s wrong.
+- **Minimal memory usage** - One class instance per database row, minimizing memory usage and avoiding duplicates through smart state management.
+- **Optimized querying** - Fewer queries through intelligent transaction grouping without sacrificing data integrity.
+- **Expressive template-literal WHERE clauses** - Write complex, readable conditions such as LIKE, ≥, nested property access, array element matching (and more) by using IntelliSense-enabled tagged template literals. Any SQL WHERE logic can be expressed through this API.
+- **Cross-column conditions** - Easily write WHERE clauses that compare two columns (within the same table or across joined tables).
+- **Powerful relation capabilities** - Full support for eager & lazy loading, unidirectional / bidirectional / self-referencing relationships, and modifying associations even when they are not loaded.
+- **SQL injection protection** - All queries are parameterized.
+- **Minimal data transfer size** - Improves performance in client-server setups (not applicable for embedded databases like SQLite).
+- **Soft + hard deletion support**
+- **Abstract and non-abstract inheritance** - Enables the use of abstract classes, even in JavaScript.
+- **Strong typing even in JavaScript** - Powered by JSDoc, no compile step required.
+- **Smart schema cleanup** - Automatically detect and easily remove unused tables and columns, reducing database bloat and improving performance.
+- **Lightweight** - Minimal dependencies.
 - **Combines the convenience of embedded SQLite with the strict typing of RDBMS**
-- **Eager and lazy relations**
-- **Unidirectional, bidirectional, and self-referenced relations**
 
 
 # Example Code Implementation

package/bin/universalTsInit.js

@@ -1,59 +1,59 @@
-#!/usr/bin/env node
-
-import ts from "typescript"
-import fs from "fs"
-import path from "path"
-import { createSourceFile, SyntaxKind, ScriptKind, ScriptTarget } from "typescript"
-import { nodeArr2ClassDict } from "../src/ORM/bootOrm.js"
-
-const configPath = ts.findConfigFile(
-  "./",
-  ts.sys.fileExists,
-  "tsconfig.json"
-)
-
-if (!configPath) {
-  throw new Error("tsconfig.json not found")
-}
-
-const configFile = ts.readConfigFile(
-  configPath,
-  ts.sys.readFile
-)
-
-const parsed = ts.parseJsonConfigFileContent(
-  configFile.config,
-  ts.sys,
-  "./"
-)
-
-const program = ts.createProgram({
-  rootNames: parsed.fileNames,
-  options: parsed.options
-})
-
-const classNodesArr = []
-
-for (const sourceFile of program.getSourceFiles()) {
-  if (sourceFile.isDeclarationFile) continue
-  const fileText = sourceFile.getFullText()
-  const fileNodesArr = createSourceFile('', fileText, ScriptTarget.Latest, true, ScriptKind.TSX).statements
-
-  for (const node of fileNodesArr) {
-    //@ts-ignore
-    if ((node.kind === SyntaxKind.ClassDeclaration || node.kind === SyntaxKind.ClassExpression) && node.heritageClauses) 
-      classNodesArr.push(node)
-  }
-}
-
-const classDict = nodeArr2ClassDict(classNodesArr)
-const filePath = path.join(
-  process.cwd(),
-  "ormTypeScriptSetup.js"
-)
-const content = `export function UniversalTsSetup() {globalThis.masqueradeClassDict_ = ${JSON.stringify(classDict)};\n}`
-fs.writeFileSync(filePath, content, "utf8")
-
-
-
-
+#!/usr/bin/env node
+
+import ts from "typescript"
+import fs from "fs"
+import path from "path"
+import { createSourceFile, SyntaxKind, ScriptKind, ScriptTarget } from "typescript"
+import { nodeArr2ClassDict } from "../src/ORM/bootOrm.js"
+
+const configPath = ts.findConfigFile(
+  "./",
+  ts.sys.fileExists,
+  "tsconfig.json"
+)
+
+if (!configPath) {
+  throw new Error("tsconfig.json not found")
+}
+
+const configFile = ts.readConfigFile(
+  configPath,
+  ts.sys.readFile
+)
+
+const parsed = ts.parseJsonConfigFileContent(
+  configFile.config,
+  ts.sys,
+  "./"
+)
+
+const program = ts.createProgram({
+  rootNames: parsed.fileNames,
+  options: parsed.options
+})
+
+const classNodesArr = []
+
+for (const sourceFile of program.getSourceFiles()) {
+  if (sourceFile.isDeclarationFile) continue
+  const fileText = sourceFile.getFullText()
+  const fileNodesArr = createSourceFile('', fileText, ScriptTarget.Latest, true, ScriptKind.TSX).statements
+
+  for (const node of fileNodesArr) {
+    //@ts-ignore
+    if ((node.kind === SyntaxKind.ClassDeclaration || node.kind === SyntaxKind.ClassExpression) && node.heritageClauses) 
+      classNodesArr.push(node)
+  }
+}
+
+const classDict = nodeArr2ClassDict(classNodesArr)
+const filePath = path.join(
+  process.cwd(),
+  "ormTypeScriptSetup.js"
+)
+const content = `export function UniversalTsSetup() {globalThis.masqueradeClassDict_ = ${JSON.stringify(classDict)};\n}`
+fs.writeFileSync(filePath, content, "utf8")
+
+
+
+

package/docs/deletion.md

@@ -1,6 +1,6 @@
 # Deleting Instances from the Database
 
-### Soft Deletion
+## Soft Deletion
 The ORM does not support soft deletion by default. To implement soft deletion, just create an abstract class like so: 
 
 **TypeScript**
@@ -69,7 +69,7 @@ const softDelUser = new SoftDeletableUser('JohnDoe', 'JohnDoe@gmail.com', 'hashe
 
 **Note:** Unlike `Entity`, the `SoftDel` classes need to be passed into the `ORM.boot` method that is being called to init the ORM.
 
-### Hard Deletion
+## Hard Deletion
 
 ```ts
 import { sql } from "masquerade-orm"
@@ -91,7 +91,7 @@ The `delete` method hard-deletes the instance from the database; the instance ca
 </div>
 
 
-## Pre-Deletion Step
+## Pre-Deletion Step for Hard Deletion
 
 ### When is a pre-deletion step required?  
 A pre-deletion step is required when the class instance has **dependents**.  

package/docs/find.md

@@ -13,7 +13,7 @@ The three optional fields are:
 
 - relations
 - where
-- relationalWhere
+- templateWhere
 
 
 
@@ -138,6 +138,16 @@ await User.find({
 // '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"
@@ -176,27 +186,27 @@ const completedOrders = await Order.find({
 - **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:
+## 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({
-   relationalWhere: (user) => sql`${user.chats.messages.sender.username} = 'Glory2Christ'`
+   templateWhere: (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.
+// 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: {
-      relationalWhere_: (chat) => sql`${chat.messages.sender.username} = 'Glory2Christ'`,
+      templateWhere_: (chat) => sql`${chat.messages.sender.username} = 'Glory2Christ'`,
       // can be combined with regular 'where' conditions - below is valid code
       // chatName: 'The History of Orthodoxy' 
     }

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.2",
+  "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)
   }
-}
+
+}

package/src/misc/ormStore.js

@@ -12,7 +12,10 @@ export class OrmStore {
     }
 
     static getClassWiki(instanceClass) {
+        if (typeof instanceClass === 'string')
         return this.store.classWikiDict[instanceClass]
+
+        return this.store.classWikiDict[instanceClass.constructor.name]
     }
 }
 

package/src/misc/types.d.ts

@@ -204,7 +204,7 @@ type NonRelationsProperties<T> = Exclude<keyof T, RelationsProperties<T>>
 export type FindObj<T> = {
   relations?: Partial<RelationsOnly<T>>
   where?: WhereProperties<T>
-  relationalWhere?: sqlArrowFnTable<T> | (sqlArrowFn<T> | null)[] | null
+  templateWhere?: sqlArrowFnTable<T> | (sqlArrowFn<T> | null)[] | null
 }
 
 // ---------------------------------------------------------
@@ -455,7 +455,7 @@ type ArrColumnsRawParams =
 // export type FindObj<T> = {
 //   relations?: Partial<RelationsOnly<T>>
 //   where?: WhereProperties<T>
-//   relationalWhere?: sqlArrowFn<T> | sqlArrowFn<T>[]
+//   templateWhere?: sqlArrowFn<T> | sqlArrowFn<T>[]
 // }
 
 // // ---------------------------------------------------------

package/src/proxies/instanceProxy.js

@@ -65,8 +65,8 @@ export function rowObj2InstanceProxy(resultObj, findWiki, Entities) {
                 while (!currentWiki.uncalledJunctions[property]) currentWiki = currentWiki.parent
                 const uncalledJunctionObj = currentWiki.uncalledJunctions[property]
                 const nameOfMapWithJunction = uncalledJunctionObj.className
-                const promiseOf = uncalledJunctionObj.isArray ? nameOfMapWithJunction + `[]` : nameOfMapWithJunction
-                instance[property] = new LazyPromise(promiseOf)
+                const promiseType = uncalledJunctionObj.isArray ? nameOfMapWithJunction + `[]` : nameOfMapWithJunction
+                instance[property] = new LazyPromise(instance, property, promiseType, (resolve, reject) => promiseExecutor(instance, property, resolve, reject))
             }
         }
 
@@ -76,43 +76,57 @@ export function rowObj2InstanceProxy(resultObj, findWiki, Entities) {
     }
 }
 
-export function insertProxyIntoEntityMap(proxy, entityMap) {
-    entityMap.set(proxy.id, new WeakRef(proxy))
-    ORM[FinalizationRegistrySymb].register(proxy, [proxy.constructor.name, proxy.id])
-}
-
-export function instanceProxyGetHandler(target, key, classWiki) {
-    const val = target[key]
-    if (!(val instanceof LazyPromise)) return val
-
+function promiseExecutor(target, key, resolve, reject) {
+    if (ChangeLogger.scheduledFlush) ChangeLogger.save().then()
     const { sqlClient, dbConnection } = OrmStore.store
-    const [classification, joinedClassMap, mapWithProp] = getPropertyClassification(key, classWiki)
-    let joinedTable
-
-    if (classification === "Join") joinedTable = classWiki.junctions[key]
-    else joinedTable = mapWithProp.junctions[key]
-
-    const isArrayOfInstances = joinedClassMap.isArray
+    const classWiki = OrmStore.getClassWiki(target)
+    const [classification, joinedClassWiki, mapWithProp] = getPropertyClassification(key, classWiki)
+    const isArrayOfInstances = joinedClassWiki.isArray
 
     let queryStr = `SELECT entity.* FROM ${nonSnake2Snake(mapWithProp.className)}___${nonSnake2Snake(key)}_jt jt` +
-        ` LEFT JOIN ${nonSnake2Snake(joinedClassMap.className)} entity ON jt.joined_id = entity.id WHERE jt.joining_id = `
+        ` LEFT JOIN ${nonSnake2Snake(joinedClassWiki.className)} entity ON jt.joined_id = entity.id WHERE jt.joining_id = `
     queryStr += sqlClient === "postgresql" ? `$1` : `?`
 
     let queryFunc
     if (sqlClient === "postgresql") queryFunc = (queryStr, id) => dbConnection.query(queryStr, [id])
     else queryFunc = (queryStr, id) => dbConnection.prepare(queryStr).all(id)
 
-    let promise
     try {
-        let queryRes = queryFunc(queryStr, target.id)
-        promise = createLazyPromise(target, key, queryRes, mapWithProp.junctions[key], isArrayOfInstances, sqlClient)
-        promise.then(res => target[key] = res)
+        Promise.resolve(queryFunc(queryStr, target.id))
+            .then(rows => {
+                const { className, columns, junctions } = joinedClassWiki
+                const findWiki = { className, columns, uncalledJunctions: junctions }
+                let currentWiki = joinedClassWiki
+                let currentScopedMap = findWiki
+                while (currentWiki.parent) {
+                    const { className, columns, junctions } = currentWiki.parent
+                    currentScopedMap.parent = { className, columns, uncalledJunctions: junctions }
+                    currentScopedMap = currentScopedMap.parent
+                    currentWiki = currentWiki.parent
+                }
+
+                const proxyArr = []
+                for (const row of rows) {
+                    const rowWithCamelCasedProps = Object.fromEntries(Object.entries(row).map(([key, val]) => [snake2Pascal(key, true), val]))
+                    proxyArr.push(rowObj2InstanceProxy(rowWithCamelCasedProps, findWiki, OrmStore.store.entities))
+                }
+
+                if (isArrayOfInstances) target[key] = createRelationalArrayProxy(target, key, proxyArr, classWiki.className)
+                else target[key] = proxyArr[0]
+
+                resolve(target[key])
+            })
+            .catch(reject)
     }
-    catch (e) {
-        coloredBackgroundConsoleLog(`Lazy loading failed. ${e}\n`, `failure`)
+    catch (err) {
+        coloredBackgroundConsoleLog(`Lazy loading failed. ${err}`, 'failure')
+        reject(err)
     }
+}
 
-    return promise
+export function insertProxyIntoEntityMap(proxy, entityMap) {
+    entityMap.set(proxy.id, new WeakRef(proxy))
+    ORM[FinalizationRegistrySymb].register(proxy, [proxy.constructor.name, proxy.id])
 }
 
 export function instanceProxySetHandler(target, key, value, eventListenersObj, classWiki) {
@@ -356,57 +370,6 @@ export function createLazyLoadQueryStr(property, classWiki) {
 }
 
 
-export function createLazyPromise(target, key, queryRes, classWiki, isArrayOfInstances, client) {
-    return new Promise(async (resolve) => {
-        let resultArr
-        try {
-            if (client === "postgresql") resultArr = (await queryRes).rows
-            else resultArr = queryRes
-
-            if (!resultArr.length) {
-                if (isArrayOfInstances) {
-                    target[key] = []
-                    resolve([])
-                }
-                else {
-                    target[key] = undefined
-                    resolve(undefined)
-                }
-            }
-
-            const { className, columns, junctions } = classWiki
-            const findWiki = { className, columns, uncalledJunctions: junctions }
-            let currentWiki = classWiki
-            let currentScopedMap = findWiki
-            while (currentWiki.parent) {
-                const { className, columns, junctions } = currentWiki.parent
-                currentScopedMap.parent = { className, columns, uncalledJunctions: junctions }
-                currentScopedMap = currentScopedMap.parent
-                currentWiki = currentWiki.parent
-            }
-
-            const proxyArr = []
-            for (const row of resultArr) {
-                const rowWithCamelCasedProps = Object.fromEntries(Object.entries(row).map(([key, val]) => [snake2Pascal(key, true), val]))
-                proxyArr.push(rowObj2InstanceProxy(rowWithCamelCasedProps, findWiki, OrmStore.store.entities))
-            }
-
-            if (isArrayOfInstances) {
-                target[key] = createRelationalArrayProxy(target, key, proxyArr, classWiki.className)
-                resolve(target[key])
-            }
-            else {
-                target[key] = proxyArr[0]
-                resolve(target[key])
-            }
-        }
-        catch (e) {
-            coloredBackgroundConsoleLog(`Lazy loading failed. ${e}\n`, `failure`)
-        }
-    })
-}
-
-
 export function uncalledPropertySetHandler(target, key, value, columnClassificationArr) {
     const [propertyType, propertyTypeObj, mapWithProp] = columnClassificationArr
     const joiningId = target.id
@@ -496,7 +459,8 @@ export function proxifyEntityInstanceObj(instance, uncalledRelationalProperties)
             else if (key === "eEmitter_") return emitter
             else if (key === "eListener_") return eventListenersObj
             else if (key === "_isDeleted_") return target[key]
-            return instanceProxyGetHandler(target, key, classWiki)
+            return target[key]
+            //return instanceProxyGetHandler(target, key, classWiki)
         },
         set: (target, /**@type {string}*/ key, value) => {
             instanceProxySetHandler(target, key, value, eventListenersObj, classWiki)

package/src/webpack/masquerade-loader.js

@@ -1,14 +1,16 @@
-import { store } from "./store.js"
-import { createSourceFile, SyntaxKind, ScriptKind, ScriptTarget } from "typescript"
-
-
-export default function (source) {
-	const nodes = Object.values(source).map(source => createSourceFile('', source.toString(), ScriptTarget.Latest, true, ScriptKind.TSX).statements[0])
-	for (const node of nodes) {
-		//@ts-ignore
-		if ((node.kind === SyntaxKind.ClassDeclaration || node.kind === SyntaxKind.ClassExpression) && node.heritageClauses)
-					//@ts-ignore
-			store.nodeArr.push(node)
-	}
-	return source
-}
+import { store } from "./store.js"
+import { SyntaxKind } from "typescript"
+import ts from "typescript"
+
+export default function (source) {
+	const sourceFile = ts.createSourceFile("", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
+	const nodes = sourceFile.statements
+	for (const node of nodes) {
+		if (!node) continue
+		//@ts-ignore
+		const isValid = (node.kind === SyntaxKind.ClassDeclaration || node.kind === SyntaxKind.ClassExpression) && node.heritageClauses
+		//@ts-ignore
+		if (isValid) store.nodeArr.push(node)
+	}
+	return source
+}

package/src/webpack/plugin.js

@@ -1,43 +1,42 @@
-
-import { store } from "./store.js"
-
-import { nodeArr2ClassDict } from "../ORM/bootOrm.js"
-
-export class MasqueradePlugin {
-  apply(compiler) {
-    compiler.hooks.compilation.tap(this.constructor.name, (compilation) => {
-      compilation.hooks.processAssets.tap(
-        {
-          name: this.constructor.name,
-          stage: compilation.constructor.PROCESS_ASSETS_STAGE_ADDITIONS,
-        },
-        (assets) => {
-          const classDict = nodeArr2ClassDict(store.nodeArr)
-          const prefix = `globalThis.masqueradeClassDict_ = ${JSON.stringify(classDict)};\n`
-
-          for (const entry of compilation.entrypoints.values()) {
-            for (const file of entry.getFiles()) {
-              if (!file.endsWith(".js")) continue
-
-              const asset = compilation.getAsset(file)
-              const source = asset.source.source()
-
-              compilation.updateAsset(
-                file,
-                new compiler.webpack.sources.RawSource(prefix + source)
-              )
-            }
-          }
-        }
-      )
-    })
-  }
-}
-
-
-
-
-
-
-
-
+
+import { store } from "./store.js"
+import { nodeArr2ClassDict } from "../ORM/bootOrm.js"
+
+export class MasqueradePlugin {
+  apply(compiler) {
+    compiler.hooks.compilation.tap(this.constructor.name, (compilation) => {
+      compilation.hooks.processAssets.tap(
+        {
+          name: this.constructor.name,
+          stage: compilation.constructor.PROCESS_ASSETS_STAGE_ADDITIONS,
+        },
+        (assets) => {
+          const classDict = nodeArr2ClassDict(store.nodeArr)
+          const prefix = `globalThis.masqueradeClassDict_ = ${JSON.stringify(classDict)};\n`
+
+          for (const entry of compilation.entrypoints.values()) {
+            for (const file of entry.getFiles()) {
+              if (!file.endsWith(".js")) continue
+
+              const asset = compilation.getAsset(file)
+              const source = asset.source.source()
+
+              compilation.updateAsset(
+                file,
+                new compiler.webpack.sources.RawSource(prefix + source)
+              )
+            }
+          }
+        }
+      )
+    })
+  }
+}
+
+
+
+
+
+
+
+

package/testing/postgres.test.js

@@ -10,7 +10,7 @@ import { OrmStore } from '../src/misc/ormStore.js'
 
 const { House, Person, NonRelationalClass2 } = classes
 
-const configObj = createConfigObj()
+const configObj = createConfigObj('postgres', '123456789')
 await resetPostgresDb(configObj.dbConnection)
 await initORM(configObj, classes)
 let dbChanges = OrmStore.store.dbChangesObj

package/testing/testInit.js

@@ -0,0 +1,34 @@
+import { ORM } from "../index.js"
+import { DatabaseSync } from 'node:sqlite'
+import { Pool } from 'pg'
+/**@typedef {import('../index.js').OrmConfigObj} OrmConfigObj */
+
+
+export function createConfigObj(client, /**@type {undefined | string}*/ dbPaswword = undefined) {
+    if (client === `sqlite`) return {
+        dbConnection: new DatabaseSync('test'),
+        idTypeDefault: "INT"
+    }
+
+    return {
+        dbConnection: new Pool({
+            user: 'postgres',                   // e.g., 'postgres'
+            host: 'localhost',                 // database host
+            database: 'masquerade-test',      // database name
+            password: `${dbPaswword}`,           // your password
+            port: 5432,                     // default PostgreSQL port
+        }),
+        idTypeDefault: "INT"
+    }
+}
+
+export async function initORM(configObj, ...classes) {
+    await ORM.javascriptBoot(configObj, ...classes)
+}
+
+export async function resetPostgresDb(pool) {
+    await pool.query(
+        `DROP SCHEMA public CASCADE;
+        CREATE SCHEMA public;`
+    )
+}