lamix 4.2.9 → 4.2.11

package/README.md

@@ -106,6 +106,185 @@ npm i lamix
 
 npm install mysql2  # or pg or sqlite3
 
-```bash
 # TO See All the Available CLI Commands Run in Terminal
 npx lamix
+
+#Basic CRUD & Query
+
+const User = require('./models/User');
+
+# Create new user
+const user = await User.create({ name: 'Alice', email: 'alice@example.com', password: 'secret' });
+
+# Fill & save (update)
+user.name = 'Alice Smith';  // you can also use user.fill({ name: 'Alice Smith' })
+await user.save();
+
+# Find by primary key
+const user1 = await User.find(1);
+const user2 = await User.findOrFail(param.id);
+
+# Query with where
+const someUsers = await User.where('email', 'alice@example.com').get();
+
+# First match
+const firstUser = await User.where('name', 'Alice').first();
+const firstOrFail = await User.where('name', 'Alice').firstOrFail();
+
+const user = await User.findBy('email', 'jane@example.com');
+# by default Field password is Auto encrypted when creating
+const isValid = await user.checkPassword('user_input_password');
+# Delete (soft delete if enabled)
+await user.delete();
+
+# destroy (delete Multiple ids)
+await user.destroy();
+
+# update (by default)
+await user.update({ body });
+
+# or update
+await user.fill({ body });
+await user.save();
+
+# Restore (if softDeletes enabled)
+await user.restore();
+
+# List all (excluding trashed, by default)
+const allUsers = await User.all();
+
+# Query including soft-deleted (trashed) records
+const withTrashed = await User.withTrashed().where('id', 1).first();
+
+#QueryBuilder Advanced Features
+
+const qb = User.query();
+
+# Select specific columns
+const names = await User.query().select('id', 'name').get();
+
+# Aggregates
+const cnt = await User.query().count();          // count(*)
+const sumId = await User.query().sum('id');
+const avgId = await User.query().avg('id');
+const minId = await User.query().min('id');
+const maxId = await User.query().max('id');
+
+# status a column (returns status of boolean values)
+const usersAll = await User.all();
+const users = await User.query().where('status', true).get();
+const usersorderbyid = await User.query().where('status', true).orderBy('id', 'desc').get();
+const usersorderbycreateAt = await User.query().where('status', true).orderBy('created_at', 'desc').get();
+
+# Pluck a column (returns array of values)
+const Pluckemails = await User.query().pluck('email');
+
+# Pagination
+const page1 = await User.query().paginate(1, 10);
+// page1 = { total, perPage, page, lastPage, data: [users...] }
+
+# Where In
+const usersIn = await User.query().whereIn('id', [1, 2, 3]).get();
+
+// Where Null / Not Null
+const withNull = await User.query().whereNull('deleted_at').get();
+const notNull = await User.query().whereNotNull('deleted_at').get();
+
+# Where Between
+const inRange = await User.query().whereBetween('id', [10, 20]).get();
+
+# Ordering, grouping, having
+const grouped = await User.query()
+  .select('user_id', 'COUNT(*) as cnt')
+  .groupBy('user_id')
+  .having('cnt', '>', 1)
+  .get();
+
+# Joins
+const withPosts = await User.query()
+  .select('users.*', 'posts.title as post_title')
+  .join('INNER', 'posts', 'users.id', '=', 'posts.user_id')
+  .get();
+
+# Using “forUpdate” (locking)
+await User.query().where('id', 5).forUpdate().get();
+
+# Raw queries
+const rows = await User.raw('SELECT * FROM users WHERE id = ?', [5]);
+
+# Caching
+const cachedRows = await User.raw('SELECT * FROM users', []).then(rows => rows);
+const cached = await DB.cached('SELECT * FROM users WHERE id = ?', [5], 60000);
+
+#You can use relations:
+
+const user = await User.find(1);
+const posts = await user.posts().get();  // all posts for the user
+
+# Eager load in a query with Relations:
+const usersWithPosts = await User.query().with('posts').get();
+# Each user will have a `posts` field with array of post models.
+
+# Many-to-many example
+# Suppose you have an intermediate pivot table user_roles (user_id, role_id)
+# and models User and Role, with pivot user_roles.
+#
+
+# Then:
+const user = await User.find(2);
+const roles = await user.roles().get();
+
+# Eager load with Relations:
+const usersWithRoles = await User.query().with('roles').get();
+
+# Eager load with Many to Many Relations:
+const usersWith_Roles_posts_comments = await User.query().with(['roles', 'posts', 'comments' ]).get();
+#OR with Many to Many Relations:
+const users_With_Roles_posts_comments = await User.with(['roles', 'posts', 'comments' ]).get();
+
+# Find by field
+const user = await User.findBy('email', 'jane@example.com');
+
+# Check hashed password
+const isValid = await user.checkPassword('password');
+
+# models/User.js(Example)
+const { BaseModel} = require('lamix');
+
+class User extends BaseModel {
+  static table = 'users';
+  static primaryKey = 'id';
+  static timestamps = true;
+  static softDeletes = false; # Optional if you don't need it
+  static fillable = ['name', 'email', 'password'];  # password is Auto encrypted when creating.
+  static rules = {   # Optional if you don't need it
+    name: 'required|string',
+    email: 'required|email|unique:users,email',
+    password: 'required|string|min:6',
+    phone: 'nullable|phone',
+    status: 'boolean'
+  };
+
+  profile() {
+    const Profile = require('./Profile');
+    return this.hasOne(Profile).onDelete('restrict');
+  }
+
+  
+  // Many-to-many: User ↔ Role via pivot user_roles (user_id, role_id)
+  roles() {
+    const Role = require('./Role');
+    return this.belongsToMany(
+      Role,
+      'user_roles',
+      'user_id',
+      'role_id'
+    ).onDelete('detach');
+  }
+
+  // One-to-many: User -> Post
+  posts() {
+    const Post = require('./Post');
+    return this.hasMany(Post', 'user_id', 'id').onDelete('cascade');
+  }
+}

package/{artisan.js → bin/cli.js}

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 const fs = require('fs');
 const path = require('path');

package/{index.d.ts → lib/index.d.ts}

@@ -7,7 +7,10 @@ export class DB {
     static eventHandlers: {
         query: any[];
         error: any[];
+        reconnect: any[];
     };
+    static _grammar: any;
+    static _als: AsyncLocalStorage<any>;
     static initFromEnv({ driver, config, retryAttempts }?: {
         driver?: string;
         config?: any;
@@ -17,17 +20,22 @@ export class DB {
     static _emit(event: any, payload: any): void;
     static _ensureModule(): any;
     static connect(): Promise<any>;
+    static getConnection(): Promise<any>;
+    static reconnect(): Promise<any>;
     static end(): Promise<void>;
-    static _pgConvert(sql: any, params: any): {
-        text: any;
-        values: any;
-    };
-    static _extractTable(sql: any): string;
-    static _tableExists(table: any): Promise<boolean>;
-    static raw(sql: any, params?: any[], options?: {}): Promise<any>;
+    static run(sql: any, bindings: any, executor: any, { isWrite }?: {
+        isWrite?: boolean;
+    }): Promise<any>;
+    static raw(sql: any, bindings?: any[]): Promise<any>;
+    static affectingStatement(sql: any, bindings?: any[]): Promise<any>;
+    static select(sql: any, bindings?: any[]): Promise<any>;
+    static statement(sql: any, bindings?: any[]): Promise<any>;
+    static insert(sql: any, bindings?: any[]): Promise<any>;
+    static update(sql: any, bindings?: any[]): Promise<any>;
+    static delete(sql: any, bindings?: any[]): Promise<any>;
     static transaction(fn: any): Promise<any>;
     static escapeId(id: any): any;
-    static cached(sql: any, params?: any[], ttl?: number): Promise<any>;
+    static cached(sql: any, bindings?: any[], ttl?: number): Promise<any>;
 }
 export class Model {
     static table: any;
@@ -520,6 +528,7 @@ declare class SimpleCache {
     del(k: any): void;
     clear(): void;
 }
+import { AsyncLocalStorage } from "node:async_hooks";
 declare class HasManyThrough extends Relation {
     constructor(parent: any, relatedClass: any, throughClass: any, firstKey: any, secondKey: any, localKey: any, secondLocalKey: any);
     throughClass: any;

package/{index.js → lib/index.js}

@@ -2,6 +2,7 @@
 
 const util = require('util');
 const { performance } = require('perf_hooks');
+const { AsyncLocalStorage } = require('async_hooks');
 require('dotenv').config();
 
 /* ---------------- Utilities ---------------- */
@@ -10,6 +11,8 @@ function tryRequire(name) {
   try { return require(name); } catch { return null; }
 }
 
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
 /* ---------------- Errors ---------------- */
 
 class DBError extends Error {
@@ -17,6 +20,7 @@ class DBError extends Error {
     super(message);
     this.name = 'DBError';
     this.meta = meta;
+    if (meta.err?.stack) this.stack += `\nCaused by: ${meta.err.stack}`;
   }
 }
 
@@ -33,20 +37,45 @@ class SimpleCache {
     }
     return e.v;
   }
-  set(k, v, ttl = 0) { this.map.set(k, { v, ts: Date.now(), ttl }); }
+  set(k, v, ttl = 0) {
+    this.map.set(k, { v, ts: Date.now(), ttl });
+  }
   del(k) { this.map.delete(k); }
   clear() { this.map.clear(); }
 }
 
+/* ---------------- Grammar ---------------- */
+
+class Grammar {
+  prepare(sql, bindings) {
+    return { sql, bindings };
+  }
+}
+
+class PostgresGrammar extends Grammar {
+  prepare(sql, bindings) {
+    let i = 0;
+    return {
+      sql: sql.replace(/\?/g, () => `$${++i}`),
+      bindings
+    };
+  }
+}
+
 /* ---------------- DB Core ---------------- */
 
 class DB {
   static driver = null;
   static config = null;
   static pool = null;
+
   static cache = new SimpleCache();
   static retryAttempts = 1;
-  static eventHandlers = { query: [], error: [] };
+
+  static eventHandlers = { query: [], error: [], reconnect: [] };
+
+  static _grammar = null;
+  static _als = new AsyncLocalStorage();
 
   /* ---------- Init ---------- */
 
@@ -58,6 +87,9 @@ class DB {
     this.driver = driver.toLowerCase();
     this.retryAttempts = Math.max(1, Number(retryAttempts));
 
+    this._grammar =
+      this.driver === 'pg' ? new PostgresGrammar() : new Grammar();
+
     if (config) {
       this.config = config;
       return;
@@ -128,7 +160,7 @@ class DB {
     throw new DBError(`Unsupported driver: ${this.driver}`);
   }
 
-  /* ---------- Connect ---------- */
+  /* ---------- Connection ---------- */
 
   static async connect() {
     if (this.pool) return this.pool;
@@ -137,26 +169,25 @@ class DB {
 
     if (this.driver === 'mysql') {
       this.pool = driver.createPool(this.config);
-      return this.pool;
     }
 
     if (this.driver === 'pg') {
       const { Pool } = driver;
       this.pool = new Pool(this.config);
-      return this.pool;
     }
 
     if (this.driver === 'sqlite') {
       const db = new driver.Database(this.config.filename);
-
       db.runAsync = util.promisify(db.run.bind(db));
-      db.getAsync = util.promisify(db.get.bind(db));
       db.allAsync = util.promisify(db.all.bind(db));
       db.execAsync = util.promisify(db.exec.bind(db));
 
+      await db.execAsync('PRAGMA journal_mode=WAL');
+      await db.execAsync('PRAGMA busy_timeout=5000');
+
       this.pool = {
         __sqlite_db: db,
-        query: async (sql, params = []) => {
+        async query(sql, params = []) {
           const isSelect = /^\s*(select|pragma)/i.test(sql);
           if (isSelect) return [await db.allAsync(sql, params)];
           const r = await db.runAsync(sql, params);
@@ -164,9 +195,21 @@ class DB {
         },
         close: () => new Promise((r, j) => db.close(e => e ? j(e) : r()))
       };
-
-      return this.pool;
     }
+
+    return this.pool;
+  }
+
+  static async getConnection() {
+    const store = this._als.getStore();
+    if (store?.conn) return store.conn;
+    return this.connect();
+  }
+
+  static async reconnect() {
+    await this.end();
+    this._emit('reconnect', {});
+    return this.connect();
   }
 
   static async end() {
@@ -179,159 +222,130 @@ class DB {
     }
   }
 
-  /* ---------- Query ---------- */
-
-  static _pgConvert(sql, params) {
-    let i = 0;
-    return {
-      text: sql.replace(/\?/g, () => `$${++i}`),
-      values: params
-    };
-  }
-
-  static _extractTable(sql) {
-    if (typeof sql !== 'string') return null;
-
-    const cleaned = sql
-      .replace(/`|"|\[|\]/g, '')
-      .replace(/\s+/g, ' ')
-      .trim()
-      .toLowerCase();
-
-    const match =
-      cleaned.match(/\bfrom\s+([a-z0-9_]+)/) ||
-      cleaned.match(/\binto\s+([a-z0-9_]+)/) ||
-      cleaned.match(/\bupdate\s+([a-z0-9_]+)/);
-
-    return match ? match[1] : null;
-  }
-
-  static async _tableExists(table) {
-    if (!table) return true;
-
-    const pool = await this.connect();
-
-    if (this.driver === 'mysql') {
-      const [rows] = await pool.query(
-        `SELECT 1 FROM information_schema.tables 
-        WHERE table_schema = DATABASE() AND table_name = ? LIMIT 1`,
-        [table]
-      );
-      return rows.length > 0;
-    }
-
-    if (this.driver === 'pg') {
-      const res = await pool.query(
-        `SELECT 1 FROM information_schema.tables 
-        WHERE table_schema = 'public' AND table_name = $1 LIMIT 1`,
-        [table]
-      );
-      return res.rows.length > 0;
-    }
-
-    if (this.driver === 'sqlite') {
-      const [rows] = await pool.query(
-        `SELECT 1 FROM sqlite_master WHERE type='table' AND name=? LIMIT 1`,
-        [table]
-      );
-      return rows.length > 0;
-    }
-
-    return true;
-  }
-
-  static async raw(sql, params = [], options = {}) {
-    const { checkTable = false } = options;
-    if (checkTable) {
-      const table = this._extractTable(sql);
-      if (table) {
-        const exists = await this._tableExists(table);
-        if (!exists) {
-          throw new DBError(`Table does not exist: ${table}`, { sql });
-        }
-      }
-    }
+  /* ---------- Core Runner ---------- */
 
+  static async run(sql, bindings, executor, { isWrite = false } = {}) {
     let attempt = 0;
 
     while (++attempt <= this.retryAttempts) {
-      const pool = await this.connect();
       const start = performance.now();
 
       try {
-        this._emit('query', { sql, params });
-
-        if (this.driver === 'pg') {
-          const q = this._pgConvert(sql, params);
-          const r = await pool.query(q.text, q.values);
-          return r.rows;
-        }
-
-        const [rows] = await pool.query(sql, params);
-        return rows;
-
+        const result = await executor();
+        this._emit('query', {
+          sql,
+          bindings,
+          time: performance.now() - start,
+          driver: this.driver
+        });
+        return result;
       } catch (err) {
-        this._emit('error', { err, sql, params, attempt });
-
-        if (attempt < this.retryAttempts &&
-            /dead|lost|timeout|reset/i.test(err.message)) {
-          await this.end();
-          await new Promise(r => setTimeout(r, 100 * attempt));
+        this._emit('error', { err, sql, bindings, attempt });
+
+        const canRetry =
+          !isWrite ||
+          this._als.getStore()?.inTransaction;
+
+        if (
+          canRetry &&
+          attempt < this.retryAttempts &&
+          /dead|lost|timeout|reset|closed/i.test(err.message)
+        ) {
+          await this.reconnect();
+          await sleep(100 * attempt);
           continue;
         }
 
-        throw new DBError('DB raw() failed', { sql, params, err });
+        throw new DBError('DB query failed', { sql, bindings, err });
       }
     }
   }
 
+  /* ---------- Queries ---------- */
+
+  static async raw(sql, bindings = []) {
+    const pool = await this.getConnection();
+    const prepared = this._grammar.prepare(sql, bindings);
+
+    return this.run(sql, bindings, async () => {
+      if (this.driver === 'pg') {
+        const r = await pool.query(prepared.sql, prepared.bindings);
+        return r.rows;
+      }
+      const [rows] = await pool.query(prepared.sql, prepared.bindings);
+      return rows;
+    });
+  }
+
+  static async affectingStatement(sql, bindings = []) {
+    const pool = await this.getConnection();
+    const prepared = this._grammar.prepare(sql, bindings);
+
+    return this.run(sql, bindings, async () => {
+      if (this.driver === 'pg') {
+        const r = await pool.query(prepared.sql, prepared.bindings);
+        return { affectedRows: r.rowCount };
+      }
+      const [r] = await pool.query(prepared.sql, prepared.bindings);
+      return r;
+    }, { isWrite: true });
+  }
+
+  static select(sql, bindings = []) { return this.raw(sql, bindings); }
+  static statement(sql, bindings = []) { return this.affectingStatement(sql, bindings); }
+  static insert(sql, bindings = []) {
+    return this.affectingStatement(sql, bindings)
+      .then(r => r.insertId ?? true);
+  }
+  static update(sql, bindings = []) {
+    return this.affectingStatement(sql, bindings)
+      .then(r => r.affectedRows ?? 0);
+  }
+  static delete(sql, bindings = []) { return this.update(sql, bindings); }
+
   /* ---------- Transactions ---------- */
 
   static async transaction(fn) {
     const pool = await this.connect();
 
-    if (this.driver === 'mysql') {
-      const c = await pool.getConnection();
-      try {
-        await c.beginTransaction();
-        const r = await fn(c);
-        await c.commit();
-        return r;
-      } catch (e) {
-        await c.rollback();
-        throw e;
-      } finally {
-        c.release();
-      }
-    }
+    return this._als.run({ inTransaction: true }, async () => {
+      let conn;
 
-    if (this.driver === 'pg') {
-      const c = await pool.connect();
       try {
-        await c.query('BEGIN');
-        const r = await fn(c);
-        await c.query('COMMIT');
-        return r;
-      } catch (e) {
-        await c.query('ROLLBACK');
-        throw e;
-      } finally {
-        c.release();
-      }
-    }
+        if (this.driver === 'mysql') {
+          conn = await pool.getConnection();
+          await conn.beginTransaction();
+          this._als.getStore().conn = conn;
+          const r = await fn(conn);
+          await conn.commit();
+          return r;
+        }
 
-    if (this.driver === 'sqlite') {
-      const db = pool.__sqlite_db;
-      try {
-        await db.execAsync('BEGIN');
-        const r = await fn(pool);
-        await db.execAsync('COMMIT');
-        return r;
+        if (this.driver === 'pg') {
+          conn = await pool.connect();
+          await conn.query('BEGIN');
+          this._als.getStore().conn = conn;
+          const r = await fn(conn);
+          await conn.query('COMMIT');
+          return r;
+        }
+
+        if (this.driver === 'sqlite') {
+          await pool.__sqlite_db.execAsync('BEGIN');
+          this._als.getStore().conn = pool;
+          const r = await fn(pool);
+          await pool.__sqlite_db.execAsync('COMMIT');
+          return r;
+        }
       } catch (e) {
-        await db.execAsync('ROLLBACK');
+        try {
+          await conn?.query?.('ROLLBACK');
+        } catch {}
         throw e;
+      } finally {
+        conn?.release?.();
       }
-    }
+    });
   }
 
   /* ---------- Helpers ---------- */
@@ -344,11 +358,11 @@ class DB {
       : `\`${id.replace(/`/g, '``')}\``;
   }
 
