masquerade-orm 0.1.0

package/src/changeLogger/changeLogger.js

@@ -0,0 +1,55 @@
+import { OrmStore } from "../misc/ormStore.js"
+import { handleRelationalChanges, handleUpserts, organizeChangeObj } from "./save.js"
+import { postgresSaveQuery } from "./sqlClients/postgres.js"
+import { sqliteSaveQuery } from "./sqlClients/sqlite.js"
+import { setImmediate } from "node:timers/promises";
+
+export class ChangeLogger {
+    static scheduledFlush = false
+    static currentlySaving = false
+    static flushChanges() {
+        const dbChangesObj = OrmStore.store.dbChangesObj
+        if (!Object.keys(dbChangesObj).length || this.scheduledFlush) return
+        this.scheduledFlush = true
+        const func = async () => await ChangeLogger.save()
+        //queueMicrotask(func)
+        setImmediate(func)
+    }
+
+
+    static async save() {
+        const dbChanges = OrmStore.store.dbChangesObj
+        if (!Object.keys(dbChanges).length || ChangeLogger.currentlySaving) return
+        // ChangeLogger.currentlySaving = true
+
+        let paramIndex = 1
+        const { sqlClient, dbConnection } = OrmStore.store
+        const deletedInstancesArr = dbChanges.deletedInstancesArr
+        const deletedUncalledRelationsArr = dbChanges.deletedUncalledRelationsArr //this has to fire first
+        if (deletedInstancesArr) delete dbChanges.deletedInstancesArr
+        if (deletedUncalledRelationsArr) delete dbChanges.deletedUncalledRelationsArr
+
+        const organizedChangeObj = {}
+        organizeChangeObj(dbChanges, organizedChangeObj, sqlClient)
+
+        const entitiesChangeObj = organizedChangeObj.tables ?? {}
+        const junctionTablesChangeObj = organizedChangeObj.junctions ?? {}
+
+        const classesQueryObj = {}
+        const junctionsQueryObj = {}
+
+        for (const [tableName, classChangesObj] of Object.entries(entitiesChangeObj)) {
+            if (!Object.keys(classChangesObj).length) continue
+            paramIndex = handleUpserts(tableName, classChangesObj, classesQueryObj, paramIndex, sqlClient)
+        }
+
+        for (const [tableName, junctionChangesObj] of Object.entries(junctionTablesChangeObj)) {
+            if (!Object.keys(junctionChangesObj).length) continue
+            paramIndex = handleRelationalChanges(tableName, junctionChangesObj, junctionsQueryObj, paramIndex, sqlClient)
+        }
+
+        if (sqlClient === "postgresql") await postgresSaveQuery(deletedUncalledRelationsArr, classesQueryObj, junctionsQueryObj, deletedInstancesArr, paramIndex, dbConnection)
+        else sqliteSaveQuery(deletedUncalledRelationsArr, classesQueryObj, junctionsQueryObj, deletedInstancesArr, dbConnection)
+    }
+}
+

package/src/changeLogger/save.js

