@shadow-dev/orm 1.0.0

package/.eslintrc.json

@@ -0,0 +1,21 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "env": {
+    "node": true,
+    "es2021": true
+  },
+  "parserOptions": {
+    "ecmaVersion": 2021,
+    "sourceType": "module"
+  },
+  "rules": {
+    "@typescript-eslint/no-unused-vars": ["warn"],
+    "@typescript-eslint/no-explicit-any": "off"
+  }
+}

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+## 📝 Description
+<!-- Describe your changes in detail. Explain the problem and how your PR fixes it. -->
+
+## 🔍 Related Issues
+<!-- Link any relevant issues (e.g., "Closes #123") -->
+
+## 🚀 Changes Made
+- [ ] Bug fix 🐛
+- [ ] New feature ✨
+- [ ] Code refactor 🔧
+- [ ] Documentation update 📖
+- [ ] Security improvement 🔒
+- [ ] Other (please specify): ____________
+
+## ✅ Testing Steps
+<!-- Provide instructions for testing your changes. Include commands, expected behavior, and test cases if applicable. -->
+1. 
+2. 
+3. 
+
+## 🔒 Security Considerations
+<!-- Any security implications? Dependencies updated? New permissions required? -->
+
+## 📸 Screenshots / Logs (if applicable)
+<!-- Add screenshots or logs if they help understand the change. -->
+
+## ⏳ Checklist
+- [ ] My code follows the project coding style.
+- [ ] I have run tests to verify my changes.
+- [ ] I have updated the documentation if needed.
+- [ ] My changes do not introduce new vulnerabilities.
+- [ ] This PR is ready for review.
+
+---
+
+### 🚀 Additional Notes
+<!-- Anything else reviewers should know? -->

package/.github/dependabot.yml

@@ -0,0 +1,34 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  # 📦 Keep npm dependencies up to date
+  - package-ecosystem: "npm"
+    directory: "/"  # Root directory (where package.json is)
+    schedule:
+      interval: "daily"
+    open-pull-requests-limit: 5
+    versioning-strategy: increase
+    labels:
+      - "dependencies"
+      - "npm"
+    reviewers:
+      - "Shadows-Development"  # Add yourself or contributors as reviewers
+    commit-message:
+      prefix: "⬆️ Bump"
+      include: "scope"  # Includes dependency name in commit message
+
+  # 🔒 Check for security updates in GitHub Actions (workflow dependencies)
+  - package-ecosystem: "github-actions"
+    directory: "/"  # Root directory (where workflows are)
+    schedule:
+      interval: "daily"
+    labels:
+      - "security"
+      - "github-actions"
+    commit-message:
+      prefix: "🔄 Update"
+      include: "scope"

package/.github/workflows/pr-checks.yml

@@ -0,0 +1,139 @@
+name: PR Checks
+
+on:
+  pull_request:  # Runs on every commit in an open PR
+
+jobs:
+  build:
+    name: 🏗 Build & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'  # Speeds up installs
+
+      - name: Restore dependency cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+
+      - name: TypeScript type checking
+        run: npm run type-check
+
+      - name: Build project
+        run: npm run build
+
+  lint:
+    name: 🎨 Lint Code
+    runs-on: ubuntu-latest
+    needs: build  # Runs only if "build" passes
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Restore dependency cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+
+      - name: Run ESLint
+        run: npm run lint
+
+  security:
+    name: 🔒 Security Audit
+    runs-on: ubuntu-latest
+    needs: lint  # Runs only if "lint" passes
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Restore dependency cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+
+      - name: Run npm audit
+        run: npm audit --audit-level=high || exit 1
+
+  tests:
+    name: 🧪 Run Tests
+    runs-on: ubuntu-latest
+    needs: security  # Runs only if "security" passes
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Restore dependency cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: |
+            npm-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          else
+            npm install
+          fi
+
+      - name: Run tests
+        run: npm test

package/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - "v*"  # Triggers when you push a tag like "v1.0.0"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          registry-url: "https://registry.npmjs.org/"
+
+      - name: Install Dependencies
+        run: npm install
+
+      - name: Build Package
+        run: npm run build  # Skip if no build step
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/release-please.yml

@@ -0,0 +1,23 @@
+name: Release Please
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v4
+
+      - name: Run Release Please
+        uses: googleapis/release-please-action@v4
+        with:
+          release-type: node

package/.github/workflows/setup-project.yml

