free-framework 4.4.0

package/database/orm.js

@@ -0,0 +1,379 @@
+/**
+ * database/orm.js
+ * Production-grade Active Record ORM powered by Knex.
+ * Supports: SQLite, PostgreSQL, MySQL.
+ * Features: Relations, Transactions, Pagination, Eager Loading, Soft Deletes.
+ */
+
+const knex = require('knex');
+const path = require('path');
+const fs = require('fs');
+
+// Extend Knex QueryBuilder with .get() for Laravel-like syntax
+const tempKnex = knex({ client: 'sqlite3' });
+const KnexQueryBuilder = tempKnex.queryBuilder().constructor;
+KnexQueryBuilder.prototype.get = function () {
+    return this.select();
+};
+class ORM {
+    static connect() {
+        if (!this.db) {
+            const client = process.env.DB_CLIENT || 'mysql2';
+            let connection = {};
+
+            if (client === 'mysql2' || client === 'pg') {
+                connection = {
+                    host: process.env.DB_HOST || '127.0.0.1',
+                    port: process.env.DB_PORT || (client === 'pg' ? 5432 : 3306),
+                    user: process.env.DB_USER || (client === 'pg' ? 'postgres' : 'root'),
+                    password: process.env.DB_PASS || '',
+                    database: process.env.DB_NAME || 'free_db',
+                };
+                if (client === 'pg' && process.env.DB_SSL === 'true') {
+                    connection.ssl = { rejectUnauthorized: false };
+                }
+            } else {
+                // SQLite fallback
+                const dbPath = process.env.DB_PATH || 'database.sqlite';
+                const fullPath = path.isAbsolute(dbPath) ? dbPath : path.join(process.cwd(), dbPath);
+                connection = { filename: fullPath };
+
+                const dbDir = path.dirname(fullPath);
+                if (!fs.existsSync(dbDir)) {
+                    fs.mkdirSync(dbDir, { recursive: true });
+                }
+            }
+
+            this.db = knex({
+                client,
+                connection,
+                useNullAsDefault: client === 'sqlite3',
+                acquireConnectionTimeout: 10000,
+                pool: {
+                    min: parseInt(process.env.DB_POOL_MIN || '0'),
+                    max: parseInt(process.env.DB_POOL_MAX || '10'),
+                }
+            });
+
+            console.log(`🗄️  ORM connected. Driver: ${client} (Pool: ${process.env.DB_POOL_MIN || 0}-${process.env.DB_POOL_MAX || 10})`);
+        }
+        return this.db;
+    }
+
+    /**
+     * Auto-migrate all registered models.
+     * Supports: string, number, boolean, text, float, json fields.
+     * Supports: index declarations.
+     */
+    static async migrate(models) {
+        const db = this.connect();
+
+        try {
+            for (const [name, model] of Object.entries(models)) {
+                const tableName = name.toLowerCase() + 's';
+                const exists = await db.schema.hasTable(tableName);
+
+                if (!exists) {
+                    await db.schema.createTable(tableName, table => {
+                        table.increments('id').primary();
+
+                        if (model.fields) {
+                            model.fields.forEach(field => {
+                                if (!field.name || field.name === 'id' || field.name === 'created_at' || field.name === 'updated_at' || field.name === 'timestamps' || field.type === '}' || field.name === '}') return;
+                                let col;
+                                if (field.type === 'string') col = table.string(field.name);
+                                else if (field.type === 'integer') col = table.integer(field.name);
+                                else if (field.type === 'number') col = table.integer(field.name).defaultTo(0);
+                                else if (field.type === 'boolean') col = table.boolean(field.name).defaultTo(false);
+                                else if (field.type === 'text') col = table.text(field.name);
+                                else if (field.type === 'float') col = table.float(field.name).defaultTo(0);
+                                else if (field.type === 'json') col = table.json(field.name);
+                                else if (field.type === 'datetime') col = table.timestamp(field.name);
+                                else col = table.string(field.name);
+
+                                if (field.unique) col.unique();
+                                if (field.index) col.index();
+                                if (field.default !== undefined) col.defaultTo(field.default);
+                            });
+                        }
+
+                        if (model.softDeletes) {
+                            table.timestamp('deleted_at').nullable();
+                        }
+
+                        table.timestamps(true, true);
+                    });
+
+                    if (model.indexes && model.indexes.length > 0) {
+                        await db.schema.table(tableName, table => {
+                            model.indexes.forEach(field => {
+                                table.index(field, `idx_${tableName}_${field}`);
+                            });
+                        });
+                        console.log(`🔍 Indexed: ${tableName} → [${model.indexes.join(', ')}]`);
+                    }
+
+                    console.log(`📦 Migrated: ${tableName}`);
+                }
+            }
+        } catch (err) {
+            console.error('❌ Migration Error:', err);
+            throw err;
+        }
+    }
+
+    /**
+     * Execute operations inside a single DB transaction.
+     * Auto-rollback on error.
+     */
+    static async transaction(callback) {
+        const db = this.connect();
+        return db.transaction(callback);
+    }
+}
+
+
+
+/**
+ * Base Model class with full Active Record methods.
+ */
+class Model {
+    static table = null;
+    static fields = [];
+
+    static _tableName() {
+        return this.table || (this.name.toLowerCase() + 's');
+    }
+
+    static _db() {
+        return ORM.connect();
+    }
+
+    // ── Query Builders ───────────────────────────────────────────────────────
+
+    static query() {
+        return this._db()(this._tableName());
+    }
+
+    static all() {
+        return this.query();
+    }
+
+    static async find(id) {
+        return this._db()(this._tableName()).where({ id }).first();
+    }
+
+    static where(column, value) {
+        if (typeof column === 'object') {
+            return this._db()(this._tableName()).where(column);
+        }
+        return this._db()(this._tableName()).where(column, value);
+    }
+
+    static first(conditions) {
+        return this._db()(this._tableName()).where(conditions || {}).first();
+    }
+
+    /**
+     * Paginate results.
+     * @param {number} page  - 1-based page number
+     * @param {number} limit - records per page
+     * @returns {{ data, total, page, lastPage }}
+     */
+    static async paginate(page = 1, limit = 20) {
+        const offset = (page - 1) * limit;
+        const db = this._db();
+        const tableName = this._tableName();
+
+        const [{ total }] = await db(tableName).count('id as total');
+        const data = await db(tableName).limit(limit).offset(offset);
+
+        return {
+            data,
+            total: Number(total),
+            page,
+            limit,
+            lastPage: Math.ceil(Number(total) / limit),
+        };
+    }
+
+    // ── Mutations ────────────────────────────────────────────────────────────
+
+    static async create(attributes) {
+        const [id] = await this._db()(this._tableName()).insert(attributes);
+        return this.find(id);
+    }
+
+    static async update(id, attributes) {
+        await this._db()(this._tableName()).where({ id }).update(attributes);
+        return this.find(id);
+    }
+
+    static async delete(id) {
+        return this._db()(this._tableName()).where({ id }).del();
+    }
+
+    /**
+     * hasMany relation.
+     * e.g. User.hasMany(Post, 'authorId', userId)
+     */
+    static async hasMany(RelatedModel, foreignKey, id) {
+        return ORM.connect()(RelatedModel._tableName()).where({ [foreignKey]: id });
+    }
+
+    /**
+     * belongsTo relation.
+     * e.g. Post.belongsTo(User, 'authorId', post.authorId)
+     */
+    static async belongsTo(ParentModel, foreignKey, foreignId) {
+        return ORM.connect()(ParentModel._tableName()).where({ id: foreignId }).first();
+    }
+
+    // ── Eager Loading ─────────────────────────────────────────────────────────
+
+    /**
+     * Fluent eager loading builder.
+     * @param {string | string[]} relations - e.g. "author" or ["author", "comments"]
+     * @returns {EagerBuilder}
+     */
+    static with(relations) {
+        return new EagerBuilder(this, Array.isArray(relations) ? relations : [relations]);
+    }
+
+    // ── Soft Deletes ──────────────────────────────────────────────────────────
+
+    static softDeletes = false;
+
+    /** Soft-delete: sets deleted_at timestamp instead of removing row. */
+    static async softDelete(id) {
+        return this._db()(this._tableName()).where({ id }).update({ deleted_at: new Date().toISOString() });
+    }
+
+    /** Restore a soft-deleted record. */
+    static async restore(id) {
+        return this._db()(this._tableName()).where({ id }).update({ deleted_at: null });
+    }
+
+    /** Query including soft-deleted rows. */
+    static withTrashed() {
+        return this._db()(this._tableName());
+    }
+
+    /** Query only soft-deleted rows. */
+    static onlyTrashed() {
+        return this._db()(this._tableName()).whereNotNull('deleted_at');
+    }
+
+    /** Override all() to exclude soft-deleted by default. */
+    static all() {
+        if (this.softDeletes) {
+            return this._db()(this._tableName()).whereNull('deleted_at');
+        }
+        return this._db()(this._tableName());
+    }
+}
+
+// ── EagerBuilder ──────────────────────────────────────────────────────────────
+
+/**
+ * Fluent builder for eager-loading relations.
+ * Registered via Model.with("relation") 
+ * Relations must be declared as static properties on the model:
+ *   static relations = { author: { model: User, foreignKey: 'authorId', type: 'belongsTo' } }
+ */
+class EagerBuilder {
+    constructor(ModelClass, relations) {
+        this.ModelClass = ModelClass;
+        this.relations = relations;
+        this._query = ModelClass._db()(ModelClass._tableName());
+    }
+
+    where(column, value) {
+        if (typeof column === 'object') {
+            this._query = this._query.where(column);
+        } else {
+            this._query = this._query.where(column, value);
+        }
+        return this;
+    }
+    limit(n) { this._query = this._query.limit(n); return this; }
+    offset(n) { this._query = this._query.offset(n); return this; }
+
+    async get() {
+        if (this.ModelClass.softDeletes) this._query = this._query.whereNull('deleted_at');
+        const rows = await this._query;
+        return this._loadRelations(rows);
+    }
+
+    async first() {
+        const rows = await this.get();
+        return rows[0] || null;
+    }
+
+    async paginate(page = 1, limit = 20) {
+        const offset = (page - 1) * limit;
+        this.limit(limit).offset(offset);
+        const data = await this.get();
+        const [{ total }] = await this.ModelClass._db()(this.ModelClass._tableName()).count('id as total');
+        return { data, total: Number(total), page, lastPage: Math.ceil(Number(total) / limit) };
+    }
+
+    async _loadRelations(rows) {
+        if (!rows || rows.length === 0) return rows;
+        const declared = this.ModelClass.relations || {};
+
+        // Group nested relations by their top-level key
+        // e.g. ["author.profile", "comments"] -> { author: ["profile"], comments: [] }
+        const groups = {};
+        for (const rel of this.relations) {
+            const [top, ...rest] = rel.split('.');
+            if (!groups[top]) groups[top] = [];
+            if (rest.length > 0) groups[top].push(rest.join('.'));
+        }
+
+        for (const [rel, nested] of Object.entries(groups)) {
+            const def = declared[rel];
+            if (!def) { console.warn(`[ORM] Unknown relation "${rel}" on ${this.ModelClass.name}`); continue; }
+            const { model: RelModel, foreignKey, type } = def;
+
+            if (type === 'hasMany') {
+                const ids = rows.map(r => r.id);
+                let query = RelModel.query().whereIn(foreignKey, ids);
+
+                // If nested relations exist, use with() on the related models
+                let related;
+                if (nested.length > 0) {
+                    related = await RelModel.with(nested).whereIn(foreignKey, ids).get();
+                } else {
+                    related = await query;
+                }
+
+                for (const row of rows) {
+                    row[rel] = related.filter(r => r[foreignKey] === row.id);
+                }
+            } else if (type === 'belongsTo') {
+                const ids = [...new Set(rows.map(r => r[foreignKey]).filter(Boolean))];
+                if (ids.length === 0) {
+                    rows.forEach(r => r[rel] = null);
+                    continue;
+                }
+
+                let related;
+                if (nested.length > 0) {
+                    related = await RelModel.with(nested).whereIn('id', ids).get();
+                } else {
+                    related = await RelModel.query().whereIn('id', ids);
+                }
+
+                const map = Object.fromEntries(related.map(r => [r.id, r]));
+                for (const row of rows) {
+                    row[rel] = map[row[foreignKey]] || null;
+                }
+            }
+        }
+        return rows;
+    }
+}
+
+module.exports = { ORM, Model, EagerBuilder };
+