@@ -0,0 +1,237 @@
+import { newEntityInstanceSymb } from "../misc/constants.js"
+import { coloredBackgroundConsoleLog, getPropertyClassification, jsValue2SqliteValue, nonSnake2Snake } from "../misc/miscFunctions.js"
+import { OrmStore } from "../misc/ormStore.js"
+import { ChangeLogger } from "./changeLogger.js"
+import { junctionTableRemovalPostgres } from "./sqlClients/postgres.js"
+import { junctionTableRemovalSqlite } from "./sqlClients/sqlite.js"
+
+const idTypeSymb = Symbol(`idType`)
+
+export function successfullSaveOperation() {
+  coloredBackgroundConsoleLog(`Save ran successfully.\n`, `success`)
+  OrmStore.clearDbChanges()
+  ChangeLogger.scheduledFlush = false
+  ChangeLogger.currentlySaving = false
+}
+
+function expandBuffer(arr, lengthAdded) {
+  arr.length += lengthAdded
+  return arr
+}
+
+function passEntityColumnsToAncestorMaps(id, entityInstanceChangeObj, classWiki, cteMap, client) {
+  const isNewEntityInstance = entityInstanceChangeObj[newEntityInstanceSymb] ? true : false
+  cteMap.tables ??= {}
+  const baseClassCteMap = cteMap.tables[classWiki.className] ??= {}
+  baseClassCteMap[id] = { id }
+  let currentWiki = classWiki
+  while (currentWiki.parent) {
+    const classCteMap = cteMap.tables[currentWiki.parent.className] ??= {}
+    classCteMap[id] ??= { id }
+    classCteMap[id][newEntityInstanceSymb] = isNewEntityInstance
+    currentWiki = currentWiki.parent ?? currentWiki
+  }
+  cteMap.tables[currentWiki.className][id].updatedAt = client === "postgresql" ? new Date() : new Date().toISOString()
+}
+
+export function handleRelationalChanges(tableName, tableChangesObj, queryObj, paramIndex, sqlClient) {
+  /**@type {any}*/ const target = queryObj[tableName] = {}
+  const categorizedIds = { added: {}, removed: {} }
+  const entries = Object.entries(tableChangesObj)
+  const idTypeArr = tableChangesObj[idTypeSymb]
+
+  for (const [baseEntityId, addedAndRemovedIds] of entries) {
+    if (addedAndRemovedIds.added) {
+      categorizedIds.added[baseEntityId] = []
+      for (const addedJoinId of addedAndRemovedIds.added) categorizedIds.added[baseEntityId].push(addedJoinId)
+    }
+    if (addedAndRemovedIds.removed) {
+      categorizedIds.removed[baseEntityId] = []
+      for (const removedJoinId of addedAndRemovedIds.removed) categorizedIds.removed[baseEntityId].push(removedJoinId)
+    }
+  }
+
+  let addedIds = Object.entries(categorizedIds.added)
+  let removedIds = Object.entries(categorizedIds.removed)
+
+  addedIds = addedIds.map(([joiningId, joinedIdArr]) => [typecastStringId(joiningId, idTypeArr[0]), joinedIdArr])
+  removedIds = removedIds.map(([joiningId, joinedIdArr]) => [typecastStringId(joiningId, idTypeArr[0]), joinedIdArr])
+
+  if (addedIds.length) [target.newRelationsObj, paramIndex] = junctionTableInsertion(addedIds, tableName, paramIndex, sqlClient)
+  if (removedIds.length) [target.deletedRelationsObj, paramIndex] = sqlClient === `postgresql`
+    ? junctionTableRemovalPostgres(removedIds, tableName, paramIndex, idTypeArr)
+    : junctionTableRemovalSqlite(removedIds, tableName)
+  return paramIndex
+}
+
+function junctionTableInsertion(addedIds, tableName, paramIndex, sqlClient) {
+  const snakedTableName = nonSnake2Snake(tableName)
+  let queryStr = `INSERT INTO ${snakedTableName} (joining_id, joined_id) VALUES `
+  const params = []
+  //const [joiningIdTypeCast, joinedIdTypeCast] = [getPostgresIdTypeCasting(idTypeArr[0]), getPostgresIdTypeCasting(idTypeArr[1])]
+  for (const baseAndJoinedIds of addedIds) {
+    const baseId = baseAndJoinedIds[0]
+    const joinedIds = baseAndJoinedIds[1]
+    while (joinedIds.length) {
+      queryStr += sqlClient === "postgresql" ? `($${paramIndex++}, $${paramIndex++}), ` : `(?, ?), `
+      params.push(baseId, joinedIds.pop())
+    }
+  }
+  queryStr = queryStr.slice(0, -2)
+  if (sqlClient === "postgresql") queryStr += ` RETURNING 1`
+
+  const returnedJunctionObj = { queryStr, params }
+  return [returnedJunctionObj, paramIndex]
+}
+
+
+export function handleUpserts(tableName, classChangesObj, queryObj, paramIndex, sqlClient) {
+  const classInstances = Object.entries(classChangesObj)
+  const inserts = []
+  const updates = []
+  queryObj[tableName] ??= {}
+  while (classInstances.length) {
+    //@ts-ignore
+    const [instanceId, instance] = classInstances.pop()
+    if (Object.keys(instance).length === 1) continue
+    if (instance[newEntityInstanceSymb]) inserts.push(instance)
+    else updates.push(instance)
+  }
+
+  if (inserts.length) paramIndex = insertNewRows(inserts, tableName, queryObj, paramIndex, sqlClient)
+  if (updates.length) paramIndex = updateRows(updates, tableName, queryObj, paramIndex, sqlClient)
+  return paramIndex
+}
+
+export function typecastStringId(instanceId, idType) {
+  if (idType === `number`) return parseInt(instanceId, 10)
+  return instanceId
+}
+
+function insertNewRows(newRows, tableName, queryObj, paramIndex, client) {
+  /**@type {any}*/ const target = queryObj[tableName].insert = { queryStr: ``, params: [] }
+  const snakedTableName = nonSnake2Snake(tableName)
+  const classWiki = OrmStore.store.classWikiDict[tableName]
+  const columns = Object.keys(classWiki.columns)
+
+  if (classWiki.parent) queryObj[tableName].parent = classWiki.parent.className
+
+  target.params = expandBuffer(target.params, newRows.length * columns.length)
+  let i = 0
+  let queryStr = `INSERT INTO ${snakedTableName} (${columns.map(column => nonSnake2Snake(column)).join(', ')}) VALUES `
+
+  for (const instance of newRows) {
+    if (client === "postgresql") queryStr += `(${columns.map(column => `$${paramIndex++}`).join(', ')}), \n`
+    else queryStr += `(${columns.map(column => `?`).join(', ')}), \n`
+
+    for (const column of columns) target.params[i++] = instance[column]
+  }
+
+  if (client === "postgresql") target.queryStr = queryStr.slice(0, -3) + ` RETURNING 1`
+  else target.queryStr = queryStr.slice(0, -3)
+  return paramIndex
+}
+
+function updateRows(updatedRows, tableName, queryObj, paramIndex, client) {
+  /**@type {any}*/ const target = queryObj[tableName].update = { queryStrArr: [], params2dArr: [] }
+  const snakedTableName = nonSnake2Snake(tableName)
+  const idType = OrmStore.getClassWiki(tableName).columns.id.type
+
+  for (const row of updatedRows) {
+    let rowId = row.id
+    delete row.id
+    const updatedColumns = Object.entries(row)
+    //if (!updatedColumns.length) continue
+    rowId = typecastStringId(rowId, idType)
+    let queryStr = ``
+    let params = []
+
+    queryStr += `UPDATE ${snakedTableName} SET `
+    for (const [columnName, val] of updatedColumns) {
+      if (client === "postgresql") queryStr += `${nonSnake2Snake(columnName)} = $${paramIndex++}, `
+      else queryStr += `${nonSnake2Snake(columnName)} = ?, `
+
+      params.push(val)
+    }
+    if (client === "postgresql") queryStr = queryStr.slice(0, -2) + ` WHERE id = $${paramIndex++} RETURNING 1`
+    else queryStr = queryStr.slice(0, -2) + ` WHERE id = ?`
+
+    params.push(rowId)
+    target.queryStrArr.push(queryStr)
+    target.params2dArr.push(params)
+  }
+  return paramIndex
+}
+
+export function organizeChangeObj(dbChanges, cteMap, client) {
+  const classNames = Object.keys(dbChanges)
+
+  for (const className of classNames) {
+    const tableChangeObj = dbChanges[className]
+    const entityChangeObjects = Object.entries(tableChangeObj)
+
+    for (const [instanceId, entityInstanceChangeObj] of entityChangeObjects) {
+
+      const classWiki = OrmStore.store.classWikiDict[className]
+      let properties = Object.keys(entityInstanceChangeObj)
+
+      if (classWiki.parent) {
+        passEntityColumnsToAncestorMaps(instanceId, entityInstanceChangeObj, classWiki, cteMap, client)
+        properties = properties.filter(prop => prop !== "id" && prop !== "updatedAt")
+      }
+
+      for (const property of properties) {
+        const [classification, columnType, mapWithProp] = getPropertyClassification(property, classWiki)
+
+        if (classification === "Join" || classification === "ParentJoin") {
+          const added = entityInstanceChangeObj[property].added
+          const removed = entityInstanceChangeObj[property].removed
+          if (!added.length && !removed.length) continue
+
+          const junctionTableName = `${nonSnake2Snake(mapWithProp.className)}___${nonSnake2Snake(property)}_jt`
+
+          cteMap.junctions ??= {}
+          const tableCteMap = cteMap.junctions[junctionTableName] ??= {}
+          tableCteMap[idTypeSymb] = [mapWithProp.columns.id.type, columnType.columns.id.type]
+
+          if (added.length) {
+            tableCteMap[instanceId] ??= {}
+            tableCteMap[instanceId].added = entityInstanceChangeObj[property].added
+          }
+          if (removed.length) {
+            tableCteMap[instanceId] ??= {}
+            tableCteMap[instanceId].removed = entityInstanceChangeObj[property].removed
+          }
+        }
+        else {
+          const tableName = mapWithProp.className
+          cteMap.tables ??= {}
+          const tableCteMap = cteMap.tables[tableName] ??= {}
+          const entityInstanceMap = tableCteMap[instanceId] ??= {}
+          //tableCteMap[idTypeSymb] = [mapWithProp.columns.id.type, columnType.type]
+
+          if (client === "postgresql") entityInstanceMap[property] = entityInstanceChangeObj[property]
+          else {
+            const value = entityInstanceChangeObj[property]
+            entityInstanceMap[property] = jsValue2SqliteValue(value)
+          }
+          entityInstanceMap[newEntityInstanceSymb] = entityInstanceChangeObj[newEntityInstanceSymb] ? true : false
+        }
+      }
+    }
+  }
+}
+
+
+// function getPostgresTypeCasting(columnObj) {
+//   const { type, isArray } = columnObj
+//   let returnedType
+//   if (type === `string`) returnedType = `::text`
+//   else if (type === `number`) returnedType = `::int`
+//   else if (type === `bigint`) returnedType = `::bigint`
+//   else if (type === `Date`) returnedType = `::timestamptz`
+//   else if (type === `boolean`) returnedType = `::bool`
+//   else if (type === `object`) returnedType = `::jsonb`
+//   if (isArray && type !== `object`) returnedType += `[]`
+//   return returnedType
+// }