-  static async cached(sql, params = [], ttl = 0) {
-    const key = JSON.stringify([sql, params]);
+  static async cached(sql, bindings = [], ttl = 0) {
+    const key = JSON.stringify([sql, bindings]);
     const hit = this.cache.get(key);
     if (hit) return hit;
-    const rows = await this.raw(sql, params);
+    const rows = await this.raw(sql, bindings);
     this.cache.set(key, rows, ttl);
     return rows;
   }
@@ -356,6 +370,7 @@ class DB {
 
 const escapeId = s => DB.escapeId(s);
 
+
 // -----------------------------
 // MAIN Validator
 // -----------------------------

package/package.json

@@ -1,21 +1,17 @@
 {
   "name": "lamix",
-  "version": "4.2.9",
+  "version": "4.2.11",
   "description": "lamix - ORM for Node-express js",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "main": "./lib",
   "exports": {
     ".": {
-      "import": "./index.js",
-      "require": "./index.js",
-      "types": "./index.d.ts"
+      "require": "./lib/index.js",
+      "types": "./lib/index.d.ts"
     }
   },
   "files": [
-    "index.js",
-    "index.d.ts",
-    "artisan.js",
-    "artisan.d.ts",
+    "lib",
+    "bin",
     "README.md",
     "examples"
   ],
@@ -24,7 +20,7 @@
     "url": "https://github.com/andrewkhabweri-spec/lamix.git"
   },
   "bin": {
-    "lamix": "./artisan.js"
+    "lamix": "./bin/cli.js"
   },
   "scripts": {
     "build": "tsc && echo 'Build complete'"
@@ -43,21 +39,14 @@
     "orm",
     "nodejs",
     "database",
-    "laravel-inspired"
+    "sql"
   ],
   "author": {
     "name": "Andrew Khabweri",
     "email": "andrewkhabweri@gmail.com"
   },
-  "tsdown": {
-    "entry": [
-      "index.d.ts"
-    ],
-    "outDir": ".",
-    "clean": true,
-    "dts": true,
-    "sourcemaps": true,
-    "theme": "default"
-  },
-  "license": "MIT"
+  "license": "MIT",
+  "engines": {
+    "node": ">= 0.8.0"
+  }
 }