@dbcube/query-builder 5.1.5 → 5.1.6

package/dist/index.cjs

@@ -38,6 +38,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/lib/Database.ts
 var import_fs = __toESM(require("fs"));
+var import_path2 = __toESM(require("path"));
 var import_core2 = require("@dbcube/core");
 
 // src/lib/Trigger.ts
@@ -91,6 +92,7 @@ var Database = class _Database {
   engine;
   computedFields;
   triggers;
+  txId = null;
   constructor(name) {
     this.name = name;
     const engine = new import_core2.QueryEngine(name);
@@ -98,6 +100,54 @@ var Database = class _Database {
     this.computedFields = [];
     this.triggers = [];
   }
+  /**
+   * Executes raw SQL (MySQL/PostgreSQL/SQLite) or a raw command document (MongoDB)
+   * with bound parameters. The escape hatch for anything the builder doesn't cover.
+   *
+   * @example
+   * const rows = await db.raw('SELECT * FROM users WHERE age > ?', [25]);
+   * await db.raw('CREATE INDEX idx_users_email ON users(email)');
+   */
+  async raw(query, params = []) {
+    const response = await this.engine.rawQuery(query, params, this.txId ?? void 0);
+    if (response.status != 200) {
+      returnFormattedError(response.status, response.message);
+      throw new Error(response.message);
+    }
+    return response.data;
+  }
+  /**
+   * Runs a callback inside a database transaction. Everything executed through
+   * the received connection is committed atomically; any thrown error rolls
+   * the whole transaction back.
+   *
+   * Requires daemon mode (enabled by default with an up-to-date query-engine).
+   *
+   * @example
+   * await db.transaction(async (trx) => {
+   *     await trx.table('accounts').where('id', '=', 1).update({ balance: 50 });
+   *     await trx.table('accounts').where('id', '=', 2).update({ balance: 150 });
+   * });
+   */
+  async transaction(callback) {
+    const txId = await this.engine.beginTransaction();
+    const trx = new _Database(this.name);
+    trx.engine = this.engine;
+    trx.computedFields = this.computedFields;
+    trx.triggers = this.triggers;
+    trx.txId = txId;
+    try {
+      const result = await callback(trx);
+      await this.engine.commitTransaction(txId);
+      return result;
+    } catch (error) {
+      try {
+        await this.engine.rollbackTransaction(txId);
+      } catch {
+      }
+      throw error;
+    }
+  }
   async useComputes() {
     const newDatabase = new _Database(this.name);
     const arrayComputedFields = await import_core2.ComputedFieldProcessor.getComputedFields(this.name);
@@ -164,7 +214,7 @@ var Database = class _Database {
    * const columns = await db.table('users').columns().get();
    */
   table(tableName) {
-    return new Table(this, this.name, tableName, this.engine, this.computedFields, this.triggers);
+    return new Table(this, this.name, tableName, this.engine, this.computedFields, this.triggers, this.txId);
   }
   setComputedFields(computedFields) {
     this.computedFields = computedFields;
@@ -180,12 +230,15 @@ var Table = class _Table {
   computedFields = [];
   trigger;
   triggers;
-  constructor(instance, databaseName, tableName, engine = null, computedFields = [], triggers = []) {
+  txId = null;
+  relations = [];
+  constructor(instance, databaseName, tableName, engine = null, computedFields = [], triggers = [], txId = null) {
     this.engine = engine;
     this.computedFields = computedFields;
     this.triggers = triggers;
     this.trigger = new Trigger(instance, databaseName, triggers);
     this.nextType = "AND";
+    this.txId = txId;
     this.dml = {
       type: "select",
       database: databaseName,
@@ -199,7 +252,8 @@ var Table = class _Table {
       limit: null,
       offset: null,
       data: null,
-      aggregation: null
+      aggregation: null,
+      having: []
     };
   }
   /**
@@ -761,6 +815,9 @@ var Table = class _Table {
       clone.dml.data = null;
       clone.dml.aggregation = null;
       const result = await clone.getResponse();
+      if (this.relations.length > 0 && Array.isArray(result)) {
+        return await this.attachRelations(result);
+      }
       return result;
     } catch (error) {
       throw error;
@@ -882,6 +939,310 @@ var Table = class _Table {
     const deleteData = await clone.getResponse(clone.dml, "Delete");
     return deleteData;
   }
+  /**
+   * Adds a WHERE NOT IN condition to the query.
+   *
+   * @example
+   * const users = await db.table('users').whereNotIn('status', ['banned', 'deleted']).get();
+   */
+  whereNotIn(column, values) {
+    const clone = this.clone();
+    if (Array.isArray(values) && values.length > 0) {
+      clone.dml.where.push({
+        column,
+        operator: "NOT IN",
+        value: values,
+        type: clone.nextType,
+        isGroup: false
+      });
+      clone.nextType = "AND";
+    }
+    return clone;
+  }
+  /**
+   * Sets an explicit OFFSET for the query (alternative to page()).
+   *
+   * @example
+   * const rows = await db.table('logs').orderBy('id', 'ASC').limit(50).offset(100).get();
+   */
+  offset(number) {
+    const clone = this.clone();
+    clone.dml.offset = Number(number);
+    return clone;
+  }
+  /**
+   * Appends raw expressions to the SELECT list (aggregates, functions, aliases).
+   * Combine with groupBy() and having() for per-group metrics.
+   *
+   * @example
+   * const stats = await db.table('orders')
+   *     .select(['user_id'])
+   *     .selectRaw(['COUNT(*) AS order_count', 'SUM(amount) AS total'])
+   *     .groupBy('user_id')
+   *     .having('order_count', '>', 5)
+   *     .get();
+   */
+  selectRaw(expressions) {
+    const clone = this.clone();
+    if (clone.dml.columns.length === 1 && clone.dml.columns[0] === "*") {
+      clone.dml.columns = [...expressions];
+    } else {
+      clone.dml.columns = [...clone.dml.columns, ...expressions];
+    }
+    return clone;
+  }
+  /**
+   * Adds a HAVING condition (filters grouped results).
+   *
+   * @example
+   * .groupBy('user_id').having('COUNT(*)', '>', 5)
+   */
+  having(column, operator, value) {
+    const clone = this.clone();
+    clone.dml.having = clone.dml.having ?? [];
+    clone.dml.having.push({
+      column,
+      operator,
+      value,
+      type: "AND",
+      isGroup: false
+    });
+    return clone;
+  }
+  /**
+   * Checks if at least one row matches the current conditions.
+   * Cheaper than first(): selects a constant with LIMIT 1.
+   *
+   * @example
+   * const taken = await db.table('users').where('email', '=', email).exists();
+   */
+  async exists() {
+    const clone = this.clone();
+    clone.dml.type = "select";
+    clone.dml.columns = ["1 AS dbcube_exists"];
+    clone.dml.data = null;
+    clone.dml.aggregation = null;
+    clone.dml.limit = 1;
+    clone.dml.offset = null;
+    const result = await clone.getResponse();
+    return Array.isArray(result) && result.length > 0;
+  }
+  /**
+   * Fetches one page of results plus pagination metadata in a single call.
+   * Runs the page query and the total count with the same conditions.
+   *
+   * @example
+   * const { items, total, totalPages, hasNext } = await db.table('products')
+   *     .where('published', '=', true)
+   *     .orderBy('id', 'ASC')
+   *     .paginate(2, 25);
+   */
+  async paginate(page = 1, perPage = 20) {
+    const pageNum = Math.max(1, Number(page));
+    const size = Math.max(1, Number(perPage));
+    const itemsQuery = this.limit(size).page(pageNum);
+    const [items, total] = await Promise.all([
+      itemsQuery.get(),
+      this.count()
+    ]);
+    const totalNum = Number(total);
+    const totalPages = Math.ceil(totalNum / size);
+    return {
+      items,
+      page: pageNum,
+      perPage: size,
+      total: totalNum,
+      totalPages,
+      hasNext: pageNum < totalPages,
+      hasPrev: pageNum > 1
+    };
+  }
+  /**
+   * Processes all matching rows in batches of `size`, keeping memory flat.
+   * Return `false` from the callback to stop early.
+   *
+   * @example
+   * await db.table('logs').orderBy('id', 'ASC').chunk(500, async (rows) => {
+   *     await processBatch(rows);
+   * });
+   */
+  async chunk(size, callback) {
+    const batchSize = Math.max(1, Number(size));
+    let page = 1;
+    while (true) {
+      const rows = await this.limit(batchSize).page(page).get();
+      if (rows.length === 0) break;
+      const result = await callback(rows, page);
+      if (result === false) break;
+      if (rows.length < batchSize) break;
+      page++;
+    }
+  }
+  /**
+   * Atomically increments a numeric column: `SET col = col + amount`.
+   * Requires at least one WHERE condition. Extra fields can be updated in the same statement.
+   *
+   * @example
+   * await db.table('products').where('id', '=', 5).increment('stock', 3);
+   * await db.table('posts').where('id', '=', 1).increment('views', 1, { last_viewed_at: new Date().toISOString() });
+   */
+  async increment(column, amount = 1, extra = {}) {
+    const clone = this.clone();
+    if (clone.dml.where.length === 0) {
+      throw new Error("You must specify at least one WHERE condition to perform an increment.");
+    }
+    clone.dml.type = "update";
+    clone.dml.data = { ...extra, [column]: { $inc: Number(amount) } };
+    return clone.getResponse();
+  }
+  /**
+   * Atomically decrements a numeric column: `SET col = col - amount`.
+   *
+   * @example
+   * await db.table('products').where('id', '=', 5).decrement('stock', 1);
+   */
+  async decrement(column, amount = 1, extra = {}) {
+    return this.increment(column, -Math.abs(Number(amount)), extra);
+  }
+  /**
+   * Deletes ALL rows from the table. The only write operation allowed
+   * without a WHERE — the destructive intent is explicit in the name.
+   *
+   * @example
+   * await db.table('temp_imports').truncate();
+   */
+  async truncate() {
+    const clone = this.clone();
+    clone.dml.type = "delete";
+    clone.dml.where = [];
+    return clone.getResponse();
+  }
+  /**
+   * Inserts rows, updating them instead when a conflict occurs on the given keys.
+   * MySQL → ON DUPLICATE KEY UPDATE · PostgreSQL/SQLite → ON CONFLICT ... DO UPDATE.
+   *
+   * @param data Rows to insert.
+   * @param conflictKeys Column(s) with the UNIQUE/PK constraint that triggers the update.
+   * @param updateColumns Columns to overwrite on conflict (defaults to every non-conflict column).
+   *
+   * @example
+   * await db.table('settings').upsert(
+   *     [{ key: 'theme', value: 'dark' }],
+   *     ['key']
+   * );
+   */
+  async upsert(data, conflictKeys, updateColumns) {
+    if (!Array.isArray(data) || data.length === 0) {
+      throw new Error("The upsert method requires a non-empty array of objects.");
+    }
+    if (!Array.isArray(conflictKeys) || conflictKeys.length === 0) {
+      throw new Error("The upsert method requires at least one conflict key column.");
+    }
+    const motor = this.engine?.getConfig?.()?.type ?? "mysql";
+    if (motor === "mongodb") {
+      throw new Error("upsert() is not supported for MongoDB yet. Use update() + insert() or raw commands.");
+    }
+    const table = this.dml.table;
+    const columns = Object.keys(data[0]);
+    const targets = updateColumns ?? columns.filter((c) => !conflictKeys.includes(c));
+    const quote = (id) => motor === "mysql" ? `\`${id}\`` : `"${id}"`;
+    const params = [];
+    const placeholder = () => motor === "postgres" || motor === "postgresql" ? `$${params.length}` : "?";
+    const rowsSql = data.map((row) => {
+      const cells = columns.map((col) => {
+        params.push(row[col] === void 0 ? null : row[col]);
+        return placeholder();
+      });
+      return `(${cells.join(", ")})`;
+    }).join(", ");
+    const colsSql = columns.map(quote).join(", ");
+    let sql;
+    if (motor === "mysql") {
+      const updates = targets.map((c) => `${quote(c)} = VALUES(${quote(c)})`).join(", ");
+      sql = `INSERT INTO ${quote(table)} (${colsSql}) VALUES ${rowsSql} ON DUPLICATE KEY UPDATE ${updates}`;
+    } else {
+      const conflict = conflictKeys.map(quote).join(", ");
+      const updates = targets.map((c) => `${quote(c)} = excluded.${quote(c)}`).join(", ");
+      sql = `INSERT INTO ${quote(table)} (${colsSql}) VALUES ${rowsSql} ON CONFLICT (${conflict}) DO UPDATE SET ${updates}`;
+    }
+    const response = await this.engine.rawQuery(sql, params, this.txId ?? void 0);
+    if (response.status != 200) {
+      returnFormattedError(response.status, response.message);
+      throw new Error(response.message);
+    }
+    return response.data;
+  }
+  /**
+   * Declares a relation to eager-load with the results of get().
+   * Relations are resolved from `foreign` definitions in your .cube files,
+   * or explicitly via options. Loads each relation with ONE batched query
+   * (whereIn) — no N+1.
+   *
+   * @example
+   * // hasMany: orders.user_id → users.id (auto-detected from orders.table.cube)
+   * const users = await db.table('users').with('orders').get();
+   * // users[0].orders === [{...}, {...}]
+   *
+   * // belongsTo: posts.author_id → users.id, attached as a single object
+   * const posts = await db.table('posts')
+   *     .with('author', { table: 'users', foreignKey: 'author_id', type: 'one' })
+   *     .get();
+   */
+  with(relation, options = {}) {
+    const clone = this.clone();
+    clone.relations.push({ name: relation, options });
+    return clone;
+  }
+  async attachRelations(rows) {
+    if (rows.length === 0 || this.relations.length === 0) return rows;
+    for (const { name, options } of this.relations) {
+      const relatedTable = options.table ?? name;
+      const cubeMeta = loadCubeRelations();
+      let type = options.type;
+      let foreignKey = options.foreignKey;
+      let localKey = options.localKey ?? "id";
+      if (!foreignKey || !type) {
+        const childFks = cubeMeta[relatedTable]?.foreigns ?? [];
+        const ownFks = cubeMeta[this.dml.table]?.foreigns ?? [];
+        const childToParent = childFks.find((fk) => fk.table === this.dml.table);
+        const parentToChild = ownFks.find((fk) => fk.table === relatedTable);
+        if (childToParent) {
+          type = type ?? "many";
+          foreignKey = foreignKey ?? childToParent.column_name;
+          localKey = options.localKey ?? childToParent.column;
+        } else if (parentToChild) {
+          type = type ?? "one";
+          foreignKey = foreignKey ?? parentToChild.column_name;
+          localKey = options.localKey ?? parentToChild.column;
+        } else {
+          type = type ?? "many";
+          foreignKey = foreignKey ?? `${singularize(this.dml.table)}_id`;
+        }
+      }
+      const relatedQuery = new _Table(this, this.dml.database, relatedTable, this.engine, this.computedFields, this.triggers, this.txId);
+      if (type === "one") {
+        const fkValues = [...new Set(rows.map((r) => r[foreignKey]).filter((v) => v !== null && v !== void 0))];
+        const related = fkValues.length > 0 ? await relatedQuery.whereIn(localKey, fkValues).get() : [];
+        const index = new Map(related.map((r) => [r[localKey], r]));
+        for (const row of rows) {
+          row[name] = index.get(row[foreignKey]) ?? null;
+        }
+      } else {
+        const ids = [...new Set(rows.map((r) => r[localKey]).filter((v) => v !== null && v !== void 0))];
+        const related = ids.length > 0 ? await relatedQuery.whereIn(foreignKey, ids).get() : [];
+        const groups = /* @__PURE__ */ new Map();
+        for (const rel of related) {
+          const key = rel[foreignKey];
+          if (!groups.has(key)) groups.set(key, []);
+          groups.get(key).push(rel);
+        }
+        for (const row of rows) {
+          row[name] = groups.get(row[localKey]) ?? [];
+        }
+      }
+    }
+    return rows;
+  }
   async getResponse(dml = null, type = null) {
     const localDML = dml ? dml : this.dml;
     const computedFieldsNeeded = [];
@@ -911,12 +1272,7 @@ var Table = class _Table {
           const newDML = { ...localDML, data: [data] };
           if (beffore) {
             const interceptor = await this.trigger.execute("before" + type, data);
-            const response = await this.engine.run("query_engine", [
-              "--action",
-              "execute",
-              "--dml",
-              JSON.stringify(newDML)
-            ]);
+            const response = await this.engine.executeDml(newDML, this.txId ?? void 0);
             if (response.status != 200) {
               interceptor.discard();
               returnFormattedError(response.status, response.message);
@@ -925,12 +1281,7 @@ var Table = class _Table {
             arrayResult = response.data;
           }
           if (after) {
-            const response = await this.engine.run("query_engine", [
-              "--action",
-              "execute",
-              "--dml",
-              JSON.stringify(newDML)
-            ]);
+            const response = await this.engine.executeDml(newDML, this.txId ?? void 0);
             if (response.status != 200) {
               returnFormattedError(response.status, response.message);
             }
@@ -939,24 +1290,14 @@ var Table = class _Table {
           }
         }
       } else {
-        const response = await this.engine.run("query_engine", [
-          "--action",
-          "execute",
-          "--dml",
-          JSON.stringify(localDML)
-        ]);
+        const response = await this.engine.executeDml(localDML, this.txId ?? void 0);
         if (response.status != 200) {
           returnFormattedError(response.status, response.message);
         }
         arrayResult = response.data;
       }
     } else {
-      const response = await this.engine.run("query_engine", [
-        "--action",
-        "execute",
-        "--dml",
-        JSON.stringify(localDML)
-      ]);
+      const response = await this.engine.executeDml(localDML, this.txId ?? void 0);
       if (response.status != 200) {
         returnFormattedError(response.status, response.message);
       }
@@ -980,6 +1321,8 @@ var Table = class _Table {
     cloned.computedFields = this.computedFields;
     cloned.trigger = this.trigger;
     cloned.triggers = this.triggers;
+    cloned.txId = this.txId;
+    cloned.relations = [...this.relations];
     cloned.dml = {
       ...this.dml,
       columns: [...this.dml.columns],
@@ -987,6 +1330,7 @@ var Table = class _Table {
       where: [...this.dml.where],
       orderBy: [...this.dml.orderBy],
       groupBy: [...this.dml.groupBy],
+      having: [...this.dml.having ?? []],
       // Clonar propiedades que faltaban para evitar mutación compartida
       data: this.dml.data ? Array.isArray(this.dml.data) ? [...this.dml.data] : { ...this.dml.data } : null,
       aggregation: this.dml.aggregation ? { ...this.dml.aggregation } : null
@@ -994,6 +1338,58 @@ var Table = class _Table {
     return cloned;
   }
 };
+var cubeRelationsCache = null;
+function loadCubeRelations() {
+  if (cubeRelationsCache) return cubeRelationsCache;
+  const result = {};
+  const scanDir = (dir) => {
+    let entries;
+    try {
+      entries = import_fs.default.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = import_path2.default.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name !== "node_modules" && entry.name !== "triggers" && entry.name !== "logs") {
+          scanDir(full);
+        }
+      } else if (entry.name.endsWith(".table.cube")) {
+        try {
+          const content = import_fs.default.readFileSync(full, "utf8");
+          const nameMatch = content.match(/@meta\s*\(\s*\{[\s\S]*?name\s*:\s*"([^"]+)"/);
+          const tableName = nameMatch ? nameMatch[1] : import_path2.default.basename(entry.name, ".table.cube");
+          const foreigns = [];
+          const colRegex = /(\w+)\s*:\s*\{(?:[^{}]|\{[^{}]*\})*?foreign\s*:\s*\{([^}]*)\}/g;
+          let m;
+          while ((m = colRegex.exec(content)) !== null) {
+            const fkTable = m[2].match(/table\s*:\s*"([^"]+)"/);
+            const fkColumn = m[2].match(/column\s*:\s*"([^"]+)"/);
+            if (fkTable) {
+              foreigns.push({
+                column_name: m[1],
+                table: fkTable[1],
+                column: fkColumn ? fkColumn[1] : "id"
+              });
+            }
+          }
+          result[tableName] = { foreigns };
+        } catch {
+        }
+      }
+    }
+  };
+  scanDir(import_path2.default.join(process.cwd(), "dbcube"));
+  cubeRelationsCache = result;
+  return result;
+}
+function singularize(word) {
+  if (word.endsWith("ies")) return word.slice(0, -3) + "y";
+  if (word.endsWith("ses")) return word.slice(0, -2);
+  if (word.endsWith("s") && !word.endsWith("ss")) return word.slice(0, -1);
+  return word;
+}
 function returnFormattedError(status, message) {
   const RESET = "\x1B[0m";
   const RED = "\x1B[31m";