package/src/changeLogger/sqlClients/postgres.js

@@ -0,0 +1,97 @@
+import { coloredBackgroundConsoleLog, nonSnake2Snake } from "../../misc/miscFunctions.js"
+import { successfullSaveOperation } from "../save.js"
+
+export async function postgresSaveQuery(deletedUncalledRelationsArr, classesQueryObj, junctionsQueryObj, deletedInstancesArr, paramIndex, dbConnection) {
+    let i = 0
+    let finalString = 'WITH'
+    const finalParams = []
+    paramIndex = 1
+
+    let queryFunc = dbConnection.query.bind(dbConnection)
+    let queryFuncWithTryCatch = async (query, params, forDeletedUncalledRelations = false) => {
+        try {
+            await queryFunc(query, params)
+            if (!forDeletedUncalledRelations) successfullSaveOperation()
+        }
+        catch (e) {
+            coloredBackgroundConsoleLog(`Database save failed. ${e}\n`, `failure`)
+        }
+    }
+
+    if (deletedUncalledRelationsArr) {
+        const paramsArr = []
+        let finalString = 'WITH'
+        for (const [tableName, { idType, params }] of Object.entries(deletedUncalledRelationsArr)) {
+            const queryStr = `DELETE FROM ${tableName} WHERE joining_id =  ANY($${paramIndex++}::${idType}[])`
+            finalString += ` cte${i++} AS (` + queryStr + `), `
+            paramsArr.push(params)
+        }
+        await queryFuncWithTryCatch(finalString.slice(0, -2) + ` SELECT 1`, paramsArr, true)
+    }
+
+    for (const upsertObj of Object.values(classesQueryObj)) {
+        if (upsertObj.insert) {
+            finalString += ` cte${i++} AS (` + upsertObj.insert.queryStr + `), `
+            finalParams.push(...upsertObj.insert.params)
+        }
+        if (upsertObj.update) {
+            finalString += upsertObj.update.queryStrArr.map((queryStr) => ` cte${i++} AS (${queryStr})`).join(', ') + `, `
+            finalParams.push(...upsertObj.update.params2dArr.flat())
+        }
+    }
+
+    for (const junctionObj of Object.values(junctionsQueryObj)) {
+        if (junctionObj.newRelationsObj) {
+            finalString += ` cte${i++} AS (` + junctionObj.newRelationsObj.queryStr + `), `
+            finalParams.push(...junctionObj.newRelationsObj.params)
+        }
+
+        if (junctionObj.deletedRelationsObj) {
+            finalString += ` cte${i++} AS (` + junctionObj.deletedRelationsObj.queryStr + `), `
+            finalParams.push(...junctionObj.deletedRelationsObj.params)
+        }
+    }
+
+    if (deletedInstancesArr) {
+        paramIndex = finalParams.length + 1
+        for (const [tableName, param] of deletedInstancesArr) {
+            const queryStr = `DELETE FROM ${tableName} WHERE id = $${paramIndex++}`
+            finalString += ` cte${i++} AS (` + queryStr + `), `
+            finalParams.push(param)
+        }
+    }
+
+    finalString = finalString.slice(0, -2) + ` SELECT 1`
+    await queryFuncWithTryCatch(finalString, finalParams)
+}
+
+
+function getPostgresIdTypeCasting(idType) {
+    if (idType === `string`) return `::uuid`
+    else if (idType === `number`) return `::int`
+    else return `::bigint`
+}
+
+
+export function junctionTableRemovalPostgres(removedIds, tableName, paramIndex, idTypeArr) {
+    const snakedTableName = nonSnake2Snake(tableName)
+    let queryStr = ``
+    const params = []
+
+    const [joiningIdTypeCast, joinedIdTypeCast] = [getPostgresIdTypeCasting(idTypeArr[0]), getPostgresIdTypeCasting(idTypeArr[1])]
+    queryStr = `DELETE FROM ${snakedTableName} AS jt USING (VALUES`
+    for (const idPairings of removedIds) {
+        const joiningId = idPairings[0]
+        const removedJoinedIds = idPairings[1]
+        for (const removedId of removedJoinedIds) {
+            queryStr += `($${paramIndex++}${joiningIdTypeCast}, $${paramIndex++}${joinedIdTypeCast}), `
+            params.push(joiningId, removedId)
+        }
+    }
+    queryStr = queryStr.slice(0, -2) + `) AS to_delete(joining_id, joined_id) `
+    queryStr += `WHERE jt.joining_id = to_delete.joining_id AND jt.joined_id = to_delete.joined_id `
+    queryStr += `RETURNING 1`
+
+    const returnedJunctionObj = { queryStr, params }
+    return [returnedJunctionObj, paramIndex]
+}