package/database/query-builder.js

@@ -0,0 +1,179 @@
+/**
+ * database/query-builder.js
+ * Fluent Query Builder for Free Framework ORM.
+ * Chainable API: Model.query().where("likes",">",10).orderBy("created_at","desc").limit(20).get()
+ */
+
+class QueryBuilder {
+    constructor(db, tableName) {
+        this._db = db;
+        this._table = tableName;
+        this._query = db(tableName);
+        this._eagerRelations = [];
+        this._ModelClass = null;
+    }
+
+    // ── Conditions ───────────────────────────────────────────────────────────
+
+    /**
+     * Add a WHERE clause.
+     * @param {string} column
+     * @param {string} [op]   - operator: "=", ">", "<", ">=", "<=", "!=", "like", "in"
+     * @param {*}      value
+     *
+     * Usage:
+     *   .where("name", "Omar")          → WHERE name = 'Omar'
+     *   .where("likes", ">", 10)        → WHERE likes > 10
+     *   .where("title", "like", "%hi%") → WHERE title LIKE '%hi%'
+     */
+    where(column, opOrValue, value) {
+        if (value === undefined) {
+            // Two-arg form: where("name", "Omar")
+            this._query = this._query.where(column, opOrValue);
+        } else {
+            const op = opOrValue.toLowerCase();
+            if (op === 'like') {
+                this._query = this._query.whereLike(column, value);
+            } else if (op === 'in') {
+                this._query = this._query.whereIn(column, value);
+            } else if (op === 'not in') {
+                this._query = this._query.whereNotIn(column, value);
+            } else {
+                this._query = this._query.where(column, opOrValue, value);
+            }
+        }
+        return this;
+    }
+
+    whereNull(column) { this._query = this._query.whereNull(column); return this; }
+    whereNotNull(column) { this._query = this._query.whereNotNull(column); return this; }
+    whereIn(col, arr) { this._query = this._query.whereIn(col, arr); return this; }
+
+    orWhere(column, opOrValue, value) {
+        if (value === undefined) {
+            this._query = this._query.orWhere(column, opOrValue);
+        } else {
+            this._query = this._query.orWhere(column, opOrValue, value);
+        }
+        return this;
+    }
+
+    // ── Ordering & Limiting ──────────────────────────────────────────────────
+
+    orderBy(column, direction = 'asc') {
+        this._query = this._query.orderBy(column, direction);
+        return this;
+    }
+
+    limit(n) { this._query = this._query.limit(n); return this; }
+    offset(n) { this._query = this._query.offset(n); return this; }
+
+    // ── Selection ────────────────────────────────────────────────────────────
+
+    select(...columns) {
+        this._query = this._query.select(...columns);
+        return this;
+    }
+
+    // ── Aggregates ───────────────────────────────────────────────────────────
+
+    async count(col = 'id') {
+        const [{ total }] = await this._db(this._table).count(`${col} as total`);
+        return Number(total);
+    }
+
+    async sum(col) {
+        const [{ s }] = await this._query.clone().sum(`${col} as s`);
+        return Number(s) || 0;
+    }
+
+    async avg(col) {
+        const [{ a }] = await this._query.clone().avg(`${col} as a`);
+        return Number(a) || 0;
+    }
+
+    async max(col) {
+        const [{ m }] = await this._query.clone().max(`${col} as m`);
+        return m;
+    }
+
+    async min(col) {
+        const [{ m }] = await this._query.clone().min(`${col} as m`);
+        return m;
+    }
+
+    // ── Eager Loading ─────────────────────────────────────────────────────────
+
+    with(relations) {
+        const arr = Array.isArray(relations) ? relations : [relations];
+        this._eagerRelations = this._eagerRelations.concat(arr);
+        return this;
+    }
+
+    // ── Execution ─────────────────────────────────────────────────────────────
+
+    async get() {
+        const rows = await this._query;
+        if (this._eagerRelations.length > 0 && this._ModelClass) {
+            return this._loadEager(rows);
+        }
+        return rows;
+    }
+
+    async first() {
+        this._query = this._query.first();
+        return this._query;
+    }
+
+    async pluck(column) {
+        const rows = await this._query.select(column);
+        return rows.map(r => r[column]);
+    }
+
+    async paginate(page = 1, perPage = 20) {
+        const total = await this.count();
+        const offset = (page - 1) * perPage;
+        const data = await this._db(this._table).limit(perPage).offset(offset);
+        return {
+            data,
+            total,
+            page,
+            perPage,
+            lastPage: Math.ceil(total / perPage),
+            hasNext: page < Math.ceil(total / perPage),
+        };
+    }
+
+    then(resolve, reject) {
+        return this._query.then(resolve, reject);
+    }
+
+    async _loadEager(rows) {
+        if (!this._ModelClass || !this._ModelClass.relations) return rows;
+        const declared = this._ModelClass.relations;
+
+        for (const rel of this._eagerRelations) {
+            const def = declared[rel];
+            if (!def) continue;
+            const { model: RelModel, foreignKey, type } = def;
+
+            if (type === 'hasMany') {
+                const ids = rows.map(r => r.id);
+                const related = await this._db(RelModel._tableName()).whereIn(foreignKey, ids);
+                for (const row of rows) {
+                    row[rel] = related.filter(r => r[foreignKey] === row.id);
+                }
+            } else if (type === 'belongsTo') {
+                const ids = [...new Set(rows.map(r => r[foreignKey]).filter(Boolean))];
+                const related = await this._db(RelModel._tableName()).whereIn('id', ids);
+                const map = Object.fromEntries(related.map(r => [r.id, r]));
+                for (const row of rows) {
+                    row[rel] = map[row[foreignKey]] || null;
+                }
+            }
+        }
+        return rows;
+    }
+}
+
+module.exports = { QueryBuilder };