@@ -0,0 +1,31 @@
+name: Setup Project
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+
+      - name: Run setup script
+        run: node scripts/setup.js
+
+      - name: Push updated files
+        run: |
+            git config user.name "ShadowBot"
+            git config user.email "bot@shadowdev.local"
+            git remote set-url origin https://x-access-token:${{ secrets.PAT_TOKEN }}@github.com/${{ github.repository }}
+            git add .
+            git commit -m "chore: initialize project metadata from setup script" || echo "No changes"
+            git push

package/.github/workflows/sonarcloud-analysis

@@ -0,0 +1,26 @@
+name: SonarCloud Analysis
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  sonarcloud:
+    name: SonarCloud Scan
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Set up SonarCloud
+        uses: SonarSource/sonarcloud-github-action@v1.1
+
+      - name: Run SonarCloud analysis
+        env:
+          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
+        run: |
+          sonar-scanner

package/LICENSE

@@ -0,0 +1 @@
+MIT License © Shadows Development

package/README.md

@@ -0,0 +1,118 @@
+# ShadowORM
+
+> 🧩 Lightweight, type-safe MySQL ORM for ShadowCore projects.  
+> ShadowORM is built for **modularity**, **security**, and **runtime schema sync** ΓÇö perfect for bots, services, or web apps using ShadowCore.
+
+![npm version](https://img.shields.io/npm/v/@shadow-dev/orm?style=flat-square)
+![license](https://img.shields.io/github/license/Shadows-Development/ShadowORM?style=flat-square)
+
+---
+
+## 🔍 Overview
+
+ShadowORM is a minimalist ORM that offers:
+
+- ✅ **Type-safe models** using generics
+- ✅ **Automatic schema synchronization** (no migration needed)
+- ✅ **JSON + Date normalization**
+- ✅ **Relational support** with foreign keys
+- ✅ **No decorators, no reflection, no magic**
+
+ItΓÇÖs designed to work cleanly alongside ShadowCore but can also be used standalone in any Node.js TypeScript project.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @shadow-dev/orm mysql2
+```
+
+---
+
+## 🛠 Usage Example
+
+```ts
+import { Model, Repository, initDatabase, registerModel } from "@shadow-dev/orm";
+
+const Ticket = new Model<{
+  id: string;
+  type: "support" | "report";
+  data: { message: string };
+  createdAt: Date;
+}>("tickets", {
+  id: "string",
+  type: "string",
+  data: "json",
+  createdAt: "datetime"
+});
+
+initDatabase({
+  host: "localhost",
+  user: "root",
+  password: "password",
+  database: "mydb"
+});
+
+registerModel(Ticket);
+
+// Auto-create table on startup
+await syncSchema();
+
+const tickets = new Repository(Ticket);
+
+
+// Use it
+await tickets.create({
+  id: "ticket-001",
+  type: "support",
+  data: { message: "Help me!" },
+  createdAt: new Date()
+});
+```
+
+---
+
+## 🧠 Schema Types
+
+ShadowORM supports:
+
+| Type                      | SQL Equivalent    |
+|---------------------------|-------------------|
+| `string`                  | `VARCHAR(255)`    |
+| `number`                  | `INT`             |
+| `boolean`                 | `BOOLEAN`         |
+| `json`                    | `LONGTEXT`        |
+| `datetime`                | `DATETIME`        |
+| `FOREIGN_KEY:<tbl.col>`   | Foreign key ref   |
+
+---
+
+## 🧱 Roadmap
+
+- [x] CRUD repository
+- [x] Relational schema support
+- [x] Automatic schema sync
+- [ ] CLI (optional)
+- [ ] Migrations (optional)
+- [ ] Postgres support (maybe)
+
+---
+
+## 📖 Documentation
+
+📚 Docs are coming soon and will be available on the ShadowCore documentation site:  
+➡️ [docs.shadowdevelopment.net](https://docs.shadowdevelopment.net)
+
+---
+
+## 🏢 Project Ownership
+
+ShadowORM is officially developed and maintained under [Shadow Development LLC](https://shadowdevelopment.net).
+
+---
+
+## 📜 License
+
+Licensed under the **GNU General Public License v3.0**  
+See the [LICENSE](LICENSE) file for details.

package/eslint.config.mjs

@@ -0,0 +1,39 @@
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import json from "@eslint/json";
+import { defineConfig, globalIgnores } from "eslint/config";
+
+
+// export default defineConfig([
+//   { files: ["**/*.{js,mjs,cjs,ts}"], plugins: { js }, extends: ["js/recommended"] },
+//   { files: ["**/*.js"], languageOptions: { sourceType: "script" } },
+//   { files: ["**/*.{js,mjs,cjs,ts}"], languageOptions: { globals: {...globals.browser, ...globals.node} } },
+//   tseslint.configs.recommended,
+// ]);
+export default defineConfig([
+  { files: ["**/*.{js,mjs,cjs,ts}"] },
+  {
+    files: ["**/*.{js,mjs,cjs,ts}"],
+    languageOptions: { globals: { ...globals.browser, ...globals.node } },
+  },
+  {
+    files: ["**/*.{js,mjs,cjs,ts}"],
+    plugins: { js },
+    extends: ["js/recommended"],
+  },
+  { files: ["**/*.json"], plugins: { json }, language: "json/json", extends: ["json/recommended"] },
+  tseslint.configs.recommended,
+  {
+    rules: {
+      "@typescript-eslint/explicit-module-boundary-types": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+      "@typescript-eslint/no-require-imports": "off",
+    },
+  },
+  globalIgnores([
+    "node_modules/*", // ignore its content
+    "dist/*",
+      "package-lock.json",
+  ]),
+]);

package/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/tests/**/*.test.ts']
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@shadow-dev/orm",
+  "version": "1.0.0",
+  "description": "Lightweight dynamic MySQL ORM designed for ShadowCore and modular apps.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "lint": "eslint . --ext .ts",
+    "type-check": "tsc --noEmit",
+    "setup": "node scripts/setup.js",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Shadows-Development/ShadowORM.git"
+  },
+  "author": "Shadow Development LLC",
+  "license": "LGPL-3.0-or-later",
+  "keywords": [
+    "orm",
+    "mysql",
+    "typescript",
+    "lightweight",
+    "shadowcore",
+    "shadow-dev"
+  ],
+  "devDependencies": {
+    "@eslint/json": "^0.13.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.38.0",
+    "@typescript-eslint/parser": "^8.38.0",
+    "eslint": "^9.32.0",
+    "jest": "^30.0.5",
+    "ts-jest": "^29.4.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.38.0"
+  },
+  "dependencies": {
+    "mysql2": "^3.14.3"
+  }
+}

package/src/core/Database.ts

@@ -0,0 +1,24 @@
+// Database.ts
+import mysql from "mysql2/promise";
+import { Model } from "./Model";
+
+let pool: mysql.Pool;
+const modelRegistry = new Map<string, Model<any>>();
+
+export function initDatabase(config: mysql.PoolOptions) {
+    pool = mysql.createPool(config);
+}
+
+export function getPool() {
+    if (!pool) throw new Error("Database not initialized");
+    return pool;
+}
+
+// @ts-expect-error wierd generic errors
+export function registerModel<T>(model: Model<T>) {
+    modelRegistry.set(model.name, model);
+}
+
+export function getAllModels() {
+    return modelRegistry;
+}

package/src/core/Model.ts

@@ -0,0 +1,18 @@
+export interface BaseSchema {
+    id: string;
+    data?: any;
+    createdAt: Date;
+}
+
+export interface ForeignKeyDefinition {
+    column: string;
+    reference: string;
+}
+
+export class Model<T extends Partial<BaseSchema> = BaseSchema> {
+    constructor(
+        public readonly name: string,
+        public readonly schema: Record<keyof T, string>,
+        public readonly foreignKeys: ForeignKeyDefinition[] = []
+    ) {}
+}

package/src/core/Repository.ts

@@ -0,0 +1,81 @@
+// Repository.ts
+import { getPool } from "./Database";
+import { Model } from "./Model";
+
+export class Repository<T extends object> {
+    constructor(public readonly model: Model<T>) {}
+
+    async create(data: T): Promise<void> {
+        const keys = Object.keys(data);
+        const sql = `INSERT INTO \`${this.model.name}\` (${keys.join(",")}) VALUES (${keys.map(() => "?").join(",")})`;
+        const values = keys.map((key) => this.normalizeValue((data as any)[key]));
+
+        await getPool().execute(sql, values);
+    }
+
+
+    async find(where: Partial<T> = {}): Promise<T[]> {
+        const { sql, params } = this.buildWhereClause(where);
+        const query = `SELECT * FROM \`${this.model.name}\` ${sql}`;
+        const [rows] = await getPool().execute(query, params.map(this.normalizeValue));
+        return rows as T[];
+    }
+
+    async findOne(where: Partial<T>): Promise<T | null> {
+        const { sql, params } = this.buildWhereClause(where);
+        const query = `SELECT * FROM \`${this.model.name}\` ${sql} LIMIT 1`;
+        const [rows] = await getPool().execute(query, params.map(this.normalizeValue));
+        const results = rows as T[];
+        return results.length > 0 ? results[0] : null;
+    }
+
+    async update(where: Partial<T>, data: Partial<T>): Promise<void> {
+        const setKeys = Object.keys(data);
+        const setClause = setKeys.map(k => `${k} = ?`).join(", ");
+        const setValues = setKeys.map(k => this.normalizeValue((data as any)[k]));
+
+        const { sql: whereClause, params: whereValues } = this.buildWhereClause(where);
+        const query = `UPDATE \`${this.model.name}\` SET ${setClause} ${whereClause}`;
+        await getPool().execute(query, [...setValues, ...whereValues.map(this.normalizeValue)]);
+    }
+
+    async delete(where: Partial<T>): Promise<void> {
+        const { sql, params } = this.buildWhereClause(where);
+        const query = `DELETE FROM \`${this.model.name}\` ${sql}`;
+        await getPool().execute(query, params.map(this.normalizeValue));
+    }
+
+    async count(where: Partial<T> = {}): Promise<number> {
+        const { sql, params } = this.buildWhereClause(where);
+        const query = `SELECT COUNT(*) as count FROM \`${this.model.name}\` ${sql}`;
+        const [rows] = await getPool().execute(query, params.map(this.normalizeValue));
+        return (rows as any[])[0].count || 0;
+    }
+
+    async exists(where: Partial<T>): Promise<boolean> {
+        const count = await this.count(where);
+        return count > 0;
+    }
+
+    private normalizeValue(value: any): any {
+        if (value instanceof Date) {
+            return value.toISOString().slice(0, 19).replace("T", " ");
+        }
+        if (typeof value === "object" && value !== null) {
+            return JSON.stringify(value);
+        }
+        return value ?? null;
+    }
+
+    private buildWhereClause(where: Partial<T>): { sql: string; params: any[] } {
+        const keys = Object.keys(where);
+        if (keys.length === 0) return { sql: "", params: [] };
+
+        const conditions = keys.map(k => `${k} = ?`).join(" AND ");
+        const values = keys.map(k => (where as any)[k]);
+        return {
+            sql: `WHERE ${conditions}`,
+            params: values,
+        };
+    }
+}