package/src/changeLogger/sqlClients/sqlite.js

@@ -0,0 +1,120 @@
+import { coloredBackgroundConsoleLog, nonSnake2Snake } from "../../misc/miscFunctions.js"
+import { successfullSaveOperation } from "../save.js"
+
+export function sqliteSaveQuery(deletedUncalledRelationsArr, classesQueryObj, junctionsQueryObj, deletedInstancesArr, dbConnection) {
+    const classTableNames = Object.keys(classesQueryObj ?? {})
+    const queryFuncWithTryCatch = (queryStr, params) => {
+        try {
+            const queryFunc = dbConnection.prepare(queryStr)
+            queryFunc.run(...params)
+            return true
+        }
+        catch (e) {
+            coloredBackgroundConsoleLog(`Database save failed. ${e}\n`, `failure`)
+            dbConnection.exec('ROLLBACK;')
+            return false
+        }
+    }
+
+    let visitedTables = []
+    dbConnection.exec('BEGIN;')
+
+    if (deletedUncalledRelationsArr) {
+        for (const [tableName, idArr] of Object.entries(deletedUncalledRelationsArr)) {
+            const queryStr = `DELETE FROM ${tableName} WHERE joining_id IN (${idArr.map(id => `?`).join(`, `)})`
+            if (!queryFuncWithTryCatch(queryStr, idArr)) return
+        }
+    }
+
+    for (const tableName of classTableNames) {
+        if (visitedTables.includes(tableName)) continue
+        const queryObj = classesQueryObj[tableName]
+
+        visitedTables = queryObj.parent
+            ? sqliteHandleAncestry(tableName, queryObj, visitedTables, classesQueryObj, queryFuncWithTryCatch)
+            : queryQueryObj(queryObj, tableName, visitedTables, queryFuncWithTryCatch)
+        if (!visitedTables) return
+    }
+
+    const junctionTableQueryObjects = Object.values(junctionsQueryObj ?? {})
+    for (const queryObj of junctionTableQueryObjects) {
+        if (queryObj.deletedRelationsObj)
+            if (!queryFuncWithTryCatch(queryObj.deletedRelationsObj.queryStr, queryObj.deletedRelationsObj.params)) return
+
+        if (queryObj.newRelationsObj)
+            if (!queryFuncWithTryCatch(queryObj.newRelationsObj.queryStr, queryObj.newRelationsObj.params)) return
+    }
+
+    if (deletedInstancesArr) {
+        for (const [tableName, param] of deletedInstancesArr) {
+            const queryStr = `DELETE FROM ${tableName} WHERE id = ?;`
+            if (!queryFuncWithTryCatch(queryStr, [param])) return
+        }
+    }
+
+    dbConnection.exec('COMMIT;')
+    successfullSaveOperation()
+}
+
+
+function queryQueryObj(queryObj, tableName, visitedTables, queryFuncWithTryCatch) {
+    visitedTables.push(tableName)
+    if (queryObj.insert) {
+        if (!queryFuncWithTryCatch(queryObj.insert.queryStr, queryObj.insert.params)) return false
+    }
+
+    if (queryObj.update) {
+        for (const [index, queryStr] of Object.entries(queryObj.update.queryStrArr))
+            if (!queryFuncWithTryCatch(queryStr, queryObj.update.params2dArr[index])) return false
+    }
+
+    return visitedTables
+}
+
+function sqliteHandleAncestry(tableName, queryObj, visitedTables, classesQueryObj, queryFuncWithTryCatch) {
+    if (visitedTables.includes(queryObj.parent)) {
+        const queryRes = queryQueryObj(queryObj, tableName, visitedTables, queryFuncWithTryCatch)
+        if (queryRes) {
+            visitedTables = queryRes
+            return visitedTables
+        }
+        return false
+    }
+
+    const ancestryArr = [tableName]
+    let currentQueryObj = queryObj
+    while (currentQueryObj.parent) {
+        const parentName = currentQueryObj.parent
+        ancestryArr.push(parentName)
+        currentQueryObj = classesQueryObj[parentName]
+    }
+
+    while (ancestryArr.length) {
+        const ancestorTableName = ancestryArr.pop()
+        currentQueryObj = classesQueryObj[ancestorTableName]
+        const queryRes = queryQueryObj(currentQueryObj, ancestorTableName, visitedTables, queryFuncWithTryCatch)
+        if (queryRes) visitedTables = queryRes
+        else return false
+    }
+    return visitedTables
+}
+
+
+export function junctionTableRemovalSqlite(removedIds, tableName) {
+    const snakedTableName = nonSnake2Snake(tableName)
+    let queryStr = ``
+    const params = []
+
+    queryStr = `DELETE FROM ${snakedTableName} WHERE (joining_id, joined_id) IN (`
+    for (const idPairings of removedIds) {
+        const baseId = idPairings[0]
+        const nonBaseIds = idPairings[1]
+        for (const removedId of nonBaseIds) {
+            queryStr += `(?, ?), `
+            params.push(baseId, removedId)
+        }
+    }
+    queryStr = queryStr.slice(0, -2) + `)`
+    const returnedJunctionObj = { queryStr, params }
+    return [returnedJunctionObj, undefined]
+}

