@axiosleo/orm-mysql 0.15.0 → 0.15.1

package/README.md

@@ -15,48 +15,8 @@ npm install @axiosleo/orm-mysql
 
 ## Usage
 
-### Create MySQL client
-
-```javascript
-const { createClient } = require("@axiosleo/orm-mysql");
-
-const client = createClient({
-  host: process.env.MYSQL_HOST,
-  port: process.env.MYSQL_PORT,
-  user: process.env.MYSQL_USER,
-  password: process.env.MYSQL_PASS,
-  database: process.env.MYSQL_DB,
-});
-```
-
-### Initialize database handler
-
-```javascript
-const { QueryHandler } = require("@axiosleo/orm-mysql");
-
-const db = new QueryHandler(client);
-```
-
-### Initialize query
-
 ```javascript
-const query = db.table('<table-name>');
-
-query.attr("id", "name", "age"); // set attributes
-query.where("name", "Joe");      // set where condition
-query.orWhere("age", ">", 18);   // set or where condition
-query.andWhere("age", "<", 30);  // set and where condition
-query.orderBy("age", "desc");    // set order by
-query.limit(10);                 // set limit
-query.offset(0);                 // set offset
-
-let rows = await query.select(); // select
-```
-
-### Some Query Examples
-
-```javascript
-const { createClient, QueryHandler, Query } = require("@axiosleo/orm-mysql");
+const { createClient, QueryHandler } = require("@axiosleo/orm-mysql");
 
 const conn = createClient({
   host: process.env.MYSQL_HOST,
@@ -66,416 +26,54 @@ const conn = createClient({
   database: process.env.MYSQL_DB,
 });
 
-const hanlder = new QueryHandler(conn);
-
-async function selectExample() {
-  const query = handler.table("users"); // init QueryOperator by table name
-
-  query.attr("id", "name", "age"); // set attributes
-  query.where("name", "Joe");      // set where condition
-  query.orWhere("age", ">", 18);   // set or where condition
-  query.andWhere("age", "<", 30);  // set and where condition
-  query.orderBy("age", "desc");    // set order by
-  query.limit(10);                 // set limit
-  query.offset(0);                 // set offset
+const db = new QueryHandler(conn);
 
-  let rows = await query.select(); // select
-}
-
-async function findExample() {
-  const query = handler.table("users"); // init QueryOperator by table name
-
-  query.attr("id", "name", "age");      // set attributes
-  query.where("name", "Joe");           // set where condition
-  query.orWhere("age", ">", 18);        // set or where condition
-  query.andWhere("age", "<", 30);       // set and where condition
-  query.orderBy("age", "desc");         // set order by
-  // query.limit(10);                   // not supported set limit
-  // query.offset(10);                  // not supported set offset
-
-  let row = await query.find();         // find single row
-}
+// SELECT
+const users = await db.table("users")
+  .where("age", ">", 18)
+  .orderBy("name", "asc")
+  .limit(10)
+  .select("id", "name", "age");
 
-async function insertExample() {
-  const query = handler.table("users");
-
-  // insert
-  let row = await query.insert({
-    name: "Joe",
-    age: 18,
-  });
-
-  // The insert operation will be changed to the update operation if the uuid already exists
-  row = await query.keys('uuid').insert({
-    uuid: 'uuid-string', // uuid is unique index
-    name: "Joe",
-    age: 18,
-  })
-}
+// FIND single row
+const user = await db.table("users").where("id", 1).find();
 
-async function updateExample() {
-  const query = handler.table("users");
-
-  // update
-  let row = await query.where("name", "Joe").update({
-    name: "Joe",
-    age: 18,
-  });
-
-  // incrBy with number
-  row = await query.where("name", "Joe").incrBy("age", 1);
-
-  // incrBy with string
-  row = await query.where("name", "Joe").incrBy("age", "1");
-
-  // incrBy with Callback
-  let result = { status: "success" };
-  row = await query.where("id", 1).incrBy("error_times", () => {
-    // increase error_times if result.status is not success
-    if (result.status !== "success") {
-      return 1;
-    }
-    return 0;
-  });
-}
+// INSERT
+await db.table("users").insert({ name: "Joe", age: 18 });
 
-async function deleteExample() {
-  const query = handler.table("users");
+// UPDATE
+await db.table("users").where("id", 1).update({ name: "Joe", age: 19 });
 
-  // delete with conditions
-  let result = await query.where("name", "Joe").delete();
+// DELETE
+await db.table("users").where("id", 1).delete();
 
-  // delete by id
-  result = await query.delete(1);
-}
-
-async function subqueryExample() {
-  const query = handler.table("users", "u");
-  const subQuery = new Query("select");
-  subQuery.table("users").having("COUNT(*)", ">", 1);
-
-  const sql = query.where("u.name", subQuery, "IN").buildSql("select").sql;
-  // SELECT * FROM `users` AS `u` WHERE `u`.`name` IN (SELECT * FROM `users` GROUP BY `u`.`name` HAVING COUNT(*) > ?)
-}
-```
-
-### Hook
-
-```javascript
-const { Hook } = require("@axiosleo/orm-mysql");
-
-// opt: 'select' | 'find' | 'insert' | 'update' | 'delete' | 'count'
-
-Hook.pre(async (options) => {
-  debug.log('options', options);
-}, { table: 'table_name', opt: 'insert'});
-
-Hook.post(async (options, result) => {
-  throw new Error('some error');
-}, { table: 'table_name', opt: 'insert' });
-```
-
-### Transaction
-
-#### Method 1: Using Connection Pool (Recommended)
-
-```javascript
-const mysql = require("mysql2");
-const { QueryHandler } = require("@axiosleo/orm-mysql");
-
-// Create connection pool
-const pool = mysql.createPool({
-  host: process.env.MYSQL_HOST,
-  port: process.env.MYSQL_PORT,
-  user: process.env.MYSQL_USER,
-  password: process.env.MYSQL_PASS,
-  database: process.env.MYSQL_DB,
-  connectionLimit: 10
-});
-
-const handler = new QueryHandler(pool);
-
-// Begin transaction - automatically gets a connection from pool
-const transaction = await handler.beginTransaction({ 
-  level: "RC" // READ COMMITTED
-});
+// COUNT
+const total = await db.table("users").where("age", ">", 18).count();
 
+// TRANSACTION
+const tx = await db.beginTransaction({ level: "RC" });
 try {
-  // Insert user info
-  let row = await transaction.table("users").insert({
-    name: "Joe",
-    age: 18,
-  });
-  const lastInsertId = row.insertId;
-
-  // Insert student info
-  await transaction.table("students").insert({
-    user_id: lastInsertId,
-  });
-  
-  // Commit transaction - connection automatically released back to pool
-  await transaction.commit();
+  await tx.table("users").insert({ name: "Joe", age: 18 });
+  await tx.commit();
 } catch (e) {
-  // Rollback transaction - connection automatically released back to pool
-  await transaction.rollback();
+  await tx.rollback();
   throw e;
 }
 ```
 