package/index.js

@@ -0,0 +1,51 @@
+/**
+ * index.js
+ * Public API entry point for the Free Framework NPM package.
+ * Exports all primary runtime, compiler, database, and plugin modules.
+ */
+
+// Core Runtime
+const { FreeServer } = require('./runtime/server');
+const { ClusterManager } = require('./runtime/cluster');
+const { EdgeRuntime } = require('./runtime/edge');
+
+// Compiler
+const { tokenize } = require('./compiler/lexer');
+const { parse } = require('./compiler/parser');
+const { generate } = require('./compiler/generator');
+
+// Database
+const { Model } = require('./database/model');
+const { ORM } = require('./database/orm');
+
+// Built-in Plugins
+const AuthPlugin = require('./plugins/auth');
+const UploadPlugin = require('./plugins/upload');
+const ChatPlugin = require('./plugins/chat');
+
+// Utils
+const logger = require('./utils/logger');
+
+module.exports = {
+    // Core
+    FreeServer,
+    ClusterManager,
+    EdgeRuntime,
+
+    // Compiler
+    tokenize,
+    parse,
+    generate,
+
+    // Database
+    Model,
+    ORM,
+
+    // Plugins
+    AuthPlugin,
+    UploadPlugin,
+    ChatPlugin,
+
+    // Utils
+    logger,
+};

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "free-framework",
+  "version": "4.4.0",
+  "description": "Professional Node.js engine for the .free language. Blazing-fast SSR, Islands Architecture, and built-in ORM.",
+  "main": "index.js",
+  "bin": {
+    "free": "bin/free.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "dev": "node bin/free.js serve",
+    "build": "node bin/free.js build",
+    "doctor": "node bin/free.js doctor"
+  },
+  "keywords": [
+    "framework",
+    "web",
+    "full-stack",
+    "free",
+    "freejs",
+    "free-framework",
+    "hyper-express",
+    "compiler",
+    "ssr",
+    "islands-architecture"
+  ],
+  "author": "Dev Omar Tolba",
+  "homepage": "https://github.com/dev-omartolba",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dev-omartolba/free-framework.git"
+  },
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "cli/",
+    "compiler/",
+    "database/",
+    "plugins/",
+    "router/",
+    "runtime/",
+    "template-engine/",
+    "templates/",
+    "utils/",
+    "index.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "bcrypt": "^6.0.0",
+    "chalk": "^5.6.2",
+    "chokidar": "^5.0.0",
+    "clean-css": "^5.3.3",
+    "commander": "^14.0.3",
+    "cookie": "^1.1.1",
+    "dotenv": "^17.3.1",
+    "esbuild": "^0.27.3",
+    "express": "^5.2.1",
+    "fast-json-stringify": "^6.3.0",
+    "fastify": "^5.8.2",
+    "fs-extra": "^11.3.4",
+    "html-minifier-terser": "^7.2.0",
+    "hyper-express": "^6.17.3",
+    "jsonwebtoken": "^9.0.3",
+    "knex": "^3.1.0",
+    "live-directory": "^3.0.3",
+    "lru-cache": "^11.2.6",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3",
+    "sqlite3": "^5.1.7",
+    "uWebSockets.js": "github:uNetworking/uWebSockets.js#v20.55.0"
+  },
+  "devDependencies": {
+    "vitest": "^3.0.0"
+  }
+}