masquerade-orm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Masquerade-Orm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+<div align="center">
+  <a href="#">
+  <img
+  src="https://github.com/user-attachments/assets/3bf1ab31-f9c6-4362-b17d-1dfe7c414f17"
+  alt="Masquerade ORM Logo"
+  style="max-width: 50%; height: auto;"
+  />
+  </a>
+  <br><br>
+  <a href="">
+      <br><br>
+    <img src="https://img.shields.io/badge/License-MIT-teal.svg" alt="MIT License"/>
+  </a>
+  <br><br>
+</div>
+
+**MasqueradeORM** is a lightweight ORM for Node.js that works seamlessly with both TypeScript and JavaScript.
+Its goal is to hide SQL complexity while letting you work naturally in JS/TS syntax.    
+Instead of forcing you into ORM-specific models, metadata systems, or decorators, MasqueradeORM lets you use **your own classes** directly, exactly as you normally would.
+
+MasqueradeORM improves readability, maintainability, and workflow simplicity through a unified coding approach and extremely minimal setup. 
+No ORM offers a simpler start.
+There’s no need to manage heavy configuration layers, maintain secondary schema systems, or even plan your database structure separately. 
+Your schema and tables are generated automatically from a single source of truth: **Your class definitions.**
+
+MasqueradeORM currently supports the following SQL clients: 
+- **SQLite** 
+- **Postgresql**
+
+# 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.
+- **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
+
+### Creating an ORM-Compatible Class
+```ts
+import { Entity } from 'masquerade'
+
+type UserSettings = {
+    theme: 'light' | 'dark' | 'system'
+    twoStepVerification: boolean
+    locale: 'en' | 'es' | 'fr' | 'de'
+}
+
+export class User extends Entity {
+    username: string
+    email: string
+    password: string
+    createdAt: Date = new Date()
+    friendList: User[] = []
+    settings: UserSettings & object = {
+        locale: "en",
+        theme: "system",
+        twoStepVerification: false
+    }
+
+    constructor(username: string, email: string, password: string) {
+        super()
+        this.username = username
+        this.email = email
+        this.password = password
+    }
+}
+```
+
+### Basic Find Example
+```ts		
+// finds any User instance with email === lookupEmail
+async function findUserByEmail(lookupEmail: string): Promise<User | undefined> {
+    const resultArray = await User.find({
+        where: { email: lookupEmail }
+    })
+    // the static 'find' method above is inherited from 'Entity'
+
+    return resultArray[0]
+}
+```
+
+### Saving Instances
+```ts
+// Creating a new table row in the User table
+const newUser = new User('JohnDoe57', 'johnDoe@yahoo.com', 'passwordHash')
+// newUser will be saved to the database automatically, no explicit save call is required.
+
+// Finding a user by email
+const user = await findUserByEmail('johnDoe@yahoo.com') // user's friendList is a promise
+console.log(user.username === 'JohnDoe57') // true
+```
+
+### Mutating Data
+All mutations are persisted implicitly and automatically, meaning that simply changing a value is enough for it to be reflected in the database.
+
+**Mutating non-Relational Properties**
+```ts
+user.settings.theme = 'dark' 
+```
+
+**Mutating Relational Properties**
+```ts
+// lazy-load friendList
+await user.friendList 
+// add a new relation
+user.friendList.push(new User('JaneDoe33', 'janeDoe@yahoo.com', 'passwordHash2')) 
+// remove a relation
+user.friendList.pop() 
+```
+
+
+# Further Reading
+
+- **[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)**
+- **[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)**
+
+
+
+<br>
+<div align="center">
+  <strong>
+    © 2026 
+    <a href="https://github.com/MasqueradeORM">MasqueradeORM </a>
+		-
+    Released under the MIT License
+  </strong>
+</div>
+
+
+
+
+

package/bin/universalTsInit.js

@@ -0,0 +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")
+
+
+
+

package/docs/deletion.md