package/src/entity/delete/delete.js

@@ -0,0 +1,20 @@
+export function throwDeletionErr(className, id4Deletion) {
+    throw new Error(`Unable to delete ${className} with id of ${id4Deletion} due to potential relational dependencies. Use the async method 'getDependents' to get relational dependency data and decouple it from the deleted instance for the deletion to work.`)
+}
+
+export function throwImproperDecouplingErr(className, id4Deletion) {
+    throw new Error(`Unable to delete ${className} with id of ${id4Deletion} due to incomplete decoupling.`)
+}
+
+
+export function validateDependentDataDecoupling(dependentsData, id4deletion) {
+    for (const dependency2dArr of Object.values(dependentsData)) {
+        const [dependentInstanceArr, props2Check] = dependency2dArr
+        for (const instance of dependentInstanceArr) {
+            for (const prop of props2Check) {
+                if (instance[prop].id === id4deletion) return false
+            }
+        }
+    }
+    return true
+}

package/src/entity/delete/getDependents.js

@@ -0,0 +1,46 @@
+import { OrmStore } from "../../misc/ormStore.js"
+import { DependentsFinalizationRegistry, ORM } from "../../ORM/ORM.js"
+import { aliasedFindWiki2QueryRes, parseFindWiki } from "../find/find.js"
+import { deproxifyScopeProxy, classWiki2ScopeProxy } from "../find/scopeProxies.js"
+import { postgresCreateProxyArray } from "../find/sqlClients/postgresFuncs.js"
+import { sqliteCreateProxyArray } from "../find/sqlClients/sqliteFuncs.js"
+
+export async function internalFind(dependentMap, relationalProps, searchedId) {
+    const { sqlClient, dbConnection, entities } = OrmStore.store
+    const baseProxyMap = classWiki2ScopeProxy({ ...dependentMap })
+    let findWiki = deproxifyScopeProxy(baseProxyMap)
+    const eagerLoadObj = {}
+    for (const prop of relationalProps) internalFindSetup(prop, findWiki, eagerLoadObj, searchedId)
+
+    const [aliasedFindMap, joinStatements, whereObj] = parseFindWiki(findWiki)
+    const [queryResult, eagerLoadMap] = await aliasedFindWiki2QueryRes(aliasedFindMap, joinStatements, whereObj, eagerLoadObj, dependentMap, dbConnection, true)
+    const instanceArr = sqlClient === "postgresql" ?
+        postgresCreateProxyArray(queryResult, eagerLoadMap, entities, eagerLoadObj) :
+        sqliteCreateProxyArray(queryResult, eagerLoadMap, entities, true)
+
+    return instanceArr
+}
+
+
+export function insertDependentsData(className, dependedOnId, dependentsData, dependentsMapsObj) {
+    const map = dependentsMapsObj[className] ??= new Map()
+    map.set(dependedOnId, new WeakRef(dependentsData))
+    ORM[DependentsFinalizationRegistry].register(dependentsData, [className, dependedOnId])
+}
+
+
+
+export function internalFindSetup(prop, findWiki, eagerLoadObj, searchedId) {
+    const { [prop]: relation, ...restOfRelations } = findWiki.uncalledJunctions_
+    const relationCopy = { ...relation }
+    relationCopy.where = { id: searchedId }
+    for (const key of Object.keys(relationCopy)) {
+        relationCopy[key + `_`] = relationCopy[key]
+        delete relationCopy[key]
+    }
+    const { junctions_, ...noJunctionsRelation } = relationCopy
+    findWiki.uncalledJunctions_ = restOfRelations
+    findWiki.junctions_ ??= {}
+    findWiki.junctions_[prop] = noJunctionsRelation
+    eagerLoadObj[prop] = true
+}