-#### Method 2: Using TransactionHandler Directly
-
-```javascript
-const { TransactionHandler, createPromiseClient } = require("@axiosleo/orm-mysql");
-
-const conn = await createPromiseClient({
-  host: process.env.MYSQL_HOST,
-  port: process.env.MYSQL_PORT,
-  user: process.env.MYSQL_USER,
-  password: process.env.MYSQL_PASS,
-  database: process.env.MYSQL_DB,
-});
-
-const transaction = new TransactionHandler(conn, {
-  /*
-  Transaction Isolation Levels:
-  - 'READ UNCOMMITTED' | 'RU'  : Lowest isolation, may read dirty data
-  - 'READ COMMITTED'   | 'RC'  : Prevents dirty reads
-  - 'REPEATABLE READ'  | 'RR'  : MySQL default, prevents non-repeatable reads
-  - 'SERIALIZABLE'     | 'S'   : Highest isolation, full serialization
-  */
-  level: "SERIALIZABLE", // 'SERIALIZABLE' as default value
-});
-await transaction.begin();
-
-try {
-  // Insert user info
-  let row = await transaction.table("users").insert({
-    name: "Joe",
-    age: 18,
-  });
-  const lastInsertId = row[0].insertId;
-
-  // Insert student info
-  await transaction.table("students").insert({
-    user_id: lastInsertId,
-  });
-  await transaction.commit();
-} catch (e) {
-  await transaction.rollback();
-  throw e;
-}
-```
-
-#### Row Locking with FOR UPDATE
-
-```javascript
-const transaction = await handler.beginTransaction({ level: "RC" });
-
-try {
-  // Lock rows for update
-  const product = await transaction.table("products")
-    .where("sku", "LAPTOP-001")
-    .append("FOR UPDATE")  // Lock the row
-    .find();
-
-  if (product.stock < 1) {
-    throw new Error("Out of stock");
-  }
-
-  // Update stock
-  await transaction.table("products")
-    .where("sku", "LAPTOP-001")
-    .update({ stock: product.stock - 1 });
-
-  // Create order
-  await transaction.table("orders").insert({
-    product_id: product.id,
-    quantity: 1,
-    total: product.price
-  });
-
-  await transaction.commit();
-} catch (e) {
-  await transaction.rollback();
-  throw e;
-}
-```
-
-#### Concurrent Transactions
-
-When using a connection pool, multiple transactions can run concurrently without blocking each other:
-
-```javascript
-const pool = mysql.createPool({ /* ... */ });
-const handler = new QueryHandler(pool);
-
-// Run 3 transactions concurrently
-await Promise.all([
-  (async () => {
-    const tx = await handler.beginTransaction();
-    try {
-      await tx.table("users").insert({ name: "User1" });
-      await tx.commit();
-    } catch (err) {
-      await tx.rollback();
-      throw err;
-    }
-  })(),
-  
-  (async () => {
-    const tx = await handler.beginTransaction();
-    try {
-      await tx.table("users").insert({ name: "User2" });
-      await tx.commit();
-    } catch (err) {
-      await tx.rollback();
-      throw err;
-    }
-  })(),
-  
-  (async () => {
-    const tx = await handler.beginTransaction();
-    try {
-      await tx.table("users").insert({ name: "User3" });
-      await tx.commit();
-    } catch (err) {
-      await tx.rollback();
-      throw err;
-    }
-  })()
-]);
-```
-
-#### Best Practices
-
-1. **Always use connection pools in production** - Prevents connection exhaustion and enables concurrent transactions
-2. **Choose appropriate isolation level** - Balance between consistency and performance
-3. **Use try-catch-finally** - Ensure transactions are always committed or rolled back
-4. **Keep transactions short** - Avoid long-running operations inside transactions
-5. **Use row locking when needed** - `FOR UPDATE` prevents concurrent modifications
-6. **Handle errors properly** - Always rollback on errors to maintain data consistency
+> For complete API documentation including where conditions, joins, hooks, migrations, and more, install the [AI Skills](#ai-skills) for your coding assistant, or browse the skill files in [`skills/`](skills/).
 
 ### Migration
 
-> [Migration examples](./examples/migration/).
-
-- Migration script example
-
-```javascript
-'use strict';
-
-/**
- * @param {import('@axiosleo/orm-mysql').MigrationInterface} migration
- */
-function up(migration) {
-  migration.createTable('table1', {
-    field1: {
-      type: 'varchar',
-      length: 64,
-      allowNull: false,
-      uniqIndex: true
-    },
-    field2: {
-      type: 'VARCHAR',
-      allowNull: false
-    },
-    field3: {
-      type: 'VARCHAR',
-      comment: 'comment',
-      allowNull: false
-    },
-  });
-}
-
-/**
- * @param {import('@axiosleo/orm-mysql').MigrationInterface} migration
- */
-function down(migration) {
-  migration.dropTable('table1');
-}
-
-module.exports = {
-  up,
-  down
-};
-```
-
-- Generate migration script
-
-```bash
-orm-mysql generate -h
-
-Usage:
-
-  generate [--] [name] <dir>
-  gen
-
-Arguments:
-
- *name    Migration name
-  dir     Migration scripts directory
-```
-
-- Run migration
-
 ```bash
-orm-mysql migrate -h
-
-Description:
-
-  Migrate database
-
-Usage:
-
-  migrate [options] [--] [action] <dir>
+# Generate migration script
+npx orm-mysql generate <name> [dir]
 
-Options:
-
-  -d, --debug    [false] debug mode
-  --host         [localhost] mysql host
-  --port         [3306] port number to connect to the database
-  --user         [root] username for connect to the database
-  --pass         password to connect to the database
-  --db           database name
-
-Arguments:
-
- *action         up or down
-  dir            migration directory
+# Run migration
+npx orm-mysql migrate up [dir] --host=localhost --port=3306 --user=root --pass=pwd --db=mydb
 ```
 
-### Custom query driver
-
-```javascript
-const { 
-  createClient, 
-  QueryHandler, 
-  Query,
-  Builder 
-} = require("@axiosleo/orm-mysql");
-
-const conn = createClient({
-  host: process.env.MYSQL_HOST,
-  port: process.env.MYSQL_PORT,
-  user: process.env.MYSQL_USER,
-  password: process.env.MYSQL_PASS,
-  database: process.env.MYSQL_DB,
-});
-
-const hanlder = new QueryHandler(conn, {
-  driver: 'custom',
-  queryHandler: (con, options) => {
-    const builder = new Builder(options);
-    return new Promise((resolve, reject) => {
-      if (options.operator === 'select') {
-        resolve([{ a: 1, b: 2 }]);
-      } else {
-        reject(new Error('some error'));
-      }
-    });
-  }
-});
-```
+> [Migration examples](./examples/migration/)
 
 ## AI Skills
 

package/bin/orm-mysql.js

@@ -9,7 +9,7 @@ const app = new App({
   name: 'MySQL ORM CLI',
   desc: 'migrate, model, seed, etc.',
   bin: 'orm-mysql',
-  version: '0.15.0',
+  version: '0.15.1',
   commands_dir: path.join(__dirname, '../commands'),
 });
 

package/commands/skills.js

@@ -118,7 +118,7 @@ class SkillsCommand extends Command {
       printer.info(`Found ${PKG_NAME}@${source.version} in node_modules`);
     } else if (source.outdated) {
       printer.warning(`${PKG_NAME}@${source.localVersion} is installed locally but does not include skills files.`);
-      printer.warning('Skills files are available since v0.15.0. Please update:');
+      printer.warning('Skills files are available since v0.15.1. Please update:');
       printer.warning(`  npm install ${PKG_NAME}@latest`);
       printer.println();
       printer.info(`Using skills from npx ${PKG_NAME}@${source.version} instead.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiosleo/orm-mysql",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "MySQL ORM tool",
   "keywords": [
     "mysql",

package/skills/SKILL.md

@@ -98,6 +98,7 @@ await db.table("users").where("id", 1).delete();
 
 // COUNT
 const total = await db.table("users").where("age", ">", 18).count();
+// IMPORTANT: for paginated lists, reuse the SAME builder for count() and select() -- see pagination.md
 
 // FIND single row
 const user = await db.table("users").where("id", 1).find();
@@ -124,6 +125,7 @@ console.log(builder.values); // [18]
 | Building queries (table, join, orderBy, limit, groupBy, attr) | [query-building.md](query-building.md) |
 | Where conditions (where, whereIn, whereLike, whereBetween...) | [where-conditions.md](where-conditions.md) |
 | CRUD operations (select, find, count, insert, update, delete, incrBy, upsertRow) | [crud-operations.md](crud-operations.md) |
+| Pagination (reuse the same builder for count() and select(), avoid duplicated where clauses) | [pagination.md](pagination.md) |
 | Transactions (beginTransaction, commit, rollback, FOR UPDATE) | [transactions.md](transactions.md) |
 
 ## Hooks

package/skills/crud-operations.md

@@ -39,6 +39,8 @@ const total = await db.table("users").where("status", "active").count();
 // total is a number
 ```
 
+For paginated list endpoints, do NOT create a separate count builder with duplicated `where` conditions. Reuse the same builder for both `count()` and `select()` -- `count()` ignores `attrs`/`limit`/`offset`/`orderBy`, and `select()` resets the operator. See [pagination.md](pagination.md) for the full pattern.
+
 ### explain(operator)
 
 Returns the MySQL EXPLAIN result for the query.

package/skills/pagination.md

@@ -0,0 +1,301 @@
+# Pagination
+
+Best practices for building paginated list endpoints with `@axiosleo/orm-mysql`.
+
+## Critical Rule
+
+**For paginated queries, always reuse the SAME query builder for both `count()` and `select()`.**
+NEVER construct a separate `countBuilder` and re-apply the same `where` conditions.
+
+The `Query` instance returned by `db.table(...)` is a mutable object: each `where()`, `whereIn()`, `leftJoin()`, etc. mutates `this.options` and returns `this`. Calling `count()` on a builder does NOT consume or invalidate it -- you can chain `select()` afterwards on the very same instance.
+
+## Anti-Pattern: Duplicating Conditions for COUNT
+
+The following pattern is wrong. It is verbose, fragile, and a maintenance hazard: every time a filter is added or changed, both builders must be updated, and forgetting one of them silently desynchronizes `total` from the actual result set.
+
+```javascript
+// BAD -- do not write code like this
+let queryBuilder = this.companyDB
+  .table(this.plansTable, 'pp')
+  .attr('pp.plan_no', 'pp.title', 'pp.plan_type', 'pp.status', 'pp.created_at')
+  .attr('u.name as created_by_name')
+  .leftJoin('users', 'pp.created_by=u.id', { alias: 'u' });
+
+if (query.plan_no) {
+  queryBuilder = queryBuilder.where('pp.plan_no', 'like', `%${query.plan_no}%`);
+}
+if (query.status) {
+  queryBuilder = queryBuilder.where('pp.status', query.status);
+}
+if (query.plan_type) {
+  queryBuilder = queryBuilder.where('pp.plan_type', query.plan_type);
+}
+queryBuilder = queryBuilder.where('pp.disabled', 0);
+
+const page = query.page || 1;
+const pageSize = query.page_size || 10;
+const offset = (page - 1) * pageSize;
+
+// BAD: a second builder that re-declares the same table and re-applies every where
+const countBuilder = this.companyDB
+  .table(this.plansTable, 'pp')
+  .where('pp.disabled', 0);
+if (query.plan_no) {
+  countBuilder.where('pp.plan_no', 'like', `%${query.plan_no}%`);
+}
+if (query.status) {
+  countBuilder.where('pp.status', query.status);
+}
+if (query.plan_type) {
+  countBuilder.where('pp.plan_type', query.plan_type);
+}
+
+const total = await countBuilder.count();
+
+const plans = await queryBuilder
+  .orderBy('pp.created_at', 'desc')
+  .limit(pageSize)
+  .offset(offset)
+  .select();
+```
+
+## Recommended Pattern: Reuse the Same Query Builder
+
+Build the filters once on a single `queryBuilder`, then call `count()` followed by the chained `orderBy/limit/offset/select()` on the same instance.
+
+```javascript
+// GOOD
+let queryBuilder = this.companyDB
+  .table(this.plansTable, 'pp')
+  .attr('pp.plan_no', 'pp.title', 'pp.plan_type', 'pp.status', 'pp.created_at')
+  .attr('u.name as created_by_name')
+  .leftJoin('users', 'pp.created_by=u.id', { alias: 'u' });
+
+if (query.plan_no) {
+  queryBuilder = queryBuilder.where('pp.plan_no', 'like', `%${query.plan_no}%`);
+}
+if (query.status) {
+  queryBuilder = queryBuilder.where('pp.status', query.status);
+}
+if (query.plan_type) {
+  queryBuilder = queryBuilder.where('pp.plan_type', query.plan_type);
+}
+queryBuilder = queryBuilder.where('pp.disabled', 0);
+
+const page = query.page || 1;
+const pageSize = query.page_size || 10;
+const offset = (page - 1) * pageSize;
+
+const total = await queryBuilder.count();
+
+const plans = await queryBuilder
+  .orderBy('pp.created_at', 'desc')
+  .limit(pageSize)
+  .offset(offset)
+  .select();
+```
+
+Note how the filter block (`if (query.xxx) { ... }`) appears exactly once. There is no second copy to keep in sync.
+
+## Why This Is Safe
+
+Three implementation details from this ORM make the single-builder pattern correct:
+
+1. **`Query.options` is mutable, methods return `this`.** Every chain call (`where`, `whereIn`, `leftJoin`, `attr`, `orderBy`, `limit`, `offset`, ...) mutates `this.options` on the same instance. There is no copy-on-write.
+
+2. **`count()` ignores `attrs`, `limit`, `offset`, and `orderBy`.** The COUNT SQL is built by `_countOperator` in `src/builder.js`, which only consumes `tables`, `joins`, `conditions`, `groupField`, and `having`. It emits `SELECT COUNT(*) AS count FROM ...` and never reads the `attr()` list, the limit/offset, or the order-by list. So having those configured on the builder does not affect the count.
+
+3. **`select()` overwrites `operator`.** `count()` sets `this.options.operator = 'count'`. `select()` then sets `this.options.operator = 'select'`, restoring the correct execution path. The two calls can safely happen on the same instance, in either order.
+
+## Recommended Order
+
+Call `count()` BEFORE chaining `orderBy`/`limit`/`offset`. Even though `count()` would ignore them anyway, this ordering keeps the read intent obvious:
+
+```javascript
+// 1. assemble all where / join / attr
+// 2. take the total
+const total = await queryBuilder.count();
+
+// 3. then add purely "presentation" concerns and fetch the page
+const list = await queryBuilder
+  .orderBy('pp.created_at', 'desc')
+  .limit(pageSize)
+  .offset(offset)
+  .select();
+```
+
+## Complete Pagination Template
+
+A drop-in template for a typical "list with filters" endpoint:
+
+```javascript
+async function listPlans(query) {
+  let q = db.table('procurement_plans', 'pp')
+    .attr('pp.plan_no', 'pp.title', 'pp.plan_type', 'pp.status', 'pp.created_at')
+    .attr('u.name as created_by_name')
+    .leftJoin('users', 'pp.created_by=u.id', { alias: 'u' })
+    .where('pp.disabled', 0);
+
+  if (query.plan_no) {
+    q = q.where('pp.plan_no', 'like', `%${query.plan_no}%`);
+  }
+  if (query.status) {
+    q = q.where('pp.status', query.status);
+  }
+  if (query.plan_type) {
+    q = q.where('pp.plan_type', query.plan_type);
+  }
+
+  const page = Number(query.page) || 1;
+  const pageSize = Number(query.page_size) || 10;
+  const offset = (page - 1) * pageSize;
+
+  const total = await q.count();
+
+  const list = await q
+    .orderBy('pp.created_at', 'desc')
+    .limit(pageSize)
+    .offset(offset)
+    .select();
+
+  return { list, total, page, page_size: pageSize };
+}
+```
+
+## Multi-Keyword Fuzzy Search
+
+A common pagination filter is "search by keyword across several columns", where the user may type multiple space-separated keywords (e.g. `"foo bar"`) and expect rows matching ANY keyword in ANY of the searchable columns.
+
+This pattern combines `whereCondition()` (for the per-keyword `column1 LIKE ? OR column2 LIKE ?` group) with logical operators between groups. Two foot-guns make it easy to write SQL that compiles but returns wrong results:
+
+1. **Consecutive `whereCondition()` calls join with `AND` by default.** No operator is auto-inserted "between" groups except the implicit `AND`. So writing one `whereCondition()` per keyword without anything between them means every keyword must match -- not what users expect from search.
+2. **Inserting `whereOr()` at the top level introduces an operator-precedence bug.** SQL evaluates `AND` before `OR`, so `WHERE other_filters AND (k1 group) OR (k2 group)` lets the second keyword match rows that ignore `other_filters` entirely.
+
+### Anti-Pattern A: All keywords required (silent AND)
+
+```javascript
+// BAD -- generates: ... AND (plan_no LIKE %k1% OR title LIKE %k1%) AND (plan_no LIKE %k2% OR title LIKE %k2%)
+// User searches "foo bar" but no row contains both "foo" and "bar" anywhere -- empty result.
+if (query.keyword && query.keyword.trim()) {
+  const keywords = query.keyword.trim().split(/\s+/).filter(Boolean);
+  for (const keyword of keywords) {
+    const keywordCondition = new QueryCondition();
+    keywordCondition
+      .where('pp.plan_no', 'like', `%${keyword}%`)
+      .whereOr()
+      .where('pp.title', 'like', `%${keyword}%`);
+    queryBuilder = queryBuilder.whereCondition(keywordCondition);
+  }
+}
+```
+
+### Anti-Pattern B: Top-level `whereOr()` between groups (precedence bug)
+
+```javascript
+// BAD -- generates: ... AND (k1 group) OR (k2 group)
+// AND binds tighter than OR, so disabled=0 / status / plan_type only constrain the first keyword group.
+// The second keyword group OR's against everything else, returning soft-deleted or wrong-tenant rows.
+keywords.forEach((keyword, index) => {
+  if (index !== 0) {
+    queryBuilder.whereOr();
+  }
+  const keywordCondition = new QueryCondition();
+  keywordCondition
+    .where('pp.plan_no', 'like', `%${keyword}%`)
+    .whereOr()
+    .where('pp.title', 'like', `%${keyword}%`);
+  queryBuilder = queryBuilder.whereCondition(keywordCondition);
+});
+```
+
+### Recommended: Build a single `QueryCondition` and attach it once
+
+Declare **one** `QueryCondition` outside the loop, push every keyword's `OR`-clauses into it, and attach the whole thing to the main builder with **one** `whereCondition()` call after the loop. All keyword `LIKE`s stay inside one parenthesized group, joined to the surrounding `AND` filters as a single safe sub-expression.
+
+The diff from Anti-Pattern B is small and worth memorizing:
+
+1. Move `const keywordCondition = new QueryCondition()` **out** of the loop.
+2. Inside the loop, call `.whereOr()` on `keywordCondition` (the inner condition), **not** on `queryBuilder`.
+3. Call `queryBuilder.whereCondition(keywordCondition)` **once**, after the loop, not on every iteration.
+
+```javascript
+// GOOD -- generates: ... AND (plan_no LIKE %k1% OR title LIKE %k1% OR plan_no LIKE %k2% OR title LIKE %k2%)
+const { QueryCondition } = require('@axiosleo/orm-mysql');
+
+if (query.keyword && query.keyword.trim()) {
+  const keywords = query.keyword.trim().split(/\s+/).filter(Boolean);
+  const keywordCondition = new QueryCondition();
+  keywords.forEach((keyword, index) => {
+    if (index !== 0) {
+      keywordCondition.whereOr();
+    }
+    keywordCondition
+      .where('pp.plan_no', 'like', `%${keyword}%`)
+      .whereOr()
+      .where('pp.title', 'like', `%${keyword}%`);
+  });
+  queryBuilder = queryBuilder.whereCondition(keywordCondition);
+}
+```
+
+### Rules of Thumb
+
+- One `whereCondition()` call -> one parenthesized group joined to the surrounding `WHERE` with `AND`. Safe and unambiguous.
+- For "any-of-N" search filters, accumulate all `OR` clauses into **one** `QueryCondition` declared outside the loop, then attach it with **one** `whereCondition()` after the loop. Never call `queryBuilder.whereOr()` at the top level between `whereCondition()` calls -- that leaks the `OR` past your other `AND` filters because SQL evaluates `AND` before `OR`.
+- The same rule applies to `count()` reuse: this composite condition is just data on `options.conditions`, so the same builder still produces a correct `COUNT(*)` with the keyword filter intact.
+
+## Edge Case: GROUP BY
+
+`count()` includes `GROUP BY` in the generated SQL, which means with grouping it returns one row per group rather than the total number of groups. In that case the same builder cannot be reused as-is for "how many groups are there".
+
+Two valid approaches:
+
+### Approach A: count via subquery
+
+Wrap the grouped query as a subquery and count its rows. Build the inner query without `limit/offset/orderBy`, then count it:
+
+```javascript
+const { Query } = require('@axiosleo/orm-mysql');
+
+const inner = new Query('select');
+inner.table('orders', 'o')
+  .attr('o.user_id')
+  .where('o.status', 'paid')
+  .groupBy('o.user_id');
+
+const total = await db.table(inner, 'sub').count();
+
+const rows = await db.table('orders', 'o')
+  .attr('o.user_id', 'SUM(o.total) AS total')
+  .where('o.status', 'paid')
+  .groupBy('o.user_id')
+  .orderBy('total', 'desc')
+  .limit(pageSize)
+  .offset(offset)
+  .select();
+```
+
+### Approach B: dedicated count builder (only when grouping forces it)
+
+If you genuinely need two builders because of grouping, factor the shared filters into a helper to keep them in sync:
+
+```javascript
+function applyFilters(q, query) {
+  q.where('o.status', 'paid');
+  if (query.user_id) q.where('o.user_id', query.user_id);
+  return q;
+}
+
+const groupedQ = applyFilters(
+  db.table('orders', 'o').attr('o.user_id', 'SUM(o.total) AS total').groupBy('o.user_id'),
+  query
+);
+const countInner = applyFilters(
+  new Query('select').table('orders', 'o').attr('o.user_id').groupBy('o.user_id'),
+  query
+);
+const total = await db.table(countInner, 'sub').count();
+const list = await groupedQ.orderBy('total', 'desc').limit(pageSize).offset(offset).select();
+```
+
+For all non-grouped paginated lists, stick to the single-builder pattern at the top of this file.

package/skills/where-conditions.md

@@ -131,6 +131,50 @@ query
 // WHERE `status` = ? AND (`age` > ? AND `age` < ?)
 ```
 
+### Default Joining Between Multiple `whereCondition()` Calls
+
+Each `whereCondition()` call appends one parenthesized group to `WHERE`, joined to whatever came before with **`AND`**. There is no implicit `OR` between groups.
+
+```javascript
+const g1 = new QueryCondition();
+g1.where("a", 1).whereOr().where("b", 2);
+
+const g2 = new QueryCondition();
+g2.where("c", 3).whereOr().where("d", 4);
+
+query.where("status", "active")
+  .whereCondition(g1)
+  .whereCondition(g2);
+// WHERE `status` = ? AND (`a` = ? OR `b` = ?) AND (`c` = ? OR `d` = ?)
+```
+
+### Combining Multiple Groups with `OR`: Wrap, Don't Sprinkle
+
+To `OR` two groups together, do **not** insert a top-level `whereOr()` between them on the main builder. SQL evaluates `AND` before `OR`, so the surrounding filters silently bind only to the first group:
+
+```javascript
+// BAD -- generates: WHERE `status` = ? AND (`a` = ? OR `b` = ?) OR (`c` = ? OR `d` = ?)
+// `status` = ? only constrains the first group. The second group OR's against everything.
+query.where("status", "active")
+  .whereCondition(g1)
+  .whereOr()
+  .whereCondition(g2);
+```
+
+Instead, build a single outer `QueryCondition` containing the `OR`'d groups, then attach it once:
+
+```javascript
+// GOOD -- generates: WHERE `status` = ? AND ((`a` = ? OR `b` = ?) OR (`c` = ? OR `d` = ?))
+const outer = new QueryCondition();
+outer.whereCondition(g1).whereOr().whereCondition(g2);
+
+query.where("status", "active").whereCondition(outer);
+```
+
+Rule of thumb: `whereOr()` between two `whereCondition()` calls is safe **inside** a `QueryCondition` (it only changes that group's internal logic), but at the top level of the main query builder it leaks the `OR` past your other `AND` filters.
+
+When the clauses you want to `OR` together are programmatically generated and share the same shape (e.g. an N-keyword fuzzy search across the same columns), skip the nested `g1`/`g2` and pour every clause directly into a single `QueryCondition` using its own `where()`/`whereOr()` calls -- then attach it to the main builder once. See [pagination.md](pagination.md) (Multi-Keyword Fuzzy Search) for the exact pattern.
+
 ## Complete Example
 
 ```javascript