masquerade-orm 0.1.0

package/docs/getting-started-javascript.md

@@ -0,0 +1,112 @@
+
+# Defining Classes
+
+## 1) Declaring the Class:
+```js
+import { Entity } from 'masquerade'
+
+class YourClass extends Entity {
+  // class properties
+}
+```   
+The class **MUST** extend `Entity` or a descendent of `Entity`.
+
+## 2) Making a Table Column Nullable:
+```js
+/**@type {string | undefined}*/ propertyName
+```   
+
+## 3) Making a Table Column Unique:
+```js
+/**@typedef {import('masquerade').integer} integer */
+/**@type {string | Unique}*/ propertyName
+```   
+
+## 4) Relational Properties
+Assuming we have the following classes extending Entity: `User`, `Chat` and `Message`.    
+
+```js
+import { Entity } from 'masquerade'
+
+class Example extends Entity {
+    // one-to-one relationship with a User instance
+    /** @type {User} */ user
+    
+    // One-to-one relationship with a User instance.
+    // May be undefined if no relationship is established yet. 
+    /** @type {User | undefined} */ optionalUser
+    
+    // one-to-many relationship with Message instances
+    /** @type {Message[]} */ messages
+    
+    // One-to-many relationship with Chat instances.
+    // May be undefined if no relationships are established yet.
+    /** @type {Chat[] | undefined} */ optionalChats
+}
+```
+Each relational property will create a junction table named `className___propName_jt`.
+
+
+# Booting Up the ORM
+
+## 1) Database Connection Driver:
+ 
+**SQLite**  
+
+```js
+import { DatabaseSync } from 'node:sqlite'   
+const yourDbConnection = new DatabaseSync('your-db-name')
+```
+
+**Postgresql**
+
+```js
+import pkg from 'pg'
+const { Pool } = pkg
+
+// Create a pool instance
+const yourDbConnection = new Pool({
+    user: 'your_db_user',         // e.g., 'postgres'
+    host: 'localhost',            // database host
+    database: 'your_db_name',     // database name
+    password: 'your_db_password', // your password
+    port: 5432,                   // default PostgreSQL port
+})
+```
+
+## 2) Configuration Object:
+```js
+/**@typedef {import('masquerade').OrmConfigObj} OrmConfigObj*/
+
+/** @type {OrmConfigObj} */ const ormConfig = {
+    dbConnection: yourDbConnection,
+    idTypeDefault: 'UUID', // | 'INT' | 'BIGINT'
+    skipTableCreation: true // optional, false by default
+}
+```
+
+`idTypeDefault` sets the default id-type on all classes.    
+To manually set the id-type on a class, read **[Defining Classes: In-Depth - Chapter 2](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/in-depth-class-definitions.md#2-overriding-the-default-id-type)**.
+
+
+## 3) Boot ORM:
+
+```js
+import * as classes from './classes.js'
+import * as moreClasses from './moreClasses.js'
+import { someClass } from './aSingleClass.js'
+await ORM.javascriptBoot(ormConfig, classes, moreClasses, someClass)
+```
+
+
+<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/getting-started-typescript.md

@@ -0,0 +1,159 @@
+
+# Defining Classes
+
+## 1) Declaring the Class:
+```js
+import { Entity } from 'masquerade'
+
+class YourClass extends Entity {
+  // class properties
+}
+```   
+The class **MUST** extend `Entity` or a descendent of `Entity`.
+## 2) Making a Table Column Nullable:  
+
+```ts
+propertyName?: string 
+// OR propertyName: string | undefined
+```   
+
+## 3) Making a Table Column Unique:
+
+```ts
+import { Unique } from 'masquerade'
+propertyName: string | Unique
+```   
+
+## 4) Relational Properties
+Assuming we have the following classes extending Entity: `User`, `Chat` and `Message`.   
+
+```ts
+import { Entity } from 'masquerade'
+
+class Example extends Entity {
+    // one-to-one relationship with a User instance
+    user: User
+
+    // one-to-one relationship with a User instance,
+    // but may be undefined if no relationship is established yet
+    optionalUser?: User
+
+    // one-to-many relationship with Message instances
+    messages: Message[]
+
+    // one-to-many relationship with Chat instances,
+    // but may be undefined if no relationships are established yet
+    optionalChats?: Chat[]
+}
+```
+Each relational property will create a junction table named `className___propName_jt`.
+
+
+# Booting Up the ORM
+
+## 1) Database Connection Driver:
+ 
+**SQLite**  
+
+```ts
+import { DatabaseSync } from 'node:sqlite'   
+const yourDbConnection = new DatabaseSync('your-db-name')
+```
+
+**Postgresql**
+
+```ts
+import pkg from 'pg'
+const { Pool } = pkg
+
+// Create a pool instance
+const yourDbConnection = new Pool({
+    user: 'your_db_user',         // e.g., 'postgres'
+    host: 'localhost',            // database host
+    database: 'your_db_name',     // database name
+    password: 'your_db_password', // your password
+    port: 5432,                   // default PostgreSQL port
+})
+```
+
+## 2) Configuration Object:
+```ts
+import type { OrmConfigObj } from "masquerade"
+
+const ormConfig: OrmConfigObj = { 
+    dbConnection: yourDbConnection,
+    idTypeDefault: 'UUID', // | 'INT' | 'BIGINT'
+    skipTableCreation: true // optional, false by default
+  }
+```
+
+`idTypeDefault` sets the default id-type on all classes.    
+To manually set the id-type on a class, read **[Defining Classes: In-Depth - Chapter 2](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/in-depth-class-definitions.md#2-overriding-the-default-id-type)**.
+
+## 3) Build Step
+
+### A) Universal Build Step:  
+
+First run ```bash npx orm-ts-setup``` in your terminal before your compile step. Then, compile and import ```UniversalTsSetup``` into your entry point, and run it before the boot method. Detailed example below in **[Section 4](https://github.com/MasqueradeORM/MasqueradeORM/blob/master/docs/getting-started-typescript.md#4-boot-orm)**.    
+
+
+
+**Note:**  
+Any changes to classes that are descendents of `Entity` require `UniversalTsSetup` to be rebuilt.
+To keep the ORM in sync with your entity definitions, include `npx orm-ts-setup` in your build step.
+
+**Example:** ```bash
+npx orm-ts-setup && tsc```
+
+
+### B) Webpack Build Step:
+```js
+// in your webpack.config file add:
+import { MasqueradePlugin } from './plugin.js'
+
+//other fields
+  plugins: [
+        //other plugins...
+        new MasqueradePlugin() //this should be last
+    ],
+    module: {
+        rules: [
+            {
+                test: /\.tsx?$/,
+                // add 'masquerade-loader' in the 'use' field
+                use: ['ts-loader', 'masquerade-loader'],
+                exclude: /node_modules/,
+            },
+        ],
+    },
+//other fields
+```
+
+**Note:** The universal build step will work for projects using webpack as well.
+
+## 4) Boot ORM:
+
+```ts
+import * as classes from "./classes"
+import * as moreClasses from "./moreClasses"
+import { SomeClass } from "./aSingleClass"
+
+if (!usingWebpack) {
+import { UniversalTsSetup } from "some/path/ormTypeScriptSetup"
+UniversalTsSetup()
+}
+
+await ORM.typescriptBoot(ormConfig, classes, moreClasses, someClass)
+```
+
+<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/in-depth-class-definitions.md

@@ -0,0 +1,193 @@
+
+# Defining Classes: In-Depth
+
+## 1) Special Property Typing Cases
+
+**TypseScript**
+```ts
+import { Entity, integer } from 'masquerade'
+
+type MyJSON = {
+    booleanField: boolean
+    stringArr: string[]
+    nestedObj: object
+}
+
+class ExampleClass extends Entity {
+
+    // Maps to INTEGER column
+    integer: integer = 57
+
+    // Maps to REAL/DOUBLE PRECISION column
+    float: number = 15.7
+
+    // Allowed
+    stringArrWithUndefineds: (string | undefined)[] = [
+        'hello', 'world' , undefined
+        ]
+
+    // Can use `satisfies` instead
+    json: MyJSON & object = {
+        booleanField: false,
+        stringArr: ['a', 'b', 'c'],
+        nestedObj: {}
+    }
+
+    // Can use `satisfies` instead
+    jsonArr: (MyJSON & object)[] = [
+        {
+            booleanField: false,
+            stringArr: ['a', 'b', 'c'],
+            nestedObj: {}
+        }
+    ]
+}
+```
+**JavaScript**
+```js
+import { Entity } from 'masquerade'
+/**@typedef {import('masquerade').integer} integer */
+
+/**
+ * @typedef {Object} MyJSON
+ * @property {boolean} booleanField
+ * @property {string[]} stringArr
+ * @property {object} nestedObj
+ */
+
+class ExampleClass extends Entity {
+    // Will map to an INTEGER column
+    /**@type {integer}*/ integer = 57
+
+    // Will map to an REAL/DOUBLE PRECISION column
+    /**@type {number}*/ float = 15.7
+
+    // Allowed
+    /**@type {(string | undefined)[]}*/ stringArrWithUndefineds = [
+        'hello', 'world' , undefined
+        ]
+
+    // MUST use 'satisfies'
+    /**@satisfies {MyJSON}*/ json = {
+        booleanField: false,
+        stringArr: ['a', 'b', 'c']
+        nestedObj: {}
+    }
+
+    // MUST use 'satisfies'
+    /**@satisfies {MyJSON[]}*/ jsonArr = [{
+        booleanField: false,
+        stringArr: ['a', 'b', 'c'],
+        nestedObj: {}
+    }]
+}
+```
+
+### Operational Edge Cases in Regards to the `json` and `jsonArr` Properties
+
+The ORM can keep track of **assigments** on the first layer of an `object` (`MyJSON` object in the our case). 
+
+```js
+const newInstance = new ExampleClass()
+// These will mutate the instances 
+// but the ORM will not detect these changes. 
+// The objects need assigment, not mutation.
+newInstance.json.stringArr.push('d') 
+newInstance.jsonArr.stringArr.push('d')
+// The below mutation IS an assigment, but it is
+// nested, and therefore will also not be persisted.
+newInstance.json.nestedObj.someProp = 'hola mundo'
+
+// First solution - property assigment
+const jsonStringArr = newInstance.json.stringArr
+const captureNesting = newInstance.json.nestedObj
+newInstance.json.stringArr = [...jsonStringArr]
+newInstance.jsonArr.stringArr = [...jsonStringArr]
+newInstance.nestedObj = { ...captureNesting }
+// why destructure? if an assigment is 
+// strict-equal the ORM will ignore it.
+
+// Second solution - reassigning on the instance
+newInstance.json = { ...newInstance.json }
+newInstance.jsonArr = [...newInstance.jsonArr]
+```
+Both approaches will allow for proper detection and persisting of such changes.
+
+
+## 2) Overriding the Default Id-Type
+
+```js
+import { Entity } from 'masquerade'
+
+class ClassA extends Entity {
+    // to avoid bugs put 'ormClassSettings_' as the first property.
+    static ormClassSettings_ = {idType: 'INT'} // | 'UUID' | 'BIGINT'
+    // properties and constructor...
+}
+``` 
+
+The above code lets you override the default id-type that is assigned to all Entity's descendants from the the ORM-config object passed to the `ORM.boot` function.    
+
+Setting the `idType` is only possible on a **direct child of Entity**.    
+
+```ts
+import { Entity } from 'masquerade'
+
+class ClassA extends Entity {
+    // properties and constructor...
+}
+
+class ClassB extends ClassA {
+    static ormClassSettings_ = {idType: 'INT'}
+    // properties and constructor...
+}
+```
+In the example above, `idType` has no effect because `ClassB` does not extend `Entity`. If `static ormClassSettings_ = {idType: 'INT'}` was instead on `ClassA`, the id type of `ClassA` and all of its descendants would have an id type of `integer`.
+
+At the moment, this is the only class setting supported, but it may evolve in the future.
+
+
+## 3) Abstract Classes
+
+### 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'
+
+class User extends Entity {
+    // properties...
+
+    /**@abstract*/
+    constructor() {
+        super()
+    }
+}
+```
+
+### How is an abstract class mapped to the database?  
+Abstract classes do not get a table on the database. Instead, the non-abstract descendant classes of the abstract class will inherit all its properties/columns.   
+For example, `abstract ClassA` has two children, `abstract ClassB` and `non-abstract ClassC`, with *ClassB* having a `non-abstract` child `ClassD`.
+this means *ClassD's* table will inherit columns from both *ClassA* and *ClassB*, while *ClassC's* table will inherit columns from *ClassA*.
+
+
+
+## 4) Guidelines for Classes
+
+Classes that are connected to the ORM and mapped to database tables must follow a few simple rules:
+- **Rule 1:** Class must either directly extend Entity (imported from the package) or extend another class that has Entity as an ancestor.
+- **Rule 2:** Class properties must have a single “main” type: a `primitive`, a `primitive array`, an `object`, or a class that follows **Rule 1**.
+- **Rule 3:** Class names must be PascalCasde.
+- **Rule 4:** Class property names must be camelCased.
+
+As long as these rules are adhered to, the class is valid.  
+
+
+<br>
+<div align="center">
+  <strong>
+    © 2026 
+    <a href="https://github.com/MasqueradeORM">MasqueradeORM </a>
+		-
+    Released under the MIT License
+  </strong>
+</div>

package/docs/jsdoc-ux-tips.md

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

package/docs/managing-the-database.md

@@ -0,0 +1,37 @@
+
+
+# Managing Database Tables
+
+With time, databases can get messy with unused tables or columns that need dropping.    
+On booting, the ORM will warn you of any such tables or columns, to allow you to keep track of any redundancies.    
+
+We offer a simple way to clean up your database using the `DbManager` class and its static methods.
+
+
+```js
+import { DbManager } from 'masquerade'
+// will drop all unused columns in the database
+await DbManager.dropUnusedColumns() 
+// will drop all unused columns in entity_table
+await DbManager.dropUnusedColumns('entity_table') 
+
+// will delete unused entity tables in the database
+await DbManager.dropUnusedTables() 
+// will delete the table 'unused_entity_table' (won't delete a table that is connected to the ORM)
+await DbManager.dropUnusedTables('unused_entity_table') 
+
+// will delete unused junction tables in the database
+await DbManager.dropUnusedJunctions() 
+// will delete the table 'unused_junction_table' (won't delete a table that is connected to the ORM)
+await DbManager.dropUnusedJunctions('unused_junction_table') 
+```
+
+<br>
+<div align="center">
+  <strong>
+    © 2026 
+    <a href="https://github.com/MasqueradeORM">MasqueradeORM </a>
+		-
+    Released under the MIT License
+  </strong>
+</div>

package/docs/saving-to-database.md

@@ -0,0 +1,37 @@
+# Saving to the Database
+In MasqueradeORM there is no explicit save call.
+
+The code below is all that is needed to persist a new class instance in the database:
+```js
+new YourClass() 
+```
+
+The code below is all that is needed to persist any mutation to a class instance:
+```js
+// toggles a boolean value and persists the change
+yourInstance.booleanValue = !yourInstance.booleanValue
+
+// overwrites a 1-to-1 relationship and persists it
+yourInstance.exampleRelation = new ExampleRelation()
+```
+
+**How does this work under the hood?**  
+
+When you mutate a class instance, changing a value or adding/removing a relation, the ORM doesn’t write to the database immediately.   
+Instead, it tracks those changes and batches them together to optimize the save operation.
+
+Whenever the server is about to perform an async operation (for example, when execution hits an await), the ORM assumes that a database read might happen next. Before that happens, it automatically saves everything that’s pending.
+
+
+Below is the order of operations:   
+**create/change data → hit an async boundary → ORM saves → safe to read**
+
+<br>
+<div align="center">
+  <strong>
+    © 2026 
+    <a href="https://github.com/MasqueradeORM">MasqueradeORM </a>
+		-
+    Released under the MIT License
+  </strong>
+</div>

package/index.d.ts

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

package/index.js

@@ -0,0 +1,11 @@
+
+export {ORM} from "./src/ORM/ORM.js"
+export {Entity} from './src/entity/entity.js'
+export {DbManager} from "./src/ORM/DbManager.js"
+export {sql, AND, OR} from "./src/entity/find/where/whereArgsFunctions.js"
+export {MasqueradePlugin} from "./src/webpack/plugin.js"
+
+
+/** @typedef {import('./src/misc/types.d.ts').Unique} Unique */
+/** @typedef {import('./src/misc/types.d.ts').integer} integer */
+

package/jsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    //Preferences
+    "strict": true,
+    "allowUnreachableCode": false,
+    "noImplicitAny": false,
+    "strictNullChecks": true,
+    "noImplicitReturns": false,
+    "noUncheckedIndexedAccess": false,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "checkJs": true,
+    "types": ["node"],
+    "outDir": "dist",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "exclude": ["./node_modules/**/*"]
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "masquerade-orm",
+  "version": "0.1.0",
+  "description": "Lightweight ORM compatible with SQLite and Postgresql in Node.js",
+  "keywords": [],
+  "repository": {
+    "type": "git",
+    "url": "Masquerade-Orm"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.ts",
+        "default": "./index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "orm-ts-setup": "./bin/universalTsInit.js"
+  },
+  "license": "MIT",
+  "author": "Masquerade-Orm",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "pg": "^8.11.2",
+    "typescript": "^5.9.3",
+    "uuidv7": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3"
+  },
+  "prettier": {
+    "semi": false
+  }
+}