package/src/entity/entity.d.ts

@@ -0,0 +1,46 @@
+
+import type { FindObj } from "../misc/types"
+
+export declare class Entity {
+  id: string | number | bigint
+  updatedAt: Date
+
+  /**
+  * Finds instances in the database that match the given argument.
+  * Relations do not get filtered by where conditions, only the root instances get filtered.
+  * (RootClass.find(arg)) => only RootClass instances matching the where conditions get returned. 
+  */
+  static find<T extends Entity>(
+    this: new (...args: any[]) => T,
+    obj: FindObj<T>
+  ): Promise<T[]>
+
+  /**
+  * Hard deletes the instance from the database. May require a pre-deletion step - the 'getDependents' method.
+  */
+  delete(): Promise<void>
+
+  /**
+  * A pre-deletion step that is required in certain cases.
+  * Finds all instances that have a one-to-one relationship with the calling instance
+  * where the related property cannot be set to `undefined`.
+  * These relationships must be reassigned before the calling instance
+  * can be safely deleted.
+  * Returns undefined if there are no dependents.
+  */
+  getDependents(): Promise<DependentsDict | undefined>
+
+  /**
+   * Finds all instances that have a relation with the calling instance,
+   * This method is a superset of the getDependents method, and is not meant as a pre-deletion step, but as a utility.
+   */
+  getReferencers(): Promise<DependentsDict | undefined>
+}
+
+
+type DependentsDict = {
+  [key: string]: [
+    dependentInstances: any[],
+    dependentProps: string[]
+  ]
+}