@@ -0,0 +1,186 @@
+# Deleting Instances from the Database
+
+### Soft Deletion
+The ORM does not support soft deletion by default. To implement soft deletion, just create an abstract class like so: 
+
+**TypeScript**
+```ts
+export abstract class SoftDel extends Entity {
+  isDeleted: boolean = false
+
+    constructor() {
+        super()
+    }
+}
+
+export abstract class SoftDelUuid extends Entity {
+  // switch 'UUID' to 'INT' or 'BIGINT' as needed.
+  static ormClassSettings_ = { idType: 'UUID' } 
+  isDeleted: boolean = false
+
+  constructor() {
+      super()
+  }
+}
+```
+
+**JavaScript**
+```js
+export class SoftDel extends Entity {
+  /**@type {boolean}*/ isDeleted = false
+
+  /** @abstract */
+  constructor() {
+      super()
+  }
+}
+
+export class SoftDelUuid extends Entity {
+  // switch 'UUID' to 'INT' or 'BIGINT' as needed.
+  static ormClassSettings_ = { idType: 'UUID' }
+  /**@type {boolean}*/ isDeleted = false
+
+  /** @abstract */
+  constructor() {
+      super()
+  }
+}
+```
+
+Every class that extends these `SoftDel` classes will have a boolean property `isDeleted` that is `false` by default, allowing instances to be soft-deleted by setting the `isDeleted` value to `true`.
+
+```ts
+export class SoftDeletableUser extends SoftDelUuid {
+  username: string
+  email: string
+  password: string
+
+  constructor (username, email, password) {
+    this.username = username
+    this.email = email
+    this.password = password
+  }
+}
+
+const softDelUser = new SoftDeletableUser('JohnDoe', 'JohnDoe@gmail.com', 'hashedPassword')
+// softDelUser has an 'isDeleted' property that can be toggled to true for soft deletion
+// and has an id type of UUID.
+```
+
+**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
+
+```ts
+import { sql } from "masquerade"
+const twoYearsAgo = new Date().setFullYear(new Date().getFullYear() - 2)
+
+// finds all instances that haven't been mutated in over two years
+const instances4Deletion = await ExampleClass.find({where: {updatedAt: sql`< ${twoYearsAgo}`}})
+
+// delete all instances
+instances4Deletion.forEach(instance => instance.delete())
+```
+
+The `delete` method hard-deletes the instance from the database; the instance cannot be recovered afterwards.
+
+<div align="center">
+<strong style="font-size: 1.2em;">
+** This method will throw an error in case a pre-deletion step is required. **
+ </strong>
+</div>
+
+
+## Pre-Deletion Step
+
+### When is a pre-deletion step required?  
+A pre-deletion step is required when the class instance has **dependents**.  
+
+
+### What is a dependent?     
+A dependent is a class that has a required 1-to-1 relationship with another class, meaning the relation cannot be undefined.
+
+```ts
+// dependent 1-to-1 relation, 'sender' cannot be undefined
+sender: User 
+```
+
+For example, if a `Message` has a `sender` property of type `User`, then `Message` is dependent on `User`. As a result, a `User` instance cannot be safely deleted until all dependent `Message` instances are resolved of said dependency.
+
+```ts
+sender?: User // optional relation
+sender: User | undefined // optional relation
+```
+
+If the property was optional or of type `User | undefined`, the `Message` class would **NOT** be dependent on `User`.
+In such a case, when a `User` instance is deleted, any of its messages will have an `undefined` value in the `sender` property.
+
+
+### How to find an instance's dependents? 
+Assuming `User` has dependents:
+
+```ts
+// finds the user with a username of 'JohnDoe57'
+const user = (await User.find({ where: {username: 'JohnDoe57'} }))[0]
+const dependentsDict = await user.getDependents()
+```
+
+### What is the structure of dependentsDict? 
+
+```ts
+type DependentsDict<T extends Entity> = {
+  [dependentClassName: string]: [
+    dependentInstances: T[],
+    dependentProps: string[]
+  ]
+}
+```
+
+Assuming the classes `Payment` and `Message` are dependents of the `User` class, with `Payment` having a dependent property of `sentBy` and `receivedBy`, and `Message` having a dependent property of `sender`.
+
+```ts
+// structure of dependentsDict
+dependentsDict = {
+  'Payment': [
+    // all Payment instances that depend on the deleted User instance
+    [paymentInstance1, paymentInstance2, ...],
+    // all properties on Payment that depend on the deleted User instance
+    ['sentBy', 'receivedBy']
+  ],
+  'Message': [
+    // all Message instances that depend on the deleted User instance
+    [messageInstance1, messageInstance2, ...],
+    // all properties on Message that depend on the deleted User instance
+    ['sender']
+  ]
+}
+```
+
+### Resolving dependencies
+To resolve the dependencies, access the data as such:
+```ts
+const user = (await User.find({ where: { username: 'JohnDoe57' } }))[0]
+const dependentsDict = await user.getDependents()
+const deletedUserId = user.id
+
+for (const dependentClassName of Object.keys(dependentsDict)) {
+  const [dependentInstances, dependentProps] = dependentsDict[dependentClassName]
+
+  for (const instance of dependentInstances) {
+    dependentProps.forEach(prop => {
+      if (instance[prop].id !== deletedUserId) continue
+      // decoupling logic here...
+    })
+  }
+}
+```
+
+<br>
+<div align="center">
+  <strong>
+    © 2026 
+    <a href="https://github.com/MasqueradeORM">MasqueradeORM </a>
+		-
+    Released under the MIT License
+  </strong>
+</div>

package/docs/find.md

@@ -0,0 +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>
+</div>