package/src/core/index.ts

@@ -0,0 +1,3 @@
+export * from './Model';
+export * from './Repository';
+export * from './Database';

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './core';
+export * from './utils'

package/src/utils/getNextId.ts

@@ -0,0 +1,24 @@
+import { getPool } from "../core";
+
+export async function getNextId(prefix: string): Promise<string> {
+    const pool = getPool();
+
+    await pool.execute(`
+    CREATE TABLE IF NOT EXISTS _id_counters (
+      prefix VARCHAR(255) PRIMARY KEY,
+      count INT NOT NULL
+    )
+  `);
+
+    const [rows] = await pool.query(`SELECT count FROM _id_counters WHERE prefix = ?`, [prefix]);
+    let count = 1;
+
+    if ((rows as any[]).length > 0) {
+        count = (rows as any)[0].count + 1;
+        await pool.execute(`UPDATE _id_counters SET count = ? WHERE prefix = ?`, [count, prefix]);
+    } else {
+        await pool.execute(`INSERT INTO _id_counters (prefix, count) VALUES (?, ?)`, [prefix, count]);
+    }
+
+    return `${prefix}-${String(count).padStart(3, "0")}`;
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './getNextId';
+export * from './syncSchema'

package/src/utils/syncSchema.ts

@@ -0,0 +1,37 @@
+import {getAllModels, getPool} from '../core'
+
+export async function syncSchema() {
+    const models = getAllModels();
+    const pool = getPool();
+
+    for (const [name, model] of models.entries()) {
+        const columns: string[] = [];
+        const foreignKeys: string[] = [];
+
+        for (const [key, type] of Object.entries(model.schema)) {
+            columns.push(`\`${key}\` ${mapType(type)}`);
+        }
+
+        for (const fk of model.foreignKeys) {
+            foreignKeys.push(`FOREIGN KEY (\`${fk.column}\`) REFERENCES ${fk.reference}`);
+        }
+
+        const columnDefs = [...columns, ...foreignKeys].join(",\n  ");
+        const sql = `CREATE TABLE IF NOT EXISTS \`${name}\` (\n  ${columnDefs}\n);`;
+
+        await pool.execute(sql);
+    }
+
+    console.log("✅ Schema synchronized.");
+}
+
+function mapType(type: string): string {
+    switch (type.toLowerCase()) {
+        case "string": return "VARCHAR(255)";
+        case "json": return "JSON";
+        case "datetime": return "DATETIME";
+        case "number": return "INT";
+        case "boolean": return "BOOLEAN";
+        default: return type; // fallback for raw SQL types if provided
+    }
+}

package/tests/sample.test.ts

@@ -0,0 +1,5 @@
+describe("Example test", () => {
+  it("should return true", () => {
+    expect(true).toBe(